Documentation
How a graph becomes an init system, what the one runtime artifact looks like, and exactly what has and has not been proven.
The state format
The line-oriented numos.state: six record types, why it is not
JSON, and how the content hash makes drift detectable.
The boot chain
From kernel handoff to steady state: arch resolution, fail-closed verification, phase walk, DAG resolution, failure policy.
What is proven
The honest inventory: what the 141 tests cover, what they cannot, and which verification gates remain open.
The schemas
Five node types carry the whole model.
| schema | role |
|---|---|
OSUnit | a supervisable thing: exec, kind, requires, after, restart policy, arch mask, resource envelope |
BootPhase | an ordered stage: ordinal, required units, on_failure policy |
Capability | the join advertisement a booted node emits: arch, cores, RAM, CPU features, supported ops, degraded flag |
HealthPredicate | a SHADOW detector: probe, interval, threshold, local action, and the swarm to fire |
ArchTarget | the multi-arch registry: uname -m aliases, Zig triple, busybox variant, artifact hash |
ArchTarget is the one that makes the project's central claim
literal. The bootstrap's architecture-detection table is generated from these
nodes into boot/lib/arch_table.sh, and a test asserts the committed
file still matches its generator — so the "data insert, not a code edit"
claim cannot silently rot.
Units are derived, not authored
A NumericalOS node is an Intrikata compute node: it boots, advertises its
silicon and its supported operations, and the coordinator schedules work onto it.
So the unit set comes from the ops registry rather than being written by hand
— 196 registered operations become 196 units, each depending on
join, alongside the seeded infrastructure units.
That has a consequence worth stating plainly: a node's unit set changes
when the registry changes. This is the intended behavior, and it is why
numos.state carries a content hash and why numinit
refuses a state whose hash does not match. Drift is detectable rather than
silent.
What NumericalOS does not ship
- A kernel. "Smallest bootstrap" scopes to userspace. You pair it with a distribution or upstream kernel.
- A package manager. The graph is the configuration; there is nothing for a package manager to configure.
- Images. This site hosts no artifacts. The skills build them on your machine.
- A PID-1 takeover by default. The
curl | shvector attaches a host as a node under its existing init. Replacing PID 1 on a live machine is destructive and requires an explicit flag.