README.md

back to source

# NumericalOS

A bootable Linux userspace whose init system is an intrikata-topology graph.
No unit files: every supervisable thing, boot ordering constraint, health rule,
and remediation path is a node in an M/G/S/MGS quartet, with ASEC swarms as the
self-heal loop. A booted machine joins the topology as a compute node.

**Status: bootstrap logic tested; boot unverified.** Nothing here has been
booted on real or emulated hardware yet. Verifying that requires a Linux host
with `qemu-system-*` per architecture -- see the gate table in the design spec.
No "it boots" claim will be made until that gate runs.

## Layout

| Path | What it is |
|---|---|
| `numos/` | exporter, validation, state format, arch-table generator |
| `boot/bootstrap.sh` | POSIX floor: arch detect, `numos.state` hash verify |
| `boot/numinit.sh` | shell PID-1 path: phase walk, unit DAG, `on_failure` policy |
| `boot/lib/arch_table.sh` | generated from ArchTarget nodes - do not edit |
| `tests/` | stdlib unittest suite, including shell tests via subprocess |
| `docs/superpowers/` | design spec and implementation plan |

## What is built, and what is not

The design spec describes the whole boot chain. Spec 1 builds part of it.
Understating a limitation is as much a defect as overstating a capability,
so the gaps are named here and in section 11 of the design spec rather than
left to be inferred.

`boot/bootstrap.sh` resolves `uname -m` to a canonical architecture through
the generated table, prints which init artifact it would select, and
verifies a `numos.state` file's content hash when `NUMOS_STATE` is set. It
does **not** fetch an artifact, does **not** hash-verify one
(`numos_verify_sha256` is implemented and tested but has no caller outside
the tests), does **not** mount `/proc`, `/sys` or `/dev`, and does **not**
exec `numinit`. Those steps need published artifacts and a real Linux host,
and are sequenced as later specs.

`boot/numinit.sh` walks boot phases by ordinal, resolves each phase's unit
DAG, starts units according to their `kind`, and applies each phase's
`on_failure` policy. It does **not** supervise anything: `numos_supervise`
and its backoff primitives are implemented and covered by tests, but
`numos_main` never calls them, so no unit is ever restarted and a `longrun`
unit is started and then left alone. It also does not reap zombies, does not
run `HealthPredicate` probes, and serves no control socket.

## Develop

```bash
py -m unittest discover -s tests -v   # run everything
py -m numos.archtable                 # regenerate boot/lib/arch_table.sh
py -m numos.export_state --out dist   # build numos.state from the live graph
```

Requires Python 3 stdlib only, plus `bash` for the shell tests.