stitchkit 0.103.13 → 0.104.1

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

@@ -1,14 +1,151 @@
-# Upgrading 0.44.0 → 0.60.0 — stitchkit docs slice
+# Upgrading 0.44.0 → 0.61.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.44.0 → 0.60.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.44.0 → 0.61.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.44.0 → 0.60.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.44.0 → 0.61.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## 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
@@ -965,271 +1102,3 @@ implemented or advertised.
    only if `legacy: 'serve'` is part of your support policy.
 8. Run the consumer's typecheck and runtime gates. A browser/HTTP-only consumer
    must continue to work without either MCP package.
-
-## 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.