stitchkit 0.93.0 → 0.94.1

package/llms/upgrading-0.68.0-0.94.0.txt

@@ -0,0 +1,1159 @@
+# 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.68.0 → 0.94.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.
+
+```bash
+rg -n "createAsyncOperationSnapshotSchema"
+```
+
+`progress` on a parsed snapshot used to be `unknown`. The factory built its
+object shapes with a conditional spread, and the narrowing inside it widened
+your schema back to a bare `ZodType`, so the emitted declaration threw the type
+argument away. It is now the output of the schema you configured.
+
+```ts
+const schema = createAsyncOperationSnapshotSchema({
+  progress: z.object({ done: z.number(), total: z.number() }),
+  failure: z.object({ code: z.string() }),
+})
+const snap = schema.parse(body)
+if (snap.phase === 'running') {
+  // before: `snap.progress` was `unknown` — this needed a cast or a narrow
+  // after:  it is `{ done: number; total: number } | undefined`
+  console.log(snap.progress?.done)
+}
+```
+
+**If you cast it**, delete the cast — it was working around the erased type.
+**If you assigned something else to it**, the compiler now refuses, and it was
+already a value the schema rejected at run time.
+
+**If you pass explicit type arguments**, the no-progress form takes one now, not
+two: the factory is two overloads. Pass none.
+
+```ts
+// before: createAsyncOperationSnapshotSchema<undefined, typeof Failure>({ failure: Failure })
+// after:  createAsyncOperationSnapshotSchema({ failure: Failure })
+```
+
+Nothing about parsing moves. A snapshot configured without `progress` still
+strips an unexpected `progress` rather than refusing it — that behaviour is why
+this is overloads and not one normalised key.
+
+**If you compile with `skipLibCheck: false`**, this is also the release that
+makes `stitchkit/tools/contract` compile at all: it carried five `TS2344`
+errors, one per phase, from the same conditional spread.
+
+## Released migration: 0.79.0
+
+One thing, and only if you assert on the whole snapshot.
+
+```bash
+rg -n "getSnapshot\(\)|projectApplicationStatus|status\(\)" --glob '*.test.ts' --glob '*.spec.ts'
+```
+
+`ApplicationSnapshot` and `ApplicationStatusProjection` each gained a
+`restarting` field — ids in the snapshot, a count in the projection. A reader
+that names the fields it wants is unaffected. A test that compares the whole
+object with `toEqual` fails until it adds the field:
+
+```ts
+// before
+expect(body).toEqual({ id, lifecycle: 'ready', /* … */ resources: { total: 1, ready: 1, degraded: 0, failed: 0 } })
+// after
+expect(body).toEqual({ id, lifecycle: 'ready', /* … */ resources: { total: 1, ready: 1, degraded: 0, failed: 0 }, restarting: 0 })
+```
+
+It is zero except while a restart is running, and then it names the subtree being
+replaced. That is the point: a snapshot taken mid-restart used to be
+indistinguishable from a resource that had failed on its own, so a dashboard read
+a planned replacement as an outage.
+
+**If you watch a hub across a restart**, nothing to change, but the behaviour is
+different and better: closing a hub now tells its subscribers `unavailable` /
+`source-unavailable` instead of dropping them, so a page stops showing a value
+that will never update again.
+
+**If you need a tool contract in a browser**, `stitchkit/tools/contract` now
+carries the async-operation helpers, its schemas and the view-file input/output
+without the runtime. `stitchkit/tools` still exports all of them.
+
+## Released migration: 0.78.0
+
+Two mechanical edits. Find them both:
+
+```bash
+rg -n "createDecisionPipeline|createDiagnosticJournal" --glob '*.ts' --glob '*.tsx'
+```
+
+**1. `createDecisionPipeline` takes a deadline.**
+
+```ts
+// before
+createDecisionPipeline([policyA, policyB])
+// after
+createDecisionPipeline([policyA, policyB], { policyTimeoutMs: 2_000 })
+```
+
+Pick a number your slowest policy comfortably beats. There is no default on
+purpose: a policy that never settles hangs every caller of the operation it
+guards, and the framework has no basis for choosing that number for you.
+
+Past the deadline — and on a throw, and on a non-decision — the pipeline raises
+`DecisionPolicyError` naming the policy, with the trace so far. If you already
+catch that for a bad return value, you now catch two more cases with it.
+
+**2. `createDiagnosticJournal` moved.**
+
+```ts
+// before
+import { createDiagnosticJournal } from 'stitchkit/application'
+// after
+import { createDiagnosticJournal } from 'stitchkit/application/diagnostic-journal'
+```
+
+Only the factory moved. `DiagnosticJournalConfig`, every
+`DiagnosticJournal*Schema` and `readDiagnosticJournalLockDiagnosis` stay where
+they were.
+
+**If you restart resources**, nothing to change — but three things that did not
+work now do: a managed schedule can be restarted, a restarted keyspace accepts
+writes again, and a restarted managed server is actually shut down at exit. If
+you pass `managedServerResource` a server *instance*, a restart is now refused
+by name; pass a factory (`server: (context) => …`) to restart it.
+
+## Released migration: 0.77.0
+
+Two type renames, and only if you named them. Nothing runtime moved.
+
+```bash
+rg -n "EventDecision|EventUndecided" --glob '*.ts' --glob '*.tsx'
+```
+
+```ts
+// before
+import type { EventDecision, EventUndecided } from 'stitchkit/live'
+// after
+import type { PolicyDecision, UndecidedOutcome } from 'stitchkit/live'
+```
+
+The shapes are identical — `{ outcome: 'allow' } | { outcome: 'deny', reason } | { outcome: 'defer' }`
+and `'allow' | 'deny'`. If you only ever *return* decisions from listeners and never named the
+type, the search above finds nothing and there is nothing to do.
+
+They were renamed because `createDecisionPipeline` (new in this release) votes with exactly the
+same three outcomes, and two identical types under two names is the thing that makes a search for
+either one return half the truth.
+
+## Released migration: 0.76.0
+
+One change, and only if you hand `createWatchClient` a transport you wrote yourself.
+
+```bash
+rg -n "createWatchClient" --glob '*.ts'
+```
+
+If the `transport:` you pass is a bound realtime client — `bindRealtimeClient(...)` or
+`createRealtimeClient(...)` — there is nothing to do: it already carries
+`onConnectionChange`. If it is an object you assembled, add the fourth member:
+
+```ts
+onConnectionChange(listener: (connected: boolean, reason?: string) => void): () => void
+```
+
+It is required because the client recovers through it: on a drop it publishes
+`unavailable` to subscribers and forgets what was opened, and on a fresh
+connection it re-opens every key that still has a listener. Without it a watch
+stays "open" on the client after a server restart while the hub remembers
+nothing, and the face stops updating without saying so.
+
+## Released migration: 0.75.0
+
+Two mechanical renames and one option that has to move. Nothing about a passing
+request changes.
+
+### 1. A route group's `onRequest`
+
+```bash
+rg -n "hooks:\s*\{[^}]*onRequest" --glob '*.ts'
+```
+
+Any match **inside a `groups: [...]` entry** must move. The hook was accepted and
+never dispatched, so the behaviour you have today is "no hook"; the fix is to
+decide which one you meant:
+
+```ts
+// refuse before dispatch, for the whole server
+createServer({ groups, hooks: { onRequest: gate } });
+
+// gate this group once the endpoint is known
+groups: [{ pathPrefix: '/admin', services, hooks: { authorize: gate } }]
+```
+
+A group that still declares `onRequest` fails at startup with that message.
+
+### 2. The SQLite boundary type
+
+```bash
+rg -l "AgentRuntimeSqlite(Database|Statement|Value)" | xargs sed -i \
+  -e 's/AgentRuntimeSqliteDatabase/SqliteDatabase/g' \
+  -e 's/AgentRuntimeSqliteStatement/SqliteStatement/g' \
+  -e 's/AgentRuntimeSqliteValue/SqliteValue/g'
+```
+
+Type-only: the same three methods, the same structural compatibility with
+`bun:sqlite` and a `node:sqlite` wrapper, imported from the same entrypoints.
+`initializeAgentRuntimeSqlite` keeps its name — it really is the agent runtime's
+schema.
+
+### 3. Nothing else
+
+`stitchkit/live`, the watch hub, the keyspace and the trust fence are all
+additive. Adopt them when you want them; the guide is
+[Live data](./live.md).
+
+## Released migration: 0.74.0
+
+One change, and it only reaches you if you catch a refusal the **client** raised — one it made while
+planning the request, before anything was sent. A server refusal is unchanged.
+
+### If you match on the text of a client-side refusal
+
+A missing path param, a missing scoped prefix key, a non-flat field in a `GET` input, a missing or
+invalid multipart file: each used to arrive as a plain `Error` carrying only a sentence. They now
+arrive as an `ApiError` in the same shape a server validation failure uses.
+
+```ts
+// before
+catch (e) {
+  if (/Missing path param/.test(e.message)) …
+}
+
+// after
+catch (e) {
+  if (e.code === 'VALIDATION_ERROR' && e.status === 0) …   // refused here, nothing was sent
+}
+// e.details.issues[0].path === 'id'
+```
+
+`status` is what separates the two worlds, and it is not new — `0` has always meant *this never
+reached the server*, as `REQUEST_ABORTED` and `REQUEST_TIMEOUT` already used it:
+
+| | `code` | `status` |
+|---|---|---|
+| the client refused your arguments | `VALIDATION_ERROR` | `0` |
+| the server refused your arguments | `VALIDATION_ERROR` | `400` |
+
+`details.issues` is the same `{ path, code, message }` array on both, so one rendering serves both —
+and `zodIssues` / `ZodIssueSummary` are now importable from `stitchkit` itself, not only from
+`stitchkit/server`.
+
+### If you are on `createHttpClient` and your call site relied on a synchronous throw
+
+This is the sharp one, because it is invisible in a diff. Those refusals used to be thrown
+**synchronously** on the Ky-backed client — before the call returned a promise — so
+`api.upload({}).catch(handler)` never reached the handler, while the same mistake on the bare-fetch
+client rejected normally. They now reject on both.
+
+```ts
+// before, on createHttpClient only
+try {
+  api.upload({})            // threw here
+} catch (e) { … }
+
+// after, on both transports
+await api.upload({}).catch(handler)
+```
+
+A `try/catch` around an `await`ed call keeps working. A `try/catch` around an un-awaited call no
+longer catches anything — which was already true on the other transport.
+
+Not a migration, but worth knowing: a missing multipart file used to be reported as
+`UNKNOWN_ERROR`, the code that means *this client cannot tell you what happened*, on the one refusal
+where it is certain nothing was sent. → ADR 0148 carries the reasoning, including why argument
+validation stays on the server.
+
+## Released migration: 0.73.0
+
+Two breaking changes. Nothing you send to a server changed, and only one of these
+can reach a call site the compiler already checks.
+
+### If you call `withOptions` from a call site that lost its types
+
+`withOptions` takes one argument on an endpoint with no contract input, two when
+there is one. Passing two to a no-input endpoint used to succeed and silently
+drop the options: the request went out **uncancelled**, the caller still received
+`REQUEST_ABORTED` — cancellation is decided from the signal it was handed, not
+from what the transport did — and the server ran the operation to its own
+deadline. Every symptom then points at the transport, and the investigation goes
+there. It now throws a `TypeError` naming the endpoint and the correct shape.
+
+```ts
+// before — the options were dropped and the request was never cancelled
+api.ping.withOptions({}, { signal })
+
+// after
+api.ping.withOptions({ signal })
+```
+
+A typed call site already refused the wrong arity, so this reaches only code that
+does not have the types: a `Record<string, …>` view of the client, a hand-written
+double, a dynamic dispatch. The guard counts arguments and never reads them, so a
+method handed to a callback API behaves exactly as before.
+
+### If you match on `ApiError.message`
+
+An `ApiError` that nothing explained used to carry `API Error: ${code}` — a
+string that reads like an explanation while only restating the code, so a caller
+could not tell an origin that explained a failure from one that said nothing. It
+now says which it is.
+
+```ts
+// before
+err.message === 'API Error: INVALID_INPUT'
+
+// after
+err.message === 'INVALID_INPUT (no message supplied)'   // better: match err.code
+```
+
+Match `err.code` instead: it is the contract, and it did not change. An error
+carrying a real message is untouched. An empty message now counts as no message,
+for the same reason — an empty string is not an explanation either.
+
+### If a diagnostic journal lock file is already on disk
+
+One operator step, and only on a host that has been **renamed** since its lock was written.
+
+A lock written before this version carries no machine identity, so there is nothing to compare and
+the host name is all that is left. If the name still matches, the lock reclaims exactly as it always
+did and there is nothing to do. If the name has changed, the lock is `unattributable` and is refused
+— the same refusal this release exists to end, except that this particular file predates the fix and
+cannot be repaired from the inside. Delete it once:
+
+```sh
+rm <journal path>.lock   # only when the host was renamed since the file was written
+```
+
+Locks written from this version on carry the machine identity, so the situation cannot recur. To see
+which case you are in without guessing, read the refusal instead of the file:
+`readDiagnosticJournalLockDiagnosis(err)` returns `attribution: 'unattributable'` for exactly this
+one, and `'another-machine'` for a lock that genuinely belongs elsewhere and must **not** be deleted.
+
+Two related fixes need no migration, but change what you will see. An error the
+transport raised through `createHttpClient` now carries the transport's own text
+in `message` and the original error as `cause`, where before it carried neither
+and filed the text under `details.message` alone; if you followed the retry rule
+in [the client guide](./client.md) — inspect the adapter's `cause`, retry only
+when it proves dispatch did not happen — that rule was not executable on this
+transport and now is. And the client guide now states which direction validation
+runs: responses are checked against `output`, arguments are **not** checked
+before being sent.
+
+## Released migration: 0.72.0
+
+Nothing you *pass* changed. Both items are about types you read or build, and
+both stop the compiler rather than surprising you at runtime.
+
+### If you read `perKey` off `BoundedAdmissionPolicy`
+
+`perKey` is now a union: the flat ceiling it always was, or `{ maxKeys, limits }`
+where the ceiling is resolved from the key. Declaring one is unchanged; reading
+one needs a narrowing.
+
+```ts
+// before
+const ceiling = policy.perKey?.maxConcurrent
+
+// after
+const ceiling =
+  policy.perKey && !('limits' in policy.perKey) ? policy.perKey.maxConcurrent : undefined
+```
+
+A shape carrying members of both branches — `{ maxKeys, maxConcurrent, limits }` —
+is refused. **In 0.72.0 and 0.72.1 that refusal came only from
+`createBoundedAdmission`**, not from `tsc`: an excess-property check against a
+union admits any property some member declares, so the mixed shape typechecked
+and threw when the admission was built. From **0.72.2** each branch declares the
+other's members as `never`, so it is a compile error. Nothing about the runtime
+changed — both branches always refused it — but on a path your tests do not
+construct, the earlier versions would have told you in production.
+
+### If you build a snapshot or a status by hand
+
+`CreditWindowSnapshot` gained `waiting` (producers parked in the new waiting
+`acquire`) and `DiagnosticJournalStatus` gained `lock`. Both are produced by the
+framework, so reading them is unaffected — but a test double stops compiling:
+
+```ts
+// before
+const snapshot: CreditWindowSnapshot = { state: 'open', capacityBytes: 100, /* … */ }
+
+// after
+const snapshot: CreditWindowSnapshot = { state: 'open', capacityBytes: 100, /* … */ waiting: 0 }
+```
+
+## Released migration: 0.71.0
+
+The Agent coding tools. Two of the three changes are visible to the compiler;
+the third is the one to read carefully, because nothing will point at it.
+
+### If you implement `authorize`
+
+The operation union gained `edit`, `list` and `glob` and lost `patch`. An
+exhaustive matcher stops compiling and the compiler shows you every arm. **A
+matcher with a default branch does not**, and that is the dangerous case:
+
+```ts
+// before — and after this upgrade, silently wrong in both directions
+if (request.operation === 'patch') return reviewPatch(request)
+return true            // now also authorizes edit, list and glob
+// …or: return false   // now also kills edit_file
+```
+
+```ts
+// after
+switch (request.operation) {
+  case 'edit':   return reviewEdit(request)   // the old `patch` payload, unchanged
+  case 'list':
+  case 'glob':   return true                  // or your own policy
+  // …existing read / write / search / shell / artifact-read arms
+}
+```
+
+`write` gained `createsDirectories` — the workspace-relative directories the
+call would create, outermost first, reported **before** anything is created. A
+host that wants to refuse implicit directory creation now can.
+
+### If you call `apply_patch`
+
+It is `edit_file`, and it is one call:
+
+```ts
+// before
+const read = await readFile({ path })
+await applyPatch({ path, baseSha256: read.sha256, oldText, newText, dryRun: true })
+await applyPatch({ path, baseSha256: read.sha256, oldText, newText, dryRun: false })
+
+// after
+await editFile({ path, oldText, newText })
+```
+
+`expectedSha256` is optional and still refuses a stale base with `CONFLICT` when
+you pass it; `edit_file` returns the resulting `sha256`, so a chain of edits
+never needs to re-read. If you key an approval policy or a UI label on the string
+`apply_patch`, update the key — nothing will fail loudly.
+
+### If you match on `INTERNAL_SERVER_ERROR` from a coding tool
+
+Ordinary outcomes no longer arrive that way. A missing file is `NOT_FOUND`, an
+existing file without `overwrite` is `CONFLICT`, an ambiguous snippet is
+`CONFLICT` with the occurrence count, a path outside the root is `FORBIDDEN`.
+Code that treated any coding-tool failure as an internal fault will now see
+codes it did not before; code that showed the model an empty error now has a
+sentence and a `hint` to show it. Host-level causes are unchanged and still
+scrubbed.
+
+### If you write files into new directories
+
+Nothing to change: `write_file` creates missing parents inside the root. Read
+`createdDirectories` in the result if you want to notice a typo — a path that
+was a failure before is now a successful write into a new tree.
+
+### If you want a step to know its context budget
+
+Opt in by reading it; nothing is injected for you:
+
+```ts
+loop: {
+  prepareStep: ({ contextUsage }) => {
+    const used = contextUsage?.usedTokens
+    if (used?.provenance === 'unavailable') return {}      // no step has landed yet
+    const fraction = (used?.value ?? 0) / (contextUsage?.contextWindow ?? 1)
+    // …render it wherever you put it
+    return {}
+  },
+}
+```
+
+Put it at the **tail** of the conversation rather than in the system
+instructions unless you have a reason: changing the system prompt on every step
+invalidates the provider's prefix cache for the whole conversation, and on a long
+run that is a multiple of the input cost.
+
+## Released migration: 0.70.0
+
+### Descriptor-backed Agent filesystem containment
+
+Built-in coding file/search tools and `createAgentHarnessFileResources` now require a runtime
+that can address an opened directory descriptor: Linux `/proc/self/fd`, or the packaged macOS
+Node-API backend added in 0.70.1. This is what keeps a mutable parent rename or outside-symlink replacement from changing
+the authorized target between validation and the actual effect.
+
+No call-site change is needed on those platforms. The 0.70.0 notes incorrectly inferred macOS and
+FreeBSD support from `/dev/fd`; macOS is restored by 0.70.1 and FreeBSD remains unsupported. On
+Windows or another platform without that
+boundary, move the built-in filesystem operations to a supported worker or replace them with
+application-owned tools backed by an equivalent native handle API. They fail closed rather than
+falling back to path spelling. `run_command` remains separately available under its explicit
+executable alias and authorization policy; this change does not claim an executable sandbox.
+
+## Released migration: 0.69.0
+
+### Direct coding-tool operation names
+
+`createAgentCodingTools` no longer prefixes durable operation identity with `coding_`, and the
+unguarded exact-string edit tool is gone. Update approval maps, presenters and tests together:
+
+```ts
+// before
+{ coding_read_file: 'approved', coding_search: 'approved', coding_patch_file: 'user-approval' }
+
+// after
+{ read_file: 'approved', search_files: 'approved', apply_patch: 'user-approval' }
+```
+
+The full mapping is `coding_read_file → read_file`, `coding_write_file → write_file`,
+`coding_search → search_files`, `coding_patch_file → apply_patch`, `coding_shell → run_command`,
+`coding_read_artifact → read_output` and `harness_read_resource → read_resource`. Replace
+`coding_edit_file` with `read_file` followed by guarded `apply_patch`; `read_file` now returns the
+required SHA-256. If the host declares no executable aliases, expect `run_command` to be absent.
+
+### Durable Agent approval message variants
+
+If a renderer, store adapter or export pipeline exhaustively switches over
+`AgentMessage.role`, add the `tool` branch. If it switches over
+`AgentMessagePart.type`, add `tool-approval-request` and `tool-approval-response`.
+They are durable provider-continuation evidence: preserve them in storage and provider history;
+a UI may render them as approval state or intentionally omit their visual row.
+
+```ts
+// before
+const unreachable: never = message.role
+
+// after
+if (message.role === 'tool') renderToolContinuation(message.parts)
+else renderExistingRole(message)
+```
+
+No data migration is needed. The schema still accepts all earlier records, and applications that
+do not exhaustively branch over these unions compile unchanged.
+
+## Released migration: 0.68.0
+
+### Make Unix transport selection explicit outside Bun
+
+The legacy `unix` option remains a Bun convenience, but on Node or another
+runtime it now fails before dispatch. Replace it with the owned adapter and close
+that adapter with the application:
+
+```ts
+// before — unsafe outside Bun: an unsupported fetch could dial baseUrl over TCP
+const http = createHttpClient({ baseUrl, unix: '/run/service.sock' })
+
+// after — Bun and Node; every dispatch and redirect stays on the socket
+import { createUnixClientTransport } from 'stitchkit/server' // or stitchkit/node
+const transport = createUnixClientTransport({ socketPath: '/run/service.sock' })
+const http = createHttpClient({ baseUrl, fetch: transport.fetch })
+// during shutdown
+await transport.close()
+```
+
+Do not automatically replay `possibly-dispatched`: a timeout or connection loss
+after bytes left the process does not prove that a write did not happen.
+
+### Choose tolerant stream parsing explicitly
+
+`parseNDJSON` and `parseSSE` now throw on malformed JSON, invalid UTF-8 and an
+over-limit line. The default line ceiling is 1 MiB. If a feed deliberately skips
+bad records, retain that policy explicitly:
+
+```ts
+// before — malformed input disappeared implicitly
+parseNDJSON(response)
+
+// after — ordinary fail-closed path
+parseNDJSON(response, { maxLineBytes: 256 * 1024 })
+
+// after — deliberately tolerant path
+parseNDJSON(response, { onParseError: (raw, error) => report(raw, error) })
+```
+
+### Extend exhaustive framework-error handling
+
+If a switch makes `StitchErrorCode` exhaustive, add
+`STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,
+`STREAM_TERMINAL_MISSING` and `STREAM_LIFETIME_EXCEEDED`. A partial application
+status map needs no change (ADR 0105).
+
+The admission/channel APIs and endpoint `stream` descriptor are additive; raw
+responses and raw `streamingRoute` remain supported.