stitchkit 0.93.0 → 0.94.0

package/llms/upgrading-0.53.0-0.67.0.txt

@@ -0,0 +1,1174 @@
+# 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.53.0 → 0.67.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
+strictly additive — and all three change what a running system does, which is
+what this heading is for.
+
+### A failed `start()` now drains before it rejects
+
+The rollback of a failed startup used to close every resource with a zero
+budget: it returned almost at once, by severing requests the server had already
+accepted. It now spends the application's shutdown budget, so a request already
+in flight is answered rather than killed.
+
+**What to check.** Nothing, if a failed startup has nothing in flight — the
+rollback still returns immediately. The case to think about is a request that
+never finishes: a hung upstream, a client ignoring a close frame, a streaming
+subscription. Under the default 30s grace and 5s force, a `start()` that used to
+reject in milliseconds can now take 35 seconds to reject.
+
+If a fast failure matters more than draining — a supervisor waiting to restart,
+a boot check in CI — declare a smaller budget. The same field is the default for
+`shutdown()` with no options, so this is one decision, not two:
+
+```ts
+// before
+createApplication({ id: 'app', resources })
+
+// after
+createApplication({
+  id: 'app',
+  resources,
+  shutdown: { gracePeriodMs: 5_000, forceTimeoutMs: 1_000 },
+})
+```
+
+The budget is a real bound: a `close` that never returns is abandoned when it
+runs out and reported as a `close` failure, and the startup error remains the
+`cause` of the `AggregateError` `start()` rejects with. → ADR 0107
+
+### A refused realtime frame now answers its sender
+
+A frame that fails the receiver's `args` schema used to be dropped where it
+landed. If the event carries an acknowledgement, the receiver now answers it
+with a reserved envelope and the sender's `request()` rejects at once with
+`RealtimeRequestRejectedError`. → ADR 0106
+
+**What to check before you upgrade one half of a distributed pair.** Look at the
+`ack` schemas on the OLDER peer:
+
+```ts
+// safe: a contract-first acknowledgement refuses the envelope, so the older
+// peer raises RealtimeRequestInvalidAcknowledgementError at once instead of
+// waiting out its deadline. Different error, still an error, and sooner.
+ack: z.object({ stored: z.boolean() })
+
+// NOT safe: a schema that validates nothing accepts the refusal AS A VALUE.
+// The older peer reads a refusal as a successful acknowledgement — silently.
+ack: z.unknown()
+ack: z.looseObject({})
+```
+
+If any acknowledgement on the older side is permissive, tighten it before the
+rollout, or upgrade both halves together.
+
+Also: the receiver now invokes the peer's raw acknowledgement callback for a
+refused frame, including when the peer is a plain Socket.IO client. That
+callback previously could not run on a refused frame and now can.
+
+`RealtimeRejectedEvent['reason']` gained `'rejected-by-peer'`. If you `switch`
+over it exhaustively with an `assertNever` default, that stops compiling — add
+the case.
+
+### Two smaller behaviour changes, easy to miss
+
+**`streamSSE`'s `cancel` no longer awaits the generator.** Teardown is now
+unordered relative to request completion. If your generator releases a resource
+in `return()`/`finally` — a temp file, a pooled connection — and anything
+downstream assumed that had finished by the time the response settled, it no
+longer has. Release in the generator's own `finally` and do not depend on the
+ordering.
+
+**A `socket.io-client` peer that cannot load no longer kills the process.** With
+`onConnectError` configured, the failure is delivered there with
+`terminal: true` instead of crashing. If your handler logs and moves on, you now
+have a live process whose client will never connect, where a supervisor used to
+restart it. Treat `terminal: true` as fatal if that is what you want.
+
+### `reportHealth` inside `start` is no longer discarded
+
+Becoming ready assigned `healthy` unconditionally, throwing away whatever a
+resource reported during `start`. It is now kept, and only a resource that
+reported nothing is assumed healthy.
+
+**How to find what this touches:** grep your `start` bodies for **every**
+`reportHealth` call, not only the ones reporting `degraded`. The old
+unconditional assignment was also a repair — a resource that reported
+`'unhealthy'` early in `start` and never corrected itself was quietly fixed up
+on the way to ready.
+
+Two cases, and they need opposite fixes.
+
+**1. A resource that is genuinely expected to start degraded** — up, but still
+dialling something external. `required` defaults to **`true`**, and readiness
+requires every required resource to be healthy, so such a resource now refuses
+the whole startup where before its report vanished. That is the invariant
+working as intended; what changed is that it can be reached. Say what it is:
+
+```ts
+// before: started, and its report was discarded
+defineManagedResource({ id: 'dialling', start: ({ reportHealth }) => reportHealth('degraded') })
+
+// after: says what it is, and does not gate the application
+defineManagedResource({ id: 'dialling', required: false, start: ({ reportHealth }) => reportHealth('degraded') })
+```
+
+**2. A resource that reported `'unhealthy'` early and became healthy later** —
+a pessimistic report before a connection settled. Here `required: false` is the
+**wrong** fix: it would hide a real failure. Report the recovery instead:
+
+```ts
+start: async ({ reportHealth }) => {
+  reportHealth('unhealthy')
+  await connect()
+  reportHealth('healthy')   // ← previously unnecessary; now it is the fix
+}
+```
+
+**Also check your health endpoint.** An **optional** resource reporting
+non-healthy during `start` now moves the application aggregate to `degraded`,
+where before it stayed `healthy`. A readiness probe that maps `degraded` to a
+non-200 will flip on upgrade — and a supervisor that restarts on that will loop.
+
+The refusals now say which of the two happened: a resource that was never
+healthy is told it "is not healthy" and pointed at `required: false`; one that
+was healthy and stopped is told it "lost readiness" and pointed at
+`onResourceFailure`.
+
+## Released migration: 0.60.0
+
+### close() says what it achieved
+
+`AgentRuntime.close()` returned `Promise<void>` and its contract promised three
+things that cannot hold together. It now returns
+`{ settled, timedOut, remaining }`.
+
+Nothing breaks if you ignore the value:
+
+```ts
+await runtime.close({ gracePeriodMs: 30_000, forceTimeoutMs: 5_000 })
+```
+
+What DOES change is any code that relied on the old sentence "`close()` never
+returns while a run is still in flight" while naming a `forceTimeoutMs`. That
+was never true — the force budget exists precisely to stop waiting — so if your
+process exits straight after `close()`, read the result:
+
+```ts
+const closed = await runtime.close({ gracePeriodMs: 30_000, forceTimeoutMs: 5_000 })
+if (!closed.settled) {
+  // `closed.remaining` runs were still in flight. They stay recoverable
+  // through `scanRecoverable`; close never marks them terminal on its own.
+  logger.warn({ remaining: closed.remaining }, 'exiting with runs in flight')
+}
+```
+
+If you want the old guarantee, omit `forceTimeoutMs`: that is the one
+combination in which `close()` cannot return with a run in flight — and its wait
+is unbounded, which is the trade.
+
+A TypeScript consumer that wrote `const done: void = await runtime.close()` is
+the only shape that stops compiling.
+
+### one name per concept
+
+`AgentModelDeclaration` was a bare alias of `AgentModelDescriptor`, so the same
+type reached consumers under two exported names:
+
+```ts
+// before
+defineModelRegistry<Record<string, AgentModelDeclaration>>({ … })
+// after
+defineModelRegistry<Record<string, AgentModelDescriptor>>({ … })
+```
+
+A find-and-replace covers it; there is no behavioural change. Kept name is
+`AgentModelDescriptor`, the one paired with `AgentModelDescriptorSchema` and
+returned by `registry.descriptor()`.
+
+Two names that look like the same case and are **not** being merged:
+`SocketEventMap` aliases Socket.IO's `EventsMap` so a vendor's name stays out of
+our signatures, and `AgentRun.ownerId` holds the same value a runtime publishes
+as `runtimeEpoch` on its events. The latter is one identity in two roles — "who
+owns this run" and "which runtime emitted this event" — and both declarations
+now say so. Renaming either would make the fencing comparison read worse.
+
+### a reachable public surface
+
+Three exports that the public API required and did not provide, plus one option
+it accepted and ignored.
+
+```ts
+// before — identified by string, because the class was exported nowhere
+if (error instanceof Error && error.name === 'AgentRuntimeConflictError') …
+// after
+import { AgentRuntimeConflictError } from 'stitchkit/agent-runtime'
+if (error instanceof AgentRuntimeConflictError) …
+```
+
+`ActivityTokenBrand` is exported, so `ActivityProjection` can be implemented by
+a test double. `STITCH_ERROR_STATUS` gained `APPLICATION_NOT_ACCEPTING` (503) —
+only an exhaustive `satisfies Record<StitchErrorCode, …>` map stops compiling,
+and the fix is one line. (`GRAMMY_WEBHOOK_NOT_ACCEPTING` joined it in 0.60.1,
+under the same rule — see ADR 0105. This section briefly said the opposite: that
+an adapter's code stays out of the registry. It does not, and leaving it out was
+the worse of the two, because `isStitchErrorCode` then answered `false` and the
+code reached the wire spelled stitchkit's way, past both `codeMap` and
+`unmappedCode`.)
+
+`application.shutdown()` no longer accepts `retryAfterSeconds`. Delete it from
+the call — the kernel never read it. If you meant the HTTP `Retry-After` a
+draining server sends, that lives on `managedServerResource({ retryAfterSeconds })`,
+where it always did the work.
+
+### one shutdown vocabulary
+
+```ts
+// before
+await runtime.close({ drainTimeoutMs: 30_000, forceTimeoutMs: 5_000 })
+// after
+await runtime.close({ gracePeriodMs: 30_000, forceTimeoutMs: 5_000 })
+```
+
+The rename is mechanical. The behaviour change under it is not, and it is the
+reason the rename waited: two combinations were traps.
+`close({ drainTimeoutMs })` with no force budget aborted the runs and returned
+**without waiting for them to settle** — so naming a budget gave a weaker
+guarantee than naming none — and `close({ forceTimeoutMs })` with no drain
+budget never read the force budget, leaving an unbounded wait. Both now behave
+as their names say.
+
+> **Superseded.** This section once ended "and `close()` never returns while a
+> run is in flight". That was never true with a force budget — the budget exists
+> to stop waiting — and `close()` now returns `{ settled, timedOut, remaining }`
+> instead of promising it. See *Released migration: 0.60.0 → close() says what
+> it achieved*, above.
+
+If your shutdown path measured how long `close()` took, expect it to take
+longer in exactly the case where it used to return early — that is the fix, not
+a regression. Defaults stay per-surface: `ShutdownOptions.gracePeriodMs`
+defaults to 30 seconds, and the runtime's omitted budget still means "abort
+immediately", the behaviour `close()` has always had.
+
+### unresolved attachments are omitted
+
+`history.unresolvedFile` defaulted to `text`, and the placeholder it produced
+carried the storage reference:
+
+```ts
+// before — the provider received your object key
+// "[attachment: s3://bucket/tenants/42/invoice.pdf]"
+history: {}
+// after — omitted entirely by default; ask for a placeholder explicitly
+history: { unresolvedFile: 'text' }   // "[attachment: invoice.pdf]"
+```
+
+Two things to check. If a prompt relied on the model seeing *something* where an
+unresolved file was, set `unresolvedFile: 'text'` — behaviour otherwise changes
+silently, since an omitted part produces no error. And if any stored transcript
+or provider log contains the old placeholder, it contains your storage layout;
+treat those as disclosed. The `error` policy still names the reference, because
+it is thrown into your process rather than sent upstream.
+
+### one bounded recoverable scan
+
+`AgentRuntimeStore` had two scans: a mandatory unbounded one and an optional
+paged one. The runtime only ever called the optional one, so implementing the
+interface as written produced a store that threw on its first `recover()`:
+
+```ts
+// before — the mandatory member was dead, the needed one was optional
+{
+  scanRecoverable: () => loadEveryRecoverableSnapshot(),
+  scanRecoverablePage: ({ cursor, limit }) => page(cursor, limit),
+}
+// after — one member, the bounded signature the driver already used
+{ scanRecoverable: ({ cursor, limit }) => page(cursor, limit) }
+```
+
+Delete the unbounded implementation rather than porting it: loading every
+recoverable conversation to start is the shape 0.59.0 and ADR 0101 moved away
+from, and nothing calls it now. If you built on `createAgentRuntimeStore()` you
+have nothing to do **if you only pass it to the runtime** — it implements the
+bounded page for you from the same driver member. If you CALL it yourself, the
+member changed shape: `scanRecoverable()` took no argument and returned
+snapshots; it now takes `{ cursor?, limit }` — `limit` is required — and returns
+one page of descriptors.
+```ts
+// before: const stale = await store.scanRecoverable()
+// after:  const { items, nextCursor } = await store.scanRecoverable({ limit: 100 })
+```
+
+### published application status
+
+`createApplicationHealthHandler` and `createApplicationOperationalHandlers` no
+longer serialise the whole `ApplicationSnapshot`. They publish
+`ApplicationStatusProjection` — the verdict plus resource counts:
+
+```ts
+// before — the response named every resource and its dependency edges
+const { resources } = await fetch('/status').then((r) => r.json())
+resources[0].dependsOn
+// after — the topology is read in-process, where it always belonged
+app.getSnapshot().resources[0].dependsOn
+```
+
+The consequence to check is not compilation — it is whatever already consumes
+these routes. A dashboard that drew the dependency graph from `/status`, or an
+alert keyed on `admission.pending`, goes blank rather than red: the fields are
+absent, not zero. Both are available from `getSnapshot()`, so the fix is to read
+them in the process that owns the application and publish them on a channel you
+control. If a route was reachable from outside your network, treat the previous
+payload as disclosed and rotate nothing but assume the topology is known.
+
+## Released migration: 0.59.0
+
+### Normalized agent runtime persistence
+
+`AgentRuntimeStoreDriver` no longer reads and rewrites a lifetime `AgentStoredState` JSON
+aggregate. Migrate that row and its recoverable/archive projections once:
+
+1. Copy `conversationId` and `version` into the bounded runtime head.
+2. Write every `AgentStoredState.runs[]` entry as one normalized run record.
+3. Write every `AgentStoredState.admissions[]` entry as one admission receipt and copy its
+   canonical input into that receipt.
+4. For terminal runs, retain the canonical assistant on the run record before deleting any old
+   history/archive rows.
+5. Replace the recoverable projection with an index over normalized run `state`.
+6. Cut the adapter over atomically; there is no compatibility driver or dual-write mode.
+
+```ts
+// before
+createAgentRuntimeStore({
+  state: { load, compareAndSwap },
+  history: { load, loadById, apply },
+  scanRecoverable,
+})
+
+// after
+createAgentRuntimeStore({
+  head: { load, compareAndSwap },
+  runs: { load, loadByAssistantMessageId, loadMany, listActive, save },
+  admissions: { load, loadByInputMessageId, create },
+  history: { load, apply },
+  scanRecoverable,
+})
+```
+
+`AgentRuntimeHeadSchema`, `AgentStoredRunSchema` and `AgentAdmissionReceiptSchema` replace
+`AgentStoredStateSchema` and `AgentAdmissionIdentitySchema`. Run
+`runAgentStoreConformance()` against the migrated adapter before switching production traffic.
+If an application implements `AgentRuntimeStore` directly, its duplicate result must also include
+the canonical `run` and the retained `assistant` for a terminal run.
+
+## Released migration: 0.58.0
+
+### The default history projection rejects invalid chronology
+
+`projectAgentHistory` no longer forwards records a provider contract cannot
+accept. A completed assistant record before the first user message, and an
+assistant record whose tool calls have no matching results, are omitted with an
+inspectable decision instead of being sent upstream:
+
+```ts
+// before — a leading assistant record was forwarded as-is
+projectAgentHistory(messages)
+// after — opt in explicitly, and only where the provider contract permits it
+projectAgentHistory(messages, { leadingAssistant: 'allow' })
+```
+
+Two consequences the changelog does not spell out. First, the projection can now
+return **fewer** messages than the history holds, so any assertion or metric
+that compared projected length against stored length will move; read the
+detailed projection instead — it reports what was omitted and why, which is the
+supported way to see the difference. Second, the omission is silent to the
+provider but not to you: if a conversation suddenly loses its leading context,
+the decision record is where that shows up, not the transcript.
+
+### Operator events redact `internalCause` by default
+
+Raw provider and tool failures no longer travel in operator events unless the
+sink asks for them:
+
+```ts
+// before — internalCause was present
+createAgentObservability({ write })
+// after — an explicit operator-only opt-in
+createAgentObservability({ write, includeInternalCause: true })
+```
+
+The consequence to check before upgrading: any dashboard, alert or log
+processor keyed on `internalCause` goes blind the moment you upgrade, and it
+goes blind quietly — the field is absent, not empty. Set the flag on the
+operator sink you own. Product delivery stays redacted regardless of the flag;
+this option cannot widen what reaches a user.
+
+## Released migration: 0.57.0
+
+### Duplicate admission results carry the complete identity
+
+Custom `AgentRuntimeStore` adapters must persist and return the input and
+assistant identities associated with an idempotency key:
+
+```ts
+// before
+return { outcome: 'duplicate', runId, snapshot }
+
+// after
+return { outcome: 'duplicate', input, inputMessageId, runId, assistantMessageId, snapshot }
+```
+
+Prefer replacing the custom aggregate reducer with `createAgentRuntimeStore()`;
+its admission record and transaction driver implement this contract
+automatically. Historical note: 0.59.0 reshaped this driver again, so an adapter
+crossing both versions should read that section first and migrate once.
+
+### `AgentRuntimeEvent` adds a post-commit `admission` variant
+
+Add it to any exhaustive publisher switch. Its `assistant` is either the pending
+placeholder for a new assignment or the canonical persisted assistant for a
+duplicate:
+
+```ts
+case 'admission':
+  await persistProductProjection(event.input, event.run, event.assistant)
+  break
+```
+
+The consequence for an exhaustive switch written without a `default` branch is a
+compile error, which is the point. The consequence for a switch that *has* a
+`default` is worse and silent: post-commit admissions fall into it and are
+projected as an unknown event. Grep for publisher switches before upgrading.
+
+## Released migration: 0.56.0
+
+### Surface manifests are version 2
+
+`operation.tools` could not describe a role-selected MCP surface, a different
+Agent or CLI selection, or an advertised `extend` schema, so projections moved
+out of the canonical operation:
+
+```ts
+// before
+manifest.operations[0].tools.MCP
+// after
+manifest.toolSurfaces.find((s) => s.transport === 'MCP' && s.surface === null)?.tools
+
+// before
+buildSurfaceManifest({ mcpSurfaces: { admin: { services, extend } } })
+// after
+buildSurfaceManifest({ mcpSurfaces: { admin: { services } }, mcpPreparation: { extend } })
+```
+
+A committed snapshot is regenerated once, deliberately: `manifestVersion` is
+`2`, and `ConformanceTransport` gained `REALTIME`, so any exhaustive
+`Record<ConformanceTransport, …>` must handle it.
+
+### `FILE_*` codes joined the error registry
+
+`StitchErrorCode` gained `FILE_INVALID_PATH`, `FILE_OUTSIDE_ROOT`,
+`FILE_NOT_FOUND`, `FILE_NOT_REGULAR`, `FILE_INSPECTION_REJECTED`,
+`FILE_TOO_LARGE` and `FILE_EXISTS`. Only exhaustive maps break:
+
+```ts
+// before — compiled while the registry had no file codes
+const copy: Record<StitchErrorCode, string> = { …, RATE_LIMITED: '…' }
+// after — add the seven managed-file codes (or use Partial<Record<…>>)
+```
+
+Unexpected IO stays scrubbed as `INTERNAL_SERVER_ERROR`: the new codes are the
+caller-safe ones only.
+
+### `ScopedAuthHook` is nominal
+
+A hand-written function shaped like an auth hook is no longer assignable —
+identity now comes from the factory, so scope ownership and the inferred
+context cannot drift apart:
+
+```ts
+// before — a structural stand-in
+const auth: ScopedAuthHook<Scopes> = async (ctx, endpoint) => { … }
+// after — create it, then compose domains
+const auth = createAuthHook({ resolve, rules })
+const composed = composeAuthHooks({ hooks: [auth, billingAuth], defaultScope: 'public' })
+```
+
+### Managed-file inspectors also run on reads
+
+An inspector is no longer write-only, and it has a finite default deadline
+(15 s). Make it read-aware and idempotent — a read carries no
+`declaredMediaType`:
+
+```ts
+// before
+inspect: ({ declaredMediaType }) => inspectDeclaredType(declaredMediaType!)
+// after
+inspect: ({ prefix, declaredMediaType, signal }) =>
+  inspectBytes(prefix, { declaredMediaType, signal })
+```
+
+Set `inspectionTimeoutMs` explicitly when 15 seconds is the wrong budget.
+
+### Direct async-operation binding needs a wire-stable ID
+
+A direct binding reuses the start output as the follow-up wire input, so the ID
+schema must parse to itself (`z.input` equals `z.output`, no transform,
+coercion, default or overwrite). Anything else is parsed twice:
+
+```ts
+// before — a transform silently ran on start and again on every follow-up
+defineAsyncOperationContract({ binding: 'direct', id: z.string().transform(Number) })
+// after — keep the wire shape, adapt explicitly
+defineAsyncOperationContract({
+  binding: 'adapted',
+  id,
+  adapters: { idFromStart, inputFor },
+})
+```
+
+## Released migration: 0.55.0
+
+### Peer-free `implementRemote`
+
+`implementRemote` now has one canonical, optional-peer-free owner. This keeps
+MCP SDK and AI SDK modules out of CLI bundles that only proxy HTTP calls:
+
+```ts
+// before
+import { implementRemote } from 'stitchkit/tools'
+// after
+import { implementRemote } from 'stitchkit/remote'
+```
+
+### Managed file boundary and strict auth returns
+
+Create one boundary during application bootstrap and pass the capability, never
+a per-call directory or host path:
+
+```ts
+import { createManagedFileBoundary } from 'stitchkit/files'
+
+const files = await createManagedFileBoundary({ root: '/srv/app-files' })
+
+// before
+defineDownloadTool({ defaultDir: '/srv/app-files', resolveUrl, ...common })
+defineUploadTool({ upload: (path) => provider.uploadFile(path), ...common })
+defineViewFileTool({ baseDir: '/srv/app-files', ...common })
+
+// after
+defineDownloadTool({ files, resolveUrl, ...common })
+defineUploadTool({ files, upload: ({ bytes }) => provider.upload(bytes), ...common })
+defineViewFileTool({ files, ...common })
+```
+
+Downloaded `path` is now relative to the boundary and MIME metadata is named
+`mediaType`. Update raw `mountDownload`/`mountUpload`/`mountViewFile` configs the
+same way. Auth predicates must explicitly return `true`, `false`, or a plain
+object of context fields; replace accidental `undefined` fallthroughs with the
+intended boolean.
+
+## Released migration: 0.53.0
+
+### Realtime `emit` returns `boolean` instead of `void`
+
+Every **call site** compiles and behaves exactly as before — the return value
+is new information (`true` = accepted by the transport, `false` = dropped
+while the browser client was disconnected), not a behavior change. What breaks
+is **implementing** the interfaces: a test mock or app-side adapter of
+`SocketIOClient` / `RealtimeClient` / `ValidatedRealtimeSocket` /
+`RealtimeServer` whose `emit` returns `void` no longer typechecks.
+
+```ts
+// before — a void mock satisfied the interface
+const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => {} }
+// after — report acceptance (true is what a live server-side emit reports)
+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`.