stitchkit 0.98.2 → 0.100.0

package/llms/application.2.txt

@@ -5,7 +5,35 @@
 
 Parts of this slice:
 - `llms/application.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md)
-- `llms/application.2.txt`: Guide: Application migration recipes  (docs/guide/application-migration-recipes.md) · API reference: `stitchkit/application`  (docs/api/reference.md)
+- `llms/application.2.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md) · Guide: Application migration recipes  (docs/guide/application-migration-recipes.md) · API reference: `stitchkit/application`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: Managed application kernel  (docs/guide/application-kernel.md)  (continued)
+==============================================================================
+
+## Multi-action notification delivery
+
+Opt into `delivery: { version, actions, project }` on `createNotificationOutbox`.
+The pure `actions(payload)` selector runs at enqueue; the versioned plan remains
+fixed throughout retry. Each `send` receives its action and a stable idempotency
+key; return a small JSON receipt such as a remote message or uploaded object ID.
+`project(notification, receipts)` applies all confirmed results locally and must
+be idempotent. Checkpoints and the final projection timestamp live in the existing
+atomic StateStore; completed receipts retain them within retention/byte limits.
+
+This supports, for example, text plus attachment delivery with a local timeline
+projection, or upload plus publication with a local asset index. These are protocol
+examples, not claims of deployed consumer adoption. A failure in projection does
+not repeat confirmed sends. A crash after remote success but before receipt commit
+is ambiguous: the provider must deduplicate the action key or reconcile its result.
+A projection can also repeat if its completion checkpoint is lost.
+
+A new executor version must explicitly migrate or terminally classify incompatible
+queued plans. Existing `classify`/`onDropped` handles terminal items; a durable
+quarantine is the application's responsibility. Whole-state file and memory stores
+remain supported. Atomic enqueue with an unrelated business transaction is not
+provided by this contract; retain the application's transactional adapter when that
+boundary is required. Send and projection callbacks own their external deadlines.
 
 ==============================================================================
 # Guide: Application migration recipes  (docs/guide/application-migration-recipes.md)
@@ -386,7 +414,7 @@ cutovers are covered by the executable
 | `DiagnosticJournalConfig` / `DiagnosticJournal` | _type_ | owner schema/path/limits/failure observer and the synchronous `submit`, bounded-wait `flush`/`close`, status handle |
 | `DiagnosticJournalLimitsSchema` / `DiagnosticJournalLimits` | schema / _type_ | positive event, pending-item, pending-byte, file-byte and retained-file limits |
 | `DiagnosticJournalLockPolicySchema` / `DiagnosticJournalLockPolicy` | schema / _type_ | `refuse` (default) or `reclaim-stale`, which reclaims only a lock whose recorded owner is provably gone |
-| `readDiagnosticJournalLockDiagnosis` / `DiagnosticJournalLockDiagnosis` | function / _type_ | why a `reclaim-stale` acquisition refused — owner alive, another machine, or a lock this host cannot attribute — read off the thrown `EEXIST` |
+| `readDiagnosticJournalLockDiagnosis` / `DiagnosticJournalLockDiagnosis` | function / _type_ | why a `reclaim-stale` acquisition refused — attribution, PID liveness and optional process `identity` evidence (`matched`, `different-boot`, `reused-pid`, `pid-gone`, `legacy`, `unavailable`) — read off the thrown `EEXIST` |
 | `DiagnosticJournalSubmitResultSchema` / `DiagnosticJournalSubmitResult` | schema / _type_ | accepted epoch/sequence or explicit invalid, oversized, capacity, closed or failed refusal |
 | `DiagnosticJournalStatusSchema` / `DiagnosticJournalStatus` | schema / _type_ | state, limits, exact admission/write/failure counters, pending ownership, rotations, partial tails and last safe sequences |
 | `DiagnosticJournalFrameSchema` / `DiagnosticJournalFrame` | schema / _type_ | version-1 JSONL frame carrying process epoch, contiguous accepted sequence and schema-validated JSON event |
