@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.
| Subpath | What you import it for |
|---|---|
@kolu/surface-daemon | Everything below. The root value-re-exports daemonMain and daemonProcessMain. |
@kolu/surface-daemon/home | daemonHome, resolveDaemonHome and the home path types. |
@kolu/surface-daemon/lifetime | DaemonLifetime, DaemonLifetimeInfo, lifetimeInfo. |
@kolu/surface-daemon/upgrade-window.testlib | The mixed-version test kit. |
@kolu/surface-daemon/pidGate.testlib | The 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.
| entry | carries | what it no longer compiles |
|---|---|---|
@kolu/surface-daemon/home | daemonHome, resolveDaemonHome and the home path types | daemonMain, daemonProcessMain, the process-signal tier |
@kolu/surface-daemon/lifetime | DaemonLifetime, DaemonLifetimeInfo, lifetimeInfo | the 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
getRuntimeSocketPathfrom@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.
DaemonLifetimeInfois the serializable projection a daemon publishes about itself, so a browser-safe vocabulary downstreamsatisfies-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
versionFieldrecords 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,listenerandstatearms, 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.
| Export | Subpath | What 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 tagssurface/control/core/helloandsurface/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.
hellodeclaresControlCoreHelloSchemaas its output anddraindeclares nothing at all. commitandbuildIdareSchema.optionalKey: the key is present with a string or absent, never an explicitundefinedround-tripped throughnull.
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
onDrainthrows, 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.
draindeclares no error schema, socontrolCoreFragmentruns the hook underEffect.promiseand an undeclared throw stays a defect. There is noPRECONDITION_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_VERSIONis frozen at"1.0". It is not an application contract version: it versions the hello payload, whose six fields are byte-pinned incontrolCore.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.
| Export | Subpath | What 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
0700and verifies it is owner-only. A non-private directory throws. - Gate and socket come back side by side, so the two cannot drift apart.
artifactsis a pair ofSharedArtifactregistry 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.
placement | Directory |
|---|---|
"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, neverpadi-<digest>.pid). Do not stuff a pre-joined name intoapp.socketFileoverrides the socket basename, as kaval’spty-host.sockdoes.runtimeRoot(string | null, pure resolve only) lets discovery evaluate under another drawer without mutatingprocess.env.nullforces/tmp.socketOverrideabsorbs a command-line override such as--socketinto 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.
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 tohome.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
DaemonExitand never callsprocess.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-runningandshutdowngive0,serve-failedgives1. - A rejection is narrated as
name: messageand exits1. 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
boundToPidpoll 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-gonepath 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
daemonMaintests, 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
ReadProcessIdentityAsyncon@kolu/surface-daemon-supervisor, besideEndpointSpec, 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 exactpid\tstart…, and matches within ±2 s. - Writers emit
${pid}\t${startUnixUs}\n. liveHolderFromRecordtakes an already-read observation.liveHolderPidreads once, then delegates.
The read outcome has a three-way law, and it is exhaustive. Never collapse a case into free or stale.
| Outcome | Verdict |
|---|---|
absent | free |
malformed | reap |
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_MSis a latency ceiling only. A timeout reportsindeterminateand never authorizes a reclaim.- A non-ENOENT
lstatfailure 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 ofpid_trange. - A
boundToPidshutdown 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.
lifetime | Shuts down when | Tenant |
|---|---|---|
{ kind: "forever" } | a signal or external abort | kaval / padi in production |
{ kind: "idleTimeout", ms, isIdle } | ms of continuous idleness | odu 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-secondPID_WATCH_POLL_MS.- The
pidmust be a single-process pid, a positive integer inpid_trange. An invalid value throws at consumption, rather than being reclassified into a clean shutdown. - Under
boundToPid,daemonProcessMainalso 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 areidleTimeout’sisIdleandboundToPid’spollMs. - kaval carries it on its
system.versionhandshake, and padi on itsidentitycell. - kolu’s Kaval and Padi info dialogs each render it as a lifetime row:
foreverin production,bound to run pid Nunder 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_MARKERand 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, agit worktree removeleaves a zombie holding its sockets and RSS. - Proof is ENOENT-only (
anchorGone(path)). Any otherlstatfailure (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-rootmanifest its padi writes around kaval’s own boot. () => undefinedis the spelling for a daemon with no on-disk identity. It is never reaped. Omittinganchoris 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. daemonMainpasses its ownlogthrough, so the listener’s lifetime (bound, post-listen fault, closed) lands in the daemon’s journal beside its boot and teardown narration.
outcome.kind | Meaning |
|---|---|
listening | bound and serving |
dir-not-private · not-a-socket · bind-failed | could not bind |
already-served · probe-failed | another 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.
| Export | Subpath | What 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:netonly, 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.tsproves 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; }.
| Recipe | File | What it is |
|---|---|---|
mkDaemonIdentity | nix/daemon-identity.nix | Hashes a daemon’s behaviour into a build id, and the args that bake it. |
mkWorkspaceClosure | nix/workspace-closure.nix | Derives what to hash from the dependencies graph. |
mkProvenAgentSource | nix/agent-source.nix | Assembles 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 }.
| Arg | Role |
|---|---|
name | the daemon’s name, used in this recipe’s error messages |
prefix | its identity-env namespace ("KAVAL", "PADI"), the <PREFIX> that readBakedIdentity reads |
root | the lib.fileset.toSource root; must be a common ancestor of behavioralFileset |
behavioralFileset | what counts as this daemon’s behaviour, which is the consumer’s own policy decision |
pinnedSources | behavioural members that are pins, not files: name → store path |
commitHash | the navigable git ref this build was made from; "" throws |
override | test-only: force buildId instead of hashing (build-skew arms) |
| Return | Value |
|---|---|
buildId | 64-char sha256 of the fileset.toSource store path, plus one sorted <name>=<store path> line per pinnedSources entry |
bakeArgs | the --set <PREFIX>_BUILD_ID … --set <PREFIX>_COMMIT_HASH … string to splice into a makeWrapper invocation |
- Every
pinnedSourcesvalue must be a string underbuiltins.storeDir. The assert names the offending attrs. bakeArgsemits the pair together, so the joint invariant cannot be half-baked.- The
buildIdis platform-independent: it hashes source, never the runtime engine, so a cross-platform comparison is not a false mismatch. - With
pinnedSources = { }the id ishashString "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.
| Arg | Role |
|---|---|
members | package name → package dir, one path literal per local member and one store-path string per pinned member |
pinned | the member names that are pins, declared rather than inferred from how the value is spelled |
mustCover | name prefixes that must never resolve outside members ([ "@kolu/" ]) |
| Return | Value |
|---|---|
members | the 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 |
depClosuresubtracts eachstopentry and everything reachable only through it.identityInputsrendersbehavioralFilesetas each local member’s filteredsrcplus itspackage.json, andpinnedSourcesas the pinned members’ store paths.isHashedSourcedefaults to real.tsand.tsx, dropping.test.ts·.test.tsx·.test-d.ts·.testlib.ts.mustCoveris the by-name tripwire a pinned consumer needs, having noworkspace:protocol to give a stale map away.devDependenciesare 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:
| Failure | Message names |
|---|---|
a pinned name that is not a members key | the 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 belongs | the member, and which declaration to fix |
a members key that disagrees with the package’s own name | the key, the manifest name, the dir |
a workspace: (or mustCover-matching) edge whose target is not a member | the importer, the target, and the prefix that matched |
a stop / stableLeaves entry that is not in the closure | the 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-hashandbinary-cache.json. binary-cache.jsonis{ substituters, trustedPublicKeys, index }. The caches are derived fromflakeNix’s ownnixConfig.indexcomes fromclosureIndex, which is{ repo, branch }or an explicitnull. The branch is a GitHub branch thepublish-closureaction writes<commitHash>/<system>/<attr>.jsonto, andrawBaseis derived.closureIndexis required, with no default. A malformed one fails the binder’s eval.@kolu/surface-remotereads it asreadBakedDeclaration(…).index, withrevtaken fromcommit-hash.provisionAgentlooks 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.
| Value | Meaning |
|---|---|
{ 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), whichodu 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
bucketororigin.