The Ten Commandments of Godspeed

These Commandments define the architectural boundaries of Godspeed. They are not coding guidelines or stylistic preferences. They exist to preserve a system that remains simple, recoverable, and understandable as it grows.

They are the human-readable distillation of the constitution in CLAUDE.md - each is grounded in the invariants and sections it enforces. Where a Commandment and the code disagree, the code is wrong (CLAUDE.md §1). Where a Commandment and the constitution disagree, the constitution is the law and this document is amended to match.

For a catalog of concrete violations of these Commandments - each paired with the correct pattern and grounded in the section it breaks - see docs/anti-patterns.md, the field guide to constitutional violations.

Respect Godspeed

I. Thou shalt not expand the responsibilities of the kernel. It is complete. Use a service.

The kernel's responsibilities are complete: memory isolation, scheduling, IPC, capability enforcement, interrupt routing, and cross-core routing - and nothing else. New hardware support, new CPU architectures, and bug fixes are welcome. New responsibilities are not.

Before proposing a kernel change, ask: "Why isn't this a service?" If the answer is "because it is more convenient," it belongs outside the kernel.

Why the kernel stays tiny - and why that boundary is a reward, not a restriction.

The kernel is audited regularly and exhaustively against these Commandments (the living record is audits/kernel-audit.md).

The cost of that audit does not grow linearly with the kernel - it grows with the interactions between its responsibilities. A real audit never examines each responsibility in isolation; it cross-checks every responsibility against every other, looking for shared state, lock ordering, fault propagation, hidden assumptions, and the cracks between subsystems where the most dangerous bugs emerge.

Every new responsibility therefore creates more than additional code. It creates additional interactions that must be understood, verified, and trusted. In practice, N responsibilities produce roughly N² relationships to reason about.

A tiny kernel can be audited end-to-end. Its guiding promise - that nothing above it may panic or wedge it - can be continuously verified rather than merely hoped for. Add one more responsibility, and the increase in trust required is far greater than the increase in code.

A bounded kernel is therefore not a limitation imposed on the architecture. It is the property that makes the architecture continuously auditable, and therefore trustworthy. Every responsibility refused permanently reduces future audit effort, shrinks the privileged attack and failure surface, and keeps the kernel's guarantees affordable to verify.

Refuse responsibility, and be rewarded.

Grounded in: §4.3-§4.4 (kernel scope and anti-scope), §26.10 (the kernel is mechanism, not policy), §26.11 (understandability is a hard requirement - the 30-minute whiteboard rule), §22 (the identity/audit suites that keep the guarantee executable), Invariant 4 (the kernel remains tiny).

II. Thou shalt love Chaos and trust in it. Thy service shall pass through Maximum Carnage.

Passing unit tests does not prove correctness. Every service shall eventually face failure, memory pressure, restart storms, spawn storms, queue floods, and whatever new forms Chaos invents.

If Chaos finds a bug, the bug already existed. Treat Chaos as your teacher, not your enemy.

Grounded in: §22 (the identity, stress, adversarial, and chaos suites - and chaos max-carnage), §2.3 (execution over theory), §26.7 (loud failure over hidden recovery).

III. Thou shalt not duplicate truth. Store irreducible facts. Derive the rest.

There must be exactly one irreducible source of truth - the minimal state from which everything else can be reconstructed, and which cannot itself be reduced to anything smaller. Everything else is a derived view of it.

This is not a ban on caches, indexes, or precomputed counts. A derived view may be stored, and may even drift, provided it is reconstructible from the source, reconciled when it drifts (a repair path rebuilds it from the source), and subordinate - on any disagreement the source wins; the view is never authoritative. A filesystem's free bitmap is a stored index of its file tree (fsck rebuilds it from the tree); the free count is a stored index of the bitmap. Neither is a second truth - both reduce to the tree.

What is forbidden is a second irreducible truth: two stored facts that can diverge with no way to decide which is right, or trusting a derived view as if it were the source. The test is not "is it stored?" nor "can it drift?" - it is "does it reduce to one source, and does that source win?"

Grounded in: §3.8 (state explicit and owned), §3.9 / Invariant 9 (no unowned global mutable state), §26.4 (caching must be visible and reconcilable, never hidden).