@@ -488,3 +516,41 @@ vocabulary with an event topic declared `mode: 'decision'`.
 
 → [ADR 0152](../decisions/0152-a-keyspace-is-memory-that-nothing-reaches-before-it-is-durable.md),
 [ADR 0153](../decisions/0153-a-watched-read-is-one-read-per-question.md).
+
+### Managed change subscriptions and scoped watches
+
+`changeSubscriptionResource` (`stitchkit/application`) accepts
+`ChangeSubscriptionConfig`: `id`, unique `keys` (1–128, at most 256 characters each),
+`connect(signal)`, `reconcile(key, context)`, required `reconcileIntervalMs` (10 ms–1 h),
+optional `timeoutMs` (30000; 1 ms–1 h), `backoff`, and `onError`.
+`ChangeConnection` supplies `subscribe({ signal, hint, disconnected })`, which completes subscription
+before the first read; `close()` releases it. `ChangeReconciliation` exposes `signal`
+and a synchronous `commit(callback)` guard against late publication. Drivers must
+honor cancellation. Uncooperative work retains its slot until settled instead of
+allowing overlapping connections/reads. Errors reach `onError`; no raw payload or
+connection string is logged by this resource. Recovery runs after reconnect and
+periodically even when no notification arrives.
+
+`WatchHubConfig` adds `maxSources` (1024), `maxSubscribers` (1024), and optional
+`reconcileIntervalMs` (10 ms–1 h). `hub.attach(subscriber, scope?)` accepts a
+`WatchAdmissionScope` containing a **server-verified** `key` (1–512 characters) and
+revocation `signal`. The key separates sharing and is the optional third argument
+of `read(operation, args, scope)`. It must represent account, session and permissions;
+never trust a client-supplied owner ID as that scope.
+
+
+
+### Notification action and projection receipts
+
+`NotificationOutboxConfig.delivery` accepts `NotificationDeliveryConfig`:
+immutable executor `version`, pure `actions(payload)` plan selector (1–128 unique
+names, each at most 128 characters), and idempotent `project(notification, receipts)`.
+`send` receives optional `action` and stable `idempotencyKey`, and returns a JSON
+remote receipt (void becomes null). `NotificationDeliveryStateSchema` validates the
+optional `NotificationDeliveryState` on queued items and completed receipts:
+`version`, `actions`, `receipts` and optional `projectedAt`. Checkpoints share the
+existing atomic StateStore and lease fence. Receipt retention and serialized byte
+budgets still apply. Single-send configuration remains valid without `delivery`.
+A remote result lost before its checkpoint may be sent again; provider idempotency
+or reconciliation is required. A projection may repeat after a crash before its
+checkpoint. Business-transaction enqueue and durable quarantine are not implied.

package/llms/application.txt

@@ -6,7 +6,7 @@
 
 Parts of this slice:
 - `llms/application.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md)
-- `llms/application.2.txt`: Guide: Application migration recipes  (docs/guide/application-migration-recipes.md) · API reference: `stitchkit/application`  (docs/api/reference.md)
+- `llms/application.2.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md) · Guide: Application migration recipes  (docs/guide/application-migration-recipes.md) · API reference: `stitchkit/application`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: Managed application kernel  (docs/guide/application-kernel.md)
@@ -656,7 +656,12 @@ refusals are explicit; accepted ordered frames are never evicted.
 The absolute path's parent must already exist and be operator-controlled. One manager owns it via
 an exclusive `.lock`; new files use mode `0600` by default. `maxFiles` includes the active file,
 and a non-newline startup tail is rotated intact rather than guessed or repaired. An abrupt process
