stitchkit 0.94.1 → 0.95.1

package/llms/application.txt

@@ -815,39 +815,74 @@ application-owned.
 ## Durable process facts and owner notifications
 
 `createProcessLifecycleLedger` records a bounded versioned list of process runs.
-Start, readiness and shutdown target both `runId` and `pid`, so hot reload and
-PID reuse cannot close the wrong generation. A start classifies what happened to
-the newest run before it, and the classification is decided by three facts —
-whether that run recorded its own exit, whether the pid is the same, and whether
-the version changed:
+Start, readiness, draining and shutdown target both `runId` and `pid`, so hot
+reload and PID reuse cannot close the wrong generation. `lifecycleLedgerResource`
+drives it from the kernel's phases: `start` records the start, `activate` the
+readiness, `stopAdmission` the drain — the run's `unavailableAt`, the moment it
+stops answering new work — and `close` / `force` the stop. A run that stops
+without ever becoming ready (a failed startup rolls back with `close` only)
+ends as `startup-failed`, not `clean`.
+
+A start classifies what happened to the newest run before it, and the
+classification is decided by four facts — whether that run recorded its own
+exit, whether the pid is the same, whether the version changed and whether it
+ever became ready:
 
 | newest run | same pid | version | `previousExit` | predecessor's `termination` |
 |---|---|---|---|---|
 | none | — | — | `first-boot` | — |
-| recorded `stoppedAt` | — | — | `clean` / `forced` / `abnormal` as recorded | unchanged |
-| still `active` | yes | — | `hot-reload` | `hot-reload`, closed at the new start |
-| still `active` | no | changed | `handoff` | stays `active`; it records its own stop later |
-| still `active` | no | same | `abnormal` (default) | `abnormal`, closed at the new start — an upper bound, the crash time is unknown |
+| recorded `stoppedAt` | — | — | `clean` / `forced` / `startup-failed` / `abnormal` as recorded | unchanged |
+| still open | yes | — | `hot-reload` | `hot-reload`, closed at the new start |
+| still open | no | changed | `handoff` | stays open; it records its own stop later |
+| still open, was ready | no | same | `abnormal` (default) | `abnormal`, closed at the new start — an upper bound, the crash time is unknown |
+| still open, never ready | no | same | `startup-failed` (default) | `startup-failed`, closed at the new start |
+
+Every other open run the start finds was abandoned too and is closed the same
+way — two crashes in a row leave two open runs, and both are closed, not only
+the newest. Open means `active` or `draining`.
 
 A version of `unknown` on either side is never a version change, so a dev build
 after a crashed release reads `abnormal`, not `handoff`. `forced` means the
 process itself acknowledged a kill; `abnormal` means a successor found it dead.
 
-The last row is a choice, and the default is the single-process deployment:
+### Downtime is the window nobody answered in
+
+`ReadyFact.downtimeMs` is `readyAt` of the new run minus `unavailableAt` of the
+last run that served — the predecessor's drain plus the successor's boot. A
+110 s forced drain followed by a 4 s boot is 114 s of downtime; the gap between
+the two processes alone would read 4 s before and after that defect was fixed.
+Runs that never became ready answered nobody, so the count passes them: after a
+failed start it still opens where the last serving run stopped answering. It is
+`0` when that run still answers (a handoff whose predecessor has not drained
+yet) and `null` on first boot and when the end was never timed — a crash or a
+hot reload records no `unavailableAt`. `unavailableSince` names the moment it is
+counted from. The gap between two processes is still there, under its own
+name: `StartFact.processGapMs` is the start minus the predecessor's recorded
+stop.
+
+The ledger records what the process says while it can say it. stitchkit never
+calls `process.exit` (ADR 0074), so a stop is recorded on the kernel's `close`
+or `force` path, both awaited. An application that exits the process on its
+own before its shutdown settles loses that last write; the successor then
+finds the run open and closes it as `abnormal`, keeping the `unavailableAt`
+already recorded — which is why the drain moment is written first, at
+`stopAdmission`, and the downtime survives a stop that was never recorded.
+
+The `abnormal` default is a choice, and it is the single-process deployment:
 one process per build, a new pid of the same build means the old one stopped
