Daemon invariants
The rules the daemon packages hold. Each one is enforced in code or by the type system. The reasoning behind them is in The daemon spine.
Boundary
Which half of the spine owns which code, and what that split buys you.
| Rule | What it says |
|---|---|
| Binary-only | Only daemon binary code lives in @kolu/surface-daemon. |
| Client-only | Only supervising code lives in @kolu/surface-daemon-supervisor. |
| The package boundary is the hash boundary | A supervisor change cannot change what a daemon restart loads. |
Binary-only
Only daemon binary code (serve and front) lives in @kolu/surface-daemon.
Client-only
Only supervising code lives in @kolu/surface-daemon-supervisor. It runs in
the client, never the daemon, so it is never a staleKey root.
The package boundary is the hash boundary
A change to the supervisor cannot change what a daemon restart would load. That is the daemon half’s job alone.
Lifecycle
How a daemon claims its scope, shuts down, and gets reaped.
| Rule | What it says |
|---|---|
| Single-instance | A second daemon for the same scope exits 0. |
| Idempotent adopt | A racing second claim is a clean no-op. |
| Teardown ordering | Shutdown always runs the same seven stages, in order. |
No process.exit in the skeleton | The value core returns DaemonExit; only the bin half exits. |
The lingering-daemon state is unspellable in a daemonProcessMain bin | A finished daemon’s process ends, whatever is still live. |
| A wedged bound-to-pid daemon still dies | A sibling off the event loop kills a daemon whose bind pid is gone. |
| Every daemon declares its anchor | DaemonSpec.anchor is required, and the spine reaps on it. |
| Reaping requires proof | Only a repeated ENOENT proves an anchor gone. |
| Serves without asking | The daemon holds no env or spawn policy. |
| A route set is one set | Advertised group and bound handlers are equal at boot. |
| Frozen within an epoch | The control-core fragment never versions inside a protocol epoch. |
| A refusal the wire did not declare is a defect | An undeclared refusal is an Effect.die, not a member failure. |
Single-instance
acquirePidGate is an atomic link(2) claim. If the gate is held, the
process exits 0, because another live daemon already serves this scope.
Idempotent adopt
The adopt-or-spawn poll is idempotent under the daemon’s own pid-gate, so a racing second claim is a clean no-op.
Teardown ordering
Shutdown always runs in this order:
- stop accepting;
- disconnect established peers;
- remove the socket file (the listener
close()); - release the gate;
- return
DaemonExit; - release the wrapper’s resources;
- exit.
daemonProcessMainruns the exit strictly after everything inside itsrun()promise, so the exit cannot preempt a release stage.- A shutting-down daemon leaves no still-connected clients being served by a closed socket.
No process.exit in the skeleton
daemonMain (the value core) returns a DaemonExit and never exits, so the
whole lifecycle stays drivable in-process from a test.
- Process ownership lives in
daemonProcessMain, the bin half, and nowhere else. - The socket
close()is idempotent and safe to call from aprocess.on("exit")handler.
The lingering-daemon state is unspellable in a daemonProcessMain bin
A bin that adopts daemonProcessMain cannot forget the exit or the crash arm.
Once its run() settles (the tenure ended, resources released) the process
ends.
- A live resource or timer cannot keep a finished daemon alive.
- A
run()that never settles is a different state: the daemon is not finished.
A wedged bound-to-pid daemon still dies
daemonProcessMain arms a sibling that does not share the daemon’s event loop.
- When
KOLU_DAEMON_BIND_PIDis set, the sibling polls the bind pid, waits a grace for the cleanpid-gonepath, then SIGKILLs if the daemon is still up. - It does not SIGTERM, because that handler is already gone on the clean path.
- In-process
daemonMaintests never arm it: they share the runner’s pid.
Every daemon declares its anchor
DaemonSpec.anchor is required, so a daemon author must answer “which
directory’s deletion makes me garbage?” to compile.
- The spine polls the anchor under every lifetime and reaps the daemon
(
anchor-gone, exit 0) once it is proven gone, so agit worktree removecannot strand a daemon forever. - A daemon with genuinely no on-disk identity says so visibly
(
() => undefined). There is no opt-out knob.
Reaping requires proof
Only ENOENT counts as “the anchor is gone” (anchorGone), and only after two
consecutive polls.
- An unreadable path (EACCES, EIO, ENOTDIR) is “I could not read whether it exists”, which is the opposite of proof.
- A single miss could be a transient unmount. Neither case ever reaps.
- The supervisor side (kolu-server’s padi binder) shares the same predicate, so the two ends cannot drift on what “gone” means.
Serves without asking
The daemon serves the { group, handlers } it is handed and asks no questions.
No env or spawn policy lives in it.
A route set is one set
The group a daemon advertises and the handlers it binds are asserted equal at boot. An advertised-but-unanswered tag and an answered-but-unadvertised one are both crashes, never a runtime 404.
Frozen within an epoch
The control-core fragment never versions inside a protocol epoch.
CONTROL_CORE_VERSIONversions the payload, and the payload’s six fields are byte-pinned. A value carried inside the frame cannot describe a break in the frame itself.- A peer from a previous epoch is observed as
unspeakable-protocol, never as an incompatible version. controlCore.ts’s header is the source of truth for this doctrine.- Why: What a frozen contract survives, and what it does not.
A refusal the wire did not declare is a defect
core.drain declares no error schema, so a not-drainable daemon’s refusal is an
Effect.die, not a member failure. A supervisor cannot narrow on it and handle
it: the daemon is not busy, it is not drainable.
Identity and versioning
What a supervisor may conclude about the daemon it found, and from what evidence.
| Rule | What it says |
|---|---|
| Version-agnostic control core | Identity is read before the versioned handshake. |
| One probe assembly authority | probeDaemonIdentityFrom assembles every convergence probe. |
| Link loss is not exit | A closed transport alone never proves the process exited. |
| Contracts are ordered | Contract versions compare as newer and older. |
| Builds are match-only | Build ids compare as the same, or not. |
| Honest absence | Identity is both fields or neither, never invented. |
| A missing frozen route is not a missing daemon | null means an absent listener, nothing else. |
| Not-drainable stays alive | A refused drain cannot exit the daemon. |
| A proven skew is named, never collapsed | A contract skew reports incompatible, with both versions. |
| An unspeakable peer is a third observation, not a skew | A previous-epoch peer is its own observation, at two triggers. |
| An observation may only act on a daemon proven ours | Two attestations turn the transport fact into a verdict. |
| The disposition is takeover, for every policy | A corroborated unspeakable peer is stopped and replaced. |
Version-agnostic control core
Identity is read over a version-agnostic channel, before the versioned handshake, so it stays reachable at a skew.
One probe assembly authority
probeDaemonIdentityFrom turns an already-dialled control-core client plus its
exit oracle into the complete convergence probe.
- The socket-path
probeDaemonIdentitydelegates to it. - Transports do not reconstruct identity or drain fields themselves.
Link loss is not exit
A connector’s exit oracle must prove the daemon process exited. A closed
transport alone never becomes the stronger ClosedInfo.kind === "exit" fact.
Contracts are ordered
Contract versions are ordered. contractIsCompatible and contractIsNewer
reuse @kolu/surface’s predicate.
Builds are match-only
Build ids are match-only, with no ordering exported. Store hashes do not order.
Honest absence
readBakedIdentity returns empty strings only when both identity variables are
absent off-nix, rather than inventing an identity.
- The build id and commit are one fact: both must be non-empty, or both variables absent. A half-pair or an explicitly empty baked value crashes at daemon boot.
readControlCoreHelloenforces the same joint fact on observations: both absent, both empty, or both non-empty.- A partial frozen identity is rejected at the shared reader, before convergence can make a decision.
A missing frozen route is not a missing daemon
null means only an honest absent listener. During a named upgrade window, a
live pre-fragment daemon’s structured NOT_FOUND is an older-build observation.
Every other hello failure throws.
Not-drainable stays alive
The frozen wire retains drain(): void, but a not-drainable daemon refuses a
direct call with a typed application error. Its policy cannot invoke drain, and
the refusal cannot exit the daemon or touch its owned resources.
A proven skew is named, never collapsed
The endpoint flips failures to dead before they throw, with one carve-out: a
connect rejection that is a DaemonContractSkewError reports incompatible.
- The report carries
daemonVersionandrequiredVersionoff the error’s own fields. - It is never
dead(a fresh spawn that skews) and neverdegraded(a refuse-policy survivor that skews). - A restart hold does not coerce it. The skew is the restart’s terminal verdict.
- Consumers derive affordances from the state sum, so no restart verb can be offered against a daemon a restart provably cannot fix.
An unspeakable peer is a third observation, not a skew
A daemon from a previous protocol epoch cannot report a version at all, so convergence carries a third narrowly-typed observation beside “identity” and “absent”.
- It is raised at exactly two triggers: the peer speaks first in a framing we
cannot parse (
undecodable-frame), or it accepts the connection and says nothing forUNSPEAKABLE_SILENCE_MS(silence). - The
silencetrigger is what the previous epoch’s server looks like while it waits for its own hello. - Every other dial failure stays an ordinary
probe-failed, andprobe-failedis never widened to absorb one.
An observation may only act on a daemon proven ours
The unspeakable fact becomes an unspeakable verdict only under two attestations: the gate file at this rendezvous is ours, and the pid it names passed the holder identity law.
- Uncorroborated, it is
probe-failed. - A foreign socket-squatter keeps the
SocketSquatterForeignErrorpath, so no disposition can put a SIGTERM near a process we have not proven is our own daemon. - That split is what lets the
silencetrigger exist at all: a merely slow peer stops at the fact.
The disposition is takeover, for every policy
A corroborated unspeakable peer is taken over, in four steps:
- re-attest that our gate still names the classified pid;
SIGTERMit, so its own in-process shutdown runs (the act a drain verb would have requested);- wait, and escalate to
SIGKILLonly past a stated deadline; - spawn a daemon of this epoch, which seeds from disk.
- The contract-skew policy is not consulted: an undecodable wire is not a skew, and the drain verb does not exist on it.
- The one refusal left is the residual where the gate stopped naming the
classified pid before the kill. Nothing is signalled, and the
unconvergedanomaly carries theunspeakable-protocolcause withsocketPath,gatePathand that pid as data.
Mistakes the kit makes impossible
The supervisor’s convergence kit makes three classes of mistake unrepresentable rather than merely discouraged:
- A drainless daemon cannot declare a drain policy. The
drain-and-replacepolicy arms exist only for a drain-capable handshake; a drainless daemon (kaval) declaring one is a compile error. - Contracts order, builds do not. The ordering predicate exists for contract versions and is simply absent for build ids: you cannot ask whether one build “is newer than” another.
- Identity precedes the handshake. The control-core identity is probed pre-connect, so a version skew can never hide it.