-death may leave the lock for an operator to remove only after proving the former owner is gone.
+death may leave a lock. The default `refuse` policy leaves recovery to the operator;
+`lock: 'reclaim-stale'` compares machine, boot and process birth identity before
+recovery. A reused PID cannot impersonate a modern owner. Legacy records with a
+live PID, foreign namespaces and unavailable identity refuse automatic recovery;
+see the upgrading guide for quiescent legacy recovery. The same mechanism owns the
+short-lived reclaim guard.
 
 `flush()` means every accepted append through that call's boundary settled. It is not `fsync`, a
 durable receipt, exactly-once execution or remote delivery. Timeout/cancellation bound only the
@@ -986,3 +991,28 @@ so a scheduler stall on a loaded host cannot pull a live lock from under its
 holder — after which the heartbeat wins and the lock is abandoned. Temporary files a crashed writer left beside the state are swept on
 the store's first update. Ledger corruption may be declared reconstructable;
 an outbox must fail closed rather than silently discard pending delivery.
+
+## Recovering change subscriptions
+
+`changeSubscriptionResource` is an optional resource over a consumer-owned driver.
+It uses a finite declared key set, subscribes before reading, reconciles after
+reconnect and periodically repairs lost hints. `reconcileIntervalMs` is explicit;
+notifications alone cannot prove freshness. Within a key, hints coalesce into one
+trailing read and a failed read retries with backoff. Use the supplied
+`context.commit(() => publish(value))` after awaits to reject an obsolete connection.
+
+Drivers implement `connect(signal)` and return `subscribe({ signal, hint,
+disconnected })` plus `close()`. Subscribe must establish the notification boundary
+before resolving. A database LISTEN driver owns its connection, channels, decoding
+and transaction ordering; no SQL or database driver is included here. The resource
+owns reconnect, deadlines and shutdown. Drivers must honor abort. If one ignores it,
+its slot remains occupied until settlement; deadlines cannot safely manufacture
+successful cleanup or permit an overlapping connection.
+
+For watched reads, set `reconcileIntervalMs` on the existing `createWatchHub` rather
+than building a second read loop. Its per-key machinery is shared with managed
+subscriptions. Limits default to 1024 sources and 1024 subscribers per hub; set
+explicit finite values for larger workloads. Supply a server-verified admission
+scope to `attach` and abort it on logout, permission revocation or session replacement.
+The read callback receives the trusted scope as its third argument. A client owner
+ID in arguments is not authentication.

package/llms/files.txt

@@ -27,7 +27,7 @@ available from `stitchkit/contract`.
 | `ManagedFileInspector` | _type_ | bounded-prefix read/write inspection callback with a finite cancellation signal that cannot own path or size |
 | `ManagedFileInspectionInput` / `ManagedFileInspection` | _type_ | inspector prefix/name/declared media/signal input and validated metadata-only result |
 | `writeFileAtomic` / `writeFileAtomicSync` / `WriteFileAtomicOptions` | function / _type_ | replace a file atomically: a random staging name created exclusively (never through a planted link), the mode set on the descriptor before the file is visible (default `0o600`, not masked by the umask), `fsync`, rename; a failure leaves the target and no staging file. The asynchronous form keeps the event loop running |
-| `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; an ownerless lock only after `ownerlessGraceMs` |
+| `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time and nullable kernel process identity); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; an ownerless lock only after `ownerlessGraceMs` |
 | `ExclusiveLockError` | class | `LOCK_TIMEOUT` naming the resource and its holder, or `LOCK_ABORTED` with the signal's reason |
 
 ---

package/llms/live.txt

