stitchkit 0.104.2 → 0.105.0

package/llms/{upgrading-0.62.0-0.80.0.txt → upgrading-0.68.0-0.94.0.txt}

@@ -1,14 +1,573 @@
-# Upgrading 0.62.0 → 0.80.0 — stitchkit docs slice
+# Upgrading 0.68.0 → 0.94.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.62.0 → 0.80.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.68.0 → 0.94.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.62.0 → 0.80.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.68.0 → 0.94.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.94.0
+
+One breaking minor that consolidates: tool options move into one group, and
+names that were exported from two entrypoints keep only their owner. Every step
+is an edit a type checker or `defineContract` points at; the few behaviour
+changes that need no edit are under Changed and Fixed in the changelog.
+
+1. **Move endpoint tool options into `tool`.** **Who must act:** every project
+   with an endpoint that sets `toolName`, `ui`, `annotations` or `mcp`. Run the
+   codemod from a checkout of this repository, then typecheck:
+
+   ```bash
+   bun packages/core/scripts/codemod-tool-group.ts --check path/to/your/src   # list
+   bun packages/core/scripts/codemod-tool-group.ts path/to/your/src           # rewrite
+   ```
+
+   ```ts
+   // before
+   { method: 'GET', path: '/', desc: 'List', toolName: 'user_list', mcp: { inputRequired } }
+   // after
+   { method: 'GET', path: '/', desc: 'List', tool: { name: 'user_list', mcp: { inputRequired } } }
+   ```
+
+   The codemod leaves two kinds of endpoint for a person and prints where: one
+   built with a spread (`{ ...base, toolName }`), and one exposed on HTTP only,
+   whose tool options never reached a tool — delete them there. Anything left
+   over fails at startup, by name — a key moved into the group under its old
+   name (`tool: { toolName }`) included:
+
+   ```text
+   Contract "users": endpoint "list" sets `toolName` — tool options live in `tool` since 0.94.0: use tool.name
+   ```
+
+   `expose` does not move. `MethodDef` — what hooks and runtime tools see — keeps
+   `toolName`, `ui`, `annotations` and `mcp` at the top level, so hook code does
+   not change. A tool view is declared only with `withToolView`, which now puts
+   it in `tool.view`.
+
+2. **Change imports of moved names.** **Who must act:** projects importing any
+   of these; the compiler lists every site.
+
+   | Name | From | To |
+   |---|---|---|
+   | `RuntimeToolTransport`, `ToolSurfaceTransport`, `ToolInvokerTransport` | `stitchkit/tools`, `stitchkit/tools/invoker`, `stitchkit/tools/connections` | `ToolTransport` from `stitchkit/contract` |
+   | `createCli`, `defineCliCommand`, `CliConfig`, `CliSurfaceSource`, `CliPresentationPolicyConfig`, `CliWaitConfig`, `ExitCodeMap`, `CliCommand*` | `stitchkit/tools` | `stitchkit/cli` |
+   | `parseSSE`, `ParseSSEOptions` | `stitchkit/server` | `stitchkit` |
+   | `runAgentStoreConformance`, `AgentStoreConformance*`, `createAgentRace*`, `AgentRace*` | `stitchkit/testing` | `stitchkit/agent-runtime/testing` |
+   | `createLocalStepDurability`, `LocalStepDurability`, `LocalStepDurabilityOptions`, `StepDurabilityLedger` | `stitchkit/agent-runtime` | `stitchkit/tools` |
+
+3. **Regenerate a surface snapshot only if it reports drift.** **Who must act:**
+   a project whose committed snapshot has an object with integer-like keys
+   (`"9"`, `"10"`) — they are now sorted like every other key. Every other
+   snapshot, CLI manifest signature and agent-store archive is byte-identical.
+
+## Released migration: 0.93.0
+
+1. **Regenerate every committed surface snapshot, once.** `manifestVersion` is
+   `3` and each operation row gained `mcp` — the rounds it declares before it
+   runs. Most rows get `null`, so the first diff is large and mechanical.
+   **Who must act:** anyone with a committed snapshot. A snapshot on the older
+   version is refused by name rather than failing a schema literal:
+
+   ```text
+   Surface snapshot is manifestVersion 2; this build writes 3. Regenerate it
+   and review the diff — the format changed, so the first regeneration is
+   expected to be large.
+   ```
+
+   ```ts
+   // before — a declared round left no trace, so declaring or removing one
+   // passed review invisibly
+   manifest.operations[0]
+   // after
+   manifest.operations[0].mcp
+   // null | { inputRequired: [{ key, message, schema }] }
+   //      | { inputRequired: 'resolved-per-call' }
+   ```
+
+   A project that kept its own test for "declared `inputRequired` implies a
+   configured state key" can drop it: the snapshot holds that link now.
+
+2. **Nothing else to do.** Native commands that declare `output` became
+   invokable in process; a name that answered `NOT_FOUND` from
+   `createCliInvoker` in 0.92.0 may now resolve. If an application relied on
+   native commands being unreachable there, stop passing them to the invoker.
+
+## Released migration: 0.92.0
+
+1. **`RequestEvent.method`, `path` and `statusCode` are optional.** Work that did
+   not arrive over a transport now records their **absence** instead of inventing
+   values — a background loop used to write `method: 'AGENT'`, which is not a
+   verb. **Who must act:** anyone whose `RequestEventSinkConfig.write` puts these
+   into NOT NULL columns, or whose filter reads `event.method`.
+
+   ```ts
+   // before
+   write: (event) => db.audit.create({ data: { method: event.method, path: event.path, status: event.statusCode } })
+   // after — a job has none of the three; `kind` says which kind of row it is
+   write: (event) => db.audit.create({ data: {
+     kind: event.kind,
+     name: event.name ?? null,
+     method: event.method ?? null,
+     path: event.path ?? null,
+     status: event.statusCode ?? null,
+   } })
+   ```
+
+   A filter written as `event.method !== 'GET'` keeps jobs (`undefined !== 'GET'`),
+   which is usually what you want. To exclude them deliberately:
+   `event.kind === 'request' && event.method !== 'GET'`.
+
+2. **`applyCliUpdate` needs the manifest when given a trust root.** The signature
+   covers the manifest and every asset digest together, so an asset alone cannot
+   be verified. **Who must act:** only callers adopting signature verification;
+   the unsigned call is unchanged.
+
+   ```ts
+   // before
+   await applyCliUpdate({ asset })
+   // after
+   await applyCliUpdate({ asset, manifest: check.manifest, trust })
+   ```
+
+3. **An MCP continuation minted before this release is refused once.** The signed
+   round state now carries a fingerprint of the question plan, checked on every
+   round, so a plan that moved between rounds is a refusal rather than a
+   different question asked under the previous one's key. A conversation already
+   in flight at deploy time has no fingerprint and gets
+   `INVALID_REQUEST_STATE`; the host re-asks and the second attempt succeeds.
+   **Who must act:** nobody — but expect a small number of these in the minutes
+   after a deploy, and do not read them as tampering.
+
+## Released migration: 0.91.0
+
+1. `STITCH_ERROR_STATUS` gained `NOT_IMPLEMENTED` (501). An **exhaustive** error
+   vocabulary must name it — without the row `defineErrors({ mapping: { exhaustive:
+   true } })` stops compiling and then throws at startup. Nothing else in this
+   release requires action.
+
+   ```ts
+   // before
+   map: { …, WAIT_TIMEOUT: 'timeout' }
+   // after
+   map: { …, NOT_IMPLEMENTED: 'not_implemented', WAIT_TIMEOUT: 'timeout' }
+   ```
+
+   The code is thrown only by the new dev-only `onMissingHandler: 'stub'` policy;
+   a vocabulary that is not exhaustive is unaffected.
+
+## Released migration: 0.90.0
+
+1. `stitchkit.watch.value` is a discriminated union on `kind` — `full`, `delta`,
+   `unchanged` — and every frame carries `fingerprint`. **Both ends must come from
+   the same major.** A client older than this release reads a `delta` frame as a
+   value of `undefined`, silently; upgrade the hub and the pages that talk to it
+   together, or set `deltaMemoryBytes: 0` on the hub until they are.
+
+   Applications using `createWatchClient` need no code change: it rebuilds the
+   value and hands the listener the whole answer as before. Code that reads
+   `WatchValueFrame.value` directly — a hand-written subscriber, a test double —
+   narrows on `kind` first.
+
+   ```ts
+   // before: frame.value
+   // after:
+   if (frame.kind === 'full') hold(frame.value);
+   else if (frame.kind === 'delta') hold(applyWatchDelta(held, frame.delta));
+   // 'unchanged' leaves what you hold standing
+   ```
+
+2. `AttachedWatcher.open` takes an optional third argument, `have`. A custom
+   server binding that forwards `stitchkit.watch.open` should pass the payload's
+   `have` through; omitting it costs a whole value on every reconnection and is
+   otherwise harmless.
+
+## Released migration: 0.89.0
+
+1. Custom `AgentRuntimeStore` adapters implement `seedConversationInput`; custom
+   `AgentRuntimeStoreDriver` adapters implement `seeds.load` and `seeds.create` together
+   with atomic, ordered history insertion. Use the maintained Prisma example and run
+   `runAgentStoreConformance` against the adapter. Built-in memory and SQLite
+   stores already implement the contract; SQLite migrates to schema version 3.
+2. OpenRouter usage normalization consumes each completed SDK step's `usage`, including
+   `raw`, rather than aggregate usage. Missing counters stay `unavailable`.
+
+   ```ts
+   // before: normalizeOpenRouterUsage(await result.usage, metadata)
+   // after:
+   for (const step of await result.steps) {
+     const usage = normalizeOpenRouterUsage(step.usage, step.providerMetadata);
+     // Persist the step's measured usage with its provenance.
+   }
+   ```
+
+3. Durable step bodies return lossless JSON. Convert dates explicitly, reject invalid
+   numbers upstream, and return `null` after an effect-only operation.
+
+   ```ts
+   await context.step('send', async () => {
+     await sendIdempotently();
+     return null;
+   });
+   ```
+
+   First execution, replay and concurrent callers receive detached values. Persistence
+   does not make external effects transactional; the host retains idempotency and recovery.
+
+
+How to move a consuming project from one stitchkit version to another — including
+across many versions at once (a project frozen on an old version, then jumped
+forward). The process is mechanical: stitchkit marks every breaking change in one
+place and one format, so you can recover the full migration from the version diff.
+
+## Released migration: 0.88.0
+
+Two mechanical edits, and only if your project builds these values rather than only reading them.
+
+A completed step event now carries the provider's response identity, and the field is required:
+
+```ts
+// before
+{ type: 'step-finished', step: 0, usage }
+
+// after
+{ type: 'step-finished', step: 0, usage, response: { id: generationId } }
+```
+
+Every event the runtime emits already has it, so a sink that only reads them needs no change. A
+fixture, a test double or a pipeline that re-validates events persisted by an earlier version does:
+give the older records a response identity, or keep parsing them with the schema they were written
+under.
+
+If you implement the whole `AgentRuntime` interface — usually a mock — add the new method:
+
+```ts
+// before
+const fake: AgentRuntime = { submit, interrupt, recover, close }
+
+// after
+const fake: AgentRuntime = { submit, interrupt, abandon, recover, close }
+```
+
+No data migration is involved, and nothing in the store changes shape.
+
+## Released migration: 0.87.0
+
+Only if your project implements `AgentConversationReader` itself. A message page
+now names which of its messages compaction removed:
+
+```ts
+// before
+return { items, ...(nextCursor && { nextCursor }) }
+
+// after
+return { items, compacted: [], ...(nextCursor && { nextCursor }) }
+```
+
+An empty array is the honest answer for a reader that pages only the active
+history; it is what the SQLite reader returns unless the caller asks for
+`includeCompacted`. Calling the reader needs no change, and no data migration is
+involved.
+
+## Released migration: 0.86.0
+
+Only if you branch on `AgentTerminalReason` or show it to a person. Three
+failures that used to arrive as `provider_failure` now arrive as themselves:
+
+```ts
+// before
+if (run.terminalReason === 'provider_failure') showOutage()
+
+// after
+switch (run.terminalReason) {
+  case 'provider_failure':
+    showOutage()
+    break
+  case 'storage_conflict':
+    // Another writer took this run's revision, or the store refused the write.
+    retryOrReport()
+    break
+  case 'output_rejected':
+    // Your own `protocol.acceptTerminal` refused the finished message.
+    reportRejectedAnswer()
+    break
+  case 'runtime_failure':
+    // The runtime, or a check the SDK ran on what it was handed, failed
+    // before the provider was reached.
+    reportInternal()
+    break
+}
+```
+
+A run that never reached the provider can no longer report `provider_failure`,
+so an alert keyed on that value stops firing for causes that were never the
+provider's.
+
+If you implement `AgentRuntimeStore` directly, add the event-ledger surface:
+
+```ts
+const store: AgentRuntimeStore = {
+  // existing normalized operations
+  appendEvent,
+  readEvents,
+  exportConversation,
+  importConversation,
+}
+```
+
+If you implement an `AgentRuntimeStoreDriver` (Prisma, Postgres, any external
+database), the ledger is yours to keep: `events` is a required member, and it
+needs a table.
+
+```ts
+// before
+const driver: AgentRuntimeStoreDriver<Tx> = { transaction, head, runs, admissions, history, scanRecoverable }
+
+// after
+const driver: AgentRuntimeStoreDriver<Tx> = {
+  transaction, head, runs, admissions, history, scanRecoverable,
+  events: {
+    // One row per event; `seq` is per conversation, starts at 1, and is
+    // assigned inside the caller's transaction so concurrent appends cannot
+    // share or skip a number.
+    append: async (tx, draft) => {
+      // Two transactions that both read max(seq) and both insert max + 1
+      // collide on the primary key; under SERIALIZABLE the snapshot predates
+      // any lock you take here. Treat a unique violation on this table as a
+      // serialization conflict and re-run the whole transaction — see
+      // `runTransaction` in examples/agent-store-prisma/adapter.ts.
+      const seq = (await tx.event.aggregate({ _max: { seq: true }, where: { conversationId: draft.conversationId } }))._max.seq ?? 0
+      await tx.event.create({ data: { ...draft, seq: seq + 1, payload: JSON.stringify(draft.payload) } })
+      return { ...draft, seq: seq + 1 }
+    },
+    // Ordered by `seq`, bounded by `fromSeq`/`toSeq`/`limit`; `nextSeq` when
+    // more remain.
+    list: async (tx, input) => { /* see examples/agent-store-prisma/adapter.ts */ },
+  },
+}
+```
+
+The table carries `eventId` (unique), `conversationId`, `seq`, `schemaVersion`,
+`kind`, `occurredAt`, `ignorable` and `payload`. `runAgentStoreConformance`
+from `stitchkit/testing` now exercises it — contiguous `seq` under twenty
+concurrent appends, bounded reads, the `ignorable` flag, a byte-stable export
+— so run it against your driver before deploying. Expect one more insert per
+run operation (`runtime/transition`) and one per model step
+(`provider/request`) on the hot path; there is no opt-out.
+
+If you operate a built-in SQLite store file:
+
+1. Back the file up. The first open by 0.86.0 migrates it to schema 2 in one
+   transaction and there is no way back: a 0.85.x package refuses a migrated
+   file with `Unsupported Stitchkit agent-runtime SQLite schema version 2`.
+2. Check the build for FTS5 before deploying:
+
+   ```sql
+   SELECT sqlite_compileoption_used('ENABLE_FTS5');
+   ```
+
+   A build without it is refused at open with `requires FTS5 support`. On the
+   machine this was verified, Bun 1.3 `bun:sqlite` and Node 24.18 `node:sqlite`
+   both carry it; verify your own build rather than assuming — the table of
+   supported runtimes says Node ≥ 22.5, and FTS5 there is not verified here.
+3. Know what the migration wrote. Each existing conversation becomes one
+   `runtime/baseline` event at `seq 1`, dated when the migration ran, with
+   `asOf` inside the payload naming the last message it describes. Event
+   search and projections address that conversation's pre-migration history as
+   one snapshot at `seq 1`; event-level precision begins with the first event
+   after the migration.
+
+If you subscribe to `AgentRuntimeEvent` and switch over `event.type`
+exhaustively, add the transient `attempt-reset` case — drop the run's
+transient text — or the reducer stops compiling; a reducer that ignores it
+keeps a failed attempt's partial text on screen.
+
+New in this release, not a migration: child runs cascade only when the manager
+is given to the runtime —
+`createAgentRuntime({ ...config, children: createSqliteAgentChildManager({ sqlite, spawn }) })`
+— and the SQLite companions take the store handle (`{ sqlite }`), whose
+`database` and `transaction` they share.
+
+## Released migration: 0.85.0
+
+Only if you implement `AgentRuntimeStore` directly. Add the new durable
+operation mutation beside the existing run mutations:
+
+```ts
+// before
+const store: AgentRuntimeStore = {
+  checkpointRunAssistant,
+  commitRunTerminal,
+  // ...
+}
+
+// after
+const store: AgentRuntimeStore = {
+  checkpointRunAssistant,
+  recordRunOperation,
+  commitRunTerminal,
+  // ...
+}
+```
+
+It must atomically replace `AgentRun.lastOperation`, increment the run revision
+and conversation snapshot version, and enforce the supplied owner, fencing
+token and expected revision. Adapters built with `createAgentRuntimeStore`
+already receive the reference implementation; no driver method is added.
+
+## Released migration: 0.84.0
+
+Only if you call `createAgentCodingTools`.
+
+```bash
+rg -n "createAgentCodingTools"
+```
+
+**1. Backslashes are refused.** If anything in your system hands the tools a Windows-style path,
+it now gets `FORBIDDEN`. Convert to `/` at the boundary:
+
+```ts
+// before: read_file({ path: 'src\\index.ts' })   // reached openat as two segments
+// after:  read_file({ path: 'src/index.ts' })
+```
+
+This is the half that matters most: until now a backslash bypassed your **required**
+`authorize({ operation, path })` callback, not just `authorizePath`. A rule denying
+`credentials/token.txt` refused that spelling and served — and overwrote — the same file spelled
+`credentials\token.txt`. If your policy denies specific files, re-read your audit logs for
+backslash spellings.
+
+**2. Denying a directory now denies everything under it — and a policy must admit every directory
+on the way to a file**, the way POSIX needs `+x` on each directory in a path.
+
+If your policy is a DENY-list, it now does what it read as:
+
+```ts
+authorizePath: ({ path }) => path !== 'credentials'
+// before: hid `credentials` from glob, served `credentials/token.txt` to read_file
+// after:  refuses `credentials/token.txt`, `credentials/nested/deep.txt` and writes under it
+```
+
+If you relied on the old behaviour — a directory hidden from discovery but readable directly — you
+were relying on a defect, and the two halves of one callback disagreeing. Name the paths you
+actually want reachable instead.
+
+If your policy is an ALLOW-list, widen it to the directories it leads through, or nothing under
+them is reachable:
+
+```ts
+// before: allowed src/index.ts, because only the leaf was ever asked
+authorizePath: ({ path }) => path.startsWith('src/')
+// after: `src` itself is asked first and refused, so the file is refused too
+authorizePath: ({ path }) => path === 'src' || path.startsWith('src/')
+```
+
+The workspace root is not asked about — it is the boundary the tools already own.
+
+**3. The policy is called more often.** A path of depth N costs N+1 calls (`.`, then each ancestor,
+then the leaf), outermost first, stopping at the first refusal. A policy that logs or meters will
+see a different sequence, and will no longer see the leaf once an ancestor has refused.
+
+## Released migration: 0.83.0
+
+Two things, both mechanical, and only if you touch an observability sink.
+
+```bash
+rg -n "createObservability|createApplicationEventSink|createApplicationSnapshotSink|createAgentRuntimeEventSink|createAgentObservability"
+```
+
+**1. `flush()` returns `Promise<boolean>`.** `await sink.flush()` needs no
+change. Only a declared type does:
+
+```ts
+// before
+const flushAudit: () => Promise<void> = observability.flush
+// after
+const flushAudit: () => Promise<boolean> = observability.flush
+```
+
+**2. `ObservabilityDrainReport` carries `drained`.** The framework builds it, so
+reading code is unchanged. A hand-built report — a test double, or one persisted
+and re-parsed through `ObservabilityDrainReportSchema` — needs the field:
+
+```ts
+// before
+{ request, tools, total, durationMs }
+// after
+{ request, tools, total, durationMs, drained: true }
+```
+
+Then take the thing this release exists for. Every drain now accepts
+`{ timeoutMs?, signal? }`, so a shutdown can give the audit drain the same
+deadline it gives every other step:
+
+```ts
+const report = await observability.close({ timeoutMs: 5_000 })
+if (!report.drained) {
+  logger.warn('audit drain incomplete', {
+    unwritten: report.total.received - report.total.filtered - report.total.completed,
+  })
+}
+```
+
+The bound ends the **waiting**, not the writes: a sink's `write` is handed no
+cancellation, so an outstanding one keeps running against whatever you close
+next. Racing `close()` against your own timer looks equivalent and is not — it
+discards the report along with the wait.
+
+## Released migration: 0.82.0
+
+One thing, and only if you mount MCP or agent tools from a `createTrackingContract` contract.
+
+```bash
+rg -n "createTrackingContract"
+```
+
+The event ingest (`track`, `POST /events`) is now `expose: ['HTTP']`, which is
+what its sibling `bootstrap` always declared. Before, it declared nothing — and
+an endpoint with no `expose` is a tool on MCP and AGENT by default, so the
+mounted surface carried a `track_<prefix>` tool. Since this contract is built
+inside the framework, an application that had made every tool opt-in for the
+endpoints *it* authors could not have opted this one out.
+
+**If you pin a tool-surface digest or count**, it moves by one; re-record it.
+**If you assert on tool names**, `track_<prefix>` is gone. **If nothing in your
+project mounts tools from this contract**, there is nothing to do — the HTTP
+routes, the client and the schemas are unchanged.
+
+Un-declaring the tool was never the intent, so there is no option to keep it. If
+an agent in your system genuinely needs to record something, give it your own
+endpoint with your own schema: the browser ingest trusts a client-minted event
+id and a visit lease, and an agent holds neither.
+
+## Released migration: 0.81.0
+
+**Path literals own string params.**
+
+An endpoint whose path contains `:id` or a terminal `*rest` no longer needs a
+duplicate `params: z.object({ …string() })` declaration. Remove schemas that do
+nothing beyond repeating path names:
+
+```ts
+// before
+{ path: '/projects/:projectId/*filePath',
+  params: z.object({ projectId: z.string(), filePath: z.string() }) }
+
+// after
+{ path: '/projects/:projectId/*filePath' }
+```
+
+Keep an explicit schema when it validates or coerces. It must cover every name
+in the path — an explicit schema that misses one now fails at `defineContract`
+with the path and the missing field named. Client calls and handler contexts
+infer the string fields from the literal, so a call that omitted one becomes a
+compile error instead of building a URL with an unresolved segment. Measured
+across three consuming applications before release (373 endpoints with path
+segments), no explicit schema missed a field: the migration is deleting
+schemas that only repeated the path, or nothing.
+
 ## Released migration: 0.80.0
 
 One thing, and only if you parse an async-operation snapshot.