IV. Thou shalt honor service contracts.

Services communicate through explicit contracts. Do not bypass a contract. Do not invent hidden communication paths. If a service cannot express its needs through its declared contract, redesign the contract - not the architecture.

Grounded in: §13 (service contracts), §3.7 / Invariant 7 (contracts are enforced, not interpreted), §13.6 (runtime enforcement from the SPAWN REQUEST at spawn; the contract is the build-time declaration reconciled against it, never the runtime source - amended 2026-09-14).

V. Thou shalt not assume thy service is special. Only the kernel is special.

Every service must be prepared to fail. Every service must be prepared to restart. No service is exempt. If the Supervisor itself must survive its own death - and it must, for the kernel respawns it

  • so must yours.

The only unkillable component is the kernel. Everything above it is identity, not location, and identity survives restart.

Being unexceptional cuts both ways. Just as no service is too important to restart, none is too important to admit when it could not recover. When a service tries to recover from a failure - a retry, a reacquire, a fallback - and that recovery itself fails, the failure is still a failure: surface it. A recovery whose own failure is discarded becomes a silent success, and the service then proceeds on a state it never actually reached - the very hidden failure this system forbids. Recover if you can; when you cannot, say so plainly.

Grounded in: §6.2-§6.3 (the supervisor is restartable; the unkillable set is {kernel} alone), Invariant 6 (services must be restartable), Invariant 11 (identity is stable; location is not), §26.7 (loud failure over hidden recovery), Invariant 12 (failures are loud, never silent).

Corrupt Not Godspeed

VI. Thou shalt not introduce shared mutable state.

Services communicate through IPC. Shared mutable state creates invisible coupling, destroys isolation, complicates recovery, and makes failure unpredictable. If multiple services require the same information, expose it through a service - not through shared memory.

Grounded in: Invariant 2 (no shared mutable memory by default), Invariant 9 (no unowned global mutable state), §2.5 (zero-copy IPC is permanently rejected for this reason).

VII. Thou shalt not introduce ambient authority.

Authority must always be explicit. A service may perform only the actions its capabilities grant. Hidden privilege eventually becomes both a security vulnerability and an architectural dependency.

There is no authority by identity, ancestry, or inheritance - only by capability.

Grounded in: Invariant 1 (no ambient authority), Invariant 3 (all authority is explicit), §7 (the capability system), §26.9 (authority must remain visible).

VIII. Thou shalt not rely upon timing for correctness. Wait for truth, not time. But ensure the truth includes failure.

Time does not prove correctness. Sleeping longer does not make a race disappear. Correctness must come from observable truth:

  • acknowledgements
  • state transitions
  • contracts
  • events
  • capabilities (and their generations)

Time may conserve CPU. It must never determine correctness.

And the truth must include failure. Waiting on the truth of success alone - the reply, the acknowledgement - is only half the discipline. If the thing you wait for dies or never comes, that truth never arrives and a pure success-wait hangs forever: a wait that cannot observe failure has quietly become an infinite wait on time. So failure is a first-class truth - a peer's death, a dead endpoint, a broken contract, a revoked capability - and you must wake on it exactly as you would on success. A caller blocked awaiting a reply must wake the instant its replier dies (ReplyDead), never hang. Only a truth that includes failure makes "wait on truth" complete.

Grounded in: §8.6 (acknowledgement is explicit - a successful send means queued, not processed; and failure is explicit - a caller blocked awaiting a reply wakes with ReplyDead when its replier dies), §7.5 (the generation check, not a delay, settles a restart race), §9.3 (yield is advisory), §22.4 (a test waits for observable output, never a fixed sleep).

IX. Thou shalt always plan for recovery, for thy service shall fail.

Failure is not exceptional. It is expected. Every service should recover cleanly without assuming a perfect world. A client whose dependency restarts must reacquire and retry, not crash.

And reacquiring is not just the endpoint. Anything the dependency's previous incarnation handed you - a connection or socket id, a handle, a cached value, a generation - is stale once it restarts, and must be re-established with the new instance or discarded. A fresh connection does not refresh what the dead one gave you; a cached view of a restarted peer's state is no longer the truth.

