The Single-Writer Kernel
Where can a rule be made real?
One writer orders changes to a local database; the chapter specifies which failures that record can survive.
Six agents may agree about a file and still overwrite one another. A log can report the collision after the fact; only a mediated writer can refuse the second effect before it lands.
This chapter identifies that local writer, separates preventable rules from detect-only claims, and states the work-unit invariants that every later institution assumes.
We model an agent-coordination system as a four-layer stack, each layer serving a different whom.
settlement and reputation
summaries linked to evidence
permissions and commitments
ordered writes and records
Figure 1.1 · Adapted from the published stack. Read upward from L0. Higher layers depend on the records beneath them, but introduce their own assumptions. Source, p. 75
Substrate (the machine). A single always-on daemon over one local database: durable storage and serialized mutation. This chapter’s core.
Coordination (the agents). The protocol agents speak over the substrate: ownership claims, a message bus, stigmergic markers, obligations, and policy enforcement. This chapter specifies the implemented half of it.
Legibility (the operator). The human-facing view that renders the swarm intelligible. Treated in an accompanying chapter (The Legible Swarm).
Economy (the market between operators). The cross-machine market in which operators trade work and reputation. Treated in an accompanying chapter (The Harbor Economy).
Later chapters depend on this kernel in different ways. The operator’s view reads its claims, bus, and policy monitor. Durable agent identity requires its continuity records. The settlement ledger adds tables under the same writer, while cross-machine transfer uses its authorization chain. A fault in these records can therefore affect supervision, attribution, or settlement; each guarantee below states the conditions it needs.
The kernel is a single-writer transactional reference monitor over a local SQLite/WAL database — the one process that mediates contended resources, and the one place where “true” is decided rather than asserted.
The two guarantees require different qualifications:
- Durability (with an edge): a write that returned success is durable across the death of any agent — and, we will be careful, across the death of the daemon process, though not unconditionally across power loss.
- Mediation (with a correction): a state the kernel regiments cannot come to exist; a state the kernel merely enforces is detected and compensated within a bounded window. These are different guarantees and we will never conflate them.
A systems paper that mixes “we proved this” with “we hope to build this” is unfalsifiable. So every consequential claim in this chapter carries an explicit maturity grade on a four-point scale, plus two refinements for fault classes and interception points.
The grade is a property of the claim, not a marketing adjective: it says how far the claim is from a verified, running artifact.
| Grade | Meaning |
|---|---|
| implemented | Realized, exercised, and true under the production runtime. |
| partial | Realized but partial: holds under a narrower condition than the prose might invite, or detects rather than prevents. |
| specified | A concrete design exists, but no running artifact realizes it. |
| proposed | Named as a direction; no design yet. |
| I1a / I1b | Durability split by fault class: I1a (process-crash) is implemented; I1b (power-loss) is not guaranteed under the default WAL configuration. A claim that conflates fault classes cannot carry one grade. |
| regimented / enforced | Prohibition split by interception point: regimented = rejected pre-commit, truly unreachable (a uniqueness constraint / boot-admission gate); enforced = detected post-commit, halted or compensated within a bounded window (the policy monitor). “Physically unreachable” is reserved for the regimented set. |
The grades are not decoration. The two most consequential corrections in this chapter — the durability split and the regimentation/detection split — are exactly the places where a single optimistic grade would let the kernel’s foundational promise be read as stronger than the artifact delivers.
When a system claims “the database survives every agent’s death,” a reader hears “power-loss durable.” It is not, by default.
Definition 1.3.1
All state-mutating operations route through a single daemon process holding one SQLite write connection. Concurrency among the many clients (command-line invocations, agents over the message transports, background workers) is resolved by the daemon’s request queue; the SQLite file lock is the backstop that preserves correctness if the discipline is ever violated by a second writer (for example a stray direct write), not the primary serialization mechanism.
“Single-writer” is an architectural discipline (everything goes through the daemon), backstopped — not replaced — by SQLite’s file lock. This distinction matters: SQLite permits multiple writer connections (it serializes them, it does not reject them), so the property holds because of where writes are routed, not because the database forbids a second writer.
The standing risk is therefore a second copy of the daemon coming up against the same file — which is why the substrate also runs self-checks that detect a divergent or stale second instance (§1.9).