stitchkit 0.59.4 → 0.60.0

package/llms-full.txt

@@ -33,24 +33,36 @@ realtime, `@tanstack/react-query` + `react-query-kit` for React). See
 
 ## Entrypoints
 
-stitchkit ships eleven entrypoints. Each is import-safe for one environment —
-keeping server-only code (`Bun.serve`, the MCP SDK) out of browser bundles.
-
-| Import | Use in | Holds |
-|--------|--------|-------|
-| `stitchkit` | browser **and** server | `defineContract`, `createClient`, `createHttpClient`, `createSocketIOClient`, `parseSSE`, the error model |
-| `stitchkit/contract` | browser **and** server | the contract layer alone — `defineContract`, errors, pagination |
-| `stitchkit/server` | server (Bun) | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
-| `stitchkit/node` | server (Node ≥ 22) | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
-| `stitchkit/tools` | server | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
-| `stitchkit/cli` | server | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
-| `stitchkit/remote` | browser **and** server | peer-free `implementRemote` for thin HTTP proxy processes |
-| `stitchkit/files` | server (Bun or Node) | peer-free managed local-file boundary |
-| `stitchkit/observability` | server | request/tool event projections — `createObservability`, trace context, sanitisation |
-| `stitchkit/agent-runtime` | server | optional durable conversation/run loop, history, models, prompts, fencing and events |
-| `stitchkit/agent-runtime/openrouter` | server | isolated OpenRouter language-model adapter |
-| `stitchkit/testing` | tests on Bun or Node | in-process generated clients over a real Fetch handler, without a TCP port |
-| `stitchkit/react` | browser | `createCursorQuery`, `createCacheBridge` |
+Every entrypoint is import-safe for one environment — keeping server-only code
+(`Bun.serve`, the MCP SDK) out of browser bundles.
+
+Each also declares how settled it is. **Stable** means the shape changes rarely
+and only with a reason worth a migration. **Evolving** means the shape is still
+being found and may be redefined in any minor — always with a
+`### ⚠️ Breaking changes` entry and a migration section, never silently. Both
+are legitimate choices; the difference is how often you should expect to read
+the changelog. Moving an entrypoint from evolving to stable is a decision on its
+own, recorded as an ADR.
+
+| Import | Use in | Maturity | Holds |
+|--------|--------|----------|-------|
+| `stitchkit` | browser **and** server | stable | `defineContract`, `createClient`, `createHttpClient`, `createSocketIOClient`, `parseSSE`, the error model |
+| `stitchkit/contract` | browser **and** server | stable | the contract layer alone — `defineContract`, errors, pagination |
+| `stitchkit/server` | server (Bun) | stable | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
+| `stitchkit/node` | server (Node ≥ 22) | stable | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
+| `stitchkit/tools` | server | stable | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
+| `stitchkit/cli` | server | stable | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
+| `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
+| `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
+| `stitchkit/observability` | server | stable | 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 store and managed-resource conformance kits |
+| `stitchkit/declaration` | build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
+| `stitchkit/react` | browser | stable | `createCursorQuery`, `createCacheBridge` |
+| `stitchkit/agent-runtime` | server | evolving | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
+| `stitchkit/application` | server | evolving | managed resource graph, readiness, admission, schedules 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` |
 
 Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
 code adds `stitchkit/server` (or `stitchkit/node` on Node) and opts into
@@ -155,7 +167,9 @@ map — feature → packages:
 | React data layer (`stitchkit/react`) | `@tanstack/react-query` `react-query-kit` |
 | **Socket.IO server on Bun** | `socket.io` `@socket.io/bun-engine` |
 | **Socket.IO server on Node** | `socket.io` |
-| Socket.IO client | `socket.io-client` |
+| Socket.IO client | `socket.io-client` (brings `@socket.io/component-emitter`, which the browser declarations reference for types only) |
+| grammY lifecycle adapters (`stitchkit/application/grammy`) | `grammy` |
+| OpenTelemetry gauges (`stitchkit/application/opentelemetry`) | `@opentelemetry/api` |
 
 ```bash
 bun add socket.io @socket.io/bun-engine    # e.g. the Socket.IO server on Bun
@@ -375,12 +389,13 @@ With this policy, omitting `expose` materializes `['HTTP']` on the returned
 endpoint. MCP, Agent and CLI then require an explicit endpoint array. The plain
 factory and `defineContract` keep the default-on behaviour above.
 
-Tool transports (`MCP`, `AGENT`) skip three kinds of endpoint automatically:
-`multipart` (a file upload is not a tool call) and
+Tool transports (`MCP`, `AGENT`) skip four kinds of endpoint automatically:
+`multipart` (a file upload is not a tool call),
 [`rawResponse`](./server.md#raw-response-endpoints) (its answer is bytes, which
-a tool result cannot carry — it would serialize to `{}`), plus
+a tool result cannot carry — it would serialize to `{}`),
 [`responseMeta`](./server.md#typed-json-response-metadata) (outbound HTTP
-headers have no meaning on a tool call).
+headers have no meaning on a tool call) and `rawBody` (HTTP-only by
+construction).
 
 ## `toolName`
 
