stitchkit 0.60.1 → 0.62.0

package/llms-full.txt

@@ -1515,6 +1515,7 @@ focused helper — not a sub-framework.
 |--------|------|
 | `serveFile()` | serve a file with `Range` / `304` / `HEAD` (media seeking) |
 | `streamSSE()` | turn an `AsyncGenerator` into a Server-Sent-Events `Response` |
+| `ndjsonRoute()` / `sseRoute()` | a **long-lived** subscription route, with the whole checklist |
 | `parseMultipart()` | parse a typed buffered/streaming multipart descriptor |
 | `createRateLimiter()` | per-key token-bucket rate limiting |
 | `createCache()` + `cacheHeaders()` | in-memory TTL cache; `Cache-Control` builder |
@@ -1540,6 +1541,64 @@ stream: () => streamSSE(tokens()),    // → a text/event-stream Response
 
 The client side is [`parseSSE`](./client.md#sse).
 
+`streamSSE` is for a stream that **finishes** — a completion, a job's output.
+For one that stays open, see below.
+
+### Long-lived subscriptions
+
+`streamSSE` assumes the generator keeps producing. A **subscription** is the
+opposite: silence is its normal state, and three unrelated things have to be
+right or it breaks without saying anything. (Measured: with a heartbeat under
+the threshold, either of the first two alone keeps an in-process connection
+alive — the first earns its place against what a heartbeat cannot reach, an
+intermediary applying its own idle rule.)
+
+1. **The generic idle timeout has to go.** Without `server.timeout(req, 0)` Bun
+   resets the connection after ten seconds — a healthy connection severed on a
+   schedule, precisely because the subscriber had nothing to be told.
+2. **Something has to be on the wire.** Even with the timeout gone,
+   intermediate proxies are under no obligation to hold a connection carrying no
+   bytes.
+3. **The headers have to leave at open.** A runtime sends nothing until the body
+   produces a byte, so the consumer's `fetch` does not return. "Subscribed and
+   silent" then looks exactly like "not answering", and there is nothing to
+   inspect because there is no response yet.
+
+`ndjsonRoute` / `sseRoute` do all three, and close the source when the consumer
+goes away:
+
+```ts
+import { ndjsonRoute } from 'stitchkit/server'
+
+const events = ndjsonRoute({
+  path: '/events/subscribe',
+  heartbeatMs: 5_000,                       // default; keep it well under 10s
+  source: async function* (request, { signal }) {
+    for await (const event of subscribe({ signal })) yield event
+  },
+})
+
+createServer({ port: 3000, rawRoutes: [events] })
+```
+
+The client half is [`parseNDJSON`](./client.md#ndjson) — and the keep-alive
+frame is an **empty line**, so "blank lines are skipped" is part of the
+documented contract rather than an agreement between two halves of one project.
+`sseRoute` frames the same source as SSE and is read by `parseSSE` unchanged.
+
+**Honour `context.signal`.** It is the one part the route cannot do for you, and
+the reason is worth knowing: an async generator serialises its requests, so
+`iterator.return()` issued while a `next()` is in flight is *queued behind it*.
+A subscription is in `next()` almost always, so the close would wait for an
+event that may never come. The signal is aborted the moment the consumer
+disconnects — through either route, a request abort or a stream cancel — and a
+source that waits on it stops at once. (`iterator.return()` is still called; it
+closes a source suspended at a `yield`.)
+
+A failure part-way through arrives as a final frame carrying the framework
+error envelope, normalised — once the headers are gone there is no status left
+to send, and an internal message must not reach the wire raw.
+
 ### Multipart
 
 The contract owns one descriptor for buffered and streaming delivery:
@@ -2172,7 +2231,42 @@ for await (const event of parseSSE(res)) {
 }
 ```
 
-The server side is [`streamSSE`](./server.md#sse-streaming).
+The server side is [`streamSSE`](./server.md#sse-streaming), or
+[`sseRoute`](./server.md#long-lived-subscriptions) for a subscription that stays
+open.
+
+## NDJSON
+
+`parseNDJSON` reads a newline-delimited JSON body — the client half of
+[`ndjsonRoute`](./server.md#long-lived-subscriptions):
+
+```ts
+import { parseNDJSON } from 'stitchkit'
+
+const subscription = new AbortController()
+const res = await fetch('/api/events/subscribe', { signal: subscription.signal })
+for await (const event of parseNDJSON(res)) {
+  console.log(event)
+}
+
+// ...to unsubscribe:
+subscription.abort()
+```
+
+**Use the `AbortController` for a subscription.** Leaving the loop with `break`
+cancels the body, and on a stream that ends that is enough — but it is not a
+reliable way to tell the *server* you are gone: measured against Bun today, the
+source stayed alive for seconds after a client-side cancel. Aborting the request
+reaches [`context.signal`](./server.md#long-lived-subscriptions) on the other
+end at once, which is what actually ends the work.
+
+**Blank lines are skipped**, and that is the contract rather than a
+convenience: a long-lived stream must send something while it is idle or
+intermediaries drop it, and an empty line is the natural pulse for this framing.
+Writing the rule down on both sides is what stops it being a verbal agreement —
+the server's keep-alive and the reader's skip are one decision with two
+implementations. A frame that is not valid JSON goes to `onParseError` rather
+than throwing, so one bad line does not end the subscription.
 
 
 ==============================================================================
@@ -3578,6 +3672,110 @@ process-local coordinator releases its lane only after terminal commit.
 input + queued run → running → execution settled → terminal CAS → successor
 ```
 
+## What happens to a run when new input arrives
+
+`runs.inputPolicy` decides. It takes three values (or a function returning one);
+the fourth row below is a behaviour it deliberately does not offer yet:
+
+| policy | the run in flight | what it already produced |
+|--------|-------------------|--------------------------|
+| `queue` (default) | finishes first | kept |
+| `interrupt` | ends | kept, and marked as cut off |
+| `supersede` | ends | discarded from the prompt, kept in the record |
+| _inject_ | continues | — not supported; see below |
+
+`interrupt` and `supersede` differ in exactly one thing, and the question that
+picks between them is **not** "was the run interrupted" but **"did anyone see
+what it produced"**:
+
+- The user pressed **stop**. The partial answer was streamed to their screen and
+  they read it. It belongs in the conversation — dropping it makes the history
+  lie to the model about what the human has seen. That is `interrupt`.
+- A newer message **superseded** the run. Whether the partial reached anyone
+  depends on the delivery surface: a token stream shows it as it is produced, a
+  surface that sends nothing until the run is done never showed it at all. When
+  it reached nobody, it is not part of the conversation. That is `supersede`.
+
+**Stitchkit cannot answer that question for you** — delivery belongs to the
+transport, and the runtime sees an abort, not a screen. Hence a declared policy
+(→ ADR 0108), and hence `inputPolicy` accepting a function, so one application
+can hold two surfaces with different rules without the core learning which is
+which:
+
+```ts
+runs: {
+  inputPolicy: (input) =>
+    protocol.parseContext(input.context).surface === 'operator' ? 'queue' : 'supersede',
+}
+```
+
+`input.context` is the **raw** context here — admission runs before the runtime
+parses it, so the callback narrows it itself with the protocol it already has.
+
+A superseded run ends with `terminalReason: 'superseded'`, run state
+`'superseded'` and an assistant message of status `'superseded'`. **The record
+is kept** — excluded from the projection, not deleted — so an operator can see
+what was thrown away, and run identity, admission receipts and the terminal CAS
+keep the row they depend on. Compaction leaves it alone for the same reason: a
+turn whose answer is never spoken is not a turn that may be summarised into one,
+because that would both feed the discarded text to the summariser and drop the
+record in `replacedMessageIds`.
+
+It is also outside the token budget. `selectAgentHistory` removes it with reason
+`'superseded'` and does not count it, so an abandoned fragment cannot push a
+real turn out of a context it never occupies.
+
+### How an interrupted turn reaches the model
+
+An interrupted turn is projected, and says so:
+
+```text
+{ role: 'assistant', content: [
+    { type: 'text', text: 'We are the team, where would you like' },
+    { type: 'text', text: '[interrupted: this turn was cut off before it finished]' },
+]}
+```
+
+`history.interruptedAssistant` chooses the form, and the difference between the
+first two is structural rather than cosmetic. **An assistant turn in provider
+history is a commitment**: the model reads its own previous turn as something it
+said and stays consistent with it. A system line is context.
+
+| value | form | right when |
+|-------|------|-----------|
+| `assistant-marked` (default) | assistant turn plus a marker | the human read the text |
+| `system-note` | `[interrupted] partial response: …` as a system line | the fragment reached nobody |
+| `omit` | not projected at all | you want it gone from the request |
+
+There is deliberately no value that reproduces what the projection used to do,
+which was to send the partial as an ordinary assistant turn and drop its
+`control` marker on the way. That was the defect, not a behaviour to stay
+compatible with.
+
+`projectAgentHistoryDetailed` reports what reached the provider, including part
+types that no projected content stands for:
+
+```ts
+const { decisions } = await projectAgentHistoryDetailed(snapshot.messages)
+// → { messageId: 'assistant-2', action: 'projected', reason: 'projected',
+//      omittedParts: ['source', 'provider'] }
+// → { messageId: 'assistant-1', action: 'omitted', reason: 'superseded' }
+```
+
+`runtime.stop(key, 'supersede')` is the same decision taken by hand: the
+process-local escape hatch chooses the reason, so a caller that knows the answer
+was never delivered can discard it without a newer input arriving.
+
+### The one that is not supported
+
+**inject** — hand the input to the loop between tool calls and let the run
+continue — has no primitive. `loop.prepareStep` passes the AI SDK return type
+through, so an application *can* append messages between steps, but nothing
+hands `prepareStep` the pending inputs and nothing attaches an absorbed input to
+the running run's `inputMessageIds`. A run that answered two messages would
+carry a durable record claiming it answered one. It is reachable by hand, not
+supported.
+
 With `runs.coalescePending: true`, an active lane has at most one queued
 successor. Every later accepted input is atomically appended to that successor;
 its `AgentRun.inputMessageIds` records the whole batch and every input ticket
@@ -3628,8 +3826,12 @@ coordinator signal. If provider completion races that revision change, the termi
 the canonical snapshot. An already-terminal winner settles the ticket directly; a still-owned
 `interrupt_requested` run is committed as `interrupted`, and unrelated aggregate-head conflicts
 remain retriable while the run is active with the same owner and fencing token. A stale owner or
-fencing token remains a conflict. Only the execution that applies the terminal mutation emits the
-terminal event and operator metrics; a loser settles from canonical state without republishing it.
+fencing token remains a conflict. Only the execution that applies the terminal mutation publishes the
+**delivery** `terminal` event — a loser settles from canonical state without republishing the turn,
+and its `AgentRuntimeResult.metrics` is `undefined`. The **operator** `run-terminal` event is not
+gated that way: a losing execution still ran, and still spent whatever it spent, so it reports its
+own usage. The two channels answer to different readers — delivering a turn twice is a user's
+problem, and omitting a run's cost is an operator's.
 `runtime.stop(key)` is the process-local signal-only escape hatch.
 
 ## Store operations
@@ -3788,10 +3990,43 @@ sending new event kinds to existing request sinks. Product events omit provider
 causes. Operator `internalCause` is also redacted by default; an operator-only sink must explicitly
 set `includeInternalCause` and own its retention policy.
 
-Usage values carry `provider-reported`, `computed`, `estimated` or
-`unavailable` provenance. Cost additionally carries an ISO currency code;
-OpenRouter-reported cost is normalized as USD. Missing values remain absent,
-never zero-filled.
+### What a run says it spent
+
+Usage values carry `provider-reported`, `computed`, `estimated` or `unavailable`
+provenance, **per field**. Cost additionally carries an ISO currency code;
+OpenRouter-reported cost is normalized as USD.
+
+Read the provenance before the number (→ ADR 0109):
+
+- **`provider-reported`** — the provider handed us exactly this. On
+  `step-finished`, that is what a step's figures are.
+- **`computed`** — a total, added up over steps. **Every figure on a terminal
+  event is this**, tokens included: the AI SDK's `totalUsage` is a sum it
+  performed, not a number a provider reported for the run. It is not a figure to
+  bill against unchanged.
+- **`unavailable`** — nobody reported it. Not zero.
+
+Two rules follow from that last one, and they differ by field on purpose:
+
+- **A token total with an unreported step is a floor**, labelled `computed`. A
+  token count is a diagnostic, and a floor is a useful one.
+- **A cost with an unreported step is `unavailable`, not a floor.** Money is what
+  people bill against, and "at least $1.00" reported as `$1.00` is the same class
+  of lie this whole section exists to remove. One step that did not report its
+  cost makes the run's cost unknown — not smaller. It also stays unknown: later
+  steps reporting normally cannot revive it.
+
+**A terminal event always carries `usage`.** A run that ended before the provider
+reported anything — superseded, interrupted, timed out, shut down, failed —
+carries every field `unavailable`. That is deliberately different from a run that
+spent nothing, and an omitted object could not tell you which one you had.
+
+Two costs in different currencies do not add: the sum reports `unavailable`
+rather than picking a label. The core records a currency and never converts one.
+
+Usage is **not durable**. It reaches you on the operator and delivery event
+streams and in `AgentRuntimeResult.metrics`, and stitchkit writes no spend to the
+store — where a figure lives afterwards is the application's (→ ADR 0002).
 
 The sink deduplicates stable event IDs by default. Cross-crash exactly-once still requires a durable
 outbox.
@@ -3939,6 +4174,71 @@ may retain lifecycle `ready`, but snapshot health is `degraded`, never
 
 Readiness is not hidden polling. A resource reports health changes through its
 lifecycle context; the application decides when a database/provider probe runs.
+
+**A `reportHealth` call inside `start` is kept.** A resource that says nothing
+is assumed healthy once it is ready; one that reports its own health has already
+answered the question, and the answer stands. (It used to be overwritten — and
+the example above hides that, because `healthy` is the same value that
+overwrote it.)
+
+**A resource is required unless you write `required: false`.** That default is
+what makes the next sentence bite.
+
+**Readiness requires every required resource to be healthy**, so "ready but
+degraded" is unreachable for a required resource by construction: an
+application whose required resource reports anything but `healthy` refuses to
+start, and says which resource and in what state. The refusal distinguishes the
+two ways to get there — a resource that was never healthy is pointed at
+`required: false`; one that was healthy and stopped is pointed at
+`onResourceFailure`. A resource that is *expected* to start
+degraded — up, but still dialling something external — belongs behind
+`required: false`, where it keeps its own health and does not gate the
+application:
+
+```ts
+defineManagedResource({
+  id: 'dialling',
+  required: false,
+  start: ({ reportHealth }) => { reportHealth('degraded') },
+})
+```
+
+An optional resource reporting non-healthy does not gate readiness, but it does
+move the application **aggregate** to `degraded` — which a readiness endpoint
+mapping `degraded` to non-200 will notice.
+
+If startup fails, every resource that was already started is closed in reverse
+order. The rollback runs **one** phase — `close` — not the five a real shutdown
+runs, and `close` receives the same deadlines a shutdown would give it, so a
+server drains what is in flight instead of aborting it.
+
+Those deadlines come from the application's declared budget, and it is worth
+knowing what they cost. With nothing in flight the rollback returns at once: a
+grace period is a ceiling, not a sleep. With something in flight it waits for
+it — that is the point — and with something that **never finishes**, a hung
+upstream or a client that ignores a close frame, it waits out the whole budget
+before forcing. Under the default 30s+5s that turns a failed `start()` that used
+to reject in milliseconds into one that can take 35 seconds to reject.
+
+An application that would rather hear about a broken start immediately says so,
+in the one place both stopping paths read:
+
+```ts
+createApplication({
+  id: 'app',
+  resources,
+  // Applies to `shutdown()` called with no options AND to the rollback of a
+  // failed `start()`, which has no call site of its own to be told.
+  shutdown: { gracePeriodMs: 5_000, forceTimeoutMs: 1_000 },
+})
+```
+
+The budget is a real bound, not just a number handed to each resource: a `close`
+that never returns is abandoned when the budget runs out, reported as a `close`
+failure, and the startup error stays the `cause` of the `AggregateError` that
+`start()` rejects with. Without that, one unresponsive resource could keep a
+failed startup from ever reporting why it failed.
+
 A required long-lived completion that rejects after startup makes readiness
 false and health unhealthy. Stitchkit records the failure but does not restart
 the resource or process.
@@ -4757,36 +5057,64 @@ const realtimeContract = defineRealtimeContract({
 })
 ```
 
-The original `z.ZodError` is retained as `RealtimeRejectedEvent.error.cause`.
-Because event arguments are a tuple, the first payload's `v` path is
-`[0, 'v']` (not `['v']`):
+A frame that fails this check is **refused, and the sender is told so** — when
+the event has an acknowledgement. `request()` rejects with
+`RealtimeRequestRejectedError`, immediately, carrying the peer's own issues:
 
 ```ts
-import type { RealtimeRejectedEvent } from 'stitchkit'
-import { z } from 'zod'
+import { RealtimeRequestRejectedError } from 'stitchkit'
 
-function isProtocolGenerationMismatch(rejected: RealtimeRejectedEvent): boolean {
-  const cause = rejected.error.cause
-  if (!(cause instanceof z.ZodError)) return false
-  const first = cause.issues[0]
-  return first?.code === 'invalid_value'
-    && first.path.length === 2
-    && first.path[0] === 0
-    && first.path[1] === 'v'
+try {
+  await socket.request('replicate', message, { timeoutMs: 5_000 })
+} catch (error) {
+  if (error instanceof RealtimeRequestRejectedError) {
+    // reason: 'invalid-arguments'; issues: [{ path: '0.v', code: 'invalid_value', … }]
+    if (error.issues?.some((issue) => issue.path === '0.v')) schedulePeerUpgrade()
+    else reportMalformedRealtimePayload(error)
+  }
 }
+```
 
-const socket = createRealtimeClient(realtimeContract, {
-  url,
-  onRejected: (rejected) => {
-    if (isProtocolGenerationMismatch(rejected)) schedulePeerUpgrade()
-    else reportMalformedRealtimePayload(rejected)
+`path` is `'0.v'` and not `'v'` because event arguments are a tuple: index `0`
+is the first payload. The issues are already flattened by Stitchkit's own
+normaliser, so telling "wrong generation" from "malformed payload" is one
+comparison rather than an inspection of a `ZodError`'s internals.
+
+The receiving side still reports it locally through `onRejected` — a refusal is
+now visible on **both** ends rather than only where it happened.
+
+**Two limits, both real.** A **fire-and-forget** event has no acknowledgement
+channel, so its refusal stays local: the sender learns nothing, and no
+convention in the payload can change that. And an event the receiver's contract
+does not contain has no listener at all, so there is nothing on that side to
+answer with — adding an event is not a change a generation field can announce.
+
+### Where protocol identity belongs
+
+For a distributed pair whose planes are mostly fire-and-forget, compare
+identity **at the handshake** instead, where a mismatch is refused before the
+first frame is interpreted and both ends see it at once. The typed handshake is
+already the place:
+
+```ts
+const handshake = {
+  schema: z.object({ token: z.string(), protocol: z.string() }),
+  verify: (auth) => {
+    if (auth.protocol !== PROTOCOL_IDENTITY) return null   // refused, with a reason
+    return { subject: verifyToken(auth.token) }
   },
-})
+}
 ```
 
-A generation mismatch means “upgrade the peer”; another schema rejection means
-“fix the producer or payload”. This stays an application convention, not a core
-API: only the application knows which field denotes protocol compatibility.
+The client sends it as `auth`, and a rejection reaches `onConnectError` with
+`terminal: true` — distinguishable in a log from a bad token, so a half-rolled
+deployment reads as a half-rolled deployment and not as an access problem.
+
+What that identity *is* remains the application's decision — a build version, a
+contract hash, a protocol generation. Stitchkit does not compare it for you
+(→ ADR 0002); it gives the place where the comparison happens before any frame
+is interpreted, and it makes the per-frame alternative honest by letting its
+refusals be seen.
 
 ## Server — `createSocketIOServer`
 
@@ -7422,6 +7750,260 @@ current one *up to* your target, and apply each snippet.
    runtime): bootstrap the server, one HTTP request, and any feature you rely on
    (Socket.IO connect, an MCP tool call, a multipart upload, …).
 
+## 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
@@ -9131,7 +9713,9 @@ The browser-and-server entrypoint. Re-exports everything from
 | `bindRealtimeClient` | function | bind contract validation and typed acknowledgements to an existing Stitchkit client transport without owning its lifecycle |
 | `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
 | `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
+| `parseNDJSON` | function | parse an NDJSON `Response`; blank keep-alive lines are skipped — [guide](../guide/client.md#ndjson) |
 | `SocketIOClient` | _type_ | low-level client handle; `emit` reports disconnected drops and `emitWithAck` exposes the native Promise primitive used by validated `request()` |
+| `SocketIOClientPeerLoaders` | _type_ | inject `socket.io-client` so a bundler can put it in a self-contained artifact |
 | `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` (incl. `retain`, `onConnectError`, `onDroppedEmit`) |
 | `SocketEventMap` | _type_ | the shape of an event map |
 | `RealtimeClient` | _type_ | validated client inferred from a realtime contract |
@@ -9146,6 +9730,12 @@ The browser-and-server entrypoint. Re-exports everything from
 | `RealtimeRequestTimeoutError` | class | stable `REALTIME_REQUEST_TIMEOUT` rejection |
 | `RealtimeRequestDisconnectedError` | class | stable `REALTIME_REQUEST_DISCONNECTED` rejection, including an immediate disconnected call |
 | `RealtimeRequestInvalidAcknowledgementError` | class | invalid ack was reported through `onRejected` and the request rejected |
+| `RealtimeRequestRejectedError` | class | the peer refused the frame against its own contract and said so — `reason`, `issues` — instead of leaving the sender to time out ([ADR 0106](../decisions/0106-a-refused-frame-answers-its-sender.md)) |
+| `REALTIME_REJECTION_KEY` | const | the reserved acknowledgement key a refusal travels under |
+| `RealtimeRejectionEnvelope` | _type_ | the wire shape of a refusal |
+| `RealtimeRejectionReport` | _type_ | what the sender is told: event, reason, message, issues |
+| `RealtimeRejectionIssue` | _type_ | one refused field, already flattened (`path: '0.v'`) |
+| `asRealtimeRejection` | function | recognise a refusal in an acknowledgement value, validating it |
 | `RealtimeContract` | _type_ | shared server-to-client and client-to-server event registries |
 | `RealtimeEventRegistry` | _type_ | string-keyed registry of event definitions |
 | `RealtimeEventDefinition` | _type_ | one tuple-shaped event and optional acknowledgement schema |
@@ -9159,6 +9749,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `ValidatedRealtimeSocket` | _type_ | runtime-validating `on`/`emit` surface inferred from registries; `emit` returns "accepted by the transport" (`false` only for a client-side disconnected drop) |
 | `RetainedTopics` | _type_ | the `createRetainedTopics` handle |
 | `ParseSSEOptions` | _type_ | options for `parseSSE` |
+| `ParseNDJSONOptions` | _type_ | options for `parseNDJSON` |
 
 ### Trace (client)
 
@@ -9414,6 +10005,10 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `streamSSE` | function | an async generator → SSE `Response` — [guide](../guide/server.md#sse-streaming) |
+| `streamingRoute` | function | a long-lived subscription route: idle timeout, heartbeat, opening flush, cancellation — [guide](../guide/server.md#long-lived-subscriptions) |
+| `ndjsonRoute` | function | `streamingRoute` framed as NDJSON |
+| `sseRoute` | function | `streamingRoute` framed as SSE |
+| `DEFAULT_STREAM_HEARTBEAT_MS` | const | 5000 — deliberately well under Bun's ten-second idle threshold |
 | `parseSSE` | function | parse an SSE `Response` (also on the root entrypoint) |
 | `MultipartLifecycle` | _type_ | request-scoped rollback ownership for accepted streamed handles |
 | `MultipartResult` | _type_ | what `parseMultipart` returns |
@@ -9449,6 +10044,9 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `RateLimitConfig` | _type_ | config for `createRateLimiter` |
 | `ClientIpOptions` | _type_ | trusted-proxy config for `extractIp` / `resolveSocketIp` |
 | `ParseSSEOptions` | _type_ | options for `parseSSE` |
+| `StreamingRouteOptions` | _type_ | options for `streamingRoute` / `ndjsonRoute` / `sseRoute` |
+| `StreamingSourceContext` | _type_ | what a streaming source is given, including the cancellation `signal` |
+| `StreamingFormat` | _type_ | `'ndjson' \| 'sse'` |
 
 ### OpenAPI
 
@@ -9479,6 +10077,7 @@ cutovers are covered by the executable
 | `ApplicationResourceFailure` | _type_ | one resource failure with the cause its phase label cannot carry — delivered to `onResourceFailure` |
 | `ApplicationResourcePhase` | _type_ | the phase a managed resource failed in — the vocabulary of `ApplicationResourceShutdown.failures` |
 | `ApplicationShutdownOptionsSchema` / `ApplicationShutdownOptions` | schema / _type_ | the two shutdown budgets and an abort signal — without the HTTP-only `retryAfterSeconds` |
+| `ApplicationShutdownBudgetSchema` / `ApplicationShutdownBudget` | schema / _type_ | the same two budgets without a signal — `ApplicationConfig.shutdown`, the default for `shutdown()` and the only budget a failed startup's rollback can read |
 | `ActivityTokenBrand` | const | the brand symbol `ActivityToken` carries, exported so `ActivityProjection` is implementable |
 | `defineManagedResource` | function | retain the exact typed resource declaration; every invoked start is rollback-eligible |
 | `managedServerResource` | function | adapt an existing managed server without copying its HTTP/WebSocket shutdown machine |
@@ -9597,7 +10196,7 @@ Server-only optional application runtime. See the
 | `defineModelRegistry` | function | typed language-model descriptors, capabilities and provider construction |
 | `composeAgentPrompt` | function | ordered prompt contributions and provenance-aware context budget |
 | `structuredCompaction` | function | summarize a provider-valid snapshot range and replace it through CAS |
-| `createAgentSessionCoordinator` | function | strict process-local queue/interrupt lifecycle |
+| `createAgentSessionCoordinator` | function | strict process-local queue/interrupt/supersede lifecycle |
 | `AgentRuntimeStopPolicy` | _type_ | named custom AI SDK stop condition persisted and published on policy stop |
 | `AgentRuntimePrepareStep` | _type_ | per-run controlled step callback with typed domain context and managed run signal/fence |
 | `AgentRuntimeRecordIds` | _type_ | optional caller-provided input, run and assistant IDs for stable application records |
@@ -9608,7 +10207,7 @@ Server-only optional application runtime. See the
 | `AgentRuntimeConflictError` | class | thrown when a store mutation loses to a concurrent writer — catchable by type from `stitchkit/agent-runtime` |
 | `AgentSessionCloseOptions` | _type_ | `gracePeriodMs` for natural settlement, then abort, then `forceTimeoutMs` for bounded settlement after it |
 | `AgentSessionCloseResult` | _type_ | what `close()` achieved: `settled`, or `timedOut` with `remaining` runs still in flight. Only omitting `forceTimeoutMs` guarantees nothing is in flight on return |
-| `AgentHistoryProjectionOptions` | _type_ | storage-neutral file resolver and explicit unresolved-file behavior |
+| `AgentHistoryProjectionOptions` | _type_ | storage-neutral file resolver, explicit unresolved-file behavior, and how an interrupted turn reaches the model (`interruptedAssistant`) |
 | `createAgentToolFenceLifecycle` | function | pre-effect and post-effect run ownership fence for `mountAgent` |
 | `AgentRuntimeEventSchema` | schema | transient stream lifecycle plus post-commit admission/checkpoint/run-state/terminal projections |
 | `createAgentObservability` | function | separate agent-run sink over the shared bounded observability lifecycle |