stitchkit 0.115.0 → 0.117.0

package/llms/tracking.txt

@@ -33,7 +33,7 @@ Both entrypoints are **evolving**.
 ## Contract
 
 ```ts
-import { createTrackingContract } from 'stitchkit/tracking'
+import { createTrackingContract } from 'stitchkit/tracking/contract'
 
 export const tracking = createTrackingContract({
   scope: 'public',
@@ -232,6 +232,76 @@ has an identity. A bot gets a lease that no store holds, so its events are
 `createPresenceRegistry` is who is here now, in this process: touch it from
 `track`, read it for a live feed. It is honestly empty after a restart.
 
+## Real-visitor speed
+
+`stitchkit/tracking/performance` collects Web Vitals from the people who use the site. Install the
+optional peer `web-vitals` and call it once on the page:
+
+```ts
+import { createPerformanceCollector } from 'stitchkit/tracking/performance'
+
+createPerformanceCollector({
+  buildId: BUILD_ID,
+  url: '/api/tracking/performance',
+  visitId: () => client.visitId(),
+})
+```
+
+The library is fetched as its own chunk after `load`, when the browser is idle, so the measurement costs
+the page nothing it is measuring. Each load posts an `early` sample five seconds later and a `final` one
+as the page goes, both with `sendBeacon` and the same `id`: keep the later one. The body is a string, so
+the endpoint declares `safelistedBody: true`. A sample that could not leave waits in session storage for the
+next page, up to 20 of them, and of one load only the newest.
+
+A browser under automation sends nothing, and neither does an agent that admits to being Lighthouse,
+headless Chrome, GTmetrix or a crawler. Lighthouse with its default settings imitates an ordinary browser, so a
+local run with `webdriver` off cannot be told from a visitor.
+
+One load is one document: a client-side navigation stays under the route the page opened on, and whatever
+`web-vitals` reports after a back-forward restore is left out, because it would replace the load's numbers
+with a restore's. A second call on a page returns the running collector.
+
+A sample carries the route, the build, `mobile` or `desktop`, and the five metrics. **A metric that did not
+arrive is `null`, never zero**: most visits have no INP at all, and a zero would pull every average down.
+
+Parse a sample on your own endpoint and store it in your own table:
+
+```ts
+import { redactTrackingText } from 'stitchkit/tracking'
+import { PerformanceSampleSchema, summarizePerformanceMetric } from 'stitchkit/tracking/contract'
+
+const sample = PerformanceSampleSchema.parse(await request.json())
+await samples.upsert({ ...sample, route: redactTrackingText(sample.route) })
+
+const lcp = summarizePerformanceMetric(rows.map((row) => row.vitals.lcpMs))
+// { samples: 42, p75: 1840, p95: null } — a p95 needs 100 samples
+```
+
+The report is yours: which routes matter and what is slow are the application's words.
+
+## Privacy
+
+`redactTrackingText` masks passwords, sign-in credentials, API keys, bearer tokens and signed Telegram launch
+data in a URL or free text, and leaves paths and campaign parameters byte for byte. Text past 16 KiB is cut
+first, because the endpoint is open to anyone. `code` and `hash` count only beside the
+`state` or `auth_date` that makes them credentials, so a promo code stays. `redactTrackingValue` applies the
+same rule through a value of any shape. The client applies it to the landing path, the referrer and the
+campaign tags before sending or storing them. Apply it again on your ingest: anyone can post to that endpoint without running the client.
+
+## Is tracking losing events?
+
+`trackingTelemetryHealth(reports, baselines)` reads the outbox figures of a visit's bootstrap
+(`browserStreamId` as `stream`, `outboxState`, `outboxQueued`, `outboxDropped`) and answers `ok`, `degraded` or
+`unknown`. An application running without an outbox reports `unavailable` and reads as `degraded`. A browser repeats its lifetime `dropped` with
+every visit, so pass what each stream reported before the window as `baselines`, and only the growth counts.
+
+## Bundle weight
+
+`stitchkit/tracking` has no `zod` in its graph: `createTrackingClient` with `indexedDbOutboxStorage` is under
+8 KB gzip, a test holds that, and the build refuses a published file that reaches `zod`. The schemas live in
+`stitchkit/tracking/contract` for the server and a shared contract. Importing that in code a browser loads
+brings `zod` back, so keep a shared contract out of the storefront's client bundle.
+
 ## Not here
 
 GeoIP, event labels, funnels, reports, the analytics page, Socket.IO push into
@@ -246,8 +316,9 @@ looks different even though their mechanics are now one.
 
 Browser-safe visitor-tracking mechanics, with no event vocabulary of their own
 and no React. The React wrapper (a provider and a hook, ~40 lines) is the
-application's — it owns the router and the session. The server half is
-`stitchkit/tracking/server`. → ADR 0166 — [guide](../guide/tracking.md)
+application's — it owns the router and the session. It imports no `zod`: the wire
+shapes are `stitchkit/tracking/contract`, the server half is
+`stitchkit/tracking/server`. → ADR 0166, ADR 0280 — [guide](../guide/tracking.md)
 
 | Export | Kind | Summary |
 |--------|------|---------|
@@ -256,15 +327,6 @@ application's — it owns the router and the session. The server half is
 | `TrackFn` / `EventsWithMetadata` / `EventsWithoutMetadata` | _type_ | `track(type)` / `track(type, metadata)` typed by the application's metadata map, and the two halves of that map |
 | `BuiltinTrackingEventTypes` / `CONVENTIONAL_TRACKING_EVENT_TYPES` | _type_ / const | the application's names for the events the client emits itself; the conventional `PAGE_VIEW` … `INTERACTION` set |
 | `browserTrackingHost` / `TrackingHost` / `TrackingPageContext` | function / _type_ | everything the client takes from a browser tab behind one interface — page context, visibility, scroll depth, events, intervals, clocks, storage — so a test or a non-tab host can supply its own |
-| `createTrackingContract` / `TrackingContractConfig` / `TrackingContractEndpoints` | function / _type_ | `bootstrap` (`POST /visit`) and `track` (`POST /events`, `safelistedBody`) from the application's event types, scope and optional extras |
-| `createTrackingSchemas` / `TrackingSchemas` / `TrackingSchemasConfig` | function / _type_ | every schema of one surface — `event`, `request`, `response`, `disposition`, `entry`, `bootstrap` — from `eventTypes`, optional `eventExtras`, `buildIdPattern`, `maxEventsPerBatch` |
-| `TrackingEventEnvelope` / `TrackingEventShape` | _type_ | `eventId`, `visitId`, `browserStreamId`, `browserSequence`, `type`, `page`, `metadata`, `clientTimestamp` |
-| `TrackEventsRequest` / `TrackEventsResponse` / `TrackEventsResponseSchema` | _type_ / schema | a batch (`buildId`, `events`, `utm`) and its answer (`accepted`, `dispositions`) |
-| `TrackingDisposition` / `TrackingDispositionSchema` / `TrackingDispositionStatus` / `TrackingDispositionStatusSchema` | _type_ / schema | `accepted` / `duplicate` / `identity-invalid` / `excluded-bot` — every one terminal |
-| `VisitEntryContext` / `VisitEntryContextShape` / `VisitBootstrapResponse` / `VisitBootstrapResponseSchema` | _type_ / schema | what a browser reports to open a visit (lineage, landing, referrer, UTM, display, screen, `buildId`, outbox health) and the lease it gets back |
-| `TrackingOutboxState` / `TrackingOutboxStateSchema` | _type_ / schema | `available` / `unavailable` |
-| `UtmData` / `UtmDataSchema` / `AttributionData` / `AttributionDataSchema` | _type_ / schema | campaign tags and a touch (UTM, referrer, landing page) |
-| `DEFAULT_BUILD_ID_PATTERN` | const | `dev` or a git SHA |
 | `createTrackingOutbox` / `TrackingOutbox` / `TrackingOutboxOptions` / `TrackingOutboxHealth` | function / _type_ | the tab-shared outbox: `streamId`, `reserveSequences`, `enqueue`, `acquireLease` / `releaseLease` (short, released on leave), `readBatch`, `acknowledge`, `health`; bounded by count and age |
 | `TrackingOutboxStorage` / `TrackingOutboxMeta` / `TrackingOutboxEvents` / `TrackingOutboxRecord` / `TrackingQueuedEvent` | _type_ | one atomic, all-or-nothing `transact` over a key/value store and an event store (`readonly` for pure reads) — the contract an adapter implements |
 | `indexedDbOutboxStorage` / `memoryOutboxStorage` | function | the IndexedDB adapter (one `readwrite` transaction per `transact`) and the in-memory one for tests and degraded mode |
@@ -276,6 +338,7 @@ application's — it owns the router and the session. The server half is
 | `createOncePerPage` / `OncePerPage` | function / _type_ | one fact per key per page within a window — the guard a twice-mounted component cannot keep itself |
 | `resolveAttribution` / `ResolveAttributionInput` / `ResolvedAttribution` / `AttributionStorage` / `ReferrerRule` | function / _type_ | first-touch once, current-touch on every new UTM; the referrer → source/medium map is the application's, there is no built-in list |
 | `parseUtmFromSearch` / `parseReferrer` | function | the two parsers `resolveAttribution` is built from |
+| `redactTrackingText` / `redactTrackingValue` | functions | mask passwords, sign-in credentials and signed launch data in text or a value of any shape; the key stays, and navigation and campaign parameters are untouched |
 | `resolveTrackedClick` / `ResolveTrackedClickOptions` / `TrackedClick` / `TrackedClickAttributes` / `ClickTarget` | function / _type_ | `data-track` → click, `data-track-action` → interaction, a link to another origin → outbound; attribute names configurable; `hrefPolicy: 'full'` retains query/fragment (default `path-only` omits them), URL credentials excluded; `leavesPage` says which path to send on |
 
 ---

package/llms/{upgrading-0.104.0-0.115.0.txt → upgrading-0.105.0-0.117.0.txt}

@@ -1,14 +1,84 @@
-# Upgrading 0.104.0 → 0.115.0 — stitchkit docs slice
+# Upgrading 0.105.0 → 0.117.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.115.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.105.0 → 0.117.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.104.0 → 0.115.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.105.0 → 0.117.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.117.0
+
+### telegram-chat-pause
+
+**Who must act:** code that relied on a 429 to one chat to stop the token's other chats. A bot that
+only sends needs no change: its other chats stop waiting.
+
+`run` pauses the `chat_id` of a refused send; the token pauses when `tokenPauseChats` chats are refused
+inside `tokenPauseWindowMs`, or when the call has no chat
+([ADR 0278](../decisions/0278-a-telegram-429-holds-the-chat-that-got-it.md)). A second budget kept under a
+derived key to isolate one group is no longer needed: remove it. Where one refusal must still stop everything,
+say so:
+
+```ts
+// before
+await api.sendMessage(chatId, text)
+// after
+await api.sendMessage(chatId, text).catch((error) => {
+  budget.pauseAfter(error)
+  throw error
+})
+```
+
+The catch belongs at the `Api` call, where grammY has turned a returned refusal into a thrown one. A raw
+`budget.run` around a client transformer's `send` gets that refusal as a value.
+
+Search pattern: `budget.run`, and budgets created under a key derived from the token.
+
+### tracking-contract-entry
+
+**Who must act:** code that imports `createTrackingContract` or a tracking schema or wire type from
+`stitchkit/tracking`. Code that only uses the browser client needs no change.
+
+The wire shapes moved to `stitchkit/tracking/contract`, so a page that sends events no longer carries `zod`
+([ADR 0280](../decisions/0280-real-visitor-speed-is-collected-after-the-page.md)):
+
+```ts
+// before
+import { createTrackingContract, createTrackingSchemas } from 'stitchkit/tracking'
+// after
+import { createTrackingContract, createTrackingSchemas } from 'stitchkit/tracking/contract'
+```
+
+Search pattern: imports from `stitchkit/tracking` naming `createTrackingContract`, `createTrackingSchemas`,
+`UtmData`, `AttributionData`, `TrackingEventEnvelope`, `TrackingDisposition`, `TrackEvents*`, `VisitEntryContext`,
+`VisitBootstrapResponse`, `TrackingOutboxState` or `DEFAULT_BUILD_ID_PATTERN`.
+
+## 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
@@ -794,124 +864,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