stitchkit 0.104.1 → 0.105.0

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

@@ -1,14 +1,587 @@
-# Upgrading 0.44.0 → 0.61.0 — stitchkit docs slice
+# Upgrading 0.53.0 → 0.67.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.53.0 → 0.67.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.44.0 → 0.61.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.53.0 → 0.67.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.67.0
+
+Three application-kernel changes. Two of them fix silent failures, so the most
+important part of this migration is not what the compiler points at — it is the
+two things that change with no compile error at all: **when your server is
+created**, and **which shutdown budget a signal spends**.
+
+### If you gave `managedServerResource` a thunk
+
+It is now called during `start`, after the resource's dependencies are ready —
+the reading the type always suggested. Before, it was called on the way *down*,
+so `app.start()` resolved, the snapshot said `healthy` and `ready`, and nothing
+was bound to the port.
+
+If your application looked like this, it was never listening:
+
+```ts
+// before — resolves clean, listens on nothing
+managedServerResource({ id: 'http', dependsOn: ['database'], server: () => createServer(config) })
+```
+
+Nothing to change: the same code now binds the port. Check your startup logs for
+a healthy report you never actually verified with a request.
+
+If you used the spread workaround — this resource's phases over your own
+`start` — it keeps working, and you can now delete it:
+
+```ts
+// before
+let handle: ManagedServerHandle<T> | null = null
+const shutdown = managedServerResource({ id: 'http', server: () => handle! })
+const http = defineManagedResource({
+  ...shutdown,
+  dependsOn: ['database', 'socket-io'],
+  start: () => { handle = createServer(config) },
+})
+
+// after
+const http = managedServerResource({
+  id: 'http',
+  dependsOn: [database, socketIo],
+  server: () => createServer(config),
+})
+```
+
+An already-created handle is adopted exactly as before.
+
+### If you passed `shutdown` to `bindProcessSignals`
+
+`bindProcessSignals` used to fill in the schema's defaults for every budget you
+omitted, which made `createApplication({ shutdown })` unreachable on the signal
+path — the one path production stops through. An application declaring five
+seconds took thirty-five.
+
+Declare the budget once, on the application, and delete the repetition:
+
+```ts
+// before — the same two numbers in two places, and only one of them applied
+const app = createApplication({ id: 'svc', resources, shutdown: SHUTDOWN_BUDGET })
+bindProcessSignals(app, { shutdown: SHUTDOWN_BUDGET })
+
+// after
+const app = createApplication({ id: 'svc', resources, shutdown: SHUTDOWN_BUDGET })
+bindProcessSignals(app)
+```
+
+**Check this even if you change nothing.** If you declared a budget on the
+application and did not repeat it on the binding, your process has been stopping
+on 30 s / 5 s and will now stop on what you declared. Compare it against the
+supervisor timeout that watches it — `kill_timeout`, `TimeoutStopSec` — because
+that number was probably calculated from the declaration.
+
+Passing `shutdown` to the binding still works and still wins, key by key: one
+key overrides that key alone and leaves the other at the declaration.
+
+### If you read `resource.dependsOn`
+
+Its type widened from `readonly string[]` to `readonly ManagedResourceDependency[]`
+— `string | ManagedResource` — so a dependency can be declared as the resource
+itself. Declaring stays compatible; reading needs one call:
+
+```ts
+// before
+const ids: readonly string[] = resource.dependsOn ?? []
+
+// after
+import { managedResourceDependencyId } from 'stitchkit/application'
+const ids = (resource.dependsOn ?? []).map(managedResourceDependencyId)
+```
+
+### If you thread a handle through a module-local
+
+This is the pattern the change exists to remove, and it is opt-in — nothing
+breaks if you keep yours:
+
+```ts
+// before
+let socket: SocketHandle | null = null
+const socketIo = defineManagedResource({
+  id: 'socket-io',
+  start: async () => { socket = await createSocketServer(config) },
+})
+const http = defineManagedResource({
+  id: 'http',
+  dependsOn: ['socket-io'],
+  start: () => {
+    if (!socket) throw new Error('socket is not initialized')   // unreachable
+    server = createServer({ socket })
+  },
+})
+
+// after
+const socketIo = defineManagedResource({
+  id: 'socket-io',
+  start: async () => ({ value: await createSocketServer(config) }),
+})
+const http = defineManagedResource({
+  id: 'http',
+  dependsOn: [socketIo],
+  start: (context) => {
+    server = createServer({ socket: context.use(socketIo) })   // SocketHandle
+  },
+})
+```
+
+Declare the dependency with the **resource** when you intend to read from it —
+that is the form `use` can type. `use` refuses a resource missing from
+`dependsOn`, and refuses one that published no value; the second refusal is a
+compile error too.
+
+## Released migration: 0.66.0
+
+Three changes, and only one of them is a feature. The other two are shapes that
+would have had to break later: a vocabulary that described one fact with two
+words, and a store whose only read was the whole conversation.
+
+The compiler points at most of it. Two things change with no compile error —
+what a **total** says about its own provenance, and the fact that token counts
+are now validated where they were not.
+
+### An input that joins a run in flight
+
+#### If you matched exhaustively on `AgentTerminalReason`
+
+`'absorbed'` is new. A run ends this way when a run already in flight took its
+input on and answered it; its state is `'superseded'`, and `absorbedIntoRunId`
+names the run that has the answer.
+
+```ts
+// after
+switch (run.terminalReason) {
+  // …
+  case 'absorbed':
+    // no assistant message of its own — follow run.absorbedIntoRunId
+    break
+}
+```
+
+A run record with `terminalReason: 'absorbed'` and no `absorbedIntoRunId` is
+refused at parse time, and so is `absorbedIntoRunId` on any other reason.
+
+#### If you render or export runs
+
+An absorbed run has **no assistant message**. Anything that assumes "every
+terminal run has one" needs the `absorbed` case — the answer is on the run
+`absorbedIntoRunId` names, and `store.loadRun` resolves it.
+
+#### If you want the policy
+
+```ts
+// after
+runs: { inputPolicy: 'inject' }
+```
+
+It was withdrawn in 0.65.0 and is back with the ordering corrected: the
+absorption commits with the terminal record, not at the step boundary. Read
+*An input that joins a run in flight* in the agent-runtime guide before turning
+it on — in particular what happens when the absorbing run does not complete, and
+how it composes with `coalescePending`.
+
+#### If you implement a store driver
+
+Nothing to do, but know what changed underneath: one terminal commit can now
+save **two** run records, and they must land in the same transaction. A driver
+that persists one of the pair fails `runAgentStoreConformance`.
+
+### A run read without its conversation
+
+#### If you implement `AgentRuntimeStore` by hand
+
+Two members to add. **If your adapter is an `AgentRuntimeStoreDriver` passed to
+`createAgentRuntimeStore`, there is nothing to do** — the driver already had
+everything both need.
+
+```ts
+// after
+loadRun(input: { conversationId: string; runId: string }): Promise<AgentRunView | undefined>
+listActiveRuns(conversationId: string): Promise<readonly AgentRun[]>
+```
+
+`AgentRunView` is `{ snapshotVersion, run, assistant? }`. `assistant` is the
+retained terminal answer, so it is present exactly when the run has ended and
+absent while it is live — a store that returns a live run's draft here lets the
+terminal path resolve a run that has not finished. `listActiveRuns` orders by
+`createdAt` then `id`, and must not report a run that has ended.
+`runAgentStoreConformance` covers both, including the boundary cases.
+
+#### If you have a store **double** in your tests
+
+The runtime now reads `loadRun` where it used to read `loadSnapshot`. A double
+that simulates a condition — a run drifting to another owner, a stale fencing
+token — must apply it to both reads, or the code under test will not see it.
+This is not hypothetical: it turned one of this repository's own fixtures into
+an infinite retry loop, which is how the bounded retry below was found.
+
+#### Nothing else changes
+
+`loadSnapshot` behaves exactly as before, and still returns the whole
+conversation — as does every mutation result. What it costs, and what bounds it,
+is now written down in *Reading a conversation* in the agent-runtime guide.
+
+### One provenance vocabulary, and integral tokens
+
+#### If you match on `'measured'`
+
+A **total** now says `computed`, because it is a sum this code performed rather
+than a count it took — the same rule `AgentUsage` has always applied to a run's
+spend. Two values change with no compile error:
+
+```ts
+// before
+if (result.totalTokens.provenance === 'measured') { /* exact */ }
+// after
+if (result.totalTokens.provenance === 'computed') { /* exact, and derived */ }
+```
+
+It affects `AgentHistoryBudgetResult.totalTokens` and
+`ComposedAgentPrompt.instructionTokens`. A per-message or per-section count is
+still `measured` — only the totals moved. When any part was estimated the total
+is still `estimated`: an estimate survives arithmetic, and that is the weaker
+claim, so it wins.
+
+#### If you produce token counts
+
+They are validated now, in the places they were not. A fractional count throws
+where it used to flow into the context-window arithmetic:
+
+```ts
+// refused from this release on
+estimateTokens: (text) => ({ value: text.length / 4, provenance: 'estimated' })
+// after
+estimateTokens: (text) => ({ value: Math.ceil(text.length / 4), provenance: 'estimated' })
+```
+
+The same applies to `ComposeAgentPromptOptions.estimateFallback` and
+`.historyTokens`, to `AgentPromptBudget.toolSchemas` / `.attachments` /
+`.providerOverhead`, and to `AgentPromptBudget.contextWindow` /
+`.reservedOutput`, which must now be non-negative safe integers.
+
+`AgentUsageValue.value` is `z.int()` too, which matters if you build usage
+records by hand or in a store double. A figure arriving from a **provider** is
+not thrown — `normalizeSdkUsage` and the OpenRouter adapter turn a non-integer
+into `{ provenance: 'unavailable' }`, so a run that already answered is not
+failed over its own bookkeeping.
+
+#### The new export
+
+`AgentProvenanceSchema` / `AgentProvenance` is the whole vocabulary:
+`provider-reported`, `measured`, `computed`, `estimated`, `unavailable`. Each
+surface declares its subset, so nothing widened — `AgentUsageValue` still refuses
+`measured` and `AgentTokenCount` still refuses `provider-reported`. Use it when
+you want one switch over the question instead of two.
+
+## Released migration: 0.65.0
+
+The largest migration of the pre-1.0 line, and most of it is the compiler
+pointing at things. One item is a feature withdrawal and two change behaviour
+with no compile error at all.
+
+### A projection a provider accepts, and a policy withdrawn
+
+### If you compact, or use `system-note`, you were broken and now are not
+
+No code change to adopt the fix — but **check your own code if you call
+`projectAgentHistory` yourself.** System and summary records no longer appear in
+`messages`; they come back in `system` and belong in the provider's instructions
+channel, which is the only place `ai` accepts them:
+
+```ts
+// before — the provider refuses this outright
+const messages = await projectAgentHistory(snapshot.messages)
+streamText({ model, messages })
+
+// after
+const { messages, system } = await projectAgentHistoryDetailed(snapshot.messages)
+streamText({
+  model,
+  instructions: system.map((content) => ({ role: 'system', content })),
+  messages,
+})
+```
+
+If you use `createAgentRuntime`, this is handled for you.
+
+### `inputPolicy: 'inject'` is withdrawn
+
+```ts
+// before
+runs: { inputPolicy: 'inject' }
+// after
+runs: { inputPolicy: 'queue' }
+```
+
+`'absorbed'`, `AgentRun.absorbedIntoRunId` and `AgentRuntimeStore.absorbQueuedRun`
+go with it. A driver built on `AgentRuntimeStoreDriver` needs no change.
+
+### Records must agree with themselves
+
+If you construct `AgentRun` values — a store double, a fixture, a migration —
+derive the state instead of setting it:
+
+```ts
+// after
+import { runStateForTerminalReason } from 'stitchkit/agent-runtime'
+AgentRunSchema.parse({ …run, terminalReason: reason, state: runStateForTerminalReason(reason) })
+```
+
+A terminal state with no reason, a queued run carrying one, and `policy_stop`
+without a `terminalPolicyName` are now all refused at parse time.
+
+### Enum and field changes the compiler will point at
+
+- `AgentTerminalReason`: `'tool_failure'` removed (never produced),
+  `'context_overflow'` added — this runtime's own refusal when the prompt does
+  not fit, which used to report `provider_failure`.
+- `AgentRunState`: `'absorbed'` removed.
+- `AgentRunMetrics.usage` is required.
+- `AgentHistoryBudgetDecision['reason']`: `'superseded'` → `'unspeakable'`.
+
+### Two behaviour changes with no compile error
+
+- **`loop.idleTimeoutMs` now defaults to 60 000.** A run whose provider stream
+  goes quiet for a minute ends as `timeout` instead of holding the lane forever.
+  Pass `null` for the old behaviour, and think about why you want it.
+- **`advanceAgentRuntimeEventCursor` stops returning `gap` for durable events.**
+  If you reload a conversation on `gap`, you were reloading after essentially
+  every run. Transient events still report it, and there it is real.
+
+## Released migration: 0.64.0
+
+Two changes, and only one of them can break a build. Nothing was removed.
+
+### An event that says which kind it is
+
+### Narrow `AgentRunEvent` on `type`
+
+```ts
+// before
+for (const event of events) record(event.usage?.cost?.value ?? 0)
+
+// after — and the compiler will point at every site
+for (const event of events) {
+  if (event.type !== 'run-terminal') continue
+  record(event.usage.cost.value ?? null)   // `usage` is present; unknown says so
+}
+```
+
+`step` is now required on `step-finished`, `terminalReason` on `run-terminal`,
+and `usage` on both. `queueWaitMs` exists only on `run-started`. Nothing was
+removed — the fields that were optional because a *different* kind of event
+lacked them are now simply on the kinds that have them.
+
+Import `AgentRunTerminalEventSchema` (or the sibling schemas) if you construct
+events in tests.
+
+### If you implement `AgentRuntimeStore` directly, move to the driver
+
+Not urgent and nothing breaks today — but the aggregate is no longer the
+supported target, so its future growth will not be announced as breaking
+(→ ADR 0111). The supported shape is one line:
+
+```ts
+const driver: AgentRuntimeStoreDriver<TransactionClient> = { /* six primitives */ }
+export const store = createAgentRuntimeStore(driver)
+```
+
+Run `runAgentStoreConformance` against your adapter before and after any bump —
+see *Before you bump, if you implement an agent store* above.
+
+## Released migration: 0.63.0
+
+Four changes to what a running system reports and how an input reaches a run
+in flight. Nothing moves an export except one added store member, and only an
+application implementing `AgentRuntimeStore` directly has to touch code.
+
+### A spend figure that survives, and an input that joins
+
+### `AgentRuntimeStore` has a ninth member
+
+Only if you implement the aggregate interface directly — an adapter built on
+`AgentRuntimeStoreDriver` needs no change, and the public conformance kit covers
+the new operation.
+
+```ts
+// after
+absorbQueuedRun(input: AbsorbQueuedRun): Promise<AgentStoreMutationResult>
+```
+
+It moves a queued successor's inputs into the run already answering, in one
+mutation, and marks the successor `absorbed`. Two run records change in one
+transaction — if your driver persists them one at a time, persist both.
+
+### A provider failure says so
+
+```ts
+// before — an upstream error arrived as a policy stop with no policy
+if (terminal.reason === 'policy_stop') retryLater()
+
+// after
+if (terminal.reason === 'provider_failure') retryLater()
+if (terminal.reason === 'provider_stop') { /* a length cap or content filter */ }
+```
+
+`policy_stop` now always carries the `policyName` that caused it. If you switch
+exhaustively on `AgentTerminalReason` or `AgentRunState`, add `'provider_stop'`
+and `'absorbed'`.
+
+### `partial` changed meaning
+
+It used to tell you which event kind you were holding. It now tells you whether
+the figure beside it is a confirmed total:
+
+```ts
+// after — true when the provider never reported the run finished
+if (metrics.partial) treatAsFloor(metrics.usage)
+```
+
+Terminal events for runs that were superseded, interrupted, timed out or failed
+before the provider finished now report `partial: true` where they reported
+`false`.
+
+### Checkpoint metrics are a running total
+
+```ts
+// wrong, and now wrong by more than it used to be
+const spent = checkpoints.reduce((total, c) => total + (c.metrics.usage?.cost?.value ?? 0), 0)
+// right
+const spent = checkpoints.at(-1)?.metrics.usage?.cost?.value
+```
+
+### You can read a run's spend back from the store
+
+`AgentRun.usage` is written at every checkpoint and with the terminal record, so
+a dropped observability event no longer loses the number, and a process that dies
+mid-stream leaves behind what it had already spent.
+
+## Released migration: 0.62.0
+
+Two groups of behaviour changes. Nothing moves an export — the surface is
+strictly additive — and every item changes what a running system reports or
+sends, which is what this heading is for. One of them changes a number you may
+already be billing against.
+
+### A run reports what it spent
+
+Three changes to what the runtime says about cost and tokens. Nothing moves an
+export; all three change numbers a running system reports, and one of them
+changes a number you may already be billing against.
+
+#### Multi-step cost was under-reported and is now summed
+
+No code change is needed to get the fix — but check any predicate that reads
+`provenance`:
+
+```ts
+// before — accepted a number that was one step's cost, not the run's
+if (usage.cost?.provenance === 'provider-reported') bill(usage.cost.value)
+
+// after — a sum stitchkit performed says so
+if (usage.cost && usage.cost.provenance !== 'unavailable') bill(usage.cost.value)
+```
+
+`'computed'` means stitchkit added up provider-reported parts. It is not a guess
+— `'estimated'` is the word for that — but it is deliberately not
+`'provider-reported'`, because that label is what a caller filters on when it
+wants a figure it can bill against unchanged, and a sum is not one.
+
+Token totals moved with it. The AI SDK's `totalUsage` is a sum *it* performed
+over per-step provider figures — not a run total any provider handed over — so
+labelling it `provider-reported` was the same overstatement. **A run total on a
+terminal event is always `computed`.** If you want a figure with the provider's
+own word on it, read `step-finished`: each step carries what that call reported.
+
+#### `usage` is always present on a terminal event
+
+```ts
+// before — absent when the run ended before the provider's `finish`
+const spent = event.usage?.cost?.value ?? 0        // silently 0 for a real spend
+
+// after — present, and it says what it does not know
+event.usage?.cost?.provenance === 'unavailable'    // we spent, and cannot say how much
+```
+
+Keep the optional chaining: one `AgentRunEvent` shape covers `run-started`,
+`step-finished` and `run-terminal`, so `usage` stays optional on the type. The
+guarantee is about terminal events, and a schema shared with `run-started`
+cannot express it.
+
+**Do not read `unavailable` as zero.** A run aborted mid-stream has spent real
+money that nobody has counted; a run that never reached the provider has not.
+Both used to look the same and now do not.
+
+#### A losing executor reports its own spend
+
+An execution that loses the terminal compare-and-swap now emits an operator
+`run-terminal` event, because it ran and it spent. If a sink treated those events
+as "runs this process committed", that is no longer true — `AgentRuntimeResult.metrics`
+is still `undefined` for a losing executor and remains the way to tell.
+
+The *delivery* `terminal` event is unchanged and still fires only for the winner,
+so nothing delivers a turn twice.
+
+### An interrupted answer stops passing as a finished one
+
+Two behaviour changes, one shared cause: a run ended by a newer input used to
+leave its half-written answer in the conversation with no sign that it was cut
+off, and the next request to the provider carried it as an ordinary assistant
+turn.
+
+#### The projection marks an interrupted turn
+
+Nothing to change to adopt the fix — the default is the fixed behaviour. What to
+check is whether the marker is the *right* form for your surface, and the
+question that decides it is not "was the run interrupted" but **"did anyone see
+what it produced"**.
+
+```ts
+// after — pick the form; the default is 'assistant-marked'
+createAgentRuntime({ history: { interruptedAssistant: 'system-note' } })
+```
+
+- **The user pressed stop and the text was on their screen** — keep
+  `'assistant-marked'`. The assistant turn is the truthful record of what the
+  human read, and the model should stay consistent with it.
+- **The partial never reached anyone** — a surface that sends nothing until the
+  run is done — prefer `'system-note'`. An assistant turn in provider history is
+  a commitment the model stays consistent with; a system line is context.
+
+If you pass `history.project` you own the projection outright and none of this
+applies — but the same question does.
+
+#### A run ended by a newer input can now say so
+
+```ts
+// before
+runs: { inputPolicy: 'interrupt' }   // ends the run, keeps its partial answer
+
+// after — for a surface where a follow-up message invalidates the answer
+// in flight rather than merely stopping it
+runs: { inputPolicy: 'supersede' }   // ends the run, discards its partial answer
+```
+
+`inputPolicy` also accepts `(input) => policy`, which is how one application
+gives two conversation surfaces different rules without the runtime learning
+which is which.
+
+A superseded run terminates with `terminalReason: 'superseded'`, state
+`'superseded'` and an assistant message of status `'superseded'`. **If you switch
+exhaustively on any of those enums, add the arm** — that is the part of this
+release that can break a build rather than a behaviour. The record itself is
+kept: it is excluded from the projection, not deleted, so an operator can still
+see what was thrown away.
+
 ## Released migration: 0.61.0
 
 Three behaviour changes between versions. None moves an export — the surface is