If recovery cannot be tested, it does not exist.

Grounded in: §14 (service lifecycle, restart, and cap rebinding), §14.3 (cascading failure is the client's responsibility), §6.2 (death is recovered, not a reboot), §22 (recovery is pinned by the chaos and identity suites).

X. Thou shalt place complexity where it belongs.

Complexity is sometimes necessary. Hidden complexity never is. Do not move complexity into the kernel because it is convenient. Do not push complexity onto users because it is easier. Place it in the layer that naturally owns it.

Good architecture is not the absence of complexity. It is complexity in the correct place.

Grounded in: §26.10 (the kernel is mechanism, not policy), §26.11 (the 30-minute whiteboard rule), §26.13 (discipline over cleverness), §26.4 (no silent complexity).

Final Admonition

These Commandments are not independent. Violate one and you eventually violate all.

Architectural corruption rarely begins with catastrophe. It begins with a single compromise:

"Just this once."

Over time, that compromise spreads in subtle and unpredictable ways until the architecture itself becomes difficult to reason about.

These Commandments were not written for style, tradition, or amusement. They were written in response to real bugs, real wedges, real failures, and real lessons learned while building Godspeed.

Treat them very seriously.

And when a compromise offers itself because the system does not yet work, know which way the trade goes:

A failing Godspeed that preserves its invariants is preferable to a working Godspeed that violates them.

This is not a love of failure. It is what a fix IS. A system that fails with its model intact is still Godspeed, and can be repaired. A system that works by breaking its model is another system wearing the name, and it has spent the only thing that made the rest of this document worth obeying.

So make it work WITHIN the model. Never widen the model to admit what is easier. And where the two truly cannot be reconciled, say so plainly and leave the gap open, for a recorded failure can be fixed by whoever comes next, and a quiet violation cannot even be found.

Grounded in: CLAUDE.md §25 (the principle that ranks the others) and §26.7 (a failure is reported, never swallowed - so a limitation that cannot be closed today is RECORDED, not papered over).

Of Borrowed Wisdom

Thou shalt read the works of others, for they have met this silicon before thee. Linux, BSD and u-boot are read here as executable datasheets, and that reading has many times been the difference between a working driver and a week of guessing.

But take from them the requirement of the DEVICE, and never the shape of THEIR HOUSE.

Both arrive in the same file, and only one of them is a fact:

  • Take the order of writes, the timing, the magic values, the error semantics, the meaning of a bit. These are properties of the hardware and are true wherever they are read.
  • Leave the ambient global, the unbounded buffer, the allocation on the hot path, the driver that lives in the kernel because that is where they put it. These are their answers to their constraints, and they are facts about nothing.

When in doubt, ask one question:

Is this a property of the device, or a property of their design?

To copy their design because they are respected is how a model rots while every single change looks justified. Where thou dost diverge from them, do not apologise - RECORD it, at the point of difference, with the reason. Silent divergence breeds bugs no one can explain; unexplained convergence breeds violations no one noticed.

Grounded in: CLAUDE.md §26.14. See also §26.6.1 - when their answer is a heap and thine cannot be, change the representation rather than the rule.

Tried by Fire

A contribution is not considered proven until it has passed through the fire.

The fire of Godspeed consists of seven complementary trials:

  1. Identity - Does it remain itself?
  2. Property - Does it preserve its invariants?
  3. Fuzz - Does unexpected input reveal hidden assumptions?
  4. Stress - Does pressure change correctness?
  5. Performance - Does it remain efficient under sustained load?
  6. Adversarial - Can deliberate attack break its guarantees?
  7. Chaos - Can it recover when the unexpected becomes reality?

Each trial has increasingly brutal variants. Passing one trial does not excuse failing another.

Grounded in: §22 - these seven are the categories of the test suite: the Identity tests and the six battle-hardening layers, each with a harsher "brutal" variant. A green check from one trial is necessary; it is never sufficient. This is Commandment II made into a gauntlet.

Blessings

Godspeed on thy journey.

  • May thy architecture remain uncorrupted.
  • May thy contracts remain true.
  • May thy services endure failure.
  • May truth be uncovered through fire.

Bankole Ogundero.