@@ -469,3 +469,10 @@ realtime contract from `stitchkit`, and the server halves live in `stitchkit/app
 | `watchDiff` / `applyWatchDelta` / `watchDeltaWins` | functions | build a difference (`undefined` when equal), rebuild the value from one (throws rather than inventing), and whether it is actually smaller than the value |
 
 ---
+
+### Session-scoped watch lifetime
+
+`WatchClientConfig.session` captures a `SessionOperation`; `maxKeys` (1024) and
+`maxListenersPerKey` (128) bound retained subscriptions. Its lifetime nonce travels
+in optional `WatchKey.instance`, preventing old-session frames from matching a new
+client on the same socket. This is routing identity, never authorization.

package/llms/react.txt

@@ -182,3 +182,11 @@ Browser- and server-render-safe React data-layer helpers. Needs the
 For the rationale behind these APIs — why `Bun.serve` and not a framework, why
 two context types, why thin wrappers — see the
 [Architecture Decisions](../decisions/).
+
+### Watched handles in the query cache
+
+`CacheBridgeConfig.watched` accepts `WatchCacheBinding` entries with `handle`,
+`queryKey` and optional `state(frame)` observer. Include the session in query keys.
+`CacheBridgeConfig.session` fences events and removes bound queries when that login
+ends. Watch loss marks a query stale without triggering an independent refetch;
+recovery belongs to the watched read.

package/llms/server.3.txt

@@ -1029,3 +1029,38 @@ registry, and a name seen once does not live on in a map. This ordering exists o
 through `emitTo`; a broadcast through `realtime.to(room).emit` reaches the
 socket immediately, replay or not, so keep room traffic whose order matters
 relative to the snapshot on the registry.
+
+## Session-scoped watches and query cache
+
+Pass the captured login operation as `createWatchClient(contract, { transport,
+session })`. It adds a lifetime nonce to watch keys and detaches on invalidation;
+a late frame for a previous login cannot match a new client's key on the same socket.
+Both client and server must support the new optional `WatchKey.instance` field.
+The nonce is not authorization: the server still admits a verified identity and
+uses `hub.attach(subscriber, { key: verifiedScope, signal: revocationSignal })`.
+The scope key must change with session and permission boundaries.
+
+`createCacheBridge` can bind watched handles directly:
+
+```ts
+const bridge = createCacheBridge({
+  socket, queryClient, handlers: {}, session,
+  watched: [{
+    handle: watches.list({ folderId }),
+    queryKey: ['items', session.id, folderId],
+    state: frame => showWatchState(frame),
+  }],
+})
+bridge.connect()
+```
+
+A value updates that exact query; non-live state marks it stale while retaining its
+value. The existing phases (`opening`, `live`, `unavailable`, `resync-required`)
+remain the status model. Do not replace unavailable data with an empty collection.
+Session invalidation removes bound queries. Include the session identity in query
+keys and guard any application-level side effects with that same operation.
+
+Use existing shared watches for paginated lists and selected-detail queries; bind
+each exact argument set to its query key. No global domain/query registry or new
+UI components are needed. Reconnect and revision/delta recovery remain owned by the
+watch client; silent lost notifications are repaired by hub reconciliation.

package/llms/stitchkit.2.txt

@@ -834,3 +834,44 @@ A delivered item resets the backoff, so a stream that reconnects, works for an
 hour and drops again starts its next retry at `minDelayMs` rather than the
 ceiling it reached last time. Aborting the signal ends the iteration promptly,
 including in the middle of a wait.
+
+## Operations belong to a login lifetime
+
+Use `createSessionScope` when a client can log out or switch accounts. The scope is
+host-owned and context is immutable. Replace it for **every** login, even to the
+same account. Capture once for an entire compound operation:
+
+```ts
+import { createClient, createSessionScope } from 'stitchkit'
+
+const sessions = createSessionScope<{ accountId: string }>()
+const operation = sessions.replace({ accountId: 'account-a' })
+const client = createClient(contract, {
+  baseUrl,
+  fetch: operation.bindFetch(fetch, () => ({ Authorization: tokenFor(operation) })),
+})
+const value = await operation.run(() => client.read())
+operation.deliver(() => applyResult(value))
+```
+
+Capture before the first request, keep the same operation for a second request or
+one explicitly allowed auth retry, and guard the **actual** final transport send
+or local state change. An async delivery callback needs another check after its
+await; `deliver` itself is synchronous. Guard error delivery too. Cancellation is
+additional protection and cannot undo server effects. `SessionExpiredError` means
+discard the stale operation, not refresh a new user's credentials. For raw/stream
+responses, guard each consumed chunk and final delivery; `run` returning a stream
+does not mean its future contents have been consumed.
+
+`createSessionCredentials({ scope, refresh, storage })` coordinates the same scope.
+`login(context, credentials)` creates a generation, `read(operation)` resolves only
+that generation's credentials, and concurrent `refresh(operation)` shares one
+flight. `logout()` invalidates memory immediately and resolves after its ordered
+storage clear (or a newer login superseding that clear). Handle storage and capacity
+errors explicitly; a rejected write is not proof of durable login/logout. Refresh
+network work never holds the storage queue. Callers decide whether a failed command
+may be retried once; do not replay a multi-step callback or treat any `403` as expiry.
+
+This is per-instance coordination. Route all writes through it; shared tabs/processes
+need storage-level locking. Replace the local session counter and refresh queue when
+adopting these primitives instead of retaining two independent lifetimes.

package/llms/stitchkit.3.txt

@@ -145,3 +145,25 @@ can emit / propagate a `traceparent` (see `HttpClientConfig.trace`).
 | `TraceContext` | _type_ | `{ traceId, spanId, parentSpanId?, tracestate?, baggage? }` |
 
 ---
+
+### Session lifetime and credential coordination
+
+`createSessionScope` (`stitchkit`) returns the generic `SessionScope`: `replace(context)`
+creates a new login lifetime (including same-account relogin), `capture()` returns
+its `SessionOperation<T>`, `clear()` invalidates it, and `stop()` permanently closes
+the host. Operations expose `id`, `generation`, `context`, `signal`, `current()` and
+`assertCurrent()`. `run(callback)` checks both success and failure across an await;
+`deliver(callback)` admits a synchronous final send/state change or returns false.
+`bindFetch(fetch, headers?)` guards every attempt and scopes its abort signal. Wrap
+the complete client call in `run` too: headers are not the response body boundary.
+Expired work throws `SessionExpiredError`, not a refresh instruction.
+
+`createSessionCredentials` accepts `SessionCredentialsConfig`:
+`scope`, `refresh(credentials, signal)`, `storage.write(session, credentials)`,
+`storage.clear()`, `maxPendingWrites` (128), and `refreshTimeoutMs` (30000, at most one
+hour). `SessionCredentials` provides `login`, `logout`, `read(operation)` and
+`refresh(operation)`. Concurrent refresh calls in one generation share the same
+promise. Logout invalidates memory before its returned persistence promise settles.
+Storage errors and queue-capacity refusals reject; callers must handle them. All
+writes must pass through the same instance. There is no cross-process/tab lock,
+provider error classifier or automatic retry of arbitrary application callbacks.

package/llms/stitchkit.txt

@@ -77,11 +77,11 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 43 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 45 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the managed-resource conformance kit |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 43 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 45 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -91,7 +91,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 9 of the 43 minors since 0.56.2, most recently 0.96.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 10 of the 45 minors since 0.56.2, most recently 0.100.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |

package/llms/tools.txt

@@ -722,14 +722,15 @@ as one thing. Where they agree, that is what you get; where they disagree — a
 `.refine()` only one of them carries, two different bounds on the same number, an
 enum against a free string — the *constraint* is dropped and the **type** is not.
 A field that is a number in every variant is advertised as a number, not as a
-bare description. When the kinds genuinely differ, the flat projection keeps
-every provable kind in a deterministic JSON Schema type array — for example
-`type: ['string', 'array']` — while dropping constraints that are not sound for
-all branches. Nested `oneOf` / `anyOf` values still contribute their provable
-base kinds without reintroducing union keywords. Only a branch whose kind is
+bare description. Scalar collisions keep every provable kind in a deterministic
+JSON Schema type array. If any alternative is an object or array, the property
+retains distinct structural alternatives in `anyOf`: object properties, typed
+array items, bounds and nullable values remain available to the model. The
+containing discriminated union still becomes one object; flat mode does not
+promise to remove every nested union keyword. Only a branch whose kind is
 actually unknowable, such as a free-form schema or unresolved reference, leaves
 the collision unconstrained. → ADRs [0044](../decisions/0044-a-collided-field-keeps-its-type.md)
-and [0065](../decisions/0065-flat-collisions-preserve-every-known-kind.md)
+and [0205](../decisions/0205-flat-tool-collisions-retain-structural-alternatives.md).
 
 It is **deep** because the projection walks the generated JSON Schema document,
 including objects, arrays, tuples and schema-definition nodes. Structurally
@@ -738,8 +739,8 @@ Plain unions and unions hidden behind unresolved external references remain
 unions because Stitchkit cannot soundly invent a discriminator.
 
 Use the default `flattenUnionInput: false` when the model must see the exact
-relationship between a discriminator and each branch. The flat type array is a
-sound set of possible JSON kinds, not a reconstruction of those correlations.
+relationship between a discriminator and each branch. Joined property schemas
+describe allowed values without reconstructing those correlations.
 
 The flattened form is **lossy but never executable**. Per-variant refinements
 and incompatible constraints are widened in the presentation document; the

package/llms/upgrading-0.37.0.txt

@@ -0,0 +1,176 @@
+# Upgrading 0.37.0 → 0.37.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.37.0 → 0.37.0  (docs/guide/upgrading.md)
+
+==============================================================================
+# Guide: Upgrading, 0.37.0 → 0.37.0  (docs/guide/upgrading.md)
+==============================================================================
+
+## The 0.37 migration
+
+Tool presentation is no longer an executable Zod parser. Replace the removed
+flatten helpers with the JSON Schema compiler, and choose the explicit
+`MountableTool` surface when using the advanced collection API:
+
+```ts
+// before
+const flat = flattenUnionsDeep(zodSchema)
+mountable.schema
+
+// after
+const flat = flattenToolJsonSchema(
+  z.toJSONSchema(zodSchema, { target: 'draft-07', io: 'input' }),
+)
+mountable.presentationSchema // model/MCP/manifest JSON Schema
+mountable.argumentSchema     // executable CLI argument adapter only
+```
+
+Contract and native handlers keep their original Zod schemas; MCP and agent SDK
+adapters now forward raw arguments so defaults, coercions, refinements and
+transforms execute exactly once inside Stitchkit. There are no compatibility
+exports for `flattenDiscriminatedUnion`, `flattenUnionsDeep` or
+`MountableTool.schema`. → ADR 0050
+
+Tool-call hooks now take one options object. Migrate all three callbacks; there
+are no positional overloads:
+
+```ts
+// before
+beforeToolCall: (toolName, args, context, endpoint) => {}
+afterToolCall: (toolName, args, result, durationMs, context, endpoint, error) => {}
+onToolError: (toolName, error, context, endpoint) => {}
+
+// after
+beforeToolCall: ({ toolName, args, context, endpoint }) => {}
+afterToolCall: ({ toolName, args, result, durationMs, context, endpoint, error }) => {}
+onToolError: ({ toolName, error, context, endpoint }) => {}
+```
+
+### MCP schema validation
+
+The standalone validator now takes one object and live MCP configs carry the
+same rules under `schemaValidation`. Migrate every positional call and every
+`onIncompatibleSchema` field; there is no old-shape overload:
+
+```ts
+// before
+validateMcpSchemas(services, 'throw', logger, { requireTypedProperties: true })
+createMcpHandler({ services, onIncompatibleSchema: 'throw' })
+
+// after
+validateMcpSchemas({ services, policy: 'throw', logger, requireTypedProperties: true })
+createMcpHandler({ services, schemaValidation: { policy: 'throw' } })
+```
+
+Put `extend` and `flattenUnionInput` beside `services`, not inside
+`schemaValidation`. The handler applies the profile to the exact prepared schema
+it advertises. Add `requirePortableFormats: true` when every custom JSON Schema
+format must be rejected before a client sees it.
+
+Native MCP registration also changed shape in 0.37. Move protected tools to the
+framework registrar; keep an SDK-raw tool only by naming the opt-out:
+
+```ts
+// before
+nativeTools: (server, auth) => server.registerTool(name, config, handler)
+
+// after — lifecycle, hooks and schema policy apply
+nativeTools: ({ registerTool }, auth) => registerTool({
+  name, description, identity, input, output, handler,
+})
+
+// after — intentionally raw
+nativeTools: ({ rawServer }, auth) => rawServer.registerTool(name, config, handler)
+```
+
+If a tool hook annotated `endpoint` as `MethodDef`, remove that annotation or
+use `OperationIdentity`: native operations have service/action/scope/method but
+no HTTP path.
+
+### Node-facing server types
+
+`stitchkit/server` remains Bun-concrete: an explicitly annotated `RawRoute`
+still receives `BunServer`. `stitchkit/node` no longer drags Bun declarations
+into a Node project. Its raw routes default the host server to `unknown`, and
+its Socket.IO handle exposes only Node capabilities:
+
+```ts
+// before — Node entry still leaked Bun-only fields and ambient types
+const route: RawRoute = { handler: (_req, ctx) => ctx.server?.upgrade(...) }
+const socket = await createSocketIOServer(config)
+socket.websocket
+
+// after — name a custom embedding host only when one exists
+const route: RawRoute<MyHostServer> = {
+  handler: (_req, ctx) => useHost(ctx.server),
+}
+const socket = await createSocketIOServer(config)
+socket.io
+socket.attach(nodeHttpServer)
+```
+
+Node consumers can remove `@types/bun` unless another dependency independently
+requires it.
+
+### Managed server shutdown
+
+`createServer()` and `serveNode()` now return the same structural managed
+lifecycle. Replace every direct runtime stop and parallel Socket.IO close:
+
+```ts
+// before — split ownership
+const socket = await createSocketIOServer(config)
+const server = createServer({
+  services,
+  websocket: socket.websocket,
+  rawRoutes: [socket.route],
+})
+server.stop()
+await socket.io.close()
+
+// after — one owner and one total deadline
+const socket = await createSocketIOServer(config)
+const server = createServer({ services, socket })
+const result = await server.shutdown({ gracePeriodMs: 30_000 })
+```
+
+On Node, keep the same `socket` field and replace `handle.close()` with
+`handle.shutdown()`. Runtime-specific diagnostics move under `handle.runtime`;
+do not use it as a second shutdown path. Standalone CLI/tools that create a
+Socket.IO handle without an HTTP server call `await socket.close()`.
+
+If Bun Socket.IO shares the port with a raw lane, keep the explicit composition
+but let the server mount the Socket.IO route:
+
+```ts
+createServer({
+  services,
+  socket,
+  websocket: composeWebSocketHandlers([
+    webSocketLane({ match: isRaw, handlers: rawHandlers }),
+    socketIoLane(socket.websocket),
+  ]),
+  rawRoutes: [rawUpgradeRoute],
+})
+```
+
+Move native Bun `routes` entries to `rawRoutes`. Native routes run before the
+Fetch handler and therefore cannot participate in admission or drain. Wire
+`SIGTERM`/`SIGINT` in the application; the first signal starts `shutdown()`, and
+a later signal may abort the same controller. Close MCP, databases and queues
+after the server result—those resources remain application-owned.
+
+Move a handshake policy from the Node-only callback shape inside
+`serverOptions` to the runtime-neutral top-level policy. It receives a Web
+`Request`, may be async, and returns whether to admit the handshake:
+
+```ts
+// before
+serverOptions: { allowRequest: (request, done) => done(null, allowed(request)) }
+
+// after
+allowRequest: (request) => allowed(request)
+```