stitchkit 0.113.3 → 0.114.0

package/llms/{upgrading-0.103.13-0.113.0.txt → upgrading-0.104.0-0.114.0.txt}

@@ -1,14 +1,56 @@
-# Upgrading 0.103.13 → 0.113.0 — stitchkit docs slice
+# Upgrading 0.104.0 → 0.114.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.103.13 → 0.113.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.104.0 → 0.114.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.103.13 → 0.113.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.104.0 → 0.114.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.114.0
+
+**Who must act:** code with an exhaustive `switch` or `Record` over
+`TelegramSendFailureReason` or `TELEGRAM_SEND_FAILURE_REASONS`. Code that only
+reads `retryable` and `recipientUnreachable` needs no change.
+
+`classifyTelegramSendFailure` now returns `reason: 'bot-to-bot-disabled'` for a
+`400 USER_BOT_TO_BOT_DISABLED` ([ADR 0274](../decisions/0274-a-telegram-token-has-one-outbound-budget.md)).
+It is permanent for that send, so it is not retried; it is **not**
+`recipientUnreachable`, because Telegram disables bot-to-bot messaging when
+either bot has not enabled its Bot to Bot setting, and the missing setting may
+be the sender's.
+
+1. Add the reason to every exhaustive mapping:
+
+   ```ts
+   // before
+   const code: Record<TelegramSendFailureReason, string> = { /* … */ unknown: 'E_UNKNOWN' }
+   // after
+   const code: Record<TelegramSendFailureReason, string> = {
+     /* … */ 'bot-to-bot-disabled': 'E_BOT_TO_BOT', unknown: 'E_UNKNOWN',
+   }
+   ```
+
+   Search pattern: `TelegramSendFailureReason`, `TELEGRAM_SEND_FAILURE_REASONS`
+   and every `switch` over a send-failure reason.
+2. Type-check: the exhaustive table without the new member fails to compile.
+3. If the application wants one outbound budget per bot token, opt in at the
+   one transformer that already owns its Bot API calls:
+
+   ```ts
+   import { telegramOutboundBudget } from 'stitchkit/telegram'
+
+   const budget = telegramOutboundBudget({ token: env.BOT_TOKEN })
+   api.config.use((previous, method, payload, signal) =>
+     budget.run(method, payload, signal, () => previous(method, payload, signal)),
+   )
+   ```
+
+   Remove the old limiter rather than running it beside this one. See the
+   [Telegram guide](telegram.md#one-token-one-outbound-budget).
+
 ## Released migration: 0.113.0
 
 **Who must act:** custom `AgentRuntimeStoreDriver` adapters and custom `AgentRuntimeStore` implementations of `seedConversationInput`. The built-in memory and SQLite stores already implement the contract.
@@ -814,84 +856,3 @@ signals to `createCli` / `createCliInvoker` and cooperative handlers observe `ct
 `REQUEST_ABORTED` is nonretryable and exits 130. A disconnected caller does not prove that
 an origin ignoring cancellation or an external provider stopped; keep resource leases until
 that work actually completes.
-
-## Released migration: 0.103.13
-
-### Darwin native assets in JS distributions
-
-**Who must act:** Bun builds that import `stitchkit/server`, `stitchkit/files` or
-`stitchkit/process` (Linux-only server apps included) and use `--outfile`, copy only
-`outputs[0]`, or package a single file; custom single-file/archive packagers and installers
-delivering native process/files capabilities.
-First affected publication: **0.103.13**, through **0.104.2**. It shipped as a patch; its
-changed delivery graph requires this migration despite unchanged API signatures.
-
-In those versions every Bun bundle that reaches the lock or process-identity code,
-`stitchkit/server` included, carries both Darwin `.node` addons as extra outputs on every
-operating system. `bun build --outfile` then fails with
-`cannot write multiple output files without an output directory`, and `--outdir` writes the
-addons next to a Linux artifact. Releases after 0.104.2 resolve the default loader at run time,
-so these bundles are one JS file with no `.node` output again. The static loader exists only
-in a build that uses the `stitchkit/files/packaging` plugin.
-
-```sh
-# Before: one JS file was assumed to be the entire distribution.
-bun build src/native.ts --target=bun --outfile=dist/native.js
-# After: retain every output, with its relative path.
-bun build src/native.ts --target=bun --outdir=dist --entry-naming=native.js
-```
-
-For `Bun.build`, copy **all** `result.outputs`, not just the JS entry or `outputs[0]`.
-A single-file JS distribution cannot embed a native `.node` addon automatically.
-An archive may contain JS plus companion assets, materialized together before execution.
-Custom output layout uses the evolving build-only packaging contract in the
-[native IO guide](native-io.md#public-native-packaging).
-
-Three deliveries have different rules: an ordinary npm install retains the package's
-native assets; a JS distribution must ship its complete output graph; a Bun compiled
-executable embeds the matching addon and may still use `--outfile`. In 0.103.13–0.104.2 a plain
-`bun build` carries the addon without a plugin. Later releases load it from a bundle only when
-the build uses `createNativePackaging` (`delivery: 'companion'` for JS, `'embedded'` for a
-compiled executable). Without the plugin, Bun may still copy the addon's bytes into a compiled
-executable, but the loader never uses them, so their presence proves nothing.
-
-What an unpackaged bundle does depends on the release:
-
-- **0.105.0–0.106.1:** the bundle carries the absolute path of the package on the build machine,
-  because the loader read `__dirname`. It looks for the addon there, so it works only on that
-  machine, and the path itself leaks into a distributed artifact. Rebuild with a later release.
-- **0.107.0 and later:** no build path is in the artifact, and the first call that needs the
-  addon reports the Darwin backend `unavailable` with stage `packaging`.
-
-Only macOS is affected, and only process identity (`observeProcessInstance`,
-`probeProcessOwner`), exclusive locks and contained Agent file operations load the addon. The
-managed file boundary, atomic writes and the chunk spool never do. The
-[native IO guide](native-io.md#libraries-with-a-zod-only-runtime) is the canonical recipe and
-shows how to check an artifact by its loader without running it on a Mac. Check the resulting
-artifact offline outside the build tree and `node_modules`, including process identity,
-live-owner lock refusal, dead-owner recovery and contained IO. A missing or corrupt addon
-remains `unavailable`, never evidence that an owner died.
-
-### CLI: repeated options are refused
-
-**Who must act:** wrappers, aliases and scripts that append `--json`, `--profile X` or an
-application global to arguments the user may already have given, and anything that passes the
-same global twice.
-First affected publication: **0.103.13**. It shipped as a patch; the change in grammar needs
-this migration.
-
-A repeated option that is not an array field is an argument error:
-`--json --json` and `--profile a --profile b` fail with `--json was passed 2 times`. Before
-0.103.13 the last value won, for framework globals, application globals and repeated
-`kind: 'other'` fields alike. Array fields, and untyped passthrough fields that keep their
-raw-list grammar, still repeat.
-
-```sh
-# Before: a wrapper appended its default and the last value won.
-mytool deploy --profile staging "$@" --profile production
-# After: build the argument list once, so each option appears once.
-mytool deploy --profile "${PROFILE:-production}" "$@"
-```
-
-Dotted leaves such as `--filter.name` follow the same rule as their parent field. Declare a
-field as an array when repetition is meant.

package/llms/upgrading-0.37.0-0.44.0.txt

@@ -0,0 +1,444 @@
+# Upgrading 0.37.0 → 0.44.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.44.0  (docs/guide/upgrading.md)
+
+==============================================================================
+# Guide: Upgrading, 0.37.0 → 0.44.0  (docs/guide/upgrading.md)
+==============================================================================
+
+## Historical breaking migrations through 0.44.0
+
+HTTP observability now completes inside the framework handler instead of a
+nested fetch wrapper. Configure request and tool sinks explicitly:
+
+```ts
+// before
+const audit = createAuditHook({ write })
+createServer({
+  services,
+  wrapFetch: (handler) => wrapInRequestContext(audit.http(handler)),
+})
+mountAgent(services, { hooks: audit.toolCall })
+
+// after
+const observability = createObservability({
+  request: { write, includePayload: true },
+  tools: { write },
+})
+createServer({ services, observability: observability.request })
+mountAgent(services, { hooks: observability.toolCall })
+```
+
+Body capture changed from always-on for body methods to opt-in. Set
+`includePayload: true` only when the request sink needs the sanitized JSON body.
+There is no `createAuditHook` or `audit.http` compatibility path;
+`wrapInRequestContext` remains only for custom fetch pipelines.
+
+Tool introspection now accepts one object-shaped contract/runtime surface. Stop
+calling the internal contract collector or merging a locally converted runtime
+manifest:
+
+```ts
+// before
+buildToolManifest(services.flatMap((service) => collectTools(service, 'AGENT')))
+listToolNames(services)
+summarizeTransports(services)
+
+// after
+const surface = { services, runtimeTools }
+buildToolManifest({ ...surface, transport: 'AGENT' })
+listToolNames(surface)
+summarizeTransports(surface)
+```
+
+`ToolNameEntry` adds `kind: 'contract' | 'runtime'`. `TransportSummary` is now
+`{ contractServices, runtimeTools, totals, sources }`; replace `services` and
+`perService` reads with the explicit counts and mixed-source breakdown. There
+is no positional overload and no `buildRuntimeToolManifest`: Stitchkit owns the
+combined order, transport filtering, canonical presentation schema and
+cross-origin collision checks.
+
+`defineErrors` now uses one Zod-first definition object and returns constructors
+instead of positional throwers. Add explicit `throw`, move message/details/hint
+into one options object, and declare a details schema when that code carries
+structured context:
+
+```ts
+// before
+const { errors } = defineErrors({ QUOTA_EXCEEDED: 429 })
+errors.QUOTA_EXCEEDED('Try later', { retryAfterSeconds: 30 }, 'Wait')
+
+// after
+const { errors, definitions } = defineErrors({
+  QUOTA_EXCEEDED: {
+    status: 429,
+    details: z.object({ retryAfterSeconds: z.number().positive() }),
+  },
+})
+throw errors.QUOTA_EXCEEDED({
+  message: 'Try later',
+  details: { retryAfterSeconds: 30 },
+  hint: 'Wait',
+})
+```
+
+There is no positional overload. A code without `details` forbids them; use an
+optional object schema when the details object itself is optional. Read status
+and schemas from the frozen `definitions` registry instead of maintaining a
+parallel map.
+
+Managed MCP runtime tools are now declared as immutable data. Move protected
+registrar calls to `runtimeTools`; rename deliberate raw SDK registration to
+`rawTools`. There is no registrar alias:
+
+```ts
+// before — protected
+createMcpHandler({
+  services,
+  nativeTools: ({ registerTool }) => registerTool(preview),
+})
+
+// after — protected and prepared with the rest of the surface
+createMcpHandler({ services, runtimeTools: [preview] })
+
+// before — deliberate raw SDK opt-out
+nativeTools: ({ rawServer }, auth) => mountRaw(rawServer, auth)
+
+// after — still a deliberate raw SDK opt-out
+rawTools: (server, auth) => mountRaw(server, auth)
+```
+
+When identity selects from a bounded set, replace a repeatedly prepared
+`services(auth)` factory with a finite registry:
+
+```ts
+createMcpHandler({
+  surfaces: {
+    admin: { services: allServices, runtimeTools: [preview] },
+    member: { services: memberServices, runtimeTools: [preview] },
+  },
+  selectSurface: (auth) => auth.isAdmin ? 'admin' : 'member',
+})
+```
+
+Keep direct `services(auth)` / `runtimeTools(auth)` only for genuinely
+unbounded definitions; Stitchkit intentionally does not cache arbitrary auth
+values.
+
+Contract success bodies are now determined by the presence of `output`, not by
+the handler's runtime value. A nullable output returns JSON `null` with status
+`200`; `undefined` with a declared output and non-null data without an output
+schema are contract violations:
+
+```ts
+// nullable JSON data: 200 with body `null`
+session: {
+  method: 'GET', path: '/session', desc: 'Current session',
+  output: SessionSchema.nullable(),
+}
+
+// bodyless operation: 204 with no body
+logout: {
+  method: 'POST', path: '/logout', desc: 'End the session',
+}
+```
+
+Add an output schema to every handler that returns data. Omit `output` and
+return nothing for bodyless operations; runtime tools follow the same rule and
+type no-output handlers as `void`.
+
+`createToolInvoker` now separates immutable registry preparation from per-call
+runtime state. Move source/context/lifecycle/hooks/output-strip reporting from
+the factory config to the third invocation argument. Use `invokeOrThrow` when a
+nested operation should preserve the normalized `AppError` instead of returning
+a model-facing failure envelope:
+
+```ts
+// before
+const invoker = createToolInvoker(services, {
+  transport: 'AGENT', context: { identity }, lifecycle, hooks,
+})
+const result = await invoker.invoke(name, args)
+
+// after
+const invoker = createToolInvoker(services, { transport: 'AGENT' })
+const result = await invoker.invoke(name, args, {
+  context: { identity }, lifecycle, hooks,
+})
+const data = await invoker.invokeOrThrow(name, args, {
+  context: { identity }, lifecycle, hooks,
+})
+```
+
+There is no static runtime-config overload: request identity must not be retained
+by a reusable compiled registry.
+
+Entity cache handlers now require the cached list shape and CRUD policies. Move
+`listKey` under `list`, make detail keys event-aware, and state the list-item
+identity/projection explicitly:
+
+```ts
+// before
+createEntityCacheHandlers<Entity>({
+  getId,
+  listKey: ['entities'],
+  detailKey: (id) => ['entities', id],
+})
+
+// after
+createEntityCacheHandlers<Entity, EntityListItem>({
+  getId,
+  getListItemId: (item) => item.id,
+  toListItem: (entity) => ({ id: entity.id, name: entity.name }),
+  list: {
+    key: ['entities'],
+    shape: 'paginated',
+    createAt: 'start',
+    updateMissing: 'skip',
+  },
+  detailKey: (event) => ['entities', event.id],
+})
+```
+
+Choose `array`, `paginated`, `infinite-array` or `infinite-paginated` to match
+the actual cached data. A dynamic `list.key` / `detailKey` receives a
+discriminated event and can derive scoped keys from the created/updated entity
+or deleted payload. Add `compare` only when the backend has a canonical order;
+the framework does not guess it or mutate pagination metadata.
+
+Protected native MCP operations now use the transport-neutral runtime tool
+definition. Return the schema-owned value from the handler and move MCP content
+or metadata into `present.mcp`; `structuredContent` and `isError` are
+framework-owned:
+
+```ts
+// before
+registerTool({ input, output, handler: async () => ({
+  content: [{ type: 'image', data, mimeType: 'image/png' }],
+  structuredContent: { assetId },
+}) })
+
+// after
+const preview = defineRuntimeTool({
+  name: 'render_preview', description, identity, input, output,
+  handler: async () => ({ assetId, data }),
+  present: {
+    mcp: (result) => ({
+      content: [{ type: 'image', data: result.data, mimeType: 'image/png' }],
+    }),
+  },
+})
+runtimeTools: [preview]
+```
+
+The removed `NativeMcp*` types have no aliases. Use `RuntimeToolDefinition`,
+`RuntimeToolIdentity`, `RuntimeToolHandlerContext` and
+`RuntimeMcpPresentation`. The same definition can now be passed to
+`mountAgent(services, { runtimeTools: [preview] })`; add `present.agent` only
+when the model needs rich text/file content instead of the neutral JSON result.
+
+Trailing wildcards must be named consistently across the path and params schema:
+
+```ts
+// before
+path: '/app/:slug/*'
+params: z.object({ slug: z.string(), '*': z.string() })
+ctx.params['*']
+api.app({ slug: 'foo', '*': 'a/b' })
+
+// after
+path: '/app/:slug/*filePath'
+params: z.object({ slug: z.string(), filePath: z.string() })
+ctx.params.filePath
+api.app({ slug: 'foo', filePath: 'a/b' })
+```
+
+Bare wildcards have no compatibility alias; raw routes use the same named form.
+
+### Expected-401 matchers
+
+`HttpClientConfig.authEndpoints` is removed. Replace manual path prefixes with
+the operations whose 401 response is expected:
+
+```ts
+// before
+createHttpClient({ baseUrl, authEndpoints: ['/api/auth/'] })
+
+// after
+createHttpClient({
+  baseUrl,
+  suppressUnauthorizedFor: contractEndpointMatchers(authContract, ['login', 'verify']),
+})
+```
+
+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)
+```