stitchkit 0.108.5 → 0.109.0

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)
+```

package/llms/{upgrading-0.37.0-0.58.0.txt → upgrading-0.44.0-0.60.0.txt}

@@ -1,14 +1,240 @@
-# Upgrading 0.37.0 → 0.58.0 — stitchkit docs slice
+# Upgrading 0.44.0 → 0.60.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.58.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.44.0 → 0.60.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.37.0 → 0.58.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.44.0 → 0.60.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## 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
@@ -1007,169 +1233,3 @@ createHttpClient({
 
 There is no implicit `/auth/` suppression. Omit `suppressUnauthorizedFor` when
 every 401 should emit the global `unauthorized` event.
-
-## 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)
-```