-answering. Where two processes of **one** build overlap on purpose — a
-cluster, a zero-downtime reload of the same build — pass
-`sameVersionOverlap: 'handoff'` to the ledger, and the predecessor stays
-`active` until it records its own shutdown. The cost of that setting is
-symmetric: a real crash under it is reported as a handoff and the dead run
-stays `active` in the ledger until retention drops it. The list is kept in the
-order the transitions wrote it — every write goes through one atomic update,
-so that order is the causal one, and a successor whose clock lags its
-predecessor still finds it at the head; `startedAt` is data, not the sort key.
-Retention (`retain`, default 20) drops finished runs first and an active one —
-a live handoff predecessor — only when nothing finished is left. Facts are
-published through the ledger's own subscription and resource value;
-`ApplicationEventSink` remains the strict application-state stream.
+answering. Where processes of **one** build overlap on purpose — a cluster, a
+zero-downtime reload of the same build — pass `sameVersionOverlap: 'handoff'`
+to the ledger, and every open run stays open until it records its own
+shutdown. The cost of that setting is symmetric: a real crash under it is
+reported as a handoff and the dead run stays open in the ledger until
+retention drops it. The list is kept in the order the transitions wrote it —
+every write goes through one atomic update, so that order is the causal one,
+and a successor whose clock lags its predecessor still finds it at the head;
+`startedAt` is data, not the sort key. Retention (`retain`, default 20) drops
+finished runs first and an open one — a live handoff predecessor — only when
+nothing finished is left. Facts are published through the ledger's own
+subscription and resource value; `ApplicationEventSink` remains the strict
+application-state stream.
 
 `createNotificationOutbox` is the transport-neutral durable delivery side. It
 persists before send, claims an item with an expiring lease, carries one stable
@@ -870,7 +905,36 @@ deadline holds `stop()` — and so the resource's `force()` — for that one cal
 so give the transport a timeout. Superseding a key that is being sent right now
 does not recall it: the send completes, and only its receipt is not written.
 
-Both primitives depend on the structural `StateStore`. On a server,
+`createDirectoryInbox` is the receiving side for another program on the same
+host: it drops entries — a release transition, say — into a directory, and
+the application takes each one at least once. It is a managed resource of its
+own (`createDirectoryInbox({ id, directory, schema, handle })`, imported from
+`stitchkit/application/directory-inbox` because it touches files; its types
+and schemas are in `stitchkit/application`) and publishes a handle with
+`flush()` and `state()`. The producer writes each entry
+atomically as `<name>.json` — a temporary name, then a rename; names that start
+with a dot are never read. Entries are delivered in name order, and only after
+`activate`: none reaches the application before it is ready. `stopAdmission`
+stops taking new ones, `drain` waits for the one in flight, and `force` aborts
+the `signal` its handler was given.
+
+Taken and done are separate durable records. Before `handle` runs, the entry
+is claimed with a lease (`leaseMs`, default five minutes); after it returns,
+a receipt replaces the claim and only then is the file removed. A process that
+died mid-delivery leaves a claim, and the entry is taken again once the lease
+runs out — at least once, not exactly once, so a handler that sends somewhere
+should carry the entry's `key` as its idempotency key. A process that died
+after the receipt leaves only the file, which the next pass removes without
+delivering it again. A handler that throws is retried after a backoff from one
+second doubling to five minutes; an entry that fails `schema`, is over
+`maxEntryBytes` or was taken `maxAttempts` times (default 20 — the count
+survives restarts, so an entry whose handling kills the process is not taken
+forever) is moved to `rejected/` with its reason and reported to `onRejected`,
+and the entries after it keep flowing. The state lives in
+`<directory>/.inbox-state.json` under `createFileStateStore`'s inter-process
+lock unless a `store` is supplied.
+
+These primitives depend on the structural `StateStore`. On a server,
 `createFileStateStore` supplies the shared Zod-validated JSON adapter with an
 inter-process lock, unique temporary file, fsync and atomic rename. The lock
 is a file with a heartbeat: the holder refreshes its mtime every third of