@@ -598,576 +1157,3 @@ status map needs no change (ADR 0105).
 
 The admission/channel APIs and endpoint `stream` descriptor are additive; raw
 responses and raw `streamingRoute` remain supported.
-
-## Released migration: 0.67.0
-
-Three application-kernel changes. Two of them fix silent failures, so the most
-important part of this migration is not what the compiler points at — it is the
-two things that change with no compile error at all: **when your server is
-created**, and **which shutdown budget a signal spends**.
-
-### If you gave `managedServerResource` a thunk
-
-It is now called during `start`, after the resource's dependencies are ready —
-the reading the type always suggested. Before, it was called on the way *down*,
-so `app.start()` resolved, the snapshot said `healthy` and `ready`, and nothing
-was bound to the port.
-
-If your application looked like this, it was never listening:
-
-```ts
-// before — resolves clean, listens on nothing
-managedServerResource({ id: 'http', dependsOn: ['database'], server: () => createServer(config) })
-```
-
-Nothing to change: the same code now binds the port. Check your startup logs for
-a healthy report you never actually verified with a request.
-
-If you used the spread workaround — this resource's phases over your own
-`start` — it keeps working, and you can now delete it:
-
-```ts
-// before
-let handle: ManagedServerHandle<T> | null = null
-const shutdown = managedServerResource({ id: 'http', server: () => handle! })
-const http = defineManagedResource({
-  ...shutdown,
-  dependsOn: ['database', 'socket-io'],
-  start: () => { handle = createServer(config) },
-})
-
-// after
-const http = managedServerResource({
-  id: 'http',
-  dependsOn: [database, socketIo],
-  server: () => createServer(config),
-})
-```
-
-An already-created handle is adopted exactly as before.
-
-### If you passed `shutdown` to `bindProcessSignals`
-
-`bindProcessSignals` used to fill in the schema's defaults for every budget you
-omitted, which made `createApplication({ shutdown })` unreachable on the signal
-path — the one path production stops through. An application declaring five
-seconds took thirty-five.
-
-Declare the budget once, on the application, and delete the repetition:
-
-```ts
-// before — the same two numbers in two places, and only one of them applied
-const app = createApplication({ id: 'svc', resources, shutdown: SHUTDOWN_BUDGET })
-bindProcessSignals(app, { shutdown: SHUTDOWN_BUDGET })
-
-// after
-const app = createApplication({ id: 'svc', resources, shutdown: SHUTDOWN_BUDGET })
-bindProcessSignals(app)
-```
-
-**Check this even if you change nothing.** If you declared a budget on the
-application and did not repeat it on the binding, your process has been stopping
-on 30 s / 5 s and will now stop on what you declared. Compare it against the
-supervisor timeout that watches it — `kill_timeout`, `TimeoutStopSec` — because
-that number was probably calculated from the declaration.
-
-Passing `shutdown` to the binding still works and still wins, key by key: one
-key overrides that key alone and leaves the other at the declaration.
-
-### If you read `resource.dependsOn`
-
-Its type widened from `readonly string[]` to `readonly ManagedResourceDependency[]`
-— `string | ManagedResource` — so a dependency can be declared as the resource
-itself. Declaring stays compatible; reading needs one call:
-
-```ts
-// before
-const ids: readonly string[] = resource.dependsOn ?? []
-
-// after
-import { managedResourceDependencyId } from 'stitchkit/application'
-const ids = (resource.dependsOn ?? []).map(managedResourceDependencyId)
-```
-
-### If you thread a handle through a module-local
-
-This is the pattern the change exists to remove, and it is opt-in — nothing
-breaks if you keep yours:
-
-```ts
-// before
-let socket: SocketHandle | null = null
-const socketIo = defineManagedResource({
-  id: 'socket-io',
-  start: async () => { socket = await createSocketServer(config) },
-})
-const http = defineManagedResource({
-  id: 'http',
-  dependsOn: ['socket-io'],
-  start: () => {
-    if (!socket) throw new Error('socket is not initialized')   // unreachable
-    server = createServer({ socket })
-  },
-})
-
-// after
-const socketIo = defineManagedResource({
-  id: 'socket-io',
-  start: async () => ({ value: await createSocketServer(config) }),
-})
-const http = defineManagedResource({
-  id: 'http',
-  dependsOn: [socketIo],
-  start: (context) => {
-    server = createServer({ socket: context.use(socketIo) })   // SocketHandle
-  },
-})
-```
-
-Declare the dependency with the **resource** when you intend to read from it —
-that is the form `use` can type. `use` refuses a resource missing from
-`dependsOn`, and refuses one that published no value; the second refusal is a
-compile error too.
-
-## Released migration: 0.66.0
-
-Three changes, and only one of them is a feature. The other two are shapes that
-would have had to break later: a vocabulary that described one fact with two
-words, and a store whose only read was the whole conversation.
-
-The compiler points at most of it. Two things change with no compile error —
-what a **total** says about its own provenance, and the fact that token counts
-are now validated where they were not.
-
-### An input that joins a run in flight
-
-#### If you matched exhaustively on `AgentTerminalReason`
-
-`'absorbed'` is new. A run ends this way when a run already in flight took its
-input on and answered it; its state is `'superseded'`, and `absorbedIntoRunId`
-names the run that has the answer.
-
-```ts
-// after
-switch (run.terminalReason) {
-  // …
-  case 'absorbed':
-    // no assistant message of its own — follow run.absorbedIntoRunId
-    break
-}
-```
-
-A run record with `terminalReason: 'absorbed'` and no `absorbedIntoRunId` is
-refused at parse time, and so is `absorbedIntoRunId` on any other reason.
-
-#### If you render or export runs
-
-An absorbed run has **no assistant message**. Anything that assumes "every
-terminal run has one" needs the `absorbed` case — the answer is on the run
-`absorbedIntoRunId` names, and `store.loadRun` resolves it.
-
-#### If you want the policy
-
-```ts
-// after
-runs: { inputPolicy: 'inject' }
-```
-
-It was withdrawn in 0.65.0 and is back with the ordering corrected: the
-absorption commits with the terminal record, not at the step boundary. Read
-*An input that joins a run in flight* in the agent-runtime guide before turning
-it on — in particular what happens when the absorbing run does not complete, and
-how it composes with `coalescePending`.
-
-#### If you implement a store driver
-
-Nothing to do, but know what changed underneath: one terminal commit can now
-save **two** run records, and they must land in the same transaction. A driver
-that persists one of the pair fails `runAgentStoreConformance`.
-
-### A run read without its conversation
-
-#### If you implement `AgentRuntimeStore` by hand
-
-Two members to add. **If your adapter is an `AgentRuntimeStoreDriver` passed to
-`createAgentRuntimeStore`, there is nothing to do** — the driver already had
-everything both need.
-
-```ts
-// after
-loadRun(input: { conversationId: string; runId: string }): Promise<AgentRunView | undefined>
-listActiveRuns(conversationId: string): Promise<readonly AgentRun[]>
-```
-
-`AgentRunView` is `{ snapshotVersion, run, assistant? }`. `assistant` is the
-retained terminal answer, so it is present exactly when the run has ended and
-absent while it is live — a store that returns a live run's draft here lets the
-terminal path resolve a run that has not finished. `listActiveRuns` orders by
-`createdAt` then `id`, and must not report a run that has ended.
-`runAgentStoreConformance` covers both, including the boundary cases.
-
-#### If you have a store **double** in your tests
-
-The runtime now reads `loadRun` where it used to read `loadSnapshot`. A double
-that simulates a condition — a run drifting to another owner, a stale fencing
-token — must apply it to both reads, or the code under test will not see it.
-This is not hypothetical: it turned one of this repository's own fixtures into
-an infinite retry loop, which is how the bounded retry below was found.
-
-#### Nothing else changes
-
-`loadSnapshot` behaves exactly as before, and still returns the whole
-conversation — as does every mutation result. What it costs, and what bounds it,
-is now written down in *Reading a conversation* in the agent-runtime guide.
-
-### One provenance vocabulary, and integral tokens
-
-#### If you match on `'measured'`
-
-A **total** now says `computed`, because it is a sum this code performed rather
-than a count it took — the same rule `AgentUsage` has always applied to a run's
-spend. Two values change with no compile error:
-
-```ts
-// before
-if (result.totalTokens.provenance === 'measured') { /* exact */ }
-// after
-if (result.totalTokens.provenance === 'computed') { /* exact, and derived */ }
-```
-
-It affects `AgentHistoryBudgetResult.totalTokens` and
-`ComposedAgentPrompt.instructionTokens`. A per-message or per-section count is
-still `measured` — only the totals moved. When any part was estimated the total
-is still `estimated`: an estimate survives arithmetic, and that is the weaker
-claim, so it wins.
-
-#### If you produce token counts
-
-They are validated now, in the places they were not. A fractional count throws
-where it used to flow into the context-window arithmetic:
-
-```ts
-// refused from this release on
-estimateTokens: (text) => ({ value: text.length / 4, provenance: 'estimated' })
-// after
-estimateTokens: (text) => ({ value: Math.ceil(text.length / 4), provenance: 'estimated' })
-```
-
-The same applies to `ComposeAgentPromptOptions.estimateFallback` and
-`.historyTokens`, to `AgentPromptBudget.toolSchemas` / `.attachments` /
-`.providerOverhead`, and to `AgentPromptBudget.contextWindow` /
-`.reservedOutput`, which must now be non-negative safe integers.
-
-`AgentUsageValue.value` is `z.int()` too, which matters if you build usage
-records by hand or in a store double. A figure arriving from a **provider** is
-not thrown — `normalizeSdkUsage` and the OpenRouter adapter turn a non-integer
-into `{ provenance: 'unavailable' }`, so a run that already answered is not
-failed over its own bookkeeping.
-
-#### The new export
-
-`AgentProvenanceSchema` / `AgentProvenance` is the whole vocabulary:
-`provider-reported`, `measured`, `computed`, `estimated`, `unavailable`. Each
-surface declares its subset, so nothing widened — `AgentUsageValue` still refuses
-`measured` and `AgentTokenCount` still refuses `provider-reported`. Use it when
-you want one switch over the question instead of two.
-
-## Released migration: 0.65.0
-
-The largest migration of the pre-1.0 line, and most of it is the compiler
-pointing at things. One item is a feature withdrawal and two change behaviour
-with no compile error at all.
-
-### A projection a provider accepts, and a policy withdrawn
-
-### If you compact, or use `system-note`, you were broken and now are not
-
-No code change to adopt the fix — but **check your own code if you call
-`projectAgentHistory` yourself.** System and summary records no longer appear in
-`messages`; they come back in `system` and belong in the provider's instructions
-channel, which is the only place `ai` accepts them:
-
-```ts
-// before — the provider refuses this outright
-const messages = await projectAgentHistory(snapshot.messages)
-streamText({ model, messages })
-
-// after
-const { messages, system } = await projectAgentHistoryDetailed(snapshot.messages)
-streamText({
-  model,
-  instructions: system.map((content) => ({ role: 'system', content })),
-  messages,
-})
-```
-
-If you use `createAgentRuntime`, this is handled for you.
-
-### `inputPolicy: 'inject'` is withdrawn
-
-```ts
-// before
-runs: { inputPolicy: 'inject' }
-// after
-runs: { inputPolicy: 'queue' }
-```
-
-`'absorbed'`, `AgentRun.absorbedIntoRunId` and `AgentRuntimeStore.absorbQueuedRun`
-go with it. A driver built on `AgentRuntimeStoreDriver` needs no change.
-
-### Records must agree with themselves
-
-If you construct `AgentRun` values — a store double, a fixture, a migration —
-derive the state instead of setting it:
-
-```ts
-// after
-import { runStateForTerminalReason } from 'stitchkit/agent-runtime'
-AgentRunSchema.parse({ …run, terminalReason: reason, state: runStateForTerminalReason(reason) })
-```
-
-A terminal state with no reason, a queued run carrying one, and `policy_stop`
-without a `terminalPolicyName` are now all refused at parse time.
-
-### Enum and field changes the compiler will point at
-
-- `AgentTerminalReason`: `'tool_failure'` removed (never produced),
-  `'context_overflow'` added — this runtime's own refusal when the prompt does
-  not fit, which used to report `provider_failure`.
-- `AgentRunState`: `'absorbed'` removed.
-- `AgentRunMetrics.usage` is required.
-- `AgentHistoryBudgetDecision['reason']`: `'superseded'` → `'unspeakable'`.
-
-### Two behaviour changes with no compile error
-
-- **`loop.idleTimeoutMs` now defaults to 60 000.** A run whose provider stream
-  goes quiet for a minute ends as `timeout` instead of holding the lane forever.
-  Pass `null` for the old behaviour, and think about why you want it.
-- **`advanceAgentRuntimeEventCursor` stops returning `gap` for durable events.**
-  If you reload a conversation on `gap`, you were reloading after essentially
-  every run. Transient events still report it, and there it is real.
-
-## Released migration: 0.64.0
-
-Two changes, and only one of them can break a build. Nothing was removed.
-
-### An event that says which kind it is
-
-### Narrow `AgentRunEvent` on `type`
-
-```ts
-// before
-for (const event of events) record(event.usage?.cost?.value ?? 0)
-
-// after — and the compiler will point at every site
-for (const event of events) {
-  if (event.type !== 'run-terminal') continue
-  record(event.usage.cost.value ?? null)   // `usage` is present; unknown says so
-}
-```
-
-`step` is now required on `step-finished`, `terminalReason` on `run-terminal`,
-and `usage` on both. `queueWaitMs` exists only on `run-started`. Nothing was
-removed — the fields that were optional because a *different* kind of event
-lacked them are now simply on the kinds that have them.
-
-Import `AgentRunTerminalEventSchema` (or the sibling schemas) if you construct
-events in tests.
-
-### If you implement `AgentRuntimeStore` directly, move to the driver
-
-Not urgent and nothing breaks today — but the aggregate is no longer the
-supported target, so its future growth will not be announced as breaking
-(→ ADR 0111). The supported shape is one line:
-
-```ts
-const driver: AgentRuntimeStoreDriver<TransactionClient> = { /* six primitives */ }
-export const store = createAgentRuntimeStore(driver)
-```
-
-Run `runAgentStoreConformance` against your adapter before and after any bump —
-see *Before you bump, if you implement an agent store* above.
-
-## Released migration: 0.63.0
-
-Four changes to what a running system reports and how an input reaches a run
-in flight. Nothing moves an export except one added store member, and only an
-application implementing `AgentRuntimeStore` directly has to touch code.
-
-### A spend figure that survives, and an input that joins
-
-### `AgentRuntimeStore` has a ninth member
-
-Only if you implement the aggregate interface directly — an adapter built on
-`AgentRuntimeStoreDriver` needs no change, and the public conformance kit covers
-the new operation.
-
-```ts
-// after
-absorbQueuedRun(input: AbsorbQueuedRun): Promise<AgentStoreMutationResult>
-```
-
-It moves a queued successor's inputs into the run already answering, in one
-mutation, and marks the successor `absorbed`. Two run records change in one
-transaction — if your driver persists them one at a time, persist both.
-
-### A provider failure says so
-
-```ts
-// before — an upstream error arrived as a policy stop with no policy
-if (terminal.reason === 'policy_stop') retryLater()
-
-// after
-if (terminal.reason === 'provider_failure') retryLater()
-if (terminal.reason === 'provider_stop') { /* a length cap or content filter */ }
-```
-
-`policy_stop` now always carries the `policyName` that caused it. If you switch
-exhaustively on `AgentTerminalReason` or `AgentRunState`, add `'provider_stop'`
-and `'absorbed'`.
-
-### `partial` changed meaning
-
-It used to tell you which event kind you were holding. It now tells you whether
-the figure beside it is a confirmed total:
-
-```ts
-// after — true when the provider never reported the run finished
-if (metrics.partial) treatAsFloor(metrics.usage)
-```
-
-Terminal events for runs that were superseded, interrupted, timed out or failed
-before the provider finished now report `partial: true` where they reported
-`false`.
-
-### Checkpoint metrics are a running total
-
-```ts
-// wrong, and now wrong by more than it used to be
-const spent = checkpoints.reduce((total, c) => total + (c.metrics.usage?.cost?.value ?? 0), 0)
-// right
-const spent = checkpoints.at(-1)?.metrics.usage?.cost?.value
-```
-
-### You can read a run's spend back from the store
-
-`AgentRun.usage` is written at every checkpoint and with the terminal record, so
-a dropped observability event no longer loses the number, and a process that dies
-mid-stream leaves behind what it had already spent.
-
-## Released migration: 0.62.0
-
-Two groups of behaviour changes. Nothing moves an export — the surface is
-strictly additive — and every item changes what a running system reports or
-sends, which is what this heading is for. One of them changes a number you may
-already be billing against.
-
-### A run reports what it spent
-
-Three changes to what the runtime says about cost and tokens. Nothing moves an
-export; all three change numbers a running system reports, and one of them
-changes a number you may already be billing against.
-
-#### Multi-step cost was under-reported and is now summed
-
-No code change is needed to get the fix — but check any predicate that reads
-`provenance`:
-
-```ts
-// before — accepted a number that was one step's cost, not the run's
-if (usage.cost?.provenance === 'provider-reported') bill(usage.cost.value)
-
-// after — a sum stitchkit performed says so
-if (usage.cost && usage.cost.provenance !== 'unavailable') bill(usage.cost.value)
-```
-
-`'computed'` means stitchkit added up provider-reported parts. It is not a guess
-— `'estimated'` is the word for that — but it is deliberately not
-`'provider-reported'`, because that label is what a caller filters on when it
-wants a figure it can bill against unchanged, and a sum is not one.
-
-Token totals moved with it. The AI SDK's `totalUsage` is a sum *it* performed
-over per-step provider figures — not a run total any provider handed over — so
-labelling it `provider-reported` was the same overstatement. **A run total on a
-terminal event is always `computed`.** If you want a figure with the provider's
-own word on it, read `step-finished`: each step carries what that call reported.
-
-#### `usage` is always present on a terminal event
-
-```ts
-// before — absent when the run ended before the provider's `finish`
-const spent = event.usage?.cost?.value ?? 0        // silently 0 for a real spend
-
-// after — present, and it says what it does not know
-event.usage?.cost?.provenance === 'unavailable'    // we spent, and cannot say how much
-```
-
-Keep the optional chaining: one `AgentRunEvent` shape covers `run-started`,
-`step-finished` and `run-terminal`, so `usage` stays optional on the type. The
-guarantee is about terminal events, and a schema shared with `run-started`
-cannot express it.
-
-**Do not read `unavailable` as zero.** A run aborted mid-stream has spent real
-money that nobody has counted; a run that never reached the provider has not.
-Both used to look the same and now do not.
-
-#### A losing executor reports its own spend
-
-An execution that loses the terminal compare-and-swap now emits an operator
-`run-terminal` event, because it ran and it spent. If a sink treated those events
-as "runs this process committed", that is no longer true — `AgentRuntimeResult.metrics`
-is still `undefined` for a losing executor and remains the way to tell.
-
-The *delivery* `terminal` event is unchanged and still fires only for the winner,
-so nothing delivers a turn twice.
-
-### An interrupted answer stops passing as a finished one
-
-Two behaviour changes, one shared cause: a run ended by a newer input used to
-leave its half-written answer in the conversation with no sign that it was cut
-off, and the next request to the provider carried it as an ordinary assistant
-turn.
-
-#### The projection marks an interrupted turn
-
-Nothing to change to adopt the fix — the default is the fixed behaviour. What to
-check is whether the marker is the *right* form for your surface, and the
-question that decides it is not "was the run interrupted" but **"did anyone see
-what it produced"**.
-
-```ts
-// after — pick the form; the default is 'assistant-marked'
-createAgentRuntime({ history: { interruptedAssistant: 'system-note' } })
-```
-
-- **The user pressed stop and the text was on their screen** — keep
-  `'assistant-marked'`. The assistant turn is the truthful record of what the
-  human read, and the model should stay consistent with it.
-- **The partial never reached anyone** — a surface that sends nothing until the
-  run is done — prefer `'system-note'`. An assistant turn in provider history is
-  a commitment the model stays consistent with; a system line is context.
-
-If you pass `history.project` you own the projection outright and none of this
-applies — but the same question does.
-
-#### A run ended by a newer input can now say so
-
-```ts
-// before
-runs: { inputPolicy: 'interrupt' }   // ends the run, keeps its partial answer
-
-// after — for a surface where a follow-up message invalidates the answer
-// in flight rather than merely stopping it
-runs: { inputPolicy: 'supersede' }   // ends the run, discards its partial answer
-```
-
-`inputPolicy` also accepts `(input) => policy`, which is how one application
-gives two conversation surfaces different rules without the runtime learning
-which is which.
-
-A superseded run terminates with `terminalReason: 'superseded'`, state
-`'superseded'` and an assistant message of status `'superseded'`. **If you switch
-exhaustively on any of those enums, add the arm** — that is the part of this
-release that can break a build rather than a behaviour. The record itself is
-kept: it is excluded from the projection, not deleted, so an operator can still
-see what was thrown away.