kolu
Docs

@kolu/surface-daemon reference

The code that runs inside a long-lived daemon process: its home on disk, its single-instance gate, its lifecycle, and the frozen control core a supervisor dials. It carries no @kolu/* app dependency. The client half lives in @kolu/surface-daemon-supervisor.

Entry points

Production imports use the package root. The /home and /lifetime leaves exist for code that must not compile a daemon. Mixed-version suites use ./upgrade-window.testlib, and pid-gate test seams use ./pidGate.testlib. Neither test subpath is re-exported from the production root.

SubpathWhat you import it for
@kolu/surface-daemonEverything below. The root value-re-exports daemonMain and daemonProcessMain.
@kolu/surface-daemon/homedaemonHome, resolveDaemonHome and the home path types.
@kolu/surface-daemon/lifetimeDaemonLifetime, DaemonLifetimeInfo, lifetimeInfo.
@kolu/surface-daemon/upgrade-window.testlibThe mixed-version test kit.
@kolu/surface-daemon/pidGate.testlibThe pid-gate test seams (the connect-probe override).

The repo ships raw TypeScript, so whatever a consumer imports, its tsc compiles. That is why the two leaves exist.

entrycarrieswhat it no longer compiles
@kolu/surface-daemon/homedaemonHome, resolveDaemonHome and the home path typesdaemonMain, daemonProcessMain, the process-signal tier
@kolu/surface-daemon/lifetimeDaemonLifetime, DaemonLifetimeInfo, lifetimeInfothe same

@kolu/surface-daemon/home

The home path algebra on its own, without the process tier.

  • Everything it carries is re-exported from its original home, so the barrel’s surface is unchanged and no in-repo caller moves.
  • It still value-imports getRuntimeSocketPath from @kolu/surface/unix-socket, the module that also carries the socket serve stack. The leaf drops the daemon tier, not every node dependency.

@kolu/surface-daemon/lifetime

The lifetime vocabulary on its own.

  • DaemonLifetimeInfo is the serializable projection a daemon publishes about itself, so a browser-safe vocabulary downstream satisfies-pins its wire schema to it.
  • It is re-exported from its original home too, so the barrel is unchanged.

@kolu/surface-daemon/upgrade-window.testlib

The generic mixed-version fixture: registry matchers, sweep and message, the watchdog factory, assertRecipeWired, the bidirectional previous-release harness, the process reaper, the socket wait, and pinPreviousShapeRecovery.

  • Its module graph has no workspace or external runtime dependency. Daemon filenames, state planting and the spawn guard are injected hooks, and they are required.
  • Matchers take the consumer registry as a parameter. The framework has no global registry.
  • A versionField records the discriminator but does not excuse coverage: the artifact must name a disposition test that plants version+1 and observes a typed state.
  • The fixture returns independent discriminated process, listener and state arms, so a pid cannot exist without its child and a config path cannot exist without its state root.

The frozen control core

The immutable identity and drain verb a supervisor can speak to any resident daemon, before it knows whether the versioned application surface is compatible.

ExportSubpathWhat it is
controlCoreFragment(opts).Server deps for the frozen hello and awaited drain.
controlCoreSurface · controlCoreProcedureSpec.The standalone fragment surface, and the spec seam beside it.
ControlCoreFragment.The ImplementSurfaceDeps type of that surface.
ControlCoreHelloSchema · ControlCoreHello · CONTROL_CORE_VERSION.The immutable wire vocabulary.

controlCoreFragment(opts)

The server deps that implement the immutable core.hello identity and core.drain verb.

controlCoreFragment({ stateRoot, surfaceVersion, startedAt, commit, buildId, onDrain })

// Serve these deps beside the versioned application surface. `hello` remains
// readable even when that application contract is skewed; `drain` waits for
// the daemon's own persistence/shutdown hook. `implementSurfaces` mints ONE
// flat group covering both siblings — each member at
// `surface/<key>/<member>/<verb>`, so the two cannot collide (not even on the
// three framework-reserved `system/*` members every surface carries).
const control = controlCoreFragment({
  stateRoot: home.dir,
  surfaceVersion: "1.0",
  startedAt: Date.now(),
  commit: readIdentity.navigableCommit,
  buildId: readIdentity.staleKey,
  onDrain: () => controller.abort(),
});
const { group, handlers } = implementSurfaces(
  { app: surface, control: controlCoreSurface },
  {},
  { app: deps, control },
);
  • It is served beside the versioned application surface, composed as the sibling control. The two members sit at the wire tags surface/control/core/hello and surface/control/core/drain, where nothing the application surface mints can collide with them.
  • The hello fields are fixed: stateRoot · surfaceVersion · controlCoreVersion · startedAt · commit · buildId.
  • Build id and commit are one observation. The shared reader accepts both absent, both empty (off-Nix), or both non-empty, and rejects every partial pair before convergence policy runs.
  • Both members are Effect Schema-typed. hello declares ControlCoreHelloSchema as its output and drain declares nothing at all.
  • commit and buildId are Schema.optionalKey: the key is present with a string or absent, never an explicit undefined round-tripped through null.

Refusing to drain

The wire says only drain(): void. It does not promise that every daemon is drainable.

  • A daemon whose durable state cannot survive a drain implements the verb as a refusal: its onDrain throws, as kaval’s does.
  • Such a daemon declares the supervisor capability not-drainable, which makes a policy-driven invocation unrepresentable.
  • The refusal leaves the daemon and its owned resources alive.
  • The refusal is a defect, not a member error. drain declares no error schema, so controlCoreFragment runs the hook under Effect.promise and an undeclared throw stays a defect. There is no PRECONDITION_FAILED-style code for a supervisor to narrow on.
  • Why: Why the framework takes values, not loose fields.

controlCoreSurface · controlCoreProcedureSpec

The fragment as a standalone surface (procedures: { core: … }), plus the spec seam a daemon uses when it retains extra frozen members of its own.

ControlCoreFragment

The ImplementSurfaceDeps type of controlCoreSurface, which is what controlCoreFragment satisfies.

ControlCoreHelloSchema · ControlCoreHello · CONTROL_CORE_VERSION

The immutable wire vocabulary of the hello payload.

  • CONTROL_CORE_VERSION is frozen at "1.0". It is not an application contract version: it versions the hello payload, whose six fields are byte-pinned in controlCore.test.ts.
  • The fragment does not version within a protocol epoch. A daemon from a different epoch cannot be asked anything, because its first frame is undecodable. A supervisor observes that as unspeakable-protocol, never as an incompatible version.
  • Why: What a frozen contract survives, and what it does not.

The on-disk home

Where a daemon’s files live, who may read them, and how a stale home is swept.

ExportSubpathWhat it is
daemonHome({ app, placement, instance?, socketFile?, socketOverride? }).Creates and verifies the home, and returns its paths.
resolveDaemonHome(…).The same paths as pure algebra, with no side effect.
DaemonHomePaths.The face the spine speaks.
DaemonHome · ResolvedDaemonHome · DaemonHomeOptions · ResolveDaemonHomeOptions · DaemonHomePlacement · DaemonHomeRuntimeRoot.The return types and the options types.
isPrivateOwnedDir(dir).The owner-only privacy predicate.
runtimeRegimeInForce().Which runtime drawer this process is in.
daemonSweepRegimes().The regimes a daemon sweeps at boot.
reapStaleDaemonHomes({ app, gateFile, runtimeRoots }).Removes this app’s runtime homes whose owner is gone.
SharedArtifact.One on-disk file both generations touch.

daemonHome(opts)

The one call that decides where a daemon’s files live: daemonHome({ app, placement, instance?, socketFile? }).

// Durable ⇒ state dir (never /run): a daemon supervised over ssh must outlive
// the session that spawned it; logind deletes $XDG_RUNTIME_DIR with the last
// session. Gate and socket live side by side under the home.
const home = daemonHome({ app: "fleet-top", placement: "state" });

It returns dir · gatePath · socketPath · file(name) · artifacts.

  • It creates the directory 0700 and verifies it is owner-only. A non-private directory throws.
  • Gate and socket come back side by side, so the two cannot drift apart.
  • artifacts is a pair of SharedArtifact registry entries, one for the gate and one for the socket, so a mixed-version inventory (UW2) is fed by construction.
  • kaval and padi both ride this API. Golden tests pin every derived path byte-identical to the pre-migration formula.
placementDirectory
"state"~/.local/state/<app>/ ($HOME only, ignoring $XDG_STATE_HOME) — durable across reboots
"runtime"$XDG_RUNTIME_DIR/<app>/, falling back to /tmp/<app>-$UID/ — boot-wiped

A daemon that must outlive user sessions, which includes anything supervised over ssh, takes "state". logind deletes the runtime directory with the user’s last session, leaving an orphan process whose socket and gate have vanished.

The optional arguments

  • instance (padi’s state-root digest, or a legacy port string) is the only spelling for a decorated home. The directory is <app>-<instance>/, and the gate and socket basenames keep the bare app stem (padi-<digest>/padi.pid, never padi-<digest>.pid). Do not stuff a pre-joined name into app.
  • socketFile overrides the socket basename, as kaval’s pty-host.sock does.
  • runtimeRoot (string | null, pure resolve only) lets discovery evaluate under another drawer without mutating process.env. null forces /tmp.
  • socketOverride absorbs a command-line override such as --socket into home construction, rather than sprinkling it at call sites.

What takes a home

A home is a spine primitive. daemonMain({ home }) and the supervisor’s createEndpoint({ home, connect: (socketPath) => … }) take the home and derive the gate, the socket and, by default, the self-reap anchor from it. Path strings are not passed across the consumer and framework boundary: connect receives the socket path from the framework.

Why: Why the framework takes values, not loose fields.

resolveDaemonHome(…)

The pure path algebra behind daemonHome: no mkdir, no environment mutation. Path helpers, discovery and the spine consume this.

DaemonHomePaths

The face the spine speaks: dir · gatePath · socketPath.

DaemonHome · ResolvedDaemonHome · DaemonHomeOptions · ResolveDaemonHomeOptions · DaemonHomePlacement · DaemonHomeRuntimeRoot

The return types and the options types of the two calls above.

isPrivateOwnedDir(dir)

The owner-only privacy predicate, shared with the pid gate.

runtimeRegimeInForce()

"xdg" or "tmp": the one answer to which runtime drawer this process is in. Discovery narrows its scan to it, and pathShapeRoot renders from it.

daemonSweepRegimes()

The regimes a daemon sweeps at boot: the one in force, plus the /tmp fallback, which is the one nothing wipes.

reapStaleDaemonHomes(opts)

reapStaleDaemonHomes({ app, gateFile, runtimeRoots }) removes this app’s runtime homes under runtimeRoots whose gate proves the owner is gone. It returns { removed, skipped } (StaleHomeSweep · StaleHomeSkip).

  • It keeps a live holder, a gateless home (a daemon mid-boot looks the same) and an unreadable gate.
  • It reports a root it cannot list, and never throws.
  • The roots are a parameter, never the ambient environment, so a sweep is testable without the developer’s real /tmp.

SharedArtifact

One shared on-disk file both generations touch: the inventory entry shape.

The lifecycle

The gate-to-serve-to-teardown skeleton, the pid gate under it, and the policies that decide when a daemon stops.

ExportSubpathWhat it is
daemonMain({ home, processIdentity, readProcessIdentity, … }).The gate, serve and teardown skeleton.
daemonProcessMain({ name, run }).The bin half: it owns the process exit.
claimPidGate(gatePath, socketPath, self, readProcessIdentity).The named full claim.
acquirePidGate(gatePath, self, readProcessIdentity).The atomic single-instance claim.
ProcessIdentity · ReadProcessIdentity.The start-qualified identity and its injected reader.
readGateIdentity · gatePid · gateIdentity · liveHolderFromRecord · liveHolderPid · throwIfGateUnreadable · identitiesMatch · startTimesMatch · START_TIME_TOLERANCE_US.The pid-first tolerant gate reader.
confirmHeldGate(held, …).The socket fence for a one-field holder.
isHolderLive(pid).A kill(0) liveness probe.
socketServeState(socketPath) · SOCKET_SERVE_PROBE_MS.The four-way socket probe.
stderrLogger() · Logger · DaemonExit.The logging contract and the exit record.
daemonLifetimeFromEnv(fallback) · DAEMON_BIND_PID_ENV.Reads the lifetime from the environment.
lifetimeInfo(lifetime) · DaemonLifetimeInfo.The serializable projection of a lifetime.
anchorGone(path) · DaemonShutdownReason.The proven-absent probe and the shutdown reasons.
armRuntimeFaultExit({ done, log, subject, lastRites? }) · DAEMON_RUNTIME_FAULT_MARKER.Turns a dead runtime into a non-zero exit.
DaemonSpec.faultSignal.The owned-fault stop arm.

daemonMain(opts)

The gate, serve and teardown skeleton: daemonMain({ home, … }), whose full options are { home, processIdentity, readProcessIdentity, … }.

daemonProcessMain({
  name: "fleet-top", // crash-arm narration prefix
  run: () =>
    daemonMain({
      // gate, socket, anchor — all derived from home inside the spine
      home,
      processIdentity, // injected (pid, startUnixUs) for this process
      readProcessIdentity, // injected OS fact reader; the spine only compares
      group, // the flat RPC group the runtime serves…
      handlers, // …and its tag-keyed handlers: one pair, no router
      lifetime: { kind: "forever" }, // or { kind: "idleTimeout", ms, isIdle }
      log: stderrLogger(),
      signal: controller.signal,
      onReady: ({ socketPath, pid }) =>
        process.stderr.write(`listening on ${socketPath} (pid ${pid})\n`),
    }),
});
  • It claims the single-instance gate, serves the surface’s { group, handlers } over the unix socket, waits for the lifetime to end or for the anchor to be proven gone, then closes the socket and releases the gate.
  • Gate and socket come from home. The self-reap anchor defaults to home.dir. Override it when the on-disk identity is not the rendezvous home, as padi’s state-root is.
  • Identity is injected, never defaulted.
  • It resolves a DaemonExit and never calls process.exit, so the whole lifecycle is drivable in-process from a test.

daemonProcessMain({ name, run })

The bin half, for a process that exists to be the daemon. It runs run() (daemonMain, or a wrapper around it) to completion and then owns the process exit.

  • The exit code is classified from the DaemonExit: already-running and shutdown give 0, serve-failed gives 1.
  • A rejection is narrated as name: message and exits 1. The crash arm is swallow-proof, so a failing stderr write cannot block the exit.
  • Call it as the bin’s last statement. It returns synchronously and owns the rest of the process’s life.
  • Without it, a live resource or timer the bin never tied to the daemon’s lifetime keeps the event loop alive after the tenure ends, leaving an invisible lingering daemon.

The sibling reaper

When the process is boundToPid (KOLU_DAEMON_BIND_PID set), daemonProcessMain also arms a sibling that does not share this event loop.

  • The in-process boundToPid poll and the SIGTERM handler both live on the daemon’s loop. A wedged daemon (fd exhaustion, SIGSTOP) can neither poll nor honour the signal.
  • The sibling polls the bind pid on the same cadence, waits a grace so the clean pid-gone path can finish its release, then SIGKILLs a process that is still up.
  • It does not SIGTERM. That handler is already gone on the clean path, and TERM does not help a wedged loop.
  • It is armed only here, never from in-process daemonMain tests, which share vitest’s pid. It is disarmed on the clean-exit and crash arms.

claimPidGate(gatePath, socketPath, self, readProcessIdentity)

The named full claim: acquirePidGate, then confirmHeldGate when the gate is held. Composition roots use this, rather than the two steps by convention.

acquirePidGate(gatePath, self, readProcessIdentity)

The atomic single-instance claim, via link(2). It writes ${pid}\t${startUnixUs}\n and returns { kind: "acquired", release }, { kind: "held", pid }, or { kind: "dir-not-private", dir }.

ProcessIdentity · ReadProcessIdentity

The canonical start-qualified identity ({ pid, startUnixUs }) and the sync injected reader of that operating-system fact for the daemon claim path. The spine never imports osfacts.

  • The reader is sync because a synchronous gate claim must not reorder against the boot side effects it guards.
  • The supervisor’s awaitable inject is ReadProcessIdentityAsync on @kolu/surface-daemon-supervisor, beside EndpointSpec, and it is an Effect.

The gate reader

readGateIdentity · gatePid · gateIdentity · liveHolderFromRecord · liveHolderPid · throwIfGateUnreadable · identitiesMatch · startTimesMatch · START_TIME_TOLERANCE_US are the pid-first tolerant reader of a gate file.

  • The pid is read with a legacy parseInt (leading digits). The start time is read only from an exact pid\tstart…, and matches within ±2 s.
  • Writers emit ${pid}\t${startUnixUs}\n.
  • liveHolderFromRecord takes an already-read observation. liveHolderPid reads once, then delegates.

The read outcome has a three-way law, and it is exhaustive. Never collapse a case into free or stale.

OutcomeVerdict
absentfree
malformedreap
unreadable (EACCES/EIO)throw

confirmHeldGate(held, …)

The socket fence for a one-field (legacy) holder, and nothing more. One gate observation drives both liveness and generation.

  • A dead socket reclaims.
  • An absent or indeterminate socket waits.
  • A two-field match skips the fence, because identity is truth.

isHolderLive(pid)

A kill(0) liveness probe, for one-field holders and cheap checks.

socketServeState(socketPath) · SOCKET_SERVE_PROBE_MS

The four-way socket probe (serving · dead · absent · indeterminate) that the one-field reclaim fence uses.

  • SOCKET_SERVE_PROBE_MS is a latency ceiling only. A timeout reports indeterminate and never authorizes a reclaim.
  • A non-ENOENT lstat failure throws, so the probe fails loud.

stderrLogger() · Logger · DaemonExit

The structural logging contract, and the exit record daemonMain resolves. The classification of that record into an exit code lives inside daemonProcessMain.

daemonLifetimeFromEnv(fallback) · DAEMON_BIND_PID_ENV

Resolves the lifetime from DAEMON_BIND_PID_ENV, which is KOLU_DAEMON_BIND_PID.

  • A valid positive-integer pid selects boundToPid. There is no liveness check, so an already-dead pid still selects it and then exits at once.
  • True absence of the variable selects fallback. A production daemon cannot be weakened: only a harness or smoke run opts a spawned daemon into dying with it.
  • A set-but-malformed value throws, and never degrades to fallback. That covers the empty string (a broken expansion, distinct from unset), non-canonical decimal, fractional, and out of pid_t range.
  • A boundToPid shutdown resolves { kind: "shutdown", reason: "pid-gone" }, exit code 0. Pid reuse inside the poll window is a documented residual.

The three lifetimes

lifetime is the policy that distinguishes tenants: three constructors, rather than forever plus flags.

lifetimeShuts down whenTenant
{ kind: "forever" }a signal or external abortkaval / padi in production
{ kind: "idleTimeout", ms, isIdle }ms of continuous idlenessodu serve
{ kind: "boundToPid", pid, pollMs? }the watched pid is gone (in-process poll kill(pid, 0))a test/smoke-spawned kaval/padi — dies with its run
  • The table lists each lifetime’s own trigger. Every lifetime is additionally subject to the anchor self-reap.
  • pollMs? is a test-only seam, the liveness-poll interval. Production omits it and uses the fixed two-second PID_WATCH_POLL_MS.
  • The pid must be a single-process pid, a positive integer in pid_t range. An invalid value throws at consumption, rather than being reclassified into a clean shutdown.
  • Under boundToPid, daemonProcessMain also arms the sibling reaper. Constructing the lifetime object is not what arms it.

lifetimeInfo(lifetime) · DaemonLifetimeInfo

Projects a live DaemonLifetime to a serializable DaemonLifetimeInfo, so a daemon can publish which lifetime it is running under.

  • The shape is { kind: "forever" } | { kind: "idleTimeout"; ms } | { kind: "boundToPid"; pid }: the three kinds with the non-wire members dropped, which are idleTimeout’s isIdle and boundToPid’s pollMs.
  • kaval carries it on its system.version handshake, and padi on its identity cell.
  • kolu’s Kaval and Padi info dialogs each render it as a lifetime row: forever in production, bound to run pid N under a test or smoke run.

anchorGone(path) · DaemonShutdownReason

The ENOENT-only proven-absent probe both ends of the anchor invariant share, and the full shutdown-reason union: signal · abort · idle · pid-gone · anchor-gone · runtime-fault.

Every shutdown reason exits 0 except runtime-fault, which exits 1.

armRuntimeFaultExit(opts) · DAEMON_RUNTIME_FAULT_MARKER

armRuntimeFaultExit({ done, log, subject, lastRites? }) observes a served runtime’s done and hands back the AbortSignal you pass as DaemonSpec.faultSignal. Both kaval and padi wire armRuntimeFaultExit.

  • A rejection is fatal. It logs the whole error, marked with DAEMON_RUNTIME_FAULT_MARKER and with the stack intact.
  • It then runs the daemon’s last rites, for which padi captures its final session. Last rites that throw are logged, and the exit still happens.
  • The tenure ends as reason: "runtime-fault": a non-zero exit through the ordinary teardown, so the listener closes and the gate releases before the process ends.
  • The supervisor’s only channel for “that was a crash, not a stop” is the exit code, which is why an orderly teardown still scores exit 1.
  • Why: Why a runtime fault kills the process.

DaemonSpec.faultSignal

The owned-fault stop arm, separate from signal. signal is a graceful stop (exit 0) and faultSignal is structural wiring death (exit non-zero).

Omitting it leaves a runtime fault nowhere to go, which is the zombie class: process alive, gate held, socket answering, runtime dead.

Why: Why a runtime fault kills the process.

The anchor self-reap

anchor is the thunk a daemon reaps itself by once its on-disk identity is proven gone. Gate, socket and anchor all ride the home: it defaults to () => home.dir.

  • Override it only when the on-disk identity is not the rendezvous home. kaval’s anchor is its padi’s state-root, learned from a manifest, and padi’s is its own state-root.
  • The thunk is armed under every lifetime. It is an independent trigger, not a lifetime arm.
  • The directory must be proven gone for two consecutive polls, 5s apart in production. anchorPollMs? is the test seam.
  • The daemon then reaps itself through the normal teardown: socket unlinked, gate released, { kind: "shutdown", reason: "anchor-gone" }, exit code 0. Without it, a git worktree remove leaves a zombie holding its sockets and RSS.
  • Proof is ENOENT-only (anchorGone(path)). Any other lstat failure (EACCES, EIO, ENOTDIR) means the daemon could not read whether the anchor exists, and never counts toward a reap.
  • The thunk is re-evaluated every tick, so an anchor learned after boot self-corrects. kaval reads the state-root manifest its padi writes around kaval’s own boot.
  • () => undefined is the spelling for a daemon with no on-disk identity. It is never reaped. Omitting anchor is the normal case, and defaults to the home.

Serving the surface

The listener is serveOverUnixSocket({ socketPath, group, handlers, log }), from @kolu/surface/unix-socket. That is a @kolu/surface subpath, not one of this package’s.

  • It never crashes. Every failure mode resolves to a no-op listener with a machine-readable outcome.
  • daemonMain passes its own log through, so the listener’s lifetime (bound, post-listen fault, closed) lands in the daemon’s journal beside its boot and teardown narration.
outcome.kindMeaning
listeningbound and serving
dir-not-private · not-a-socket · bind-failedcould not bind
already-served · probe-failedanother holder is (or may be) live

Fronting over stdio

Adopt a durable daemon from a short-lived front process, so a remote (ssh) session survives the link.

ExportSubpathWhat it is
frontDaemonOverStdio(opts).Adopts or spawns the daemon, and relays this process’s stdio to it.
reExecAsDetachedDaemon({ stripArgs, stderrLog? }).Re-execs this binary as the detached daemon.

frontDaemonOverStdio(opts)

The front half. It adopts or spawns the gate-held daemon and raw-byte-relays this process’s stdio onto its socket. It is the durable counterpart to serveOverStdio.

return frontDaemonOverStdio({
  socketPath: home.socketPath,
  spawnDaemon: () => reExecAsDetachedDaemon({ stripArgs: ["--stdio"] }),
  log: (msg) => process.stderr.write(`--stdio: ${msg}\n`),
});
  • It relays with node:net only, and imports no surface, which keeps the daemon closure contract-blind.
  • That blindness is legal because the stdio leg and the socket leg are byte-identical ndjson. packages/surface/src/links/byteSplice.test.ts proves it on captured raw bytes in both directions, including that nothing on the wire is non-JSON binary.

reExecAsDetachedDaemon({ stripArgs, stderrLog? })

Re-execs this binary, minus the front flag, as a detached and unref’d process, so it survives the SIGHUP that drops the link.

Baked identity

readBakedIdentity(prefix) reads a Nix-baked environment pair (<PREFIX>_BUILD_ID / <PREFIX>_COMMIT_HASH) into { staleKey, navigableCommit }.

  • Off Nix, with both variables absent, it returns empty strings rather than inventing an identity.
  • The pair is joint: both variables must hold non-empty values, or both must be absent. A half-baked or explicitly empty baked identity throws at daemon boot, because a build id without its knowable commit is contradictory.
  • How to produce the pair: How to bake an identity.

The two convergence axes

contractIsNewer and contractIsCompatible (ordered) and buildsMatch (match-only, no ordering) live in this package, and the supervisor re-exports them. They are daemon-domain vocabulary, even though the supervisor depends on @kolu/surface to dial the frozen core. Their use is in How to recycle and upgrade a daemon.

Nix recipes

The package’s nix/ directory is public surface too, the build-time half of what readBakedIdentity reads back. Each file is a function of { lib }: import "${kolu}/packages/surface-daemon/nix/<file>.nix" { inherit lib; }.

RecipeFileWhat it is
mkDaemonIdentitynix/daemon-identity.nixHashes a daemon’s behaviour into a build id, and the args that bake it.
mkWorkspaceClosurenix/workspace-closure.nixDerives what to hash from the dependencies graph.
mkProvenAgentSourcenix/agent-source.nixAssembles a remote-agent source tree and proves it.

All of it is pure evaluation, with no import-from-derivation, so nix flake check forces every output without realising a build mid-eval. The how-to is How to bake an identity.

mkDaemonIdentity — nix/daemon-identity.nix

mkDaemonIdentity { name, prefix, root, behavioralFileset, pinnedSources ? { }, commitHash, override ? null } → { buildId, bakeArgs }.

ArgRole
namethe daemon’s name, used in this recipe’s error messages
prefixits identity-env namespace ("KAVAL", "PADI"), the <PREFIX> that readBakedIdentity reads
rootthe lib.fileset.toSource root; must be a common ancestor of behavioralFileset
behavioralFilesetwhat counts as this daemon’s behaviour, which is the consumer’s own policy decision
pinnedSourcesbehavioural members that are pins, not files: name → store path
commitHashthe navigable git ref this build was made from; "" throws
overridetest-only: force buildId instead of hashing (build-skew arms)
ReturnValue
buildId64-char sha256 of the fileset.toSource store path, plus one sorted <name>=<store path> line per pinnedSources entry
bakeArgsthe --set <PREFIX>_BUILD_ID … --set <PREFIX>_COMMIT_HASH … string to splice into a makeWrapper invocation
  • Every pinnedSources value must be a string under builtins.storeDir. The assert names the offending attrs.
  • bakeArgs emits the pair together, so the joint invariant cannot be half-baked.
  • The buildId is platform-independent: it hashes source, never the runtime engine, so a cross-platform comparison is not a false mismatch.
  • With pinnedSources = { } the id is hashString "sha256" "${src}", which is byte-identical to the unpinned formula, so a workspace-only consumer’s live daemon ids do not move.

mkWorkspaceClosure — nix/workspace-closure.nix

mkWorkspaceClosure { members, pinned ? [ ], mustCover ? [ ] } derives what the identity should hash from the package.json dependencies graph, instead of a hand-kept file list that can silently drift. The file also exports defaultIsHashedSource at its top level.

ArgRole
memberspackage name → package dir, one path literal per local member and one store-path string per pinned member
pinnedthe member names that are pins, declared rather than inferred from how the value is spelled
mustCovername prefixes that must never resolve outside members ([ "@kolu/" ])
ReturnValue
membersthe checked map, with the same keys, which the two functions below read
depClosure { entries, stop ? [ ] }the member names reachable from entries over dependencies edges whose target is a member
identityInputs { entries, stableLeaves ? [ ], isHashedSource ? defaultIsHashedSource }the same closure rendered as mkDaemonIdentity’s behavioralFileset and pinnedSources
  • depClosure subtracts each stop entry and everything reachable only through it.
  • identityInputs renders behavioralFileset as each local member’s filtered src plus its package.json, and pinnedSources as the pinned members’ store paths. isHashedSource defaults to real .ts and .tsx, dropping .test.ts · .test.tsx · .test-d.ts · .testlib.ts.
  • mustCover is the by-name tripwire a pinned consumer needs, having no workspace: protocol to give a stale map away.
  • devDependencies are not followed, because they never ship behaviour. The residual failure direction is over-inclusion (one extra id flip), never a silent escape.

Every mistake is a loud eval failure:

FailureMessage names
a pinned name that is not a members keythe stale names
a member whose value shape disagrees with its declared kind — a path where a pin string belongs, or a string where a local path belongsthe member, and which declaration to fix
a members key that disagrees with the package’s own namethe key, the manifest name, the dir
a workspace: (or mustCover-matching) edge whose target is not a memberthe importer, the target, and the prefix that matched
a stop / stableLeaves entry that is not in the closurethe stale entries

mkProvenAgentSource — nix/agent-source.nix

The third recipe in the same directory, unrelated to identity. It assembles a remote-agent source tree and proves an agent evaluates from it before the path reaches any wrapper. The file’s own header carries the prove/expose rule.

Arguments: { root, fileset, pkgs, commitHash, agents, flakeNix, closureIndex, pusher? }.

  • The baked tree carries flake.nix, commit-hash and binary-cache.json.
  • binary-cache.json is { substituters, trustedPublicKeys, index }. The caches are derived from flakeNix’s own nixConfig.
  • index comes from closureIndex, which is { repo, branch } or an explicit null. The branch is a GitHub branch the publish-closure action writes <commitHash>/<system>/<attr>.json to, and rawBase is derived.
  • closureIndex is required, with no default. A malformed one fails the binder’s eval.
  • @kolu/surface-remote reads it as readBakedDeclaration(…).index, with rev taken from commit-hash. provisionAgent looks the binder’s own build up there before staging anything (Publish your daemon content-addressed).

pusher

pusher (optional, default null) says how the declaration’s first substituter is pushed. It is emitted as a pusher field only when given, so null bakes a declaration byte-identical to one from a tree that never set it.

ValueMeaning
{ kind = "attic"; }the publisher’s attic path, spelled out
{ kind = "odu"; }the substituter is an odu cache bucket
  • An odu bucket states its own push origin and bucket in its nix-cache-info (Odu-Origin, Odu-Bucket), which odu cache push --cache <substituter> reads. No address is spelled here, so none can drift.
  • Any other shape fails the binder’s eval: an unknown kind, an extra key, or the retired bucket or origin.