package/llms/stitchkit.txt

@@ -76,11 +76,11 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 39 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 40 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the managed-resource conformance kit |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 21 of the 39 minors since 0.56.2, most recently 0.94.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 21 of the 40 minors since 0.56.2, most recently 0.94.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -90,11 +90,12 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 39 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 8 of the 40 minors since 0.56.2, most recently 0.95.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
 | `stitchkit/application/diagnostic-journal` | server | evolving | the local diagnostic journal — the one part of the kernel that spawns, locks and writes files |
+| `stitchkit/application/directory-inbox` | server | evolving | the directory inbox — entries another program drops into a directory, delivered to the application at least once |
 
 Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
 code adds `stitchkit/server` (or `stitchkit/node` on Node) and opts into

package/llms/{upgrading-0.37.0-0.50.0.txt → upgrading-0.37.0-0.53.0.txt}

@@ -1,14 +1,36 @@
-# Upgrading 0.37.0 → 0.50.0 — stitchkit docs slice
+# Upgrading 0.37.0 → 0.53.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.37.0 → 0.50.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.37.0 → 0.53.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.37.0 → 0.50.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.37.0 → 0.53.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.53.0
+
+### Realtime `emit` returns `boolean` instead of `void`
+
+Every **call site** compiles and behaves exactly as before — the return value
+is new information (`true` = accepted by the transport, `false` = dropped
+while the browser client was disconnected), not a behavior change. What breaks
+is **implementing** the interfaces: a test mock or app-side adapter of
+`SocketIOClient` / `RealtimeClient` / `ValidatedRealtimeSocket` /
+`RealtimeServer` whose `emit` returns `void` no longer typechecks.
+
+```ts
+// before — a void mock satisfied the interface
+const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => {} }
+// after — report acceptance (true is what a live server-side emit reports)
+const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => true }
+```
+
+While migrating, consider replacing hand-rolled `if (client.connected)` guards
+with the new honest surface: check `client.emit(...) === false`, or observe
+drops centrally with `onDroppedEmit`.
+
 ## Released migration: 0.50.0
 
 ### The factory's scope union now covers per-endpoint overrides

package/llms/{upgrading-0.53.0-0.67.0.txt → upgrading-0.55.0-0.68.0.txt}

