stitchkit 0.94.0 → 0.95.0

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
 

package/llms-full.txt

@@ -67,11 +67,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 |
@@ -81,7 +81,7 @@ 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 |
@@ -820,7 +820,7 @@ endpoint that can never be a tool (a raw response, a stream, `responseMeta`,
 | `tool.` | Purpose |
 |---------|---------|
 | `name` | explicit tool name (default: a verb-aware derivation, below) |
-| `view` | a different answer on MCP / agent / CLI — input defaults and a projected, separately validated output; declared only with `withToolView` — see [MCP & agents](./mcp-and-agents.md#a-different-answer-for-tools--withtoolview) |
+| `view` | a different call or answer on MCP / agent / CLI — input defaults alone, or with a projected, separately validated output; declared only with `withToolView` — see [MCP & agents](./mcp-and-agents.md#a-different-answer-for-tools--withtoolview) |
 | `ui` | MCP Apps widget for the tool's results — see [MCP & agents](./mcp-and-agents.md) |
 | `annotations` | MCP behavioural hints (`readOnlyHint`, `destructiveHint`, `title`, …) |
 | `mcp` | elicitation rounds asked before the handler runs (`inputRequired`) |
@@ -3642,6 +3642,30 @@ enters the `stitchkit/tools` graph. An application that *does* run on
 `agent-runtime` gets durability through the run context and needs no option;
 where both exist the runtime's wins, because the run is recorded in its ledger.
 
+#### An effect in another system — `effect`, at most once
+
+`step` records its result **after** the body, so a body cut short by a crash
+runs again. For sending a message or starting a turn at a provider, a repeat is
+worse than a loss. The engine's `effect` records the intent **before** it runs:
+
+```ts
+const sent = await engine.effect('reply', {
+  run: () => chat.send({ clientId, text }),                 // → { messageId }
+  reconcile: (signal) => chat.findByClientId(clientId, { signal }), // → { messageId } | null
+})
+if (sent.outcome === 'uncertain') reportPossiblyLost(clientId)
+```
+
+A later call — the same process or a restarted one — that finds the intent with
+no outcome calls `reconcile`, never `run`. Found is `accepted` with the proof;
+not found is `uncertain`. Both are recorded and final: `run` is never called for
+that name again, and `uncertain` is not asked again — it is the honest third
+answer, and retrying it is the caller's decision under a new name. A `run` that
+throws, or a `reconcile` that throws or overruns `reconcileTimeoutMs` (default
+30 s), rejects with `EffectUnresolvedError` and leaves the intent for the next
+call. The proof is JSON of at most 64 KiB — the identity the recipient assigned,
+not a payload. → [ADR 0200](../decisions/0200-an-effect-is-recorded-before-it-runs.md)
+
 ### Typed MCP call metadata
 
 Contract handlers, runtime-tool handlers/factories, lifecycle and tool hooks all
@@ -4185,7 +4209,26 @@ path (one `expose: ['HTTP']`, one for the tools) duplicate the description, the
 schemas and the handler; branching on `ctx.source` teaches every handler about
 transports and still advertises the full output schema.
 
-A **tool view** declares the difference on the endpoint instead:
+A **tool view** declares the difference on the endpoint instead. Most often the
+difference is only the call — a model needs a lighter one, and the answer keeps
+its one shape:
+
+```ts
+import { defineContract, withToolView } from 'stitchkit';
+
+export const items = defineContract({ prefix: 'items' }, {
+  list: withToolView(
+    {
+      method: 'GET', path: '/:slug/items', desc: 'List items', tool: { name: 'db_items' },
+      input: ItemsQuery,        // include: z.array(...).default(['relations'])
+      output: ItemsResponse,    // one answer on HTTP and on the tools
+    },
+    { defaults: { include: [] } },   // what a tool call gets when it passes nothing
+  ),
+});
+```
+
+When the answer itself differs, the view carries its own schema too:
 
 ```ts
 import { defineContract, withToolView } from 'stitchkit';
@@ -4221,17 +4264,19 @@ export const users = defineContract({ prefix: 'users' }, {
   catalog stamp and the surface snapshot follow it. HTTP, OpenAPI, the typed
   client and the in-process [`createToolInvoker`](#in-process-calls--createtoolinvoker)
   keep the full answer — code, not a model, is calling there.
-- **Three forms, one helper.** With `output` and `project` the answer has its
-  own schema. With `project` alone it reshapes values inside the full schema.
-  With `output` alone it is a slice, and the full result must fit that schema —
-  `withToolView` refuses the endpoint at compile time when it does not.
+- **Four forms, one helper.** With `defaults` alone the call changes and the
+  answer is the full `output`, validated by it and advertised as it. With
+  `output` and `project` the answer has its own schema. With `project` alone it
+  reshapes values inside the full schema. With `output` alone it is a slice, and
+  the full result must fit that schema — `withToolView` refuses the endpoint at
+  compile time when it does not.
 - **Exposure.** A view needs a tool transport. With `createContractFactory({
   toolExposure: 'explicit' })` an endpoint without `expose` is HTTP-only, so an
   endpoint with a view names its tool transports in `expose`.
 - **What it refuses.** `defineContract` rejects a view on an endpoint with no
   tool transport or no full `output`, on a raw, `rawBody`, multipart,
-  `responseMeta` or streaming endpoint, a view that declares neither `output`
-  nor `project`, and a default for a key the input does not have, for a path
+  `responseMeta` or streaming endpoint, a view that declares no `defaults`,
+  `output` or `project` — it would change nothing — and a default for a key the input does not have, for a path
   param, or with a value the input would reject.
 
 A projection adds nothing the full result does not carry: a field the tool
@@ -6409,6 +6454,12 @@ answered the question, and the answer stands. (It used to be overwritten — and
 the example above hides that, because `healthy` is the same value that
 overwrote it.)
 
+**Reporting the same health again is not a change.** A resource may confirm its
+health on a timer; a report with the value it already reported publishes
+nothing — no new revision, no `changedAt`, no subscriber call. A change of value
+publishes once, as does the first report that confirms the `healthy` the kernel
+assumed at readiness.
+
 **A resource is required unless you write `required: false`.** That default is
 what makes the next sentence bite.
 
@@ -7010,39 +7061,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
@@ -7781,6 +7867,15 @@ fields in declaration order, so `myapp generate "a fox"` is
 `--prompt "a fox"`. A piped value fills the first required unset field:
 `echo "a fox" | myapp generate`.
 
+A token is an option only when it is a long form (`--name`, `--name=value`,
+`--`) or `-` followed by a letter. Anything else that starts with `-` is data:
+`myapp note a "- item"` fills a positional, and after an option that expects a
+value the next token is that value — `--grep -foo`, `--count -5`. The next
+token is refused as a value only when it is itself an option, so `--grep --json`
+still reports that `--grep` requires a value. A value that cannot be read as
+its field's type is refused naming the flag and what was typed:
+`--tail expects a whole number, got "abc"`.
+
 For a stable shell grammar, declare the default command, short aliases and the
 exact positional fields on `createCli`:
 
@@ -8253,6 +8348,37 @@ nothing to keep, which is not a failure.
 happens to be at the backup path is a second install of an unverified binary,
 and the day it is used is the day nobody is in a position to check.
 
+### Run it before it replaces anything — `verify`
+
+A digest proves the bytes are the ones published, not that they load. A tool
+that updates itself unattended — a daemon — and installs a build that does not
+start takes its own updater down with it, and every machine is then repaired by
+hand. `verify` is the step between "digest matched" and "target replaced":
+
+```ts
+await applyCliUpdate({
+  asset, targetPath, backupPath,
+  verify: async (candidate, signal) => {
+    const child = Bun.spawn(['bun', candidate, 'version'], { signal, stdout: 'pipe' })
+    const printed = (await new Response(child.stdout).text()).trim()
+    if ((await child.exited) !== 0 || printed !== check.version) {
+      throw new Error(`printed ${printed}, expected ${check.version}`)
+    }
+  },
+  verifyTimeoutMs: 15_000,   // default 30 000
+})
+```
+
+The verified bytes are written beside the target as an executable candidate
+with the target's extension, and `verify` gets its path — a path rather than a
+command, because a JavaScript bundle is started through its runtime. It runs
+before the backup and the replacement. If it throws or outlives
+`verifyTimeoutMs` (its `signal` aborts at the deadline), the candidate is
+removed, the target and any earlier backup are untouched, and the update is
+refused with the reason as its cause. The target is written from the checked
+bytes in memory, never from the candidate file, so nothing the candidate did
+while it ran can change what is installed.
+
 ### Two release tracks
 
 `assertCliPublishable` takes one manifest **or every manifest already
@@ -12573,6 +12699,48 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## 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
@@ -16393,12 +16561,12 @@ from the root `stitchkit`.
 | `PathParams` | _type_ | infer named `:segments` and a terminal `*wildcard` from a path literal as string params |
 | `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` and `meta` (a default every endpoint shallow-merges over) |
 | `EndpointDef` | _type_ | a single endpoint definition; `output` declares JSON response presence (`null` is data, `undefined` is invalid); `safelistedBody: true` admits the JSON body as `text/plain` from an allow-listed `Origin` — [guide](../guide/server.md#safelisted-request-bodies-beacons) |
-| `withToolView` | function | declare an endpoint's answer on the tool surface (MCP, AGENT, CLI): input `defaults`, a view `output` and an optional `project`, typed against the endpoint's own schemas; HTTP keeps the full answer — [guide](../guide/mcp-and-agents.md#a-different-answer-for-tools--withtoolview) |
+| `withToolView` | function | declare an endpoint's call and answer on the tool surface (MCP, AGENT, CLI): input `defaults`, and optionally a view `output` and a `project`, typed against the endpoint's own schemas; HTTP keeps the full answer — [guide](../guide/mcp-and-agents.md#a-different-answer-for-tools--withtoolview) |
 | `EndpointToolOptions` | _type_ | an endpoint's `tool` group — `name`, `view`, `ui`, `annotations`, `mcp`: what the tool surfaces read that HTTP does not |
 | `EndpointToolView` | _type_ | the stored shape of a tool view (`MethodDef.toolView`) |
 | `DeclaredToolView` | _type_ | a tool view as `withToolView` produces it — the only form `tool.view` accepts |
 | `WithToolView` | _type_ | the endpoint `withToolView` returns: its own tool options plus the declared view in `tool.view` — name it when a helper returns such an endpoint |
-| `ProjectedToolView` / `ReshapedToolView` / `SlicedToolView` | _type_ | the three forms `withToolView` accepts: own schema + `project`, `project` inside the full schema, a slice by `output` |
+| `DefaultsOnlyToolView` / `ProjectedToolView` / `ReshapedToolView` / `SlicedToolView` | _type_ | the four forms `withToolView` accepts: input `defaults` alone with the full answer, own schema + `project`, `project` inside the full schema, a slice by `output` |
 | `ToolViewCall` | _type_ | what `project` is told besides the full result: the parsed `input` and the `source` |
 | `ToolViewSliceMismatch` | _type_ | the compile-time refusal of a slice whose schema does not accept the full output |
 | `ToolViewNeedsToolTransport` | _type_ | the compile-time refusal of a view on an `expose: ['HTTP']` endpoint |
@@ -16801,11 +16969,11 @@ cutovers are covered by the executable
 | `createApplication` | function | compose a validated resource DAG into one startup, readiness, admission and shutdown state machine |
 | `StateStore` / `StateStoreUpdate` | _type_ | async atomic read/update boundary shared by durable application state machines |
 | `createProcessLifecycleLedger` / `ProcessLifecycleLedger` / `ProcessLifecycleLedgerConfig` | function / _type_ | durable bounded run history and typed fact subscription |
-| `LifecycleRunSchema` / `LifecycleRun` / `LifecycleStateSchema` / `LifecycleState` / `LifecycleTerminationSchema` / `LifecycleTermination` | schema / _type_ | versioned process-run state and termination vocabulary |
-| `PreviousExitSchema` / `PreviousExit` / `StartFact` / `ReadyFact` / `ShutdownFact` / `ProcessLifecycleFact` | schema / _type_ | first-boot, hot-reload, clean, forced, handoff and abnormal lifecycle facts |
-| `transitionProcessStart` / `transitionProcessReady` / `transitionProcessShutdown` | function | pure idempotent runId+pid-owned transitions |
-| `LifecycleTransition` / `TransitionStartInput` / `TransitionReadyInput` / `TransitionShutdownInput` / `SameVersionOverlap` | _type_ | pure transition inputs, the same-build overlap policy (`abnormal` default / `handoff`) and state+fact result |
-| `lifecycleLedgerResource` / `LifecycleLedgerResource` / `LifecycleLedgerResourceConfig` | function / _type_ | managed-resource adapter that records start, readiness and shutdown |
+| `LifecycleRunSchema` / `LifecycleRun` / `LifecycleStateSchema` / `LifecycleState` / `LifecycleTerminationSchema` / `LifecycleTermination` | schema / _type_ | versioned process-run state — open (`active`, `draining` with `unavailableAt`) and ended (`clean`, `forced`, `startup-failed`, `hot-reload`, `abnormal`) |
+| `PreviousExitSchema` / `PreviousExit` / `StartFact` / `ReadyFact` / `DrainingFact` / `ShutdownFact` / `ProcessLifecycleFact` | schema / _type_ | first-boot, hot-reload, clean, forced, startup-failed, handoff and abnormal lifecycle facts; `processGapMs` on start, `downtimeMs` (unavailable → ready) on ready |
+| `transitionProcessStart` / `transitionProcessReady` / `transitionProcessDraining` / `transitionProcessShutdown` | function | pure idempotent runId+pid-owned transitions |
+| `LifecycleTransition` / `TransitionStartInput` / `TransitionRunInput` / `TransitionShutdownInput` / `SameVersionOverlap` | _type_ | pure transition inputs (`TransitionRunInput` for ready and draining, extended with `forced` for shutdown), the same-build overlap policy (`abnormal` default / `handoff`) and state+fact result |
+| `lifecycleLedgerResource` / `LifecycleLedgerResource` / `LifecycleLedgerResourceConfig` | function / _type_ | managed-resource adapter that records start, readiness, admission stop (draining) and shutdown |
 | `createNotificationOutbox` / `NotificationOutbox` / `NotificationOutboxConfig` | function / _type_ | bounded at-least-once queue with durable claims, leases, retries and supersede |
 | `NotificationOutboxItem` / `NotificationOutboxReceipt` / `NotificationOutboxState` / `NotificationSend` / `NotificationFailureClassification` / `DroppedNotification` / `EnqueueNotification` | _type_ | versioned queue records, stable send identity and delivery decisions |
 | `notificationOutboxStateSchema` | function | strict persisted-state schema over an application payload schema |
@@ -17817,7 +17985,9 @@ mountAgent(services, { durability: (toolCallId) => myLedgerFor(toolCallId) });
 | `DurableJsonValue` | _type_ | what a durable step result may hold — a record is read back in another process, so it must be JSON |
 | `createLocalStepDurability` | function | the durability engine — replay, absolute deadlines, park/deliver — over a two-method ledger the application owns |
 | `StepDurabilityLedger` | _type_ | the two methods an engine needs: `appendEvent`, `readEvents` |
-| `LocalStepDurability` | _type_ | what the engine returns; satisfies `ToolDurability` and adds `deliver` and record introspection for the ledger's owner |
+| `LocalStepDurability` | _type_ | what the engine returns; satisfies `ToolDurability` and adds `deliver`, `effect` and record introspection for the ledger's owner |
+| `EffectHandlers` / `EffectOutcome` / `EffectRunOptions` | _type_ | `effect(name, { run, reconcile }, { signal, reconcileTimeoutMs })`: the intent is recorded before `run`, an intent without an outcome is settled by `reconcile` and never run again; `accepted` with the proof or a recorded, final `uncertain` → ADR 0200 |
+| `EffectUnresolvedError` | class | an effect whose outcome this call could not settle — `run` or `reconcile` threw, `reconcile` overran, the proof was not recordable; the intent stands and the next call reconciles |
 | `LocalStepDurabilityOptions` | _type_ | `{ store, conversationId, runId, signal?, subscribe?, clock? }` |
 | `AppendAgentStoreEvent` / `ReadAgentStoreEvents` / `AgentStoreEventEnvelope` / `AgentStoreEventPage` | _type_ | the ledger's row shapes, re-exported so a ledger is typed from the entrypoint that consumes it |
 | `AgentToolError` | class | the model-safe envelope a failed agent tool throws |
@@ -17996,6 +18166,9 @@ available from `stitchkit/contract`.
 | `ManagedFileError` / `ManagedFileErrorCode` | class / _type_ | stable boundary failures; registered `FILE_*` mistakes are caller-safe while `FILE_IO_ERROR` remains internal |
 | `ManagedFileInspector` | _type_ | bounded-prefix read/write inspection callback with a finite cancellation signal that cannot own path or size |
 | `ManagedFileInspectionInput` / `ManagedFileInspection` | _type_ | inspector prefix/name/declared media/signal input and validated metadata-only result |
+| `writeFileAtomic` / `writeFileAtomicSync` / `WriteFileAtomicOptions` | function / _type_ | replace a file atomically: a random staging name created exclusively (never through a planted link), the mode set on the descriptor before the file is visible (default `0o600`, not masked by the umask), `fsync`, rename; a failure leaves the target and no staging file. The asynchronous form keeps the event loop running |
+| `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; an ownerless lock only after `ownerlessGraceMs` |
+| `ExclusiveLockError` | class | `LOCK_TIMEOUT` naming the resource and its holder, or `LOCK_ABORTED` with the signal's reason |
 
 ---
 
@@ -18276,7 +18449,7 @@ SDK nor the `ai` peer.
 | `CliBuildStampSchema` / `CliBuildStamp` | schema / _type_ | the version/commit/build time carried inside a binary |
 | `CliInstallerConfig` | _type_ | manifest, binary name, default install directory, and an optional `asset` — omit it for one script that selects the target by `uname` |
 | `CliUpdateCheckConfig` / `CliUpdateCheck` | _type_ | check inputs, and its four answers — `skipped`, `current`, `outdated`, `unknown` |
-| `CliUpdateApplyConfig` / `AppliedCliUpdate` | _type_ | apply inputs and the replaced path, byte count and digest |
+| `CliUpdateApplyConfig` / `AppliedCliUpdate` | _type_ | apply inputs — including `verify`, run on an executable candidate beside the target before the backup and the replacement, within `verifyTimeoutMs` — and the replaced path, byte count and digest |
 | `CliProfileStore` / `CliProfileStoreConfig` / `ResolvedCliProfile` | _type_ | the profile store, its directory/schema/hint config, and one resolution |
 | `CliResultView` | _type_ | the requested view — `count`, `sum`, or `records` (ordered and/or table-rendered) |
 | `CliViewOutput` | _type_ | a JSON value, or the one human-facing text shape |

package/llms.txt

@@ -12,13 +12,13 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 15.1 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 35.0 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 14.2 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.2 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.6 KB
-- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 47.2 KB → [llms/tools.2.txt](llms/tools.2.txt) 46.2 KB
+- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 44.9 KB → [llms/tools.2.txt](llms/tools.2.txt) 26.3 KB → [llms/tools.3.txt](llms/tools.3.txt) 25.4 KB
 - **stitchkit/tools/contract**: [llms/tools-contract.txt](llms/tools-contract.txt) 0.2 KB
 - **stitchkit/tools/invoker**: [llms/tools-invoker.txt](llms/tools-invoker.txt) 0.2 KB
 - **stitchkit/tools/connections**: [llms/tools-connections.txt](llms/tools-connections.txt) 3.1 KB
-- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 46.9 KB
+- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 41.3 KB → [llms/cli.2.txt](llms/cli.2.txt) 8.1 KB
 - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
-- **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 31.8 KB
+- **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 31.9 KB
 - **stitchkit/primitives**: [llms/primitives.txt](llms/primitives.txt) 9.3 KB
 - **stitchkit/server**: [llms/server.txt](llms/server.txt) 45.3 KB → [llms/server.2.txt](llms/server.2.txt) 14.6 KB → [llms/server.3.txt](llms/server.3.txt) 42.7 KB → [llms/server.4.txt](llms/server.4.txt) 37.3 KB → [llms/server.5.txt](llms/server.5.txt) 21.8 KB
 - **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 42.8 KB
@@ -30,14 +30,14 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/agent-runtime/openrouter**: [llms/agent-runtime-openrouter.txt](llms/agent-runtime-openrouter.txt) 1.1 KB
 - **stitchkit/agent-runtime/sqlite/bun**: [llms/agent-runtime-sqlite-bun.txt](llms/agent-runtime-sqlite-bun.txt) 1.8 KB
 - **stitchkit/agent-runtime/sqlite/node**: [llms/agent-runtime-sqlite-node.txt](llms/agent-runtime-sqlite-node.txt) 1.7 KB
-- **stitchkit/application**: [llms/application.txt](llms/application.txt) 47.3 KB → [llms/application.2.txt](llms/application.2.txt) 22.0 KB
+- **stitchkit/application**: [llms/application.txt](llms/application.txt) 40.1 KB → [llms/application.2.txt](llms/application.2.txt) 31.9 KB
 - **stitchkit/application/grammy**: [llms/application-grammy.txt](llms/application-grammy.txt) 1.5 KB
 - **stitchkit/application/opentelemetry**: [llms/application-opentelemetry.txt](llms/application-opentelemetry.txt) 1.6 KB
 - **stitchkit/application/diagnostic-journal**: [llms/application-diagnostic-journal.txt](llms/application-diagnostic-journal.txt) 1.4 KB
 - **stitchkit/application/schemas**: [llms/application-schemas.txt](llms/application-schemas.txt) 1.8 KB
 - **stitchkit/testing**: [llms/testing.txt](llms/testing.txt) 30.8 KB
 - **stitchkit/agent-runtime/sandbox**: [llms/agent-runtime-sandbox.txt](llms/agent-runtime-sandbox.txt) 8.1 KB
-- **stitchkit/files**: [llms/files.txt](llms/files.txt) 2.0 KB
+- **stitchkit/files**: [llms/files.txt](llms/files.txt) 2.9 KB
 - **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 2.0 KB
 - **stitchkit/tracking**: [llms/tracking.txt](llms/tracking.txt) 16.8 KB
 - **stitchkit/release**: [llms/release.txt](llms/release.txt) 8.9 KB
@@ -50,9 +50,9 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 10.3 KB
-- **Upgrading 0.68.0 → 0.94.0**: [llms/upgrading-0.68.0-0.94.0.txt](llms/upgrading-0.68.0-0.94.0.txt) 46.5 KB
-- **Upgrading 0.53.0 → 0.67.0**: [llms/upgrading-0.53.0-0.67.0.txt](llms/upgrading-0.53.0-0.67.0.txt) 46.1 KB
-- **Upgrading 0.37.0 → 0.50.0**: [llms/upgrading-0.37.0-0.50.0.txt](llms/upgrading-0.37.0-0.50.0.txt) 31.6 KB
+- **Upgrading 0.69.0 → 0.95.0**: [llms/upgrading-0.69.0-0.95.0.txt](llms/upgrading-0.69.0-0.95.0.txt) 46.6 KB
+- **Upgrading 0.55.0 → 0.68.0**: [llms/upgrading-0.55.0-0.68.0.txt](llms/upgrading-0.55.0-0.68.0.txt) 47.0 KB
+- **Upgrading 0.37.0 → 0.53.0**: [llms/upgrading-0.37.0-0.53.0.txt](llms/upgrading-0.37.0-0.53.0.txt) 32.6 KB
 
 ## Guide (web)
 - [Getting started](https://github.com/max-listov/stitchkit/blob/master/docs/guide/getting-started.md): install, entrypoints, and a first contract → server → client app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.94.0",
+  "version": "0.95.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",