stitchkit 0.114.2 → 0.116.0

package/llms/{upgrading-0.104.0-0.114.0.txt → upgrading-0.105.0-0.116.0.txt}

@@ -1,14 +1,96 @@
-# Upgrading 0.104.0 → 0.114.0 — stitchkit docs slice
+# Upgrading 0.105.0 → 0.116.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.104.0 → 0.114.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.105.0 → 0.116.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.104.0 → 0.114.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.105.0 → 0.116.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.116.0
+
+### send-only-telegram-pause
+
+**Who must act:** code that relied on a 429 from `editMessage*`, `deleteMessage` or a read to stop a
+token's sends. Code that only sends needs no change.
+
+`run` pauses the token only on a method that spends the budget
+([ADR 0277](../decisions/0277-a-telegram-budget-serves-replies-first.md)). Where an edit must still stop
+the sends, say so:
+
+```ts
+// before
+await budget.run('editMessageText', payload, signal, send)
+// after
+await budget.run('editMessageText', payload, signal, send).catch((error) => {
+  budget.pauseAfter(error)
+  throw error
+})
+```
+
+Search pattern: `budget.run` next to edit and read methods.
+
+## Released migration: 0.115.0
+
+### contained-cli-downloads
+
+**Who must act:** a CLI that uses `--output-dir` on Windows, from a macOS bundle or compiled binary
+built without `createNativePackaging`, into a directory it cannot write or over bind-mounted files;
+a coding-tools host that allows `edit` but refuses `read` for a path; and code or CSS that reads
+`aria-orientation` of a `role: 'none'` zone. A CLI writing into its own directory on Linux or
+unbundled macOS, and every CLI command without a download, need no change.
+
+`--output-dir` now writes through a pinned directory descriptor
+([ADR 0276](../decisions/0276-a-download-writes-through-its-root-capability.md)). There is no
+path-based fallback, so a platform without that backend refuses the download: the operation still
+succeeds, its result stays on stdout, stderr names the refusal and the exit is non-zero.
+
+1. On macOS, build a bundled or compiled CLI with the native packaging plugin:
+
+   ```ts
+   // before
+   await Bun.build({
+     entrypoints: ['src/cli.ts'],
+     compile: { target: 'bun-darwin-arm64', outfile: 'dist/cli' },
+   })
+   // after
+   import { createNativePackaging } from 'stitchkit/files/packaging'
+
+   const native = createNativePackaging({
+     platform: 'darwin', architecture: 'arm64', delivery: 'embedded',
+   })
+   if (native.state !== 'ready') throw new Error(native.code)
+   await Bun.build({
+     entrypoints: ['src/cli.ts'],
+     compile: { target: 'bun-darwin-arm64', outfile: 'dist/cli' },
+     plugins: [native.plugin],
+   })
+   ```
+
+   A JS bundle uses `delivery: 'companion'`; every shape is in the [native I/O guide](./native-io.md). Search pattern:
+   `createCli` with a `download` option in a project that runs `bun build` for macOS.
+2. On Windows, run the download through Linux or macOS, or read the URLs from the operation's
+   JSON result and fetch them yourself. Stitchkit offers no weaker path on that platform.
+3. A download now replaces a file rather than rewriting it. Give the process write permission on
+   the output directory, and do not point it at a bind-mounted file: that refuses with `EBUSY`. A
+   replaced file belongs to the process user, and a read-only file is replaced like any other.
+4. Read the orientation you configured. A zone with `role: 'none'` has no attribute, and a default
+   would silently turn a horizontal zone vertical:
+
+   ```ts
+   // before
+   const axis: ZoneOrientation = zone.zoneProps['aria-orientation']
+   // after
+   const axis: ZoneOrientation = options.orientation ?? 'vertical'
+   ```
+
+   Search pattern: `aria-orientation` next to `useNavZone`, and `[aria-orientation]` in CSS and
+   test selectors. Type-check: a read typed as `ZoneOrientation` fails to compile.
+5. In a coding-tools `authorize`, answer `read` for every path you answer `edit` for. `edit_file`
+   asks both, `read` first.
+
 ## Released migration: 0.114.0
 
 **Who must act:** code with an exhaustive `switch` or `Record` over