@@ -599,506 +1172,3 @@ const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => true }
 While migrating, consider replacing hand-rolled `if (client.connected)` guards
 with the new honest surface: check `client.emit(...) === false`, or observe
 drops centrally with `onDroppedEmit`.
-
-## Released migration: 0.50.0
-
-### The factory's scope union now covers per-endpoint overrides
-
-`createContractFactory<Scope>()` already required a typed `scope` on the
-contract. It now holds a per-endpoint `scope` override to the same union. Nothing
-to migrate unless an override is outside the union — which was always a bug: the
-scope reached no auth rule, and `createAuthHook` threw
-`[stitchkit] auth: no rule for scope "…"` on the first request to it.
-
-```ts
-const { defineContract } = createContractFactory<'public' | 'user' | 'admin'>()
-
-defineContract({ prefix: 'posts', scope: 'user' }, {
-  // before: compiled; failed at request time
-  // after:  compile error naming the scope (TypeScript even suggests 'admin')
-  purge: { method: 'DELETE', path: '/all', desc: 'Purge', scope: 'admn', output },
-})
-```
-
-Fix the typo, or widen the factory union if the scope is real. Contracts built
-with plain `defineContract` are unaffected.
-
-### A declared `defineErrors` message is now used
-
-`ErrorDefinition` accepts `message`. Nothing to migrate unless a registry already
-wrote that key: it type-checked before (excess-property checking does not fire
-through a `const` generic) and was ignored, so the code itself went on the wire.
-
-```ts
-const { errors } = defineErrors({ GONE: { status: 410, message: 'Long gone' } })
-// before: errors.GONE().message === 'GONE'
-// after:  errors.GONE().message === 'Long gone'
-```
-
-If a registry carried `message` as a note to the reader rather than as
-user-facing text, either fix the text or drop the key. A code with no `details`
-schema also shows that text to a model (its tool `details` is `{ message }`).
-
-### Optional: adopt `createScopedImplement`
-
-If the app declares one superset handler context because different scopes inject
-different fields, replace it with a scope map. This is additive — `createImplement`
-still works.
-
-```ts
-// before — one context for every scope; `ctx.userId` is typed even in a
-// `public` handler, where the runtime never injects it
-interface AppContext extends RuntimeContext { userId: string; isAdmin: boolean }
-export const implement = createImplement<AppContext>()
-
-// after — each handler typed by its endpoint's effective scope
-export const implementFor = createScopedImplement<{
-  public: object
-  user: { userId: string }
-  admin: { userId: string; isAdmin: boolean }
-}>()
-```
-
-`'public'` must be a key (a contract with no `scope` is `'public'`). Write
-endpoints inline in the contract literal: an endpoint hoisted into a variable
-widens its `scope` to `string` and is reported as undeclared.
-
-## Released migration: 0.49.0
-
-### The server handle became managed
-
-`createServer()` and `serveNode()` return a handle that owns admission, HTTP
-drain, realtime closure and one deadline-bounded runtime stop:
-
-```ts
-// before
-server.stop()
-await socket.io.close()
-// after
-await server.shutdown({ gracePeriodMs: 30_000 })
-```
-
-The runtime-specific instance stays reachable at `.runtime`, so an escape hatch
-you already rely on does not disappear — but code that closed transports itself,
-in its own order, is now racing the handle. Delete the manual closes rather than
-keeping both; the handle's result tells you what it drained and what it forced.
-
-### Socket.IO mounts through the whole handle
-
-```ts
-// before
-createServer({ websocket: socket.websocket, rawRoutes: [socket.route] })
-// after
-createServer({ socket })
-```
-
-One owner for the route, the WebSocket attachment and the closure. For a raw Bun
-lane, keep the composed `websocket` handler and pass `socket` beside it.
-
-### Bun native `routes` are gone
-
-Native routes run before the Fetch handler, so they bypassed managed admission —
-which means they also bypassed shutdown, logging and observability, and that is
-why they had to go rather than be wired up:
-
-```ts
-// before
-createServer({ routes: { '/health': () => Response.json({ ok: true }) } })
-// after
-createServer({ rawRoutes: [{ method: 'GET', path: '/health', handler: () => Response.json({ ok: true }) }] })
-```
-
-### The handshake policy takes a Web `Request`
-
-```ts
-// before
-createSocketIOServer({ serverOptions: { allowRequest: (req, done) => done(null, allowed(req)) } })
-// after
-createSocketIOServer({ allowRequest: (request) => allowed(request) })
-```
-
-The Node-shaped callback is gone, and the policy is now composed with shutdown
-admission on both runtimes: a handshake arriving during drain is refused for
-you.
-
-## Released migration: 0.48.0
-
-### Typed-client request options move to `.withOptions`
-
-Generated endpoint methods reserve their ordinary call signature for contract
-variables. This keeps them directly assignable to callback APIs whose runtime
-supplies its own second context argument, including `react-query-kit` and
-TanStack Query. Move imperative cancellation to the callable's explicit method:
-
-```ts
-// before — endpoint with arguments
-await api.create({ name: 'Max' }, { signal })
-
-// after
-await api.create.withOptions({ name: 'Max' }, { signal })
-
-// before — endpoint without arguments
-await api.health({ signal })
-
-// after
-await api.health.withOptions({ signal })
-```
-
-Direct query and mutation composition remains unchanged:
-
-```ts
-createMutation({ mutationFn: api.create })
-createQuery({ queryKey: ['search'], fetcher: api.search })
-```
-
-There is no positional-options alias. Ordinary generated methods ignore extra
-runtime callback arguments; only `.withOptions` reads `ClientRequestOptions`.
-
-## Released migration: 0.47.0
-
-### HTTP auth moves to the pre-body `authorize` phase
-
-Move the HTTP wiring of `createAuthHook` from `beforeHandle` to `authorize`.
-This lets Stitchkit reject an unauthorized JSON or multipart request after path
-parameter validation but before reading a body chunk. Keep application
-preconditions that depend on validated input in `beforeHandle`.
-
-```ts
-const auth = createAuthHook({ authenticate, authorize })
-
-// before
-createServer({ services, hooks: { beforeHandle: auth } })
-
-// after
-createServer({ services, hooks: { authorize: auth } })
-```
-
-Tool transports already receive parsed input, so their wiring does not move:
-
-```ts
-createMcpHandler({ services, lifecycle: { beforeHandle: auth } })
-```
-
-If a custom HTTP authorization hook read `ctx.input`, `ctx.files` or raw body
-state, split it: identity/scope checks belong in `authorize`; validated payload
-preconditions belong in `beforeHandle` or the domain service.
-
-### Multipart uses a typed descriptor and `ctx.files`
-
-Replace every string multipart declaration, top-level `maxUploadBytes` and
-`ctx.file`. The descriptor is now the only source of request, per-file,
-cardinality and declared media-type policy.
-
-```ts
-// before
-upload: {
-  method: 'POST',
-  path: '/',
-  multipart: 'file',
-  maxUploadBytes: 25 * 1024 * 1024,
-}
-upload: ({ file, input }) => store(file, input)
-
-// after
-upload: {
-  method: 'POST',
-  path: '/',
-  multipart: {
-    maxRequestBytes: 25 * 1024 * 1024,
-    files: {
-      file: {
-        maxBytes: 20 * 1024 * 1024,
-        contentTypes: ['image/*', 'application/pdf'],
-      },
-    },
-  },
-}
-upload: ({ files, input }) => store(files.file, input)
-```
-
-Multiple files are repeated under one multipart field name and arrive in the
-same order:
-
-```ts
-files: {
-  attachments: { multiple: true, maxFiles: 8 },
-}
-
-await api.upload({ attachments: [firstFile, secondFile] })
-// handler: files.attachments is File[]
-```
-
-For direct-to-storage delivery, set `delivery: 'stream'` and implement the
-endpoint with `defineMultipartStream`. A receiver must consume its Web Stream
-and return `{ value, cleanup }`; the final handler sees only receiver values.
-There is no deprecated overload or buffered compatibility path under the old
-contract shape.
-
-## Released migration: 0.46.0
-
-### `REALTIME_CONTRACT_VIOLATION` joined the error registry
-
-Realtime contract failures use the framework error model instead of a bare
-`ZodError`, so an exhaustive map stops compiling until the code is added:
-
-```ts
-// before
-{ …, INTERNAL_SERVER_ERROR: 'internal' } satisfies Record<StitchErrorCode, string>
-// after
-{ …, INTERNAL_SERVER_ERROR: 'internal', REALTIME_CONTRACT_VIOLATION: 'internal' } satisfies Record<StitchErrorCode, string>
-```
-
-Only an exhaustive map breaks. Since 0.56.1 `codeMap` itself is partial, so a
-map without the `satisfies` keeps compiling and lets the code travel as itself.
-
-### `RealtimeRejectedEvent.error` is an `AppError`
-
-```ts
-// before
-onRejected: ({ error }) => error.issues
-// after
-onRejected: ({ error }) => error.details?.issues   // the ZodError moves to error.cause
-```
-
-The envelope gained `reason` and `fault`. The consequence worth checking: code
-reading `.issues` directly does not fail to compile if the handler is loosely
-typed — it silently reads `undefined`. Grep for `.issues` on rejection handlers.
-
-### CLI construction refuses reserved names
-
-A contract field or tool named `json`, `wait`, `quiet`, `dry-run`, `help`,
-`version`, `wait-timeout` or `output-dir` now **throws while the CLI is built**,
-instead of being silently shadowed:
-
-```ts
-// before: app schedule_job --wait 2h  → {"path":"2h"}, exit 0
-// after:  building a CLI over a contract with a "wait" field throws
-```
-
-This one fires at startup, not at call time, so an application shipping such a
-field crashes on boot after the upgrade. That is deliberate — the old behaviour
-corrupted arguments silently — but it means the upgrade is not safe to deploy
-without building the CLI once locally.
-
-### `createToolLogger` writes to stderr
-
-stdout is the JSON-RPC channel of a stdio MCP server, and the previous
-`console.info` default corrupted it. Pass `log` to redirect if your process
-collected tool logs from stdout.
-
-## Released migration: 0.44.0
-
-### MCP TypeScript SDK v2 and protocol `2026-07-28`
-
-This is a hard cut: there is one Stitchkit API and no v1 aliases. Applications
-that expose MCP install the split server package; applications that implement an
-MCP host or run client E2E install the split client package.
-
-```bash
-bun remove @modelcontextprotocol/sdk
-bun add @modelcontextprotocol/server@^2 ai@^7
-# MCP hosts and client-side E2E only:
-bun add -d @modelcontextprotocol/client@^2
-```
-
-Direct SDK imports move to the split packages too:
-
-```ts
-// before
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-
-// after
-import { McpServer } from '@modelcontextprotocol/server'
-```
-
-MCP Apps additionally install `@modelcontextprotocol/ext-apps`. That adapter may
-carry its own isolated v1-era transitive/peer relationship while the ecosystem
-finishes its cutover; it does not permit application code to import the removed
-monolithic SDK. Application-owned MCP server and client code uses the v2 split
-packages exclusively.
-
-```ts
-// before
-import { Client } from '@modelcontextprotocol/sdk/client/index.js'
-import { createMcpHandler } from 'stitchkit/tools'
-
-const handleMcp = createMcpHandler({
-  serverInfo,
-  auth,
-  services,
-  sessionMode: 'stateless',
-})
-rawRoutes: [{ method: 'ALL', path: '/mcp', handler: handleMcp }]
-
-// after
-import { Client } from '@modelcontextprotocol/client'
-import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools'
-
-const mcp = createMcpHandler({
-  serverInfo,
-  auth,
-  services,
-  legacy: 'serve',
-})
-rawRoutes: [createMcpHttpRoute({ path: '/mcp', handler: mcp })]
-// graceful shutdown: await mcp.close()
-```
-
-Keep the owned handle and close it from the same shutdown path as the HTTP
-server. A minimal runtime smoke should list tools before shutdown and prove the
-closed handler no longer serves requests:
-
-```ts
-const mcp = createMcpHandler(config)
-const route = createMcpHttpRoute({ path: '/mcp', handler: mcp })
-
-const beforeClose = await route.handler(listToolsRequest)
-if (!beforeClose.ok) throw new Error('MCP list-tools smoke failed')
-
-await mcp.close()
-```
-
-Remove `@modelcontextprotocol/sdk`, `sessionMode`, `McpSessionMode`, session
-stores and all `Mcp-Session-Id` handling. HTTP is always request-isolated and
-stateless. `legacy: 'serve'` (default) lets the official SDK negotiate supported
-pre-2026 stateless clients on the same endpoint; `legacy: 'reject'` makes it
-modern-only. This is not a stateful compatibility transport.
-
-#### Output shape depends on the negotiated protocol era
-
-Stitchkit always validates the handler result against the declared output
-schema. The negotiated MCP era determines only its wire representation:
-
-| Negotiated era | Non-object `structuredContent` |
-|---|---|
-| MCP `2026-07-28` | the exact schema-valid JSON root: array, scalar or `null` |
-| supported legacy era | the official SDK codec adapts it to `{ result: value }` |
-
-Object roots keep their object shape in both eras. Do not change every consumer
-expectation to the modern shape while `legacy: 'serve'` remains enabled. Pin
-both protocol versions in the consumer's transport E2E and assert the boundary
-explicitly:
-
-```ts
-await expectToolOutputForProtocol('2026-07-28', ['a', 'b'])
-await expectToolOutputForProtocol('2025-11-25', { result: ['a', 'b'] })
-
-async function expectToolOutputForProtocol(
-  protocolVersion: '2026-07-28' | '2025-11-25',
-  expected: unknown,
-) {
-  const client = await connectConsumerMcpClient({ protocolVersion })
-  const result = await client.callTool({ name: 'list_notes', arguments: {} })
-  expect(result.structuredContent).toEqual(expected)
-  await client.close()
-}
-```
-
-`connectConsumerMcpClient` represents the consumer's real HTTP or stdio setup;
-configure its official client with `versionNegotiation.mode.pin` so the test
-cannot silently negotiate a different era.
-
-The stdio helper now returns an owned lifecycle handle:
-
-```ts
-// before
-await createStdioMcpServer(config)
-
-// after
-const stdio = await createStdioMcpServer({ ...config, legacy: 'serve' })
-await stdio.close()
-```
-
-OAuth client registration is now one explicit policy object. CIMD is secure and
-enabled by default; DCR is disabled unless supplied:
-
-```ts
-// before
-mountOAuthProvider({ ...oauth, clients, codes, refreshTokens })
-
-// after
-mountOAuthProvider({
-  ...oauth,
-  clientRegistration: {
-    preRegistered: { get: clients.get },
-    // optional: dcr: { register: clients.register, get: clients.get }
-  },
-  codes,
-  refreshTokens,
-})
-```
-
-A URL client id must be HTTPS and serve a document whose `client_id` exactly
-matches that URL, with explicit `redirect_uris` and
-`token_endpoint_auth_method: 'none'`. Do not keep a consumer-side metadata
-fetcher or DCR fallback; Stitchkit owns SSRF-safe resolution and caching.
-
-Multi-round input is opt-in on the operation and does not change Agent, CLI or
-ordinary HTTP handlers:
-
-```ts
-const ConfirmationSchema = z.object({ confirmed: z.boolean() })
-
-mcp: {
-  inputRequired: [{
-    key: 'confirmation',
-    message: 'Confirm this action',
-    schema: ConfirmationSchema,
-  }],
-}
-```
-
-Configure `multiRound.state` on the MCP server with a key of at least 32 bytes
-and a stable authenticated `principal`. Read accepted typed content from
-`ctx.mcpInput.confirmation`. Multiple declarations run in array order, the
-aggregate remains exactly typed by key, keys must be unique, and declarations
-must fit `multiRound.serving.maxRounds` (default `10`). Do not execute a
-destructive side effect before the complete aggregate is accepted. A modern
-request missing the declared elicitation capability receives JSON-RPC error
-code `-32021`. The official per-request legacy HTTP bridge cannot issue
-server-to-client elicitation, so it returns a deterministic failed tool result;
-multi-round input is never silently treated as complete.
-
-#### Compatibility matrix
-
-| Host / transport | Tools and Apps | Multi-round input | Continuity |
-|---|---|---|---|
-| `2026-07-28` HTTP | yes | yes | request-isolated |
-| supported legacy stateless HTTP | yes | unsupported result | request-isolated |
-| `2026-07-28` stdio | yes | yes | one process connection |
-| supported legacy stdio | yes | official SDK bridge | one process connection |
-| Agent / CLI / ordinary HTTP | unchanged | not exposed | unchanged |
-
-Subscriptions, cross-request progress and resumable stateful SSE are not
-implemented or advertised.
-
-#### Consumer checklist
-
-1. Replace the monolithic SDK with `@modelcontextprotocol/server@^2` and, only
-   for hosts/tests, `@modelcontextprotocol/client@^2`.
-2. Replace raw MCP route wiring with `createMcpHttpRoute`; retain and close the
-   returned handler/stdio handle during shutdown.
-3. Delete all session mode, event-store and session-id code.
-4. Move OAuth client policy under `clientRegistration`; publish CIMD or enable
-   DCR explicitly.
-5. Make `authorizeUser` return the exact consented scope subset. The framework
-   validates that it is a subset of the request before saving the authorization
-   code:
-
-   ```ts
-   // before
-   authorizeUser: async () => ({ userId })
-
-   // after
-   authorizeUser: async (_req, request) => ({
-     userId,
-     approvedScopes: request.scope?.split(' ') ?? [],
-   })
-   ```
-
-6. Snapshot `listToolNames`, run one contract tool, one runtime tool, any raw
-   multimodal tool and every MCP App resource you use.
-7. Exercise modern HTTP and stdio with protocol `2026-07-28`; exercise legacy
-   only if `legacy: 'serve'` is part of your support policy.
-8. Run the consumer's typecheck and runtime gates. A browser/HTTP-only consumer
-   must continue to work without either MCP package.