@@ -395,11 +410,13 @@ derivation from the method key + prefix (`users` + `create` ⇒ `create_user`,
 **Every tool name — derived or explicit — must match `[a-zA-Z0-9_-]` and be at
 most 64 characters**, the character class every major provider accepts.
 
-Note the two classes differ. What is *accepted* includes the hyphen; what
-derivation *keeps* does not — a derived name normalises everything outside
-`[a-zA-Z0-9_]` to `_`, the hyphen included, so `bot-status` + `get` ⇒
-`get_bot_status` and `admin/analytics` + `get` ⇒ `get_admin_analytics`. A hyphen
-survives only in an explicit `toolName`, which is taken verbatim.
+Derivation normalises **per half**, and the halves differ (→ ADR 0035). The
+*service* half collapses everything outside `[a-zA-Z0-9_]` to `_`, hyphen
+included: `bot-status` + `get` ⇒ `get_bot_status`, `admin/analytics` + `get` ⇒
+`get_admin_analytics`. The *method* half keeps its hyphen and normalises only
+what no provider accepts (`[^a-zA-Z0-9_-]`), because a hyphenated method key has
+always shipped a legal name that a client config may already pin: `notes` +
+`get-user` ⇒ `get-user_notes`. An explicit `toolName` is taken verbatim.
 
 A prefix with *no* usable character at all (`'///'`, `'_'`, a fully non-ASCII
 prefix) and any explicit `toolName` outside the accepted class **throw at
@@ -1740,14 +1757,21 @@ without repeating transport configuration.
 `headers` as a function is the hook for runtime tokens — a bearer token or any
 short-lived credential — re-evaluated on every request.
 
-Expected 401 policy is explicit and contract-driven. Select individual
-operations with `contractEndpointMatchers(contract, ['login'])`, or omit the
-second argument to select every HTTP operation in that contract. Pass the same
+Expected 401 policy is explicit and contract-driven. Name the operations you
+mean with `contractEndpointMatchers(contract, ['login'])`, or omit the second
+argument to select every HTTP operation in that contract. Pass the same
 `ContractClientConfig` as the typed client when routes use a static or dynamic
 `pathPrefix`; dynamic matchers require `stripPrefixKeys`, so the helper can
-compile the prefix structure without a concrete tenant id. Matching is exact by
-path segments, including params and trailing wildcards — a shared prefix never
-suppresses a neighbouring protected endpoint.
+compile the prefix structure without a concrete tenant id.
+
+**Matching is by PATH, not by operation.** Each named operation compiles to its
+path pattern, matched exactly by segments including params and trailing
+wildcards — so a shared *prefix* never suppresses a neighbour, but two
+operations on the **same path** are one matcher. If `login` is `POST /session`
+and `session` is `GET /session`, naming `login` suppresses the expected-401
+signal for both, and a real expired session stops raising `unauthorized`. Give
+an operation you must distinguish a path of its own, or narrow the policy with
+your own `(pathname) => boolean`.
 
 ### Unix domain sockets
 
@@ -2179,8 +2203,10 @@ By default every endpoint is a tool on every transport. `expose` narrows it:
 { method: 'GET', path: '/lookup', desc: 'Look up a price', expose: ['MCP'] }     // MCP tool only
 ```
 
-Two kinds of endpoint are **never** tools, whatever `expose` says: a `multipart`
-upload (not a tool call), and a
+Four kinds of endpoint are **never** tools, whatever `expose` says: a
+`multipart` upload (not a tool call), a `rawBody` endpoint (HTTP-only by
+construction), a [`responseMeta`](./server.md#typed-json-response-metadata)
+endpoint (outbound HTTP headers mean nothing on a tool call), and a
 [`rawResponse`](./server.md#raw-response-endpoints) endpoint (its answer is
 bytes — a tool result cannot carry them, and it would reach the model as `{}`).
 Pin the full list with `listToolNames` in a snapshot test.
@@ -2188,10 +2214,12 @@ Pin the full list with `listToolNames` in a snapshot test.
 `desc` is the tool description the model reads — write it for the model, not
 just for a human. The tool name defaults
 to a verb-aware name from the method + prefix (`list` → `list_widgets`, `get` →
-`get_widget`); set `toolName` for an explicit one. Derivation normalises every
-character outside `[a-zA-Z0-9_]` to `_` — the hyphen included, so `bot-status`
-derives `get_bot_status` — while a name is *accepted* if it matches
-`[a-zA-Z0-9_-]`, so a hyphen survives in an explicit `toolName`. A name that
+`get_widget`); set `toolName` for an explicit one. Derivation normalises **per half**
+(→ ADR 0035): the service half turns everything outside `[a-zA-Z0-9_]` into `_`,
+hyphen included (`bot-status` ⇒ `get_bot_status`), while the method half keeps
+its hyphen (`get-user` ⇒ `get-user_notes`) because such a name has always been
+legal and may already be pinned in a client config. A name is *accepted* if it
+matches `[a-zA-Z0-9_-]`. A name that
 still cannot be delivered (illegal explicit `toolName`, over 64 characters, or a
 prefix with no usable character) throws at mount rather than at the first model
 call —
@@ -3363,6 +3391,11 @@ updated: 2026-08-22
 
 # Agent application runtime
 
+> **Maturity: evolving.** This surface is still finding its shape and may be
+> redefined in any minor release — always with a `### ⚠️ Breaking changes` entry
+> and a migration section, never silently. If your application already owns the
+> conversation loop, `mountAgent` from `stitchkit/tools` is the stable path.
+
 `stitchkit/agent-runtime` is the server-only, opinionated layer above
 `mountAgent`. Use it when the application wants Stitchkit to own conversation
 mechanics: durable acceptance, history projection, the AI SDK stream loop,
@@ -3554,17 +3587,38 @@ resolves to the same terminal run. Coalescing never mutates the active run.
 while the predecessor still owns managed callbacks. A hung predecessor blocks
 the lane in the first version.
 
-Shutdown is two-phase when a drain budget is supplied:
+Shutdown is two-phase, and both budgets carry the names they carry everywhere
+else in Stitchkit:
 
 ```ts
-await runtime.close({ drainTimeoutMs: 30_000, forceTimeoutMs: 5_000 })
+const closed = await runtime.close({ gracePeriodMs: 30_000, forceTimeoutMs: 5_000 })
+if (!closed.settled) {
+  console.warn(`exiting with ${closed.remaining} run(s) still in flight`)
+}
 ```
 
-`close` first rejects new process-local admissions and gives active runs the
-natural drain budget. Only after that budget expires does it abort them with
-reason `shutdown`; `forceTimeoutMs` bounds the final settlement wait for a
-non-cooperative model or tool. Calling `close()` without `drainTimeoutMs` keeps
-the immediate-shutdown form: abort active runs, then wait for their settlement.
+`close` first rejects new process-local admissions and gives active runs
+`gracePeriodMs` to finish on their own. Only after that budget expires does it
+abort them with reason `shutdown`; `forceTimeoutMs` then bounds the settlement
+wait for a non-cooperative model or tool, measured from the abort — the two
+budgets add up rather than overlapping.
+
+**`close()` reports what it achieved rather than promising an outcome it cannot
+reach.** The result is `{ settled, timedOut, remaining }`: `settled` when every
+in-flight run finished, `timedOut` with a `remaining` count when the force
+budget expired first. There is no combination of budgets that is both bounded
+and guaranteed to leave nothing in flight — that is the trade the budgets exist
+to make, and the result is where you read which side of it you got:
+
+| budgets | behaviour | can return with a run in flight |
+|---------|-----------|---------------------------------|
+| neither | aborts immediately, waits for settlement | no — unbounded wait |
+| `gracePeriodMs` only | waits, aborts, then waits for settlement | no — unbounded wait |
+| `forceTimeoutMs` only | aborts immediately, waits at most that long | **yes** — `timedOut` |
+| both | waits, aborts, waits at most that long | **yes** — `timedOut` |
+
+A caller that wants the old shape still writes `await runtime.close(…)` and
+ignores the result. A caller deciding whether to exit the process reads it.
 Durably queued records rejected from the local queue remain recoverable through
 `scanRecoverable`; close never marks them terminal on its own.
 
@@ -3581,7 +3635,7 @@ terminal event and operator metrics; a loser settles from canonical state withou
 ## Store operations
 
 `AgentRuntimeStore` remains the runtime-facing aggregate. Application adapters
-implement the smaller `AgentRuntimeStoreDriver`, not these eight transitions:
+implement the smaller `AgentRuntimeStoreDriver` rather than these nine members:
 
 - `acceptInputAndAssignRun`
 - `acquireRun`
@@ -3590,7 +3644,10 @@ implement the smaller `AgentRuntimeStoreDriver`, not these eight transitions:
 - `recoverRun`
 - `commitRunTerminal`
 - `replaceCompactedRange`
-- `loadSnapshot` and `scanRecoverable`
+- `loadSnapshot`
+- `scanRecoverable` — one **bounded page** of recoverable runs; `recover()`
+  calls this and nothing else, so an adapter that implements the interface has
+  everything recovery needs
 
 Every mutation carries an expected run revision or snapshot version. Input
 assignment additionally carries an idempotency identity. A conflict is a
@@ -3702,9 +3759,13 @@ base64 blobs into the neutral history store.
 
 To send a stored attachment back to a multimodal model, configure
 `history.resolveFile`. It maps the neutral file reference to AI SDK file data
-(URL, bytes, provider reference or text). Without a resolver the explicit
-`unresolvedFile` policy is `text` by default; choose `omit` or `error` when a
-placeholder would be incorrect.
+(URL, bytes, provider reference or text). Without a resolver the
+`unresolvedFile` policy applies, and it is **`omit`** by default: the file part
+simply does not reach the provider. Choose `text` for a describing placeholder —
+the filename or media type, never the storage reference, because that string is
+an address inside your infrastructure and this content travels upstream — or
+`error` to fail loudly. The `error` message does name the reference: it is
+thrown into your process, where you are owed the whole story.
 
 ## Compaction
 
@@ -3759,6 +3820,11 @@ updated: 2026-08-23
 
 # Managed application kernel
 
+> **Maturity: evolving.** This surface is still finding its shape and may be
+> redefined in any minor release — always with a `### ⚠️ Breaking changes` entry
+> and a migration section, never silently. The server, contract and client
+> surfaces it composes are stable.
+
 Use `stitchkit/application` when several process-local resources must become
 ready and shut down as one application. Keep using the lower-level server and
 signal APIs when one managed server is already the complete lifecycle boundary.
@@ -3877,10 +3943,35 @@ A required long-lived completion that rejects after startup makes readiness
 false and health unhealthy. Stitchkit records the failure but does not restart
 the resource or process.
 
-`createApplicationHealthHandler` exposes the neutral lifecycle/health snapshot
+`ApplicationResourceShutdown.failures` names the phase that failed — `start`,
+`ready`, `completion`, `admission`, `drain`, `close`, `force` — and nothing
+else. To learn *why*, pass `onResourceFailure`:
+
+```ts
+createApplication({
+  id: 'app',
+  resources,
+  onResourceFailure: ({ resourceId, phase, error }) => {
+    log.error({ resourceId, phase, err: error }, 'managed resource failed')
+  },
+})
+```
+
+It fires for every phase, including the one place the cause would otherwise be
+lost entirely: an **optional** resource failing to start. A required one
+rethrows, so its cause reaches you anyway; an optional one is swallowed on
+purpose, because the application keeps running. A throwing observer cannot
+break the lifecycle it observes.
+
+`createApplicationHealthHandler` publishes an `ApplicationStatusProjection`
 through a Fetch-compatible handler, suitable for a raw route on Bun or Node.
-Product-specific probes may be composed beside it; do not put secrets or raw
-provider failures in the response.
+The projection carries the verdict — the application's own `id`, `lifecycle`,
+`health`, `ready`, `capturedAt` and resource **counts** — and never the internal
+topology: no per-resource ids, no `dependsOn` edges, no process `epoch`, no
+admission counters.
+Those stay in `getSnapshot()`, which never leaves the process, and in whatever
+telemetry you wire to it. Product-specific probes may be composed beside it; do
+not put secrets or raw provider failures in the response.
 
 For the conventional three-route surface, reuse the same semantics instead of
 copying them into the application:
@@ -3895,8 +3986,11 @@ const rawRoutes = [
 ]
 ```
 
-`status` always returns the current sanitized snapshot with HTTP 200, including
-while starting, draining or stopped. The two probes retain the existing
+`status` always returns the current published projection with HTTP 200,
+including while starting, draining or stopped. To read the full snapshot — every
+resource, its dependency edges and the live counters — call `app.getSnapshot()`
+in-process; there is no option that publishes it over HTTP, because these routes
+are meant to be reachable. The two probes retain the existing
 readiness/liveness status and `Retry-After` policy.
 
 Applications that already own an OpenTelemetry SDK may inject its `Meter` into
@@ -4733,6 +4827,12 @@ createServer({
 realtime.emit('note:created', note)
 ```
 
+`socket.io` and, on Bun, `@socket.io/bun-engine` are optional peers, resolved
+lazily so a project that never opens a socket does not have to install them. If
+you ship **one self-contained file** to a machine with no `node_modules`, tell
+the framework how to load them so your bundler can put them inside — see
+[shipping one self-contained artifact](./testing-and-deployment.md#shipping-one-self-contained-artifact).
+
 The canonical room-broadcast example below is executed by the test suite. Its
 body is kept byte-identical to `packages/core/examples/realtime-room.ts`.
 
@@ -4768,6 +4868,12 @@ await createSocketIOServer({
 })
 ```
 
+`cors` is **optional**. Omit it when the browser reaches this server on its
+own origin — Socket.IO then emits no CORS headers, which is same-origin only.
+Supply it only for a genuinely cross-origin browser: naming a foreign origin is
+naming where the code will run, and a repository that does not have to know
+should not say.
+
 The wrapper-owned fields (`cors` / `path` / `transports` / `ping*` /
 `allowRequest`) take
 precedence over the same keys in `serverOptions`. On Bun the engine-level options
@@ -5676,11 +5782,19 @@ core never models them (ADR 0002). But stitchkit itself emits a set of its own:
 `CONFLICT`, `RATE_LIMITED`, `VALIDATION_ERROR`, `FILE_INVALID_PATH`,
 `FILE_OUTSIDE_ROOT`, `FILE_NOT_FOUND`, `FILE_NOT_REGULAR`,
 `FILE_INSPECTION_REJECTED`, `FILE_TOO_LARGE`, `FILE_EXISTS`,
-`REALTIME_CONTRACT_VIOLATION`, `INTERNAL_SERVER_ERROR` — a set that grows in
+`REALTIME_CONTRACT_VIOLATION`, `APPLICATION_NOT_ACCEPTING`, `WAIT_TIMEOUT`,
+`WAIT_FAILED`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
+`OPERATION_NOT_SUCCEEDED`, `INTERNAL_SERVER_ERROR` — a set that grows in
 ordinary releases, each addition named in the changelog. They are
 published as **`STITCH_ERROR_STATUS`** (the `code → status` map) and
 **`StitchErrorCode`** (its `keyof`), with **`isStitchErrorCode()`** (→ ADR 0026).
 
+> This list is enumerated here for reading, and the enumeration is what goes
+> stale — it once dropped `APPLICATION_NOT_ACCEPTING`, which made the map below
+> stop compiling. `Object.keys(STITCH_ERROR_STATUS)` is the answer that cannot;
+> `packages/core/tests/error-registry-completeness.test.ts` keeps the registry
+> itself complete against the source.
+
 If you translate stitch's framework errors into your own wire codes in an
 `onError` hook, you choose how the set's growth reaches you. Keying the map by
 `StitchErrorCode` makes it exhaustive, so a code stitch adds or renames becomes
@@ -5691,7 +5805,10 @@ envelope is a published contract, at the cost of an edit on those releases:
 // Exhaustive on purpose: the annotation is what turns a new stitch code into a
 // compile error here. Drop it (or use `satisfies` on a partial map) to let an
 // unmapped code travel as itself instead.
-const STITCH_TO_APP: Record<StitchErrorCode, AppCode> = {
+// `Partial`, not an exhaustive `Record`: the set grows in ordinary releases, and
+// a map written exhaustively stops compiling on every addition. Codes you leave
+// out fall through to `unmappedCode`.
+const STITCH_TO_APP: Partial<Record<StitchErrorCode, AppCode>> = {
   NOT_FOUND: 'NOT_FOUND', METHOD_NOT_ALLOWED: 'METHOD_NOT_ALLOWED',
   BAD_REQUEST: 'VALIDATION_ERROR', VALIDATION_ERROR: 'VALIDATION_ERROR',
   UNAUTHORIZED: 'UNAUTHORIZED', FORBIDDEN: 'FORBIDDEN', CONFLICT: 'CONFLICT',
@@ -6114,10 +6231,18 @@ want the row to say something other than what the framework derived (a domain
 code, a curated message, structured issues). The framework writes only when the
 context carries nothing yet, so your value always wins.
 
-**Endpoint identity is automatic.** The framework writes the matched operation's
-`(serviceName, action)` into the context at route-match, *before* validation — so
-`event.serviceName` / `event.action` are present on every event, including a
-pre-handler 400. Nothing to wire.
+**Endpoint identity is automatic — for contract operations.** The framework
+writes the matched operation's `(serviceName, action)` into the context at
+route-match, *before* validation, so both are present on every event for a
+request that matched a contract route, including a pre-handler 400. Nothing to
+wire.
+
+They are **absent** on events that never reached a contract route: a raw route
+(`openApiRoute`, an MCP mount, any `rawRoutes` entry), a request short-circuited
+by `onRequest`, and an unmatched 404 or 405. Both fields are optional in
+`RequestEvent` for exactly that reason — a sink with a `NOT NULL` column on
+either, or a dashboard grouping by `(serviceName, action)`, has to allow for
+it.
 
 When failure attribution itself is asynchronous, use `createErrorHook`'s
 `onError(error, info, ctx, endpoint)` observer. The framework awaits it before
@@ -6269,7 +6394,9 @@ A payload goes into an audit row only after `sanitizePayload`:
 - **secret-named keys are masked** — a key whose words include a secret term is
   redacted (`password`, `sessionToken`, `X-Api-Key`, `authorization`, `cookie`,
   …), while identifiers that merely contain one (`authorId`, `sessionCount`,
-  `tokenizer`) survive;
+  `tokenizer`) survive. This applies wherever a key exists — an object field and
+  a `Map` entry alike, at any depth. A `Set` member has no key, so nothing there
+  is masked by name;
 - **binary blobs** (`Uint8Array`, `Blob`, `FormData`) collapse to metadata —
   never the bytes;
 - the result is **capped** — anything over the byte limit becomes a preview.
@@ -6712,6 +6839,41 @@ runtime or type-only package outside a case's budget fails with both the case id
 and package name, so an accidental eager import cannot hide behind another
 fixture's transitive dependency.
 
+Beside the matrix, one case is about the ARTIFACT rather than the inventory: a
+program that injects the Socket.IO peer loaders is bundled and started in a
+directory with no `node_modules`, under Node and under Bun with auto-install
+off. It is checked as a pair — the same program without the loaders must fail
+there — because a positive result alone would only show that the machine
+running the check happens to have the package, which is precisely how this class
+of defect stays invisible in development.
+
+### Shipping one self-contained artifact
+
+Stitchkit resolves the optional Socket.IO peers through a variable, so a
+consumer bundling an unrelated `stitchkit/server` export never has to resolve
+them. A bundler cannot follow that, which matters if you ship **one file** to a
+machine with no `node_modules`: the package never enters the artifact and the
+failure arrives at start-up, not at build time.
+
+Pass the loaders, and the literal lives in your source where your bundler sees
+it:
+
+```ts
+const socket = await createSocketIOServer({
+  cors: { origin: env.CORS_ORIGIN },
+  peers: {
+    server: () => import('socket.io'),
+    // Bun only — on Node the engine is never asked for, and bundling a
+    // Bun-only package for Node asks the bundler to carry `bun:` imports.
+    bunEngine: () => import('@socket.io/bun-engine'),
+  },
+})
+```
+
+Omit `peers` and nothing changes: the peers stay lazy and are resolved from the
+machine. Both peers must be listed as dependencies of the package you bundle,
+because they now genuinely are.
+
 ## Deployment
 
 ### Build
@@ -6855,6 +7017,43 @@ domain run-state remain application resources and close explicitly after server
 drain. Do not call `runtime.stop()` or `socket.io.close()` in parallel with
 `shutdown()`.
 
+### Let the supervisor start the role, not a launcher
+
+A shutdown chain treats a **second** signal as "stop waiting, force it now".
+That is deliberate — it is how an operator escalates. It also means an extra
+process between the supervisor and your role can escalate for you, by
+accident.
+
+Point the supervisor at the process that serves, not at a script runner that
+starts it:
+
+```js
+// supervisor entry — the role's own process
+script: 'bun', args: ['dist/index.js']
+
+// NOT this: a launcher in between
+script: 'bun', args: ['run', 'start']
+```
+
+Measured under PM2 with the launcher form: the stop signal reaches both
+processes, the launcher forwards its copy, and the server sees two presses in
+two turns. A declared 15 s grace period ended in 1.3 ms with
+`outcome: "forced"`, `reason: "signal"` — no requests drained, and the only
+visible trace was a non-zero exit code. With the direct form, the same stop is
+`outcome: "clean"`.
+
+A workspace-filtering launcher (`bun run --filter <pkg> start`) fails harder:
+the signal never reaches the role at all, so no shutdown runs and the process
+is torn down when the launcher dies.
+
+Two habits make this visible instead of silent:
+
+- log the outcome in `onComplete`, not just the exit code —
+  `result.outcome`, `result.reason` and `result.durationMs` are the difference
+  between "drained" and "was cut off";
+- keep the supervisor's kill timeout **at or above** the grace period you
+  declared, so a slow drain is not racing its own supervisor.
+
 ### Stdio process signals
 
 An MCP stdio handle has `close()`, not managed HTTP `shutdown()` with a force
@@ -7208,6 +7407,12 @@ current one *up to* your target, and apply each snippet.
    change at each call site. There are no deprecation shims to lean on; the old
    shape is gone, so every site must move.
 
+   Then read this file's **`## Released migration: X.Y.Z`** section for each of
+   those versions. That is the half the changelog does not carry: what else
+   stops working because of the change, and what changes *silently* rather than
+   at compile time — projected history returning fewer messages, a dashboard
+   field going blank. `bun run check` in step 6 cannot see either.
+
 5. **Bump and install.** `bun add stitchkit@<target>` (or update the range), then
    `bun install`. Note the caret: `^0.7.0` is `< 0.8.0`, so crossing a breaking
    minor is always an explicit version bump, never automatic.
@@ -7217,7 +7422,193 @@ current one *up to* your target, and apply each snippet.
    runtime): bootstrap the server, one HTTP request, and any feature you rely on
    (Socket.IO connect, an MCP tool call, a multipart upload, …).
 
-## Unreleased migration: normalized agent runtime persistence
+## Released migration: 0.60.0
+
+### close() says what it achieved
+
+`AgentRuntime.close()` returned `Promise<void>` and its contract promised three
+things that cannot hold together. It now returns
+`{ settled, timedOut, remaining }`.
+
+Nothing breaks if you ignore the value:
+
+```ts
+await runtime.close({ gracePeriodMs: 30_000, forceTimeoutMs: 5_000 })
+```
+
+What DOES change is any code that relied on the old sentence "`close()` never
+returns while a run is still in flight" while naming a `forceTimeoutMs`. That
+was never true — the force budget exists precisely to stop waiting — so if your
+process exits straight after `close()`, read the result:
+
+```ts
+const closed = await runtime.close({ gracePeriodMs: 30_000, forceTimeoutMs: 5_000 })
+if (!closed.settled) {
+  // `closed.remaining` runs were still in flight. They stay recoverable
+  // through `scanRecoverable`; close never marks them terminal on its own.
+  logger.warn({ remaining: closed.remaining }, 'exiting with runs in flight')
+}
+```
+
+If you want the old guarantee, omit `forceTimeoutMs`: that is the one
+combination in which `close()` cannot return with a run in flight — and its wait
+is unbounded, which is the trade.
+
+A TypeScript consumer that wrote `const done: void = await runtime.close()` is
+the only shape that stops compiling.
+
+### one name per concept
+
+`AgentModelDeclaration` was a bare alias of `AgentModelDescriptor`, so the same
+type reached consumers under two exported names:
+
+```ts
+// before
+defineModelRegistry<Record<string, AgentModelDeclaration>>({ … })
+// after
+defineModelRegistry<Record<string, AgentModelDescriptor>>({ … })
+```
+
+A find-and-replace covers it; there is no behavioural change. Kept name is
+`AgentModelDescriptor`, the one paired with `AgentModelDescriptorSchema` and
+returned by `registry.descriptor()`.
+
+Two names that look like the same case and are **not** being merged:
+`SocketEventMap` aliases Socket.IO's `EventsMap` so a vendor's name stays out of
+our signatures, and `AgentRun.ownerId` holds the same value a runtime publishes
+as `runtimeEpoch` on its events. The latter is one identity in two roles — "who
+owns this run" and "which runtime emitted this event" — and both declarations
+now say so. Renaming either would make the fencing comparison read worse.
+
+### a reachable public surface
+
+Three exports that the public API required and did not provide, plus one option
+it accepted and ignored.
+
+```ts
+// before — identified by string, because the class was exported nowhere
+if (error instanceof Error && error.name === 'AgentRuntimeConflictError') …
+// after
+import { AgentRuntimeConflictError } from 'stitchkit/agent-runtime'
+if (error instanceof AgentRuntimeConflictError) …
+```
+
+`ActivityTokenBrand` is exported, so `ActivityProjection` can be implemented by
+a test double. `STITCH_ERROR_STATUS` gained `APPLICATION_NOT_ACCEPTING` (503) —
+only an exhaustive `satisfies Record<StitchErrorCode, …>` map stops compiling,
+and the fix is one line. `GRAMMY_WEBHOOK_NOT_ACCEPTING` is deliberately *not*
+registered: the registry belongs to the generic core, and a provider name has no
+place in a union every consumer imports. It travels as itself through a partial
+`codeMap`.
+
+`application.shutdown()` no longer accepts `retryAfterSeconds`. Delete it from
+the call — the kernel never read it. If you meant the HTTP `Retry-After` a
+draining server sends, that lives on `managedServerResource({ retryAfterSeconds })`,
+where it always did the work.
+
+### one shutdown vocabulary
+
+```ts
+// before
+await runtime.close({ drainTimeoutMs: 30_000, forceTimeoutMs: 5_000 })
+// after
+await runtime.close({ gracePeriodMs: 30_000, forceTimeoutMs: 5_000 })
+```
+
+The rename is mechanical. The behaviour change under it is not, and it is the
+reason the rename waited: two combinations were traps.
+`close({ drainTimeoutMs })` with no force budget aborted the runs and returned
+**without waiting for them to settle** — so naming a budget gave a weaker
+guarantee than naming none — and `close({ forceTimeoutMs })` with no drain
+budget never read the force budget, leaving an unbounded wait. Both now behave
+as their names say.
+
+> **Superseded.** This section once ended "and `close()` never returns while a
+> run is in flight". That was never true with a force budget — the budget exists
+> to stop waiting — and `close()` now returns `{ settled, timedOut, remaining }`
+> instead of promising it. See *Released migration: 0.60.0 → close() says what
+> it achieved*, above.
+
+If your shutdown path measured how long `close()` took, expect it to take
+longer in exactly the case where it used to return early — that is the fix, not
+a regression. Defaults stay per-surface: `ShutdownOptions.gracePeriodMs`
+defaults to 30 seconds, and the runtime's omitted budget still means "abort
+immediately", the behaviour `close()` has always had.
+
+### unresolved attachments are omitted
+
+`history.unresolvedFile` defaulted to `text`, and the placeholder it produced
+carried the storage reference:
+
+```ts
+// before — the provider received your object key
+// "[attachment: s3://bucket/tenants/42/invoice.pdf]"
+history: {}
+// after — omitted entirely by default; ask for a placeholder explicitly
+history: { unresolvedFile: 'text' }   // "[attachment: invoice.pdf]"
+```
+
+Two things to check. If a prompt relied on the model seeing *something* where an
+unresolved file was, set `unresolvedFile: 'text'` — behaviour otherwise changes
+silently, since an omitted part produces no error. And if any stored transcript
+or provider log contains the old placeholder, it contains your storage layout;
+treat those as disclosed. The `error` policy still names the reference, because
+it is thrown into your process rather than sent upstream.
+
+### one bounded recoverable scan
+
+`AgentRuntimeStore` had two scans: a mandatory unbounded one and an optional
+paged one. The runtime only ever called the optional one, so implementing the
+interface as written produced a store that threw on its first `recover()`:
+
+```ts
+// before — the mandatory member was dead, the needed one was optional
+{
+  scanRecoverable: () => loadEveryRecoverableSnapshot(),
+  scanRecoverablePage: ({ cursor, limit }) => page(cursor, limit),
+}
+// after — one member, the bounded signature the driver already used
+{ scanRecoverable: ({ cursor, limit }) => page(cursor, limit) }
+```
+
+Delete the unbounded implementation rather than porting it: loading every
+recoverable conversation to start is the shape 0.59.0 and ADR 0101 moved away
+from, and nothing calls it now. If you built on `createAgentRuntimeStore()` you
+have nothing to do **if you only pass it to the runtime** — it implements the
+bounded page for you from the same driver member. If you CALL it yourself, the
+member changed shape: `scanRecoverable()` took no argument and returned
+snapshots; it now takes `{ cursor?, limit }` — `limit` is required — and returns
+one page of descriptors.
+```ts
+// before: const stale = await store.scanRecoverable()
+// after:  const { items, nextCursor } = await store.scanRecoverable({ limit: 100 })
+```
+
+### published application status
+
+`createApplicationHealthHandler` and `createApplicationOperationalHandlers` no
+longer serialise the whole `ApplicationSnapshot`. They publish
+`ApplicationStatusProjection` — the verdict plus resource counts:
+
+```ts
+// before — the response named every resource and its dependency edges
+const { resources } = await fetch('/status').then((r) => r.json())
+resources[0].dependsOn
+// after — the topology is read in-process, where it always belonged
+app.getSnapshot().resources[0].dependsOn
+```
+
+The consequence to check is not compilation — it is whatever already consumes
+these routes. A dashboard that drew the dependency graph from `/status`, or an
+alert keyed on `admission.pending`, goes blank rather than red: the fields are
+absent, not zero. Both are available from `getSnapshot()`, so the fix is to read
+them in the process that owns the application and publish them on a channel you
+control. If a route was reachable from outside your network, treat the previous
+payload as disclosed and rotate nothing but assume the topology is known.
+
+## Released migration: 0.59.0
+
+### Normalized agent runtime persistence
 
 `AgentRuntimeStoreDriver` no longer reads and rewrites a lifetime `AgentStoredState` JSON
 aggregate. Migrate that row and its recoverable/archive projections once:
@@ -7255,6 +7646,85 @@ createAgentRuntimeStore({
 If an application implements `AgentRuntimeStore` directly, its duplicate result must also include
 the canonical `run` and the retained `assistant` for a terminal run.
 
+## Released migration: 0.58.0
+
+### The default history projection rejects invalid chronology
+
+`projectAgentHistory` no longer forwards records a provider contract cannot
+accept. A completed assistant record before the first user message, and an
+assistant record whose tool calls have no matching results, are omitted with an
+inspectable decision instead of being sent upstream:
+
+```ts
+// before — a leading assistant record was forwarded as-is
+projectAgentHistory(messages)
+// after — opt in explicitly, and only where the provider contract permits it
+projectAgentHistory(messages, { leadingAssistant: 'allow' })
+```
+
+Two consequences the changelog does not spell out. First, the projection can now
+return **fewer** messages than the history holds, so any assertion or metric
+that compared projected length against stored length will move; read the
+detailed projection instead — it reports what was omitted and why, which is the
+supported way to see the difference. Second, the omission is silent to the
+provider but not to you: if a conversation suddenly loses its leading context,
+the decision record is where that shows up, not the transcript.
+
+### Operator events redact `internalCause` by default
+
+Raw provider and tool failures no longer travel in operator events unless the
+sink asks for them:
+
+```ts
+// before — internalCause was present
+createAgentObservability({ write })
+// after — an explicit operator-only opt-in
+createAgentObservability({ write, includeInternalCause: true })
+```
+
+The consequence to check before upgrading: any dashboard, alert or log
+processor keyed on `internalCause` goes blind the moment you upgrade, and it
+goes blind quietly — the field is absent, not empty. Set the flag on the
+operator sink you own. Product delivery stays redacted regardless of the flag;
+this option cannot widen what reaches a user.
+
+## Released migration: 0.57.0
+
+### Duplicate admission results carry the complete identity
+
+Custom `AgentRuntimeStore` adapters must persist and return the input and
+assistant identities associated with an idempotency key:
+
+```ts
+// before
+return { outcome: 'duplicate', runId, snapshot }
+
+// after
+return { outcome: 'duplicate', input, inputMessageId, runId, assistantMessageId, snapshot }
+```
+
+Prefer replacing the custom aggregate reducer with `createAgentRuntimeStore()`;
+its admission record and transaction driver implement this contract
+automatically. Historical note: 0.59.0 reshaped this driver again, so an adapter
+crossing both versions should read that section first and migrate once.
+
+### `AgentRuntimeEvent` adds a post-commit `admission` variant
+
+Add it to any exhaustive publisher switch. Its `assistant` is either the pending
+placeholder for a new assignment or the canonical persisted assistant for a
+duplicate:
+
+```ts
+case 'admission':
+  await persistProductProjection(event.input, event.run, event.assistant)
+  break
+```
+
+The consequence for an exhaustive switch written without a `default` branch is a
+compile error, which is the point. The consequence for a switch that *has* a
+`default` is worse and silent: post-commit admissions fall into it and are
+projected as an unknown event. Grep for publisher switches before upgrading.
+
 ## Released migration: 0.56.0
 
 ### Surface manifests are version 2
@@ -7467,6 +7937,116 @@ export const implementFor = createScopedImplement<{
 endpoints inline in the contract literal: an endpoint hoisted into a variable
 widens its `scope` to `string` and is reported as undeclared.
 
+## Released migration: 0.49.0
+
+### The server handle became managed
+
+`createServer()` and `serveNode()` return a handle that owns admission, HTTP
+drain, realtime closure and one deadline-bounded runtime stop:
+
+```ts
+// before
+server.stop()
+await socket.io.close()
+// after
+await server.shutdown({ gracePeriodMs: 30_000 })
+```
+
+The runtime-specific instance stays reachable at `.runtime`, so an escape hatch
+you already rely on does not disappear — but code that closed transports itself,
+in its own order, is now racing the handle. Delete the manual closes rather than
+keeping both; the handle's result tells you what it drained and what it forced.
+
+### Socket.IO mounts through the whole handle
+
+```ts
+// before
+createServer({ websocket: socket.websocket, rawRoutes: [socket.route] })
+// after
+createServer({ socket })
+```
+
+One owner for the route, the WebSocket attachment and the closure. For a raw Bun
+lane, keep the composed `websocket` handler and pass `socket` beside it.
+
+### Bun native `routes` are gone
+
+Native routes run before the Fetch handler, so they bypassed managed admission —
+which means they also bypassed shutdown, logging and observability, and that is
+why they had to go rather than be wired up:
+
+```ts
+// before
+createServer({ routes: { '/health': () => Response.json({ ok: true }) } })
+// after
+createServer({ rawRoutes: [{ method: 'GET', path: '/health', handler: () => Response.json({ ok: true }) }] })
+```
+
+### The handshake policy takes a Web `Request`
+
+```ts
+// before
+createSocketIOServer({ serverOptions: { allowRequest: (req, done) => done(null, allowed(req)) } })
+// after
+createSocketIOServer({ allowRequest: (request) => allowed(request) })
+```
+
+The Node-shaped callback is gone, and the policy is now composed with shutdown
+admission on both runtimes: a handshake arriving during drain is refused for
+you.
+
+## Released migration: 0.46.0
+
+### `REALTIME_CONTRACT_VIOLATION` joined the error registry
+
+Realtime contract failures use the framework error model instead of a bare
+`ZodError`, so an exhaustive map stops compiling until the code is added:
+
+```ts
+// before
+{ …, INTERNAL_SERVER_ERROR: 'internal' } satisfies Record<StitchErrorCode, string>
+// after
+{ …, INTERNAL_SERVER_ERROR: 'internal', REALTIME_CONTRACT_VIOLATION: 'internal' } satisfies Record<StitchErrorCode, string>
+```
+
+Only an exhaustive map breaks. Since 0.56.1 `codeMap` itself is partial, so a
+map without the `satisfies` keeps compiling and lets the code travel as itself.
+
+### `RealtimeRejectedEvent.error` is an `AppError`
+
+```ts
+// before
+onRejected: ({ error }) => error.issues
+// after
+onRejected: ({ error }) => error.details?.issues   // the ZodError moves to error.cause
+```
+
+The envelope gained `reason` and `fault`. The consequence worth checking: code
+reading `.issues` directly does not fail to compile if the handler is loosely
+typed — it silently reads `undefined`. Grep for `.issues` on rejection handlers.
+
+### CLI construction refuses reserved names
+
+A contract field or tool named `json`, `wait`, `quiet`, `dry-run`, `help`,
+`version`, `wait-timeout` or `output-dir` now **throws while the CLI is built**,
+instead of being silently shadowed:
+
+```ts
+// before: app schedule_job --wait 2h  → {"path":"2h"}, exit 0
+// after:  building a CLI over a contract with a "wait" field throws
+```
+
+This one fires at startup, not at call time, so an application shipping such a
+field crashes on boot after the upgrade. That is deliberate — the old behaviour
+corrupted arguments silently — but it means the upgrade is not safe to deploy
+without building the CLI once locally.
+
+### `createToolLogger` writes to stderr
+
+stdout is the JSON-RPC channel of a stdio MCP server, and the previous
+`console.info` default corrupted it. Pass `log` to redirect if your process
+collected tool logs from stdout.
+
 ## Released migration: 0.48.0
 
 ### Typed-client request options move to `.withOptions`
@@ -8286,6 +8866,203 @@ You are on the other side of this flow — see
 allowed; write the `### ⚠️ Breaking changes` block with a before → after snippet,
 bump the minor (pre-1.0), and migrate the controlled consumers in the same pass.
 
+### Where the migration section goes while the version has no number
+
+Write it here, immediately under the flow above, as
+**`## Unreleased migration: <short slug>`**. The slug matters: several unreleased
+migrations may sit side by side, and each one belongs to whoever wrote it. Do
+**not** reuse an existing `Unreleased migration` heading for a different change —
+that is how the 0.57.0 migration was lost, overwritten by the next author before
+anyone promoted it.
+
+At release, the release commit promotes every `Unreleased migration` heading into
+one `## Released migration: X.Y.Z`, each former heading becoming a `###`
+subsection under it. This is the same move the changelog makes when `[Unreleased]`
+becomes `## [X.Y.Z]`, and it happens in the same commit.
+
+A release carrying `### ⚠️ Breaking changes` and no matching
+`## Released migration: X.Y.Z` is refused by `bun scripts/release-plan.ts` — in
+`pre-push` and again in the publishing workflow. The check starts at `0.44.0`;
+breaking versions older than that are covered by the summary sections near the
+end of this file.
+
+
+==============================================================================
+# Guide: Project declaration  (docs/guide/declaration.md)
+==============================================================================
+
+---
+title: Project declaration
+description: One machine-readable statement a repository makes about itself — identity, roles, build, requirements, release steps and the names of the values a deployment supplies.
+type: architecture
+status: active
+created: 2026-08-25
+updated: 2026-08-25
+---
+
+# Project declaration
+
+> **Maturity: evolving.** This surface is still finding its shape and may be
+> redefined in any minor release — always with a `### ⚠️ Breaking changes` entry
+> and a migration section, never silently.
+
+> **Declaring yourself is optional.** A project with no `project.json` is a
+> complete stitchkit project: nothing in `stitchkit`, `stitchkit/server`,
+> `stitchkit/node`, `stitchkit/tools` or `stitchkit/cli` reads a declaration,
+> and no build, test or start path looks for one. Read this page as an offer,
+> not a requirement — it describes what you get if you decide to say these
+> things in a machine-readable way instead of in a README.
+
+`stitchkit/declaration` is the schema for what a repository says about itself:
+what it is, the roles it runs, what it builds, what has to exist before it
+starts, what must happen once on release, and the **names** of the environment
+variables a deployment has to supply.
+
+```ts
+import { parseProjectDeclaration } from 'stitchkit/declaration';
+import declaration from '../project.json';
+
+export const appDeclaration = parseProjectDeclaration(declaration);
+```
+
+`parseProjectDeclaration` checks `schemaVersion` **before** it reads any field.
+A reader that does not recognise the version refuses the repository instead of
+interpreting it partially — a half-understood declaration is the one failure
+mode that produces a running, wrong deployment rather than an error.
+
+## Why declare yourself
+
+Because the statements exist either way, and without a schema they exist three
+times. A repository already says how many roles it runs (in a process file),
+which variables it needs (in a Zod schema), what it builds (in a script) and
+what has to happen on release (in a README paragraph). Those four copies drift
+independently, and nothing fails when they do.
+
+What a declaration buys:
+
+- **One reader can be outside the tree.** Whatever builds a source into an
+  artifact and binds that artifact into a deployment can validate the project
+  with the same schema the project validates itself with, without being told
+  anything by the author.
+- **The tool is not the format.** The schema ships from the framework and is
+  plain published TypeScript plus JSON. Any side may read `project.json`
+  through `stitchkit/declaration` — or generate a JSON Schema from it with
+  `z.toJSONSchema` — and serve the project without asking the format's author
+  for anything. A repository that only one specific tool can bring up is a fork,
+  not a dependency.
+- **Generated instead of hand-kept.** The starter renders its supervision files
+  and its client-safe identity module from the declaration, so a role added in
+  one place cannot be missing in another.
+
+What it does not buy: nothing here starts, supervises or deploys anything.
+The declaration is a statement; acting on it belongs to whatever brings a
+deployment to a source.
+
+## The boundary rule
+
+> A declaration must be complete and meaningful **when no machine exists**. A
+> field that cannot be filled in without knowing where the code will run is a
+> binding supplied by the deployment, not a declaration made by the repository.
+
+So ports, hosts, absolute URLs, connection strings, machine paths, routing
+shape, supervision policy and secrets are never *values* in a declaration. A
+binding is **named** — by the variable that will carry it — and never valued:
+
+```jsonc
+{
+  "listener": { "portVariable": "API_PORT", "bindVariable": "BIND_HOST", "readinessPath": "/health" }
+}
+```
+
+**What is guaranteed is structure**: there is nowhere in the declaration that a
+value of the place must go. A command is `executable` plus an `args` array — no
+shell string, no pipe — and no part may be an absolute path or carry an inline
+value, so `--port=8080` must be written `['--port', '8080']`, where it is
+refused as a port. A listener's variables must exist in `env.variables` with the
+right shapes. Unknown keys are refused rather than stripped.
+
+**What is filtered is the rest**: every remaining free string is checked against
+`namesAMachine` — a scheme, a protocol-relative host, an absolute or
+home-relative path, a Windows drive, a `host:port` pair, a bare IPv4 literal.
+
+The second half is hygiene, not a proof, and it is worth knowing where it stops:
+a secret written as its own argument and a hostname written as a plain word look
+like any other argument. The schema will not catch them, and it is not trying
+to — the point is that a complete declaration can be written before any machine
+exists, not that nobody can type a value into one.
+
+## Three kinds of input, not two
+
+The boundary rule separates code from the values of a place. There is a third
+kind that is neither: **data read while building**. Pages prerendered from a
+database depend on bytes that are not in the source and are not a binding, and
+moving environment variables around does not make such a build portable.
+
+Decide it **per route**, not per project:
+
+| what the bytes depend on | what is legitimate |
+| --- | --- |
+| only the source | static — built once, and portable |
+| the place (domain, port) | never static; read it from the request |
+| data | render at runtime · a declared snapshot with a digest · generate it as a release step |
+
+The default is **render at runtime**: the build needs no database, and the page
+reads its data where the data lives. Choose a declared snapshot when you need
+static bytes — the build then reads a frozen export whose digest is a declared
+input, not a live database. Choose a release step when the bytes must be
+produced on the way to the deployment; that is the same kind of step as a
+migration, not a new concept.
+
+A build that reads data it has not declared is not hermetic, and the fact is
+invisible: it succeeds on the machine that happens to have the database.
+
+## What it carries
+
+| key | what it says |
+| --- | --- |
+| `schemaVersion` | which format this is; checked before anything else |
+| `kind` | `application` or `library` |
+| `identity` | `slug`, `name`, `version`, `description` per locale |
+| `roles` | each with its own working directory, per-mode argv commands, optional listener and `drainFloorMs` |
+| `build` | the build command and the artifact paths it produces |
+| `requires` | what the code needs and does not provide, per phase (`release`, `start`) |
+| `release` | what must happen once before any role starts — migrations declared as bytes |
+| `env` | the variables a deployment must supply, by name and shape |
+
+Two details are load-bearing:
+
+- **A role may declare no listener at all.** A queue consumer, a bot or a
+  scheduler is a role like any other; readiness belongs to a role rather than to
+  the application.
+- **Migrations are declared as bytes** — `engine`, `root`, `lockfile` — not as a
+  command to run. The side that can see the deployment decides what to do with
+  them: exact contents, admission verdict, whether a preflight can be skipped
+  because nothing touches the database.
+
+## Narrowing it for your project
+
+A project that speaks exactly two locales narrows the shipped schema; it does
+not write its own copy of the rest.
+
+```ts
+import { z } from 'zod';
+import { ProjectDeclarationSchema, parseProjectDeclaration } from 'stitchkit/declaration';
+
+const Narrowed = ProjectDeclarationSchema.safeExtend({
+  identity: ProjectIdentityNarrowedSchema,
+});
+```
+
+`safeExtend` keeps the refinements the shipped schema carries. Extending the
+declaration itself is a breaking change to a published schema and moves the
+minor, with a migration section like any other.
+
+## Related
+
+- [ADR 0104](../decisions/0104-the-project-declaration-ships-from-the-framework.md)
+  — why the schema ships from the framework rather than from each project.
+- [API reference](../api/reference.md#stitchkitdeclaration) — every export.
+
 
 ==============================================================================
 # API reference  (docs/api/reference.md)
@@ -8619,6 +9396,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `RealtimeServerHandle` | _type_ | minimal Socket.IO server handle accepted by `bindRealtimeServer`; carries the handshake identity type through to `connection.raw.data` |
 | `SocketIORequestPolicy` | _type_ | runtime-neutral async-capable Web `Request` handshake admission policy |
 | `SocketIOServerConfig` | _type_ | config for `createSocketIOServer`; `handshake` is the typed identity gate — [guide](../guide/realtime.md#handshake-auth--cookie-or-token) |
+| `SocketIOPeerLoaders` | _type_ | `peers: { server, bunEngine }` — literal dynamic imports written in YOUR source, so a bundler puts the optional peers inside a self-contained artifact. Omit for the lazy default |
 | `SocketIOHandshakeConfig` | _type_ | the `handshake` gate — Zod `schema` over `handshake.auth` plus optional async `verify`; the result lands typed in `socket.data` |
 | `SocketIOServerHandle` | _type_ | typed Socket.IO server plus Bun mount fields and idempotent lifecycle |
 | `SocketIOServerLifecycle` | _type_ | non-generic Bun mount/shutdown portion accepted by `createServer` |
@@ -8696,6 +9474,10 @@ cutovers are covered by the executable
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createApplication` | function | compose a validated resource DAG into one non-restartable startup, readiness, admission and shutdown state machine |
+| `ApplicationResourceFailure` | _type_ | one resource failure with the cause its phase label cannot carry — delivered to `onResourceFailure` |
+| `ApplicationResourcePhase` | _type_ | the phase a managed resource failed in — the vocabulary of `ApplicationResourceShutdown.failures` |
+| `ApplicationShutdownOptionsSchema` / `ApplicationShutdownOptions` | schema / _type_ | the two shutdown budgets and an abort signal — without the HTTP-only `retryAfterSeconds` |
+| `ActivityTokenBrand` | const | the brand symbol `ActivityToken` carries, exported so `ActivityProjection` is implementable |
 | `defineManagedResource` | function | retain the exact typed resource declaration; every invoked start is rollback-eligible |
 | `managedServerResource` | function | adapt an existing managed server without copying its HTTP/WebSocket shutdown machine |
 | `createApplicationHealthHandler` | function | build a Fetch-clean liveness or readiness response from the sanitized application snapshot |
@@ -8754,6 +9536,9 @@ The entrypoint exports each Zod schema beside its inferred type:
 `ApplicationAdmissionSnapshotSchema` / `ApplicationAdmissionSnapshot`,
 `ManagedResourceSnapshotSchema` / `ManagedResourceSnapshot`,
 `ApplicationSnapshotSchema` / `ApplicationSnapshot`,
+`ApplicationStatusProjectionSchema` / `ApplicationStatusProjection` with
+`projectApplicationStatus` — what a status or probe endpoint may publish, and
+the function that derives it from a snapshot,
 `ApplicationResourceShutdownSchema` / `ApplicationResourceShutdown`, and
 `ApplicationShutdownResultSchema` / `ApplicationShutdownResult`.
 
@@ -8818,7 +9603,9 @@ Server-only optional application runtime. See the
 | `AgentAdmissionEventSchema` | schema | post-commit admission projection; removes store rereads but does not imply exactly-once delivery |
 | `AgentRunMetricsSchema` | schema | optional provenance-aware usage and timings; `partial` distinguishes checkpoint from terminal totals |
 | `AgentRuntimeRecoverOptions` | _type_ | bounded paged startup recovery with context resolver and explicit evidence policy |
-| `AgentSessionCloseOptions` | _type_ | natural `drainTimeoutMs` followed by shutdown abort and optional bounded `forceTimeoutMs` settlement wait |
+| `AgentRuntimeConflictError` | class | thrown when a store mutation loses to a concurrent writer — catchable by type from `stitchkit/agent-runtime` |
+| `AgentSessionCloseOptions` | _type_ | `gracePeriodMs` for natural settlement, then abort, then `forceTimeoutMs` for bounded settlement after it |
+| `AgentSessionCloseResult` | _type_ | what `close()` achieved: `settled`, or `timedOut` with `remaining` runs still in flight. Only omitting `forceTimeoutMs` guarantees nothing is in flight on return |
 | `AgentHistoryProjectionOptions` | _type_ | storage-neutral file resolver and explicit unresolved-file behavior |
 | `createAgentToolFenceLifecycle` | function | pre-effect and post-effect run ownership fence for `mountAgent` |
 | `AgentRuntimeEventSchema` | schema | transient stream lifecycle plus post-commit admission/checkpoint/run-state/terminal projections |
@@ -8866,7 +9653,7 @@ selection never splits a tool chronology and reports why every canonical record
 removed.
 
 Model exports are `AgentLanguageModelProvider`, `AgentModelCapability`,
-`AgentModelCapabilitySchema`, `AgentModelDeclaration`, `AgentModelDescriptor`,
+`AgentModelCapabilitySchema`, `AgentModelDescriptor`,
 `AgentModelDescriptorSchema`, `AgentModelRegistry`, `AgentModelRegistryConfig`,
 `AgentModelRegistrySnapshot`, `AgentModelRegistrySnapshotSchema`, `AgentModelSnapshotPolicy`,
 `AgentResolvedModel` and `validateAgentModelSnapshot`. Registry `preflight` validates availability,
@@ -9303,6 +10090,75 @@ available from `stitchkit/contract`.
 
 ---
 
+## `stitchkit/declaration`
+
+Zod-only, dependency-free. The **project declaration**: the single
+machine-readable statement a repository makes about itself, read by the project,
+by the scaffolder that writes the first copy, and by whatever builds a source and
+binds the artifact into a deployment. It ships from the framework so those
+readers cannot hold different copies of the same schema.
+
+**Declaring yourself is optional.** A project with no `project.json` is a
+complete project: nothing else in the framework imports this entrypoint, no
+build, test or start path looks for a declaration, and its absence is never an
+error or a warning.
+
+The rule the schema exists to hold: **a declaration must be complete and
+meaningful when no machine exists**. A field that cannot be filled in without
+knowing where the code will run is a binding supplied by the deployment, not a
+declaration made by the repository.
+
+**Structure is the guarantee**: nothing here requires a value of the place. A
+command is `executable` plus an `args` array, no part may be an absolute path or
+carry an inline value (`--port=8080` must be `['--port', '8080']`), paths are
+repository-relative, bindings are named by variable and never valued, and a
+listener's variables must exist in `env.variables` with matching shapes.
+
+**Hygiene is the filter**: every remaining free string is checked against
+`namesAMachine` — a scheme, a protocol-relative host, an absolute or
+home-relative path, a Windows drive, a `host:port` pair, a bare IPv4 literal —
+and a number after a port flag is refused. It catches known shapes; it is not a
+secret scanner, and a secret or hostname written as a plain argument passes.
+
+Unknown keys are **refused**, not stripped. A key one reader does not recognise
+is a disagreement between programs that never meet, and discarding it silently
+is how a partially understood declaration becomes a running, wrong deployment.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `ProjectDeclarationSchema` / `ProjectDeclaration` | schema / _type_ | the declaration: `schemaVersion`, `kind`, `identity`, `roles`, `build`, `requires`, `release`, `env` |
+| `parseProjectDeclaration` | function | parse a declaration, refusing an unrecognised `schemaVersion` **before** any field is read |
+| `PROJECT_DECLARATION_SCHEMA_VERSION` | constant | the declaration format this build understands — the number a reader refuses on |
+| `namesAMachine` | function | why a string names a particular machine, or `undefined` — the one predicate every free string is checked against |
+| `findProjectRole` | function | the role with a given name, or `undefined` |
+| `ProjectIdentitySchema` / `ProjectIdentity` | schema / _type_ | `slug`, `name`, `version` and a per-locale `description` |
+| `ProjectRoleSchema` / `ProjectRole` | schema / _type_ | one runnable role: a `workingDirectory` inside the source, per-mode `commands`, an optional `listener`, and `drainFloorMs` |
+| `ProjectCommandSchema` / `ProjectCommand` | schema / _type_ | `executable` plus `args` — argv, never a shell string |
+| `ProjectRoleCommandSchema` / `ProjectRoleCommand` | schema / _type_ | a command run under a supervisor: additionally never a script runner, because a launcher duplicates the shutdown signal |
+| `ProjectListenerSchema` | schema | `portVariable`, `bindVariable` and `readinessPath` — **absent means the role has no listener at all** |
+| `ProjectRunModeSchema` | schema | the run modes a role declares commands for |
+| `ProjectBuildSchema` | schema | build `command`, the set of `artifacts` it produces — more than one path is normal — and any declared data `inputs` |
+| `ProjectBuildInputSchema` / `ProjectBuildInput` | schema / _type_ | data the build may read: a `name`, a frozen export `path` inside the source, and the `sha256:` `digest` that pins its bytes. **Absent `inputs` means the build reads no data** — an answer, not a gap |
+| `ProjectRequirementSchema` / `ProjectRequirementPhaseSchema` | schema | something the code needs but does not provide, and the `phases` — `release`, `start` — it is needed in |
+| `ProjectReleaseSchema` / `ProjectMigrationsSchema` | schema | what must happen once before roles start; migrations are declared as `engine`, `root` and `lockfile` — **bytes, not a command to run** |
+| `ProjectEnvVariableSchema` / `ProjectEnvVariable` / `ProjectEnvShapeSchema` | schema / _type_ | a variable a deployment must supply: `name`, `shape`, `required`, and `members` for an enum |
+| `ProjectSlugSchema` | schema | lowercase hyphen-separated identity everything else is named after |
+| `ProjectDescriptionSchema` | schema | description per locale tag |
+| `RepositoryPathSchema` | schema | a path inside the source — absolute, `..`, `~` and Windows paths are refused |
+| `BindingVariableSchema` | schema | the NAME of an environment variable a deployment fills in |
+
+Version handling is **fail-closed**: an unrecognised `schemaVersion` is refused,
+never assumed compatible, and refused before any field is read so a newer
+declaration reports as a version this build cannot serve rather than as a list of
+unrecognised keys.
+
+To compose a stricter declaration, build on the exported member schemas — for
+example `ProjectDeclarationSchema.safeExtend({ identity: … })`, which keeps the
+boundary refinements in force. `ProjectDescriptionSchema` is a record, so narrow
+it by replacing the field rather than extending it.
+
+---
+
 ## `stitchkit/node`
 
 Server-only, for Node ≥ 22 (Bun uses `stitchkit/server`). The runtime-agnostic
@@ -9321,7 +10177,7 @@ runtime-agnostic pieces of `stitchkit/server` and the error helpers.
 | `NodeRuntimeServer` | _type_ | concrete `srvx/node` runtime escape hatch |
 | `NodeSocketLifecycle` | _type_ | Bun-free Socket.IO lifecycle accepted by `serveNode` |
 | `HandlerConfig` / `ServiceDef` / `RawRoute` / `RawRouteContext` | _type_ | runtime-neutral handler types; raw routes default their host server to `unknown` |
-| `SocketIORequestPolicy` / `SocketIOServerConfig` / `SocketIOServerHandle` | _type_ | runtime-neutral handshake policy, config and Bun-free Node handle with `io`, `attach` and lifecycle |
+| `SocketIORequestPolicy` / `SocketIOServerConfig` / `SocketIOPeerLoaders` / `SocketIOServerHandle` | _type_ | runtime-neutral handshake policy, config, optional-peer loaders and the Bun-free Node handle with `io`, `attach` and lifecycle |
 | `AppError` + `appError` / `badRequest` / `unauthorized` / `forbidden` / `notFound` / `conflict` / `rateLimited` | — | error helpers (same as `/contract`) |
 
 ---