kolu
Docs

@kolu/surface-daemon-supervisor reference

The client half: the code that spawns, watches, recycles and upgrades a daemon. It runs in the client process, never the daemon, and carries no @kolu/* app dependency. Its only workspace edges are the daemon half and @kolu/surface, which it dials the frozen control core through.

The face is Effect-native

Every verb on this page returns an Effect, and so does every plug it takes from a consumer: connect, probe, driver.spawn, RestartSteps’ three steps, drain and awaitExit. There is no Promise-shaped twin, so a boot that loses a race, a restart you abandoned and a drain past its ceiling each tear their own work down.

Three seams are synchronous facts rather than operations:

SeamWhy it is not an Effect
Endpoint.current()A read of held state, whose eager throw callers rely on.
DaemonConnection’s dispose()The supervisor tears down from paths that cannot await.
DaemonConnection’s onClose(cb)The same: it is called from paths that cannot await.

Nothing on EndpointSpec is Promise-shaped.

  • readProcessIdentity, readSocketHolders and readProcessState each state Effect.Effect<…, OsfactsClientError>.
  • The error channel is the union of osfacts-client, the package that satisfies those seams and takes effect as its one runtime dependency. Their success halves (SocketOccupancy, SocketHolder) come from there too.
  • An identity read that fails is a typed failure the endpoint answers (report dead, then propagate), not a defect that strands the UI at connecting.
  • awaitExit takes no AbortSignal and no AbortController. Fiber interruption tells a poll-based exit oracle to stop once the drain ceiling has won, and interruption cannot be refused.
  • Why: Why the supervisor is a separate package.

The dial leaf — /dial

@kolu/surface-daemon-supervisor/dial carries exactly three things: dialSocket (the unix-socket connect/error race, won once), DaemonContractSkewError plus its brand-checked isContractSkewError, and the DaemonConnection shape a handshake produces.

entrycarrieswhat it does not compile
@kolu/surface-daemon-supervisor/dialdialSocket, DaemonContractSkewError, isContractSkewError, DaemonConnectionendpoint.ts — drivers, convergence, osfacts-client
  • @kolu/padi-client/dial needs those three and nothing more, and it is the entry an out-of-repo consumer hydrates on its own. What that consumer reaches, its tsc compiles.
  • Reaching them through the barrel instead compiles endpoint.ts: the drivers, the convergence probe, and through the process-identity seam osfacts-client, a second npins pin to graft and guard.
  • endpoint.ts imports the three from the leaf and re-exports them, so the barrel’s surface is unchanged. Its whole compile cost is node:net and effect.
  • @kolu/padi-client’s hydrate guard asserts that no bare daemon barrel is in its import closure.
  • The copy/compile split stands: a consumer still copies the supervisor’s directory, whose manifest still names osfacts-client.

The endpoint

The endpoint is the state machine that takes a daemon from nothing to a live, handshaken connection, and reports what it finds while it does.

ExportSubpathWhat it is
createEndpoint({ home, readProcessIdentity, readSocketHolders, readProcessState, policy, probe, connect, … }).Builds the state machine from your injects and policy.
Endpoint.The handle it returns: states, the live connection, the restart hold.
destructiveRecycleSteps().Named no-preservation steps for a fail-closed recycle.
survivableSpawnDriver(cfg, deps?).The default driver: a systemd service, or a detached child.
scrubDaemonNodeOptions(nodeOptions).Strips dev-only Node flags from an inherited NODE_OPTIONS.
recycle(endpoint, steps) · serializeRestart(endpoint).The restart sequence, and its single-flight trigger.
waitForPidGone(pid, opts?).Polls until a pid is reaped.
reapHolder(pid, readProcessState, opts?).The two-deadline stop every kill site shares.
ReadSocketHolders.The type of the socket-holder inject.
ReadProcessState.The type of the process-state inject.
SocketOccupancy · SocketHolder.The three-way answer to “who holds this socket?”.
SocketSquatterForeignError · isSocketSquatterForeignError(err).A foreign holder of the rendezvous socket, never killed.
SocketProbeIndeterminateError · isSocketProbeIndeterminateError(err).A connect probe that timed out, proving nothing.
DaemonContractSkewError · isContractSkewError(err)., /dialThe one typed connect rejection that proves incompatibility.
ENDPOINT_STATES · ENDPOINT_STATE_DOWN · isDownEndpointState(s)/states, .The state tuple and its down/terminal classification.

createEndpoint

Builds the state machine and returns an unforgeable public Endpoint.

createEndpoint({ home, readProcessIdentity, readSocketHolders, readProcessState, policy, probe, connect: (socketPath) => …, … })

const policy: ConvergencePolicy<"not-drainable"> = {
  capability: "not-drainable",
  baked,
  onContractSkew: { kind: "recycle" },
  onBuildMismatch: { kind: "nudge-human" },
};

const endpoint = createEndpoint<TopClient, TopIdentity>({
  hostId: "local",
  home, // SAME call as the daemon — disagreement impossible
  readProcessIdentity,
  readSocketHolders, // osfacts-client's osfactsSocketHolders(<the same resolved bin>)
  readProcessState, // processStateReader(<the same resolved bin>) — a stopped holder skips the graceful reap leg
  policy,
  probe: probeDaemonIdentity({ capability: "not-drainable" }),
  driver: survivableSpawnDriver({
    binPath: daemonEntry,
    args: [],
    // COMPLETE child env for the detached spawn: the daemon's base plus its
    // locator vars. A partial env here would spawn a daemon with no PATH/HOME.
    env: {
      ...spawnEnvBase(),
      FLEET_TOP_GATE: home.gatePath,
      FLEET_TOP_SOCKET: home.socketPath,
    },
    unitPrefix: "fleet-top",
  }),
  // the framework hands you the path
  connect: (socketPath) => connectTop(socketPath),
  log: stderrLogger(),
  onStatus: (hostId, status) =>
    process.stderr.write(`[supervisor] ${hostId}: ${status.state}\n`),
});

return Effect.gen(function* () {
  // #region converge
  // The only boot verb — policy (who I am + how I converge) is fixed on the endpoint.
  const outcome = yield* converge(endpoint);
OptionWhat you pass
homeDaemonHomePaths, the same spine primitive daemonMain takes. Gate and socket come from it.
readProcessIdentityStart-qualified gate ownership, as a ReadProcessIdentityAsync.
readSocketHoldersGate-less squatter recovery, as a ReadSocketHolders.
readProcessStateWhether the holder is stopped, so its graceful reap leg is skippable. A ReadProcessState.
policyYour whole convergence surface: who I am, and how I converge.
probeThe convergence probe, usually probeDaemonIdentity.
connectReceives the socket path from the framework, so callers never re-thread it.
  • All three OS-fact readers are required, never defaulted, because the endpoint performs no platform traversal of its own.
  • readProcessIdentity is (pid: number) => Effect.Effect<ProcessIdentity | undefined, OsfactsClientError>. It runs off the serving loop, so an osfacts spawn never blocks it. Prefer processIdentityAsync(bin), with bin resolved once at the composition root.
  • The awaitable type lives in this package beside EndpointSpec. The daemon half keeps only the sync ReadProcessIdentity, which the synchronous gate-claim paths use.
  • The boot trio lives in a package WeakMap, not on the returned object.

An unreadable gate

The endpoint’s holder probe folds the daemon half’s three-way gate-read law exhaustively. An unreadable gate (EACCES or EIO) is not free and not stale.

  • When readGateIdentity yields unreadable, ensure and recycle throw before any unlink, kill or spawn.
  • Status still emits connecting → dead, then rethrows, so the UI never wedges.
  • A mode-000 gate is the unit pin (recycleForeignGate.test.ts).

The incompatible state

incompatible is the proven contract-skew verdict: a respawn from the realised closure already skewed, or a refuse-policy survivor skews at handshake.

  • It is reported with both contract versions on the status ({ state: "incompatible", daemonVersion, requiredVersion }).
  • It is never collapsed into dead/degraded. A consumer deriving affordances from the state sum must not offer a restart against it, because restarting cannot fix a skew. Only changing the closure can.
  • A restart hold does not coerce it. A skew inside a restart is that restart’s terminal verdict, not a transition.

Endpoint

The handle createEndpoint returns, generic over the client C and the identity I.

  • Its states are connecting → connected | dead | incompatible, then connected → degraded if the daemon dies mid-session.
  • The public verbs are converge(endpoint) and recycle(endpoint, steps).
  • The boot-method trio (ensure / adoptOrEnsure / adoptOrSpawnOrRefuse) is absent from the public Endpoint type and from the runtime object.
  • Private binds live only in a package WeakMap keyed by the genuine createEndpoint handle. Kit modules (converge, recycle) and same-package tests resolve them through a package-internal relative import of endpoint.private.ts. There is no public asEndpointInternal and no ./testing subpath.
  • current() is the live connection. holdRestarting is the recycle emit-guard.

destructiveRecycleSteps()

Named no-preservation steps for a fail-closed recycle. All steps are still required.

survivableSpawnDriver(cfg, deps?)

The default DaemonDriver: systemd-run --user under a service, and a detached +unref child otherwise.

  • DaemonDriver.spawn is an Effect<void> value, not a method. Re-running it is “spawn again”.

cfg.env per launch mode

survivableSpawnDriver’s cfg.env is read differently by the mode the driver picks, so compose it for the mode you will hit.

ModeHow env is read
Detached (the production default)env is the complete child env. Nothing from the parent is layered under it, so a partial set spawns a daemon with no PATH or HOME.
Under systemdenv overlays the unit’s PAM/manager env via --setenv, so a partial set is fine.
  • On the detached path, carry the daemon’s whole base. Compose it from a fixed allowlist, as the snippet above does. kolu mines kolu-pty’s SPAWN_ENV_ALLOWLIST.
  • Launch mode and env inheritance are one union field, so the illegal combination is unspellable. fromSource omitted (or false) is a normal launch: systemd-eligible, with env complete.
  • An object { inheritParentEnv } forces the detached branch even under a session, for an actual source launch or a built binary a box forces detached.
  • inheritParentEnv decides whether env layers over the supervisor’s full parent env. Use true only for an actual from-source launch (the dev nix-shell env). A built forced-detached daemon uses { inheritParentEnv: false } and gets env alone.
  • Why: Why the framework takes values, not loose fields.

scrubDaemonNodeOptions(nodeOptions)

Strips dev-only Node flags from an inherited NODE_OPTIONS, so a spawned daemon never opens the supervisor’s inspector or writes its profiles.

  • It returns undefined when nothing of value remains, so the variable is dropped rather than emptied.
  • It is opt-in per driver.

recycle(endpoint, steps) · serializeRestart(endpoint)

recycle is the composed capture → drain → recycle → reattach sequence, as one Effect. serializeRestart returns a single-flight triggerRestart.

  • RestartSteps’ three members are Effects too. capture is a value, because an effect is already the description of work not yet done.
  • triggerRestart coalesces rather than queues: a second caller joins the restart already in flight and gets its outcome, instead of waiting and then running a second one.

waitForPidGone(pid, opts?)

An Effect<boolean> that polls isHolderLive until the pid is reaped (ESRCH), so a respawn never races a live gate holder.

reapHolder(pid, readProcessState, opts?)

An Effect<ReapOutcome, OsfactsClientError>: the two-deadline stop every supervisor kill site shares.

SIGTERM → wait REAP_TERM_CEILING_MS (120 s) → SIGKILL → wait REAP_KILL_CEILING_MS (5 s).

  • readProcessState is required, as the injected OS fact, never a default.
  • A holder observed stopped (T/t) skips the graceful leg, because a stopped process cannot run a shutdown handler. SIGKILL lands at once.
  • A read that cannot complete travels the error channel, where the endpoint reports dead and rethrows. It is never a silent “not stopped”.
  • It answers { kind: "reaped", endedBy, waitedMs, reason? } or { kind: "survived", waitedMs, reason? }. An operator reads which signal ended it, how long it took, and whether the graceful window was skipped.

ReadSocketHolders

The type of the readSocketHolders inject: (socketPath: string) => Effect.Effect<SocketOccupancy, OsfactsClientError>.

  • The reader that satisfies it is osfactsSocketHolders(bin) from osfacts-client, bound to an already-resolved osfacts binary path (bakedOsFactsBin(<your env var>)). This package never learns which variable a consumer bakes.
  • It calls osfacts socket-holders <path> --procs. The platform split, the parse, the honesty policy and the fold live in the tool and its client, not here.
  • Bind it to the same resolved path as processIdentityAsync, so one root spells its environment variable once for all the OS facts.

ReadProcessState

The type of the readProcessState inject: (pid: number) => Effect.Effect<ProcessState | undefined, OsfactsClientError>.

  • The reader that satisfies it is processStateAsync(bin) from osfacts-client, bound to the same already-resolved osfacts binary path (osfacts snapshot --pids <pid> --status).
  • undefined is the honest dead-pid answer.
  • The T/t ⇒ stopped fold lives once in this package, not in the reader.

SocketOccupancy · SocketHolder

The three-way answer to who holds a socket, never one possibly-empty list.

AnswerWhat it means
{ kind: "held", holders }holders is a non-empty tuple by type (readonly [SocketHolder, ...SocketHolder[]]), so a consumer never writes an unreachable empty-check.
{ kind: "none" }Proven nothing holds it. Only linux’s world-readable /proc/net/unix can prove this.
{ kind: "unattributed", detail }Something may hold it and the OS would not say what: a bound-but-unreadable holder, or a search that could not complete.
  • Only none is evidence of freedom, and the endpoint still re-probes before spawning.
  • Both types are re-exported from osfacts-client, whose foldSocketOccupancy(reading) produces them from a SocketHoldersReading. One fold, so kolu and drishti cannot spell the three-way differently.

SocketSquatterForeignError · isSocketSquatterForeignError(err)

Thrown when the process holding the rendezvous socket did not complete the kaval handshake. Such a foreign or non-conforming holder is never killed.

  • It carries socketPath, holders: SocketHolder[] and detail?: string, so the refusal names the squatter.
  • Each holder is a pid and an optional command. The command is absent, never "?", when the identity read lost the race, so a sentinel cannot be mistaken for a process actually named ?.
  • When the OS named nobody, detail is the unattributed reading’s own words (the holder search could not complete (darwin_proc_fds: BLIND_OR_EMPTY)), which the message renders instead of “an unidentifiable process”.
  • On darwin the nameless case is the ordinary one, so the explanation, not just the decision, has to survive the fold.
  • The guard is brand-checked and realm-robust.

SocketProbeIndeterminateError · isSocketProbeIndeterminateError(err)

Thrown when a one-shot socket connect probe times out (SocketServeState "indeterminate"). It proves neither free nor dead.

  • The endpoint never kills, unlinks or spawns on it.
  • It carries gatePath, socketPath and an optional gatePid.
  • Failures after connecting emit dead, then rethrow, so status never wedges.

DaemonContractSkewError · isContractSkewError(err)

The one typed connect rejection that proves incompatibility. It is also exported from /dial.

  • It is constructed from fields ({ subject, daemonVersion, requiredVersion, pid? }), with the message derived from them, so no consumer re-parses the prose.
  • readonly daemonVersion and requiredVersion ride the instance, so downstream translators (a typed RPC rethrow, a status arm) read them structurally.
  • The optional readonly pid is the skewed daemon’s self-reported OS pid. The gate-less-squatter recovery of an old orphan throws here before a connection exists, and this is its identity attestation.
  • The guard is brand-checked (realm-robust), never instanceof.

ENDPOINT_STATES · ENDPOINT_STATE_DOWN · isDownEndpointState(s)

The state tuple and its total down/terminal classification. Both live in the zero-dependency, browser-safe /states subpath, and are re-exported from the package root.

  • ENDPOINT_STATE_DOWN is a Record<EndpointState, boolean>, so a new state is a compile error at the home until it is classified.
  • Consumers (a dial-ended check, a client presentation table) read isDownEndpointState instead of hand-spelling the degraded || dead || incompatible disjunct.

The convergence kit

converge(endpoint) is the only boot verb. It probes the running daemon’s identity, asks a pure decide, admits drain through the per-boot budget when the daemon is drainable, and enacts through the endpoint’s private boot methods.

kaval declares recycle-on-skew. padi declares drain-newer-else-refuse with a drain-capable handshake. The step-by-step for both is in How to recycle and upgrade a daemon, and the rules the kit enforces are in Daemon invariants.

// The only boot verb — policy (who I am + how I converge) is fixed on the endpoint.
const outcome = yield* converge(endpoint);
ExportSubpathWhat it is
converge(endpoint).The boot verb: observe, decide, drain, bind.
convergeAdmit({ running, budget, drain, awaitExit, … }).The connector arm of the same policy.
probeDaemonIdentity({ capability, drainCeilingMs? })(socketPath).The endpoint’s probe of the frozen fragment.
probeDaemonIdentityFrom({ client, dispose, capability: "not-drainable" })
probeDaemonIdentityFrom({ client, dispose, capability: "drainable", awaitExit, drainCeilingMs })
.The probe assembled from an already-dialled connector.
readControlCoreHello(client) · ControlCoreProbeClient.Reads and validates the frozen hello.
dialSocket(socketPath)., /dialThe package’s own unix-socket dial.
isNoListenerError(error).The shared ECONNREFUSED/ENOENT classifier.
decide(policy, running).The pure fold that decides what to do.
createDrainBudget · createConnectorDrainBudget · outcomeAdopted · outcomeAnomaly.Opaque budget handles and outcome constructors.
InstanceKey · instanceKeyFromStartedAt · instanceKeyTag.Which instance an observation named.
BindResult · BoundResidentCharacterization.The private-bind result and its characterization.
drainAndAwaitExit(drain: Effect<void>, awaitExit: Effect<void>, { ceilingMs }).The drain-and-confirm-exit skeleton both enactments share.
ConvergenceAnomaly.What went wrong, as typed evidence.
UnconvergedCause.Why a boot ended unconverged.
UnspeakableEvidence · unspeakableClause(evidence).Why a peer is unspeakable, as data, and its renderer.
UnspeakableProtocolError · isUnspeakableProtocolError(err).The transport fact raised at either trigger.
UnspeakablePeerError · isUnspeakablePeerError(err).The corroborated verdict, with its two attestations.
UNSPEAKABLE_SILENCE_MS.The silence bound, 8 s.
contractIsNewer · contractIsCompatible · buildsMatch.The version and build comparisons, re-exported.

converge(endpoint)

A single fold over every observation, then decide, then a budget-gated drain, then a private bind. It takes a genuine createEndpoint handle only.

  • It returns a typed ConvergenceOutcome whose kinds either always carry their anomaly or never do. There are no optionals.
  • Anomaly arms carry typed evidence as data: running and expected identities, drained and observed instance keys. detail is human garnish only.
  • Same-lineage admitted drains continue (F1a).
  • A null re-probe is identity-unverifiable (F1b).
  • Give-up re-decides characterization without re-draining.
  • Connector arms (ssh) use convergeAdmit with the same policy object.

Single observation authority

Every observed identity flows through one internal fold (foldObserved): the initial probe, bind characterization, the post-drain successor, the post-give-up bind, and the drainable re-probe.

  • Every bind transition (plain, recycle, post-drain, give-up) flows through one BindResult consumer (consumeBindResult). Call sites never inspect r.kind.
  • The fold always runs decide(policy, identity | null), never a hand-copied compat/match subset.
  • It owns connection lifecycle, so refused, not-adopted and probe-failed exits call the idempotent releaseHeld unconditionally. There is no holding mirror.
  • It preserves four-valued characterizations (characterized | absent | failed | uncorrelated).
  • It reports unconverged.running: null when the running identity is honestly unknown, and never fabricates expected.
  • A characterization probe throw is probe-failed with the true message, never a catch-to-null into identity-unverifiable.
  • Named probe instance keys must match conn.startedAt. A mismatch is uncorrelated.

convergeAdmit(opts)

The connector arm, an Effect<ConvergeAdmitVerdict>. It takes { running, budget, drain, awaitExit, … }.

  • budget is a ConnectorDrainBudget, which makes recycle and nudge-human unspellable.
  • drain and awaitExit are Effects.
  • awaitExit succeeds only on process exit, never on link loss (F3).

probeDaemonIdentity(opts)(socketPath)

The endpoint probe for the frozen fragment, as a full ConvergenceProbe. It takes { capability, drainCeilingMs? }.

  • It answers null only for an honest ECONNREFUSED or ENOENT.
  • Every other dial or hello failure throws, including a control-core version other than the frozen 1.0, and an unspeakable peer (UnspeakableProtocolError).
  • It throws when a live pre-fragment daemon answers the socket but has no core.hello route.

A consumer with a named upgrade window may catch only that structured route-missing failure and project it as an older-build observation. Kaval does this, so its not-drainable policy reports the existing human nudge.

  • Such a consumer never turns the served-daemon fact into null, and catches no other probe error.
  • The narrowing derives on the Effect RPC failure. The oRPC NOT_FOUND frame does not exist on this wire.
  • A peer from a previous epoch is a different observation. See The third observation.

probeDaemonIdentityFrom(opts)

The single probe-assembly authority for an already-dialled connector.

  • probeDaemonIdentityFrom({ client, dispose, capability: "not-drainable" }) omits the exit-oracle fields.
  • probeDaemonIdentityFrom({ client, dispose, capability: "drainable", awaitExit, drainCeilingMs }) requires both of them.
  • ssh keeps its stronger process-exit oracle instead of treating link loss as exit.

readControlCoreHello(client) · ControlCoreProbeClient

Reads and validates the frozen hello on its one baked 30 s deadline: the frozen-version check, plus the joint buildId/commit fact.

  • ControlCoreProbeClient is the already-dialled client shape it takes: client.surface.control.core.hello(), which is itself an Effect.

dialSocket(socketPath)

The package’s own unix-socket dial, as an Effect<Socket>, so the control-core leg owns its framing tap.

  • A dial interrupted before it settles destroys the half-open socket rather than abandoning it.

isNoListenerError(error)

The one ECONNREFUSED/ENOENT classifier shared by generic and pre-fragment daemon probes.

decide(policy, running)

The pure fold, and the sole decision authority under converge. It reads policy.baked; there is no free-standing baked argument.

createDrainBudget · createConnectorDrainBudget · outcomeAdopted · outcomeAnomaly

Opaque budget handles and outcome constructors. There are no public admit can-openers, and the connector mint is type-gated.

InstanceKey · instanceKeyFromStartedAt · instanceKeyTag

A named instance, or pre-instance when startedAt is absent, which means older. The absence is never overloaded onto null.

BindResult · BoundResidentCharacterization

The private-bind result. Adopted residents carry a four-valued characterization: characterized | absent | failed | uncorrelated.

drainAndAwaitExit(drain, awaitExit, { ceilingMs })

The framework-run drain-and-confirm-exit skeleton both enactments share. Its signature is drainAndAwaitExit(drain: Effect<void>, awaitExit: Effect<void>, { ceilingMs }).

  • Both plugs are forked into the primitive’s own scope, so the ceiling winning interrupts the exit oracle.
  • awaitExit’s error channel is never by type, which states the F3 contract in the signature rather than in a comment.

ConvergenceAnomaly

adopted-stale | skew-refused | unconverged | cross-supervisor. Each arm carries typed evidence.

  • unconverged.running is nullable, for an unknown identity.
  • link-failed is session-owned.

UnconvergedCause

budget-exhausted | drain-not-taken | adopt-bind-failed | identity-unverifiable | probe-failed | unspeakable-protocol, with the evidence as data under unconverged.

  • The unspeakable-protocol arm carries socketPath, gatePath and the pid that was classified.
  • It rides a refusal only when the gate stopped naming that pid before the takeover could act.

UnspeakableEvidence · unspeakableClause(evidence)

Why a peer is unspeakable, as data: { trigger: "undecodable-frame", frame } or { trigger: "silence", silentForMs }.

  • There is no third arm.
  • unspeakableClause is shared, so the dial path, the corroboration site and the fold cannot drift in what they tell an operator.

UnspeakableProtocolError · isUnspeakableProtocolError(err)

The transport fact, raised by probeDaemonIdentity’s dial at one of the two triggers. It is never raised by the hello deadline, a close, or a member error.

  • It carries socketPath and the evidence field.
  • Uncorroborated, it is an ordinary probe-failed.
  • The guard is brand-checked and realm-robust.

UnspeakablePeerError · isUnspeakablePeerError(err)

The corroborated verdict: the same fact plus the two attestations the endpoint adds. The gate at this rendezvous is ours, and its pid passed the holder identity law.

  • It carries gatePath and pid beside the transport fields.
  • Only this becomes the unspeakable-protocol observation.

UNSPEAKABLE_SILENCE_MS

The silence bound, 8 s. It is pinned between two facts of the link.

  • The link pings every 5 s, and a peer of this epoch pongs below its handlers, so a merely slow daemon has still demonstrably spoken.
  • The link’s keep-alive backstop ends a silent connection only past 60 s, after which there is nothing left to classify.

contractIsNewer · contractIsCompatible · buildsMatch

Re-exported from @kolu/surface-daemon. Contract versions are ordered; build ids are match-only.

The third observation — unspeakable-protocol

A daemon from a previous protocol epoch cannot be asked its version at all, because version negotiation happens inside the protocol that was replaced. Convergence therefore has a third narrowly-typed peer observation beside “identity” and “absent”.

Such a peer betrays itself in exactly two ways, and which one you get depends on who greets whom:

TriggerWhat happensEvidence
undecodable-frameThe peer speaks first, in a framing we cannot parse.A bounded, JSON-quoted frame excerpt.
silenceThe peer waits for a greeting in a protocol we do not speak: it accepts the connection, takes our frames, and answers nothing.silentForMs, the bound it stayed mute through.
  • The silence arm is measured against the previous release: its oRPC ServerPeer waits for its own client hello, our ndjson frames never look like one, and the connection dies by timeout with no first frame to fail decoding.
  • Both triggers are the same verdict, so they are one error type with the trigger as a tagged field, never two classes a consumer would have to union.
  • The fact is raised under those triggers alone. The observation additionally requires two attestations: the gate file at this rendezvous is ours, and its pid passed the holder identity law.
  • An uncorroborated trigger stays probe-failed, and a foreign socket-squatter keeps the SocketSquatterForeignError path. A merely slow peer and a stranger on our socket both stop at the transport fact.
  • Classification happens at the trigger, not by waiting out the frozen hello’s 30 s deadline. That keeps awaitHelloGone responsive inside a drain ceiling when the peer will never answer.

The takeover

The disposition is takeover, for every policy. The contract-skew policy is not consulted, because an undecodable wire is not a skew and the drain verb does not exist on it. What is available is the act the drain verb requests: the daemon’s own in-process shutdown, asked for with a signal instead of a message.

stepwhat happens
re-attestThe gate must still name the exact pid that was classified. If it names anyone else, nothing is signalled and the pass refuses with the unspeakable-protocol cause.
SIGTERMThe old daemon’s own shutdown runs (persist, close, release the gate), bounded by REAP_TERM_CEILING_MS (120 s).
SIGKILLOnly past the graceful deadline, bounded by REAP_KILL_CEILING_MS (5 s). Still alive after it, and the endpoint reports dead and fails loud.
spawnA daemon of this epoch is started and connected at the same rendezvous. It seeds from disk, so loss is bounded by the old daemon’s autosave debounce.
  • The graceful leg is skipped entirely when the holder is observed stopped (T/t): a stopped process cannot run a shutdown handler, because the signal is queued, not delivered.
  • On that skipped path SIGKILL lands immediately. That is the reason: "stopped" in the outcome.
  • The takeover is logged as one operator-readable line: what was stopped, why it was provably ours, which signal ended it, how long the wait took, and whether the graceful leg was skipped.
  • The outcome is recycled, because the holder was replaced, not adopted.
  • Kaval’s recycle reaches the same act by the same path.
  • Why: Recycling a daemon without lying to its clients.