README.md

back to source

# NumericalOS

Graph-driven Linux userspace init. Configuration is a single content-hashed
artifact (`numos.state`) exported from an intrikata-topology M/G/S/MGS graph
quartet. There are no unit files on the target.

**Status: bootstrap logic tested; x86_64 QEMU self-init PASS (degraded=0) on kernel+initrd and hybrid ISO/GRUB serial; fleet bare-QEMU PASS-degraded; metal and non-x86_64 unverified.** Unit tests cover the shell/Python floor.
Under QEMU 10.2.2 x86_64, the **self-init** graph profile reaches
`numos: boot complete degraded=0` on both **kernel+initrd** and **hybrid ISO /
GRUB serial** paths (including CF Sandbox-built artifacts). **Fleet** on bare
QEMU still degrades (net/clock/join). Claims stay scoped: one arch, named path,
not metal. Only `numericalos-verify-boot` may assert a boot for a given
artifact and arch.

## Scope (Spec 1)

| In scope | Out of scope (stated) |
|---|---|
| POSIX bootstrap: arch → manifest → acquire → verify → exec | Kernel / package manager / distro images |
| Shell `numinit`: phases, DAG, `on_failure`, steady state | Zig static `numinit` (Spec 3) |
| Floor `numctl`: identity, join, capability, run-op dispatch edge | Control socket; op interpreter body |
| Resource envelopes (`R`): enforce `ram_mb`/`timeout_s`; refuse `cpu_pct` | cgroup-based `cpu_pct` |
| Health predicates + restart quarantine | Phase-required start of all op units as longrun daemons |
| Join outcomes: `disabled` / `joined` / `failed` | Full coordinator / fleet scheduler |
| CF Sandbox + R2 ISO/initramfs builder (no WSL) | Shipping prebuilt OS images as the primary path |
| Graph-resolved **self-init** distro (`numos-floor` + complete unit graph) | busybox as product identity; eth0/ntpd on bare QEMU |

Join and Capability writes are operator-controlled (`NUMOS_COORDINATOR`). Off by
default; never to `numericalos.com`. See `docs/PRINCIPLES.md`.

## Layout

| Path | Role |
|---|---|
| `numos/` | State format, validation, export, arch-table generator |
| `boot/bootstrap.sh` | Arch detect, manifest, acquire, hash verify, exec |
| `boot/numinit.sh` | Phase walk, unit DAG, steady state, envelopes, signals |
| `boot/numctl` | `identity-init`, `join`, `capability`; other cmds named-halt |
| `boot/lib/arch_table.sh` | Generated from `ArchTarget` seed — do not edit |
| `site/` | Static site + published `/artifacts/*` manifest |
| `site/boot.sh` | Host installer (`curl \| sh`); does not replace PID 1 |
| `skills/` | Local + Cloudflare build / QEMU verify skills |
| `deploy/cloudflare-iso-builder/` | Worker + Sandbox script for remote ISO/initramfs |
| `tests/` | stdlib unittest + bash subprocess |
| `docs/PRINCIPLES.md` | Enforced commitments + tests |
| `docs/superpowers/` | Design spec and implementation plan |

## Runtime chain

**`bootstrap.sh`**

1. Canonicalize `uname -m` via generated arch table (halt if unknown).
2. Refresh or load `manifest.txt` (online refresh; offline uses on-disk only).
3. Resolve init artifact from manifest only (`numinit-$arch` if listed, else `numinit.sh`).
4. Acquire artifact (prefer verified local; fetch if missing; `NUMOS_OFFLINE=1` refuses network).
5. Verify artifact and `numos.state` hashes; exec `numinit`.

Does not mount `/proc`/`/sys`/`/dev` (initramfs / host provide those).

Self-contained initramfs images set `NUMOS_OFFLINE=1` and pre-populate
`NUMOS_PREFIX` (typically `/opt/numericalos`) so first boot needs no network.

**`numinit.sh`**

- Phases by ordinal; Kahn-style dependency order per phase.
- Kinds: `oneshot` / `target` (sync); `longrun` (background after start-alive check).
- Immediate longrun death → phase failure; later death → restart / health / quarantine.
- Steady state: tick loop (restart policies, health, escalations). Never returns
  in a real boot (`NUMOS_MAX_TICKS` bounds tests only).
- `TERM`/`INT` → named halt. Not full `SIGCHLD` PID-1 discipline.

**`numctl`**

- `identity-init` — idempotent local identity under `NUMOS_RUNDIR`.
- `capability` — measured host fields to disk (`-` if unmeasurable).
- `join` — writes capability; if `NUMOS_COORDINATOR` set, POST and record
  `joined` or `failed`; if unset, `disabled` with no outbound traffic.
- `run-op` — dispatch edge to `NUMOS_OP_RUNTIME` (refuse undeclared ops;
  `unavailable` if runtime unset; not an op interpreter).
- `status` — named halt (no control socket).

## Build targets

| Path | Skill | Host need |
|---|---|---|
| OCI image | `numericalos-build-oci` | Docker/Podman |
| initramfs / hybrid ISO | `numericalos-build-iso` (+ initramfs) | Linux + tools |
| same artifacts, no WSL | `numericalos-build-iso-cf` | Cloudflare account; Sandbox + R2 |
| boot claim | `numericalos-verify-boot` | QEMU for target arch |
| site (self-hosted) | `numericalos-publish-site` | Cloudflare Pages `numericalos` / numericalos.com |

Protocol: `skills/AGENTS.md`. Classifier picks exactly one build skill.

## Pure graph product

Profiles live in `numos/distro.py`. Export is the only path to a bootable
state file. See `docs/GRAPH.md` and the site page `/graph/`.

```bash
py -m numos.distro list
py -m numos.distro --profile self-init graph    # nodes + edges JSON
py -m numos.distro --profile self-init mermaid
py -m numos.distro --profile self-init kernel --arch x86_64
py -m numos.export_state --profile self-init --seed-only --out dist
# dist/: numos.state + distro.{floor,kernel,profile,graph}.json + distro.graph.mmd
```

## Develop

```bash
py -m unittest discover -s tests -v
py -m numos.archtable                 # regenerate boot/lib/arch_table.sh
py -m numos.export_state --profile self-init --seed-only --out dist
py site/build.py                      # static site → public/ or NUMOS_OUT=
.\scripts\publish-site.ps1            # build + deploy all pages to numericalos.com
# (no git remote required — self-hosted via Cloudflare Pages --branch main)
```

Dependencies: Python 3 stdlib; `bash` for shell tests (Git Bash on Windows).
Cloudflare ISO path: `deploy/cloudflare-iso-builder/` (see its README).