@@ -735,124 +817,3 @@ in the second position is a type error.
 
 4. Both classes accept the standard `cause`, which `error.cause` returns; omit the option to
    leave the property absent.
-
-## Released migration: 0.104.0
-
-JS bundles carrying Darwin native capabilities also need the
-[delivery migration first affected in 0.103.13](#released-migration-010313).
-Consumers upgrading from 0.103.12 or earlier must apply it even if their TypeScript API is unchanged.
-
-### CLI runtime-tool construction
-
-**Who must act:** callers writing a schema-dependent handler or MCP/AI `present` directly
-inside an annotated `CliConfig.runtimeTools` or `CliInvokerConfig.runtimeTools` object.
-Native `commands` and values returned by `defineRuntimeTool` / `createRuntimeToolFactory`
-remain valid. Execution, auth, validation and the invocation result envelope keep their behavior.
-
-Construct a CLI-only managed definition with the neutral schema-aware type before registration:
-
-```ts
-import type { CliInvokerConfig, RuntimeToolExecutionWithOutput } from 'stitchkit/cli'
-import { z } from 'zod'
-
-const input = z.object({ text: z.string() })
-const output = z.object({ size: z.number() })
-// Before: handler receives the heterogeneous registry context.
-const config: CliInvokerConfig = {
-  name: 'app',
-  runtimeTools: [{
-    name: 'measure', description: 'Measure text',
-    identity: { serviceName: 'text', action: 'measure', method: 'POST' },
-    transports: ['CLI'], input, output,
-    handler: ({ input }) => ({ size: String(input.text).length }),
-  }],
-}
-// After: handler input and output derive from the construction schemas.
-const measure = {
-  name: 'measure', description: 'Measure text',
-  identity: { serviceName: 'text', action: 'measure', method: 'POST' },
-  transports: ['CLI'], input, output,
-  handler: ({ input }) => ({ size: input.text.length }),
-} satisfies RuntimeToolExecutionWithOutput<typeof input, typeof output>
-const nextConfig: CliInvokerConfig = { name: 'app', runtimeTools: [measure] }
-```
-
-For a shared MCP/AI tool, construct the definition with `defineRuntimeTool` from
-`stitchkit/tools`, including its typed SDK `present` callbacks, then pass the returned value
-to `runtimeTools`. Install the corresponding SDK peers for that integration. A CLI-only
-consumer needs `stitchkit`, `zod` and its ordinary Node type tooling.
-
-`RuntimeToolExecution` names the heterogeneous registration contract. Call a registered
-operation through `createCli` or `createCliInvoker`; its erased handler input is `never`
-because the managed runner owns schema validation before execution. For a managed void
-definition, use `RuntimeToolDefinitionWithoutOutput<typeof input>`.
-
-### MCP construction, state stores and delivery
-
-**Who must act:** schema-dependent runtime tool literals written directly inside MCP mount
-configuration, MCP presenters returning malformed content or metadata, custom `StateStore`
-implementations, file-store consumers using retired lock
-options, broadcast consumers reading `halt` or retrying unknown send outcomes, and consumers
-that validate HTTP error envelopes with a closed schema. Applications collecting raw tool
-causes from `console.error` must configure an internal tool hook sink.
-
-MCP-only code can import the existing server factories from `stitchkit/tools/mcp` and
-construct its schema-aware tool before heterogeneous registration:
-
-```ts
-import { buildMcpServer, type RuntimeMcpToolDefinitionWithOutput } from 'stitchkit/tools/mcp'
-import { z } from 'zod'
-const input = z.object({ value: z.number() })
-const output = z.object({ doubled: z.number() })
-// Before: runtimeTools: [{ input, output, handler, present }]
-const double = {
-  name: 'double', description: 'Double a number',
-  identity: { serviceName: 'numbers', action: 'double', method: 'POST' },
-  input, output,
-  handler: ({ input }) => ({ doubled: input.value * 2 }),
-  present: { mcp: ({ doubled }) => ({ content: [{ type: 'text', text: String(doubled) }] }) },
-} satisfies RuntimeMcpToolDefinitionWithOutput<typeof input, typeof output>
-const server = buildMcpServer({ serverInfo: { name: 'numbers', version: '1' }, services: [], runtimeTools: [double] })
-```
-
-Full MCP/AI integrations keep `defineRuntimeTool` from `stitchkit/tools`; those typed values
-remain accepted by the MCP leaf and CLI. The leaf requires the MCP SDK and Zod, with no AI peer.
-
-`RuntimeMcpPresentation` preserves the official SDK's required `content` and typed `_meta`
-fields. A presenter returning `{}` must return `{ content: [] }`; text blocks require string
-text, and metadata must be an object. `structuredContent` and `isError` remain framework-owned.
-This restores SDK checks that an indexed mapped type previously erased.
-
-Unexpected tool causes remain in `hooks.onToolError` and the `error` field of
-`hooks.afterToolCall`. Protocol stderr carries safe errors. MCP resolver failures use those
-same observers without executing the handler or its lifecycle again. HTTP's default
-unexpected-error logging retains its behavior.
-
-A custom state adapter's `update` must invoke `transition(current, context)` while it still
-owns the serialized transaction. `context.assertHeld()` checks the actual transaction or lock
-generation and refuses after completion, rollback or ownership loss. A no-op guard cannot
-satisfy this contract. Existing transition callbacks may keep one parameter. For the owning
-file adapter, replace `{ staleLockMs, retryMs, lockTimeoutMs }` with `{ lockTimeoutMs }`:
-the remaining budget controls acquisition waiting, never expiry of a live transaction.
-Unknown legacy PID locks and historical temporary files are preserved; recover them only
-after independently proving their owner is gone.
-
-Broadcast consumers change `report.halt.reason` checks to the closed `halt.kind` union:
-`retry-after`, `transient`, `permanent` or `ambiguous`. A custom MTProto adapter can classify
-an acknowledged flood refusal as `{ kind: 'retry-after', retryAfterMs: wait }`; the exact
-provider wait is respected. A wait over `maxRetryDelayMs` halts with the recipient pending.
-Unknown write outcome becomes `uncertain`; restarting the same broadcast does not send it
-again. A retry classification must certify that the attempt did not apply the external effect.
-
-HTTP errors gain optional boolean `error.retryable`; framed contract streams use the same
-field. Update closed consumer schemas before producers declaring it. `false` on 502 and
-`true` on 409 remain explicit recommendations through the remote tool path. An absent field
-retains prior status-derived defaults; the field does not change the HTTP client's retry policy.
-The existing seventh `ApiError` constructor argument remains `ErrorOptions`; retryability is
-the new eighth argument.
-
-Caller cancellation now reaches `implementRemote`'s existing HTTP call. Applications bind
-signals to `createCli` / `createCliInvoker` and cooperative handlers observe `ctx.signal`.
-`REQUEST_ABORTED` is nonretryable and exits 130. A disconnected caller does not prove that
-an origin ignoring cancellation or an external provider stopped; keep resource leases until
-that work actually completes.

package/llms/{upgrading-0.44.0-0.61.0.txt → upgrading-0.44.0-0.62.0.txt}

@@ -1,14 +1,131 @@
-# Upgrading 0.44.0 → 0.61.0 — stitchkit docs slice
+# Upgrading 0.44.0 → 0.62.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.44.0 → 0.61.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.44.0 → 0.62.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.44.0 → 0.61.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.44.0 → 0.62.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## 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.
+
 ## Released migration: 0.61.0
 
 Three behaviour changes between versions. None moves an export — the surface is

package/llms/{upgrading-0.62.0-0.78.0.txt → upgrading-0.63.0-0.83.0.txt}

@@ -1,14 +1,192 @@
-# Upgrading 0.62.0 → 0.78.0 — stitchkit docs slice
+# Upgrading 0.63.0 → 0.83.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.78.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.63.0 → 0.83.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.62.0 → 0.78.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.63.0 → 0.83.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## 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:
@@ -974,120 +1152,3 @@ const spent = checkpoints.at(-1)?.metrics.usage?.cost?.value
 `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.