@@ -1,14 +1,64 @@
-# Upgrading 0.53.0 → 0.67.0 — stitchkit docs slice
+# Upgrading 0.55.0 → 0.68.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.53.0 → 0.67.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.55.0 → 0.68.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.53.0 → 0.67.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.55.0 → 0.68.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.68.0
+
+### Make Unix transport selection explicit outside Bun
+
+The legacy `unix` option remains a Bun convenience, but on Node or another
+runtime it now fails before dispatch. Replace it with the owned adapter and close
+that adapter with the application:
+
+```ts
+// before — unsafe outside Bun: an unsupported fetch could dial baseUrl over TCP
+const http = createHttpClient({ baseUrl, unix: '/run/service.sock' })
+
+// after — Bun and Node; every dispatch and redirect stays on the socket
+import { createUnixClientTransport } from 'stitchkit/server' // or stitchkit/node
+const transport = createUnixClientTransport({ socketPath: '/run/service.sock' })
+const http = createHttpClient({ baseUrl, fetch: transport.fetch })
+// during shutdown
+await transport.close()
+```
+
+Do not automatically replay `possibly-dispatched`: a timeout or connection loss
+after bytes left the process does not prove that a write did not happen.
+
+### Choose tolerant stream parsing explicitly
+
+`parseNDJSON` and `parseSSE` now throw on malformed JSON, invalid UTF-8 and an
+over-limit line. The default line ceiling is 1 MiB. If a feed deliberately skips
+bad records, retain that policy explicitly:
+
+```ts
+// before — malformed input disappeared implicitly
+parseNDJSON(response)
+
+// after — ordinary fail-closed path
+parseNDJSON(response, { maxLineBytes: 256 * 1024 })
+
+// after — deliberately tolerant path
+parseNDJSON(response, { onParseError: (raw, error) => report(raw, error) })
+```
+
+### Extend exhaustive framework-error handling
+
+If a switch makes `StitchErrorCode` exhaustive, add
+`STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,
+`STREAM_TERMINAL_MISSING` and `STREAM_LIFETIME_EXCEEDED`. A partial application
+status map needs no change (ADR 0105).
+
+The admission/channel APIs and endpoint `stream` descriptor are additive; raw
+responses and raw `streamingRoute` remain supported.
+
 ## Released migration: 0.67.0
 
 Three application-kernel changes. Two of them fix silent failures, so the most
@@ -1150,25 +1200,3 @@ Downloaded `path` is now relative to the boundary and MIME metadata is named
 same way. Auth predicates must explicitly return `true`, `false`, or a plain
 object of context fields; replace accidental `undefined` fallthroughs with the
 intended boolean.
-
-## Released migration: 0.53.0
-
-### Realtime `emit` returns `boolean` instead of `void`
-
-Every **call site** compiles and behaves exactly as before — the return value
-is new information (`true` = accepted by the transport, `false` = dropped
-while the browser client was disconnected), not a behavior change. What breaks
-is **implementing** the interfaces: a test mock or app-side adapter of
-`SocketIOClient` / `RealtimeClient` / `ValidatedRealtimeSocket` /
-`RealtimeServer` whose `emit` returns `void` no longer typechecks.
-
-```ts
-// before — a void mock satisfied the interface
-const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => {} }
-// after — report acceptance (true is what a live server-side emit reports)
-const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => true }
-```
-
-While migrating, consider replacing hand-rolled `if (client.connected)` guards
-with the new honest surface: check `client.emit(...) === false`, or observe
-drops centrally with `onDroppedEmit`.

package/llms/{upgrading-0.68.0-0.94.0.txt → upgrading-0.69.0-0.95.0.txt}

@@ -1,14 +1,56 @@
-# Upgrading 0.68.0 → 0.94.0 — stitchkit docs slice
+# Upgrading 0.69.0 → 0.95.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.68.0 → 0.94.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.69.0 → 0.95.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.68.0 → 0.94.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.69.0 → 0.95.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.95.0
+
+One breaking change in `stitchkit/application`: the process lifecycle ledger
+counts downtime as the window nobody answered in, and gains the `draining`
+phase and the `startup-failed` outcome. A ledger file written by an earlier
+version loads unchanged — the new `unavailableAt` reads as `null`.
+
+1. **Read downtime from the ready fact.** **Who must act:** a project that
+   reads `downtimeMs` from a `started` fact. It is gone from `StartFact`; the
+   number it carried is `processGapMs`. The downtime now arrives with the new
+   run's readiness:
+
+   ```ts
+   // before
+   ledger.subscribe((fact) => {
+     if (fact.type === 'started') report(fact.previousExit, fact.downtimeMs);
+   });
+   // after
+   ledger.subscribe((fact) => {
+     if (fact.type === 'started') previousExit = fact.previousExit;
+     if (fact.type === 'ready') report(previousExit, fact.downtimeMs);
+   });
+   ```
+
+2. **Handle the new values.** **Who must act:** a project that switches
+   exhaustively over `LifecycleTermination` (new: `draining`,
+   `startup-failed`), `PreviousExit` (new: `startup-failed`) or
+   `ProcessLifecycleFact` (new: `DrainingFact`, `type: 'draining'`). The type
+   checker names each switch. An open run is `active` or `draining`; a check
+   written as `termination === 'active'` to mean "still running" becomes
+   `termination === 'active' || termination === 'draining'`.
+   `TransitionReadyInput` is renamed `TransitionRunInput` — the same fields,
+   now also taken by `transitionProcessDraining`; rename the import.
+
+3. **Record the drain and the readiness when driving the ledger by hand.**
+   **Who must act:** only a project that calls `createProcessLifecycleLedger`
+   methods itself instead of mounting `lifecycleLedgerResource`. Call
+   `recordDraining()` where the application stops admitting work, before it
+   drains; without it downtime is counted from the recorded stop. Call
+   `recordReady()` when the run serves; a run stopped without it now ends
+   `startup-failed`, not `clean`.
+
 ## Released migration: 0.94.0
 
 One breaking minor that consolidates: tool options move into one group, and
@@ -1107,53 +1149,3 @@ else renderExistingRole(message)
 
 No data migration is needed. The schema still accepts all earlier records, and applications that
 do not exhaustively branch over these unions compile unchanged.
-
-## Released migration: 0.68.0
-
-### Make Unix transport selection explicit outside Bun
-
-The legacy `unix` option remains a Bun convenience, but on Node or another
-runtime it now fails before dispatch. Replace it with the owned adapter and close
-that adapter with the application:
-
-```ts
-// before — unsafe outside Bun: an unsupported fetch could dial baseUrl over TCP
-const http = createHttpClient({ baseUrl, unix: '/run/service.sock' })
-
-// after — Bun and Node; every dispatch and redirect stays on the socket
-import { createUnixClientTransport } from 'stitchkit/server' // or stitchkit/node
-const transport = createUnixClientTransport({ socketPath: '/run/service.sock' })
-const http = createHttpClient({ baseUrl, fetch: transport.fetch })
-// during shutdown
-await transport.close()
-```
-
-Do not automatically replay `possibly-dispatched`: a timeout or connection loss
-after bytes left the process does not prove that a write did not happen.
-
-### Choose tolerant stream parsing explicitly
-
-`parseNDJSON` and `parseSSE` now throw on malformed JSON, invalid UTF-8 and an
-over-limit line. The default line ceiling is 1 MiB. If a feed deliberately skips
-bad records, retain that policy explicitly:
-
-```ts
-// before — malformed input disappeared implicitly
-parseNDJSON(response)
-
-// after — ordinary fail-closed path
-parseNDJSON(response, { maxLineBytes: 256 * 1024 })
-
-// after — deliberately tolerant path
-parseNDJSON(response, { onParseError: (raw, error) => report(raw, error) })
-```
-
-### Extend exhaustive framework-error handling
-
-If a switch makes `StitchErrorCode` exhaustive, add
-`STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,
-`STREAM_TERMINAL_MISSING` and `STREAM_LIFETIME_EXCEEDED`. A partial application
-status map needs no change (ADR 0105).
-
-The admission/channel APIs and endpoint `stream` descriptor are additive; raw
-responses and raw `streamingRoute` remain supported.

package/llms/upgrading.txt

@@ -11,9 +11,9 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.68.0 → 0.94.0: `llms/upgrading-0.68.0-0.94.0.txt`
-- 0.53.0 → 0.67.0: `llms/upgrading-0.53.0-0.67.0.txt`
-- 0.37.0 → 0.50.0: `llms/upgrading-0.37.0-0.50.0.txt`
+- 0.69.0 → 0.95.0: `llms/upgrading-0.69.0-0.95.0.txt`
+- 0.55.0 → 0.68.0: `llms/upgrading-0.55.0-0.68.0.txt`
+- 0.37.0 → 0.53.0: `llms/upgrading-0.37.0-0.53.0.txt`
 
 # Upgrading stitchkit