stitchkit 0.122.2 → 0.123.0

package/llms/process.txt

@@ -6,7 +6,7 @@
 
 Parts of this slice:
 - `llms/process.txt`: Guide: Native IO  (docs/guide/native-io.md)
-- `llms/process.2.txt`: API reference: `stitchkit/process`  (docs/api/reference.md)
+- `llms/process.2.txt`: Guide: Native IO  (docs/guide/native-io.md) · API reference: `stitchkit/process`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: Native IO  (docs/guide/native-io.md)
@@ -348,6 +348,64 @@ A command in the caller's group (`group: 'caller'`) has no group of its own: `de
 refused there and nothing is stopped after its leader exits. A command whose group this package did not create (a structural
 launcher supplied by a host) has no group to stop, and `descendants` has nothing to act on there.
 
+## A contract operation in a process of its own
+
+A handler that reads gigabytes holds the server's event loop while it reads, and every cheap
+operation on that server waits behind it. `createOperationProcesses` runs such an operation in a
+child process, one per call, on top of `runNativeCommand` and `streamNativeCommand`. What it
+returns are ordinary contract handlers, so the operation is routed, gated and validated like any
+other:
+
+```ts
+import { createOperationProcesses, runOperationProcess } from 'stitchkit/process'
+
+// server
+const processes = createOperationProcesses({
+  command: { executable: process.execPath, args: [cliPath, '__operation'], envPolicy: 'ambient' },
+  maxConcurrent: 2,              // a third call is refused, not queued
+  maxResponseBytes: 8 * 1024 * 1024,
+  timeoutMs: 60_000,
+})
+const service = implement(searchContract, {
+  search: processes.unary(searchContract, 'search'),
+  follow: processes.stream(searchContract, 'follow'),
+  count: ({ input }) => countCheaply(input),   // stays in process
+})
+
+// the child: the same contract, the real handlers
+if (process.argv[2] === '__operation') {
+  process.exitCode = await runOperationProcess([implement(searchContract, realHandlers)])
+}
+```
+
+- **The contract's schemas hold at the server.** The server validates the input before it starts
+  a process — a bad call never costs one — and validates the answer against the output schema
+  after; a stream item is validated against `stream.item` on its way out. The child receives the
+  input the server already parsed and does not parse it again.
+- **The call and the answer cross as JSON.** A schema whose parsed value JSON cannot carry — a
+  `Date`, a `Map`, a `bigint` — cannot be an input or an output of such an operation: the value
+  arrives as its JSON form and the output check refuses it. A call may weigh up to 64 MiB; bytes
+  an operation works on belong in a file it is told the path of.
+- **The call's end is the process's end.** The caller's abort (`ctx.signal`) stops the process
+  group under the command's `stop` policy. A unary call also ends at `timeoutMs` with
+  `REQUEST_TIMEOUT`. A stream's deadline is the contract's own `stream.lifetimeMs`: when it
+  passes, the stream ends with `STREAM_LIFETIME_EXCEEDED` and the process is stopped; without it
+  a stream lives until it ends or its reader leaves.
+- **The answer is bounded.** `maxResponseBytes` bounds the whole answer of a unary operation and
+  each item of a stream; more is `OPERATION_RESPONSE_TOO_LARGE`. Only stdout counts: what the
+  child writes to stderr does not spend the answer's budget.
+- **The count is bounded.** A call beyond `maxConcurrent` is refused with `503 OPERATION_BUSY`
+  (`retryable: true`) at once. There is no queue: a queue without a bound is the same memory the
+  process boundary was meant to protect. A call that cannot start gives its slot back.
+- **A stream delivers as it produces.** `processes.stream` yields each item when the child
+  writes it.
+
+A refusal the child's handler throws arrives as that same `AppError` — code, status, details,
+hint and retryability — for a unary call and in the middle of a stream alike. A process that
+dies, writes something that is not an answer, or cannot start is `OPERATION_PROCESS_FAILED`; the
+last 16 KiB of its stderr stay in the error's cause for the log and never reach the caller.
+`processes.active` reports the calls running now. The child reads one call from stdin and writes
+its answer to stdout, so its handlers must not print there.
 
 ## Replacing hand-written wrappers
 
@@ -710,27 +768,3 @@ Malformed inputs, a manifest whose `formatVersion` is not 2 and other IO errors
 A missing or corrupt companion at runtime yields the native `unavailable` result with the safe
 stage and code from the observer; it never certifies a dead owner. Preserve the raw cause internally.
 The plugin does not parse consumer JS or establish a second runtime native implementation.
-
-## Qualification boundaries
-
-Native command cleanup owns the child before launch subscriptions are installed. Setup
-refusal still settles leader closure and teardown within the cleanup budget; failure to
-prove closure reports `COMMAND_CLEANUP` with the original failure retained. Process-group
-signaling requires evidence from the actual detached launcher, not a structural PID field.
-The built-in sandbox transport carries that ownership across the package's split entrypoints.
-Internal finite deadlines and Darwin retry admission use monotonic elapsed time.
-
-Linux UID-refusal qualification is a separate privileged installed-package proof in Bun
-and real Node; an unsupported platform or insufficient UID reports an explicit skip.
-A generic native-owner marker does not certify the privileged case. Real Darwin CI remains
-the qualification for native Darwin behavior.
-
-Local filesystem tests do not attest delayed NFS visibility, shared-volume microVM or gVisor
-ownership, actual PGID reuse, power-loss durability or macOS full-sync behavior. Those
-require their actual topology or failure environment. No age-only observation proves a
-process dead; the lock's owner record exists before its name does.
-
-A sandbox admission slot is released once a direct command's pipes have closed and its owner has settled.
-A `COMMAND_CLEANUP` outcome means the death of its group was not proven, so the slot stays
-occupied, `stop` keeps rejecting with the cleanup error, and the sandbox session is recreated to
-recover.

package/llms/server.4.txt

@@ -551,7 +551,8 @@ error round-trips without adding correlation data to the response body.
 
 A `code` is a free string — your app codes (`BOT_NOT_FOUND`, …) are yours and the
 core never models them (ADR 0002). But stitchkit itself emits a set of its own:
-`BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`,
+`BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `UNKNOWN_OPERATION`,
+`METHOD_NOT_ALLOWED`,
 `CONFLICT`, `RATE_LIMITED`, `REQUEST_ABORTED`, `REQUEST_TIMEOUT`,
 `VALIDATION_ERROR`, `FILE_INVALID_PATH`,
 `FILE_OUTSIDE_ROOT`, `FILE_NOT_FOUND`, `FILE_NOT_REGULAR`,
@@ -561,7 +562,8 @@ core never models them (ADR 0002). But stitchkit itself emits a set of its own:
 `WAIT_FAILED`, `CLI_COMMAND_UNAVAILABLE`, `CLI_PRESENTATION_FAILED`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
 `CONNECTION_TIMEOUT`, `CONNECTION_RESPONSE_TOO_LARGE`,
 `CONNECTION_REQUEST_FAILED`, `UPSTREAM_TOOL_ERROR`,
-`OPERATION_NOT_SUCCEEDED`, `STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,
+`OPERATION_NOT_SUCCEEDED`, `OPERATION_BUSY`, `OPERATION_RESPONSE_TOO_LARGE`,
+`OPERATION_PROCESS_FAILED`, `STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,
 `STREAM_TERMINAL_MISSING`, `STREAM_LIFETIME_EXCEEDED`,
 `GRAMMY_WEBHOOK_NOT_ACCEPTING`, `SANDBOX_UNAVAILABLE`, `SANDBOX_INSUFFICIENT`,
 `SPILL_REFERENCE_UNKNOWN`, `INTERNAL_SERVER_ERROR` — a set that grows in
@@ -589,7 +591,8 @@ envelope is a published contract, at the cost of an edit on those releases:
 // a map written exhaustively stops compiling on every addition. Codes you leave
 // out fall through to `unmappedCode`.
 const STITCH_TO_APP: Partial<Record<StitchErrorCode, AppCode>> = {
-  NOT_FOUND: 'NOT_FOUND', METHOD_NOT_ALLOWED: 'METHOD_NOT_ALLOWED',
+  NOT_FOUND: 'NOT_FOUND', UNKNOWN_OPERATION: 'NOT_FOUND',
+  METHOD_NOT_ALLOWED: 'METHOD_NOT_ALLOWED',
   BAD_REQUEST: 'VALIDATION_ERROR', VALIDATION_ERROR: 'VALIDATION_ERROR',
   UNAUTHORIZED: 'UNAUTHORIZED', FORBIDDEN: 'FORBIDDEN', CONFLICT: 'CONFLICT',
   RATE_LIMITED: 'RATE_LIMITED', INTERNAL_SERVER_ERROR: 'INTERNAL_SERVER_ERROR',
@@ -715,7 +718,8 @@ const onError = createErrorHook({
   codeMap: {
     BAD_REQUEST: 'bad_request', VALIDATION_ERROR: 'bad_request',
     UNAUTHORIZED: 'unauthenticated', FORBIDDEN: 'forbidden',
-    NOT_FOUND: 'not_found', METHOD_NOT_ALLOWED: 'not_found',
+    NOT_FOUND: 'not_found', UNKNOWN_OPERATION: 'not_found',
+    METHOD_NOT_ALLOWED: 'not_found',
     CONFLICT: 'conflict', RATE_LIMITED: 'rate_limited',
     INTERNAL_SERVER_ERROR: 'internal',
   },

package/llms/server.5.txt

@@ -31,6 +31,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `createServer` | function | build the router and start `Bun.serve` — [guide](../guide/server.md#createserver) |
 | `createHandler` | function | the router as a bare `(req) => Response` — [guide](../guide/server.md#createserver) |
 | `implement` | function | bind a contract to typed handlers — [guide](../guide/server.md#implement) |
+| `withContractIdentity` | function | the given services plus the one answering `contractIdentityContract` with their fingerprint — the list to mount — [guide](../guide/client.md#which-contract-does-the-server-speak) |
 | `createImplement` | function | fix the handler context type once |
 | `createScopedImplement` | function | fix one scope→context map, then type every handler by its endpoint's effective scope; `.declare(contract)(handlers)` types without binding for the registry path, `.stream(scope, …)` covers streaming multipart — [guide](../guide/server.md#per-scope-handler-context--createscopedimplement) |
 | `ScopedHandlers` | _type_ | handler map typed per endpoint by its effective scope |

package/llms/stitchkit.2.txt

@@ -245,6 +245,75 @@ seventh constructor argument remains `ErrorOptions`, including `cause`; the opti
 retryability argument is eighth. Closed error/frame schemas must accept the new optional
 field before their producer declares it.
 
+## Which contract does the server speak
+
+A client is built from one version of a contract and a server from another
+whenever the two are deployed separately. Three facts then look alike unless
+they are told apart: the server has no such operation, the operation ran and
+found nothing, and the field is simply absent.
+
+**An operation the server cannot route is `UNKNOWN_OPERATION`.** A server
+answers an unmatched route with `404 UNKNOWN_OPERATION`
+(`details: { method, path }`), never `NOT_FOUND` — that code is a handler
+saying its object does not exist. A contract client adds the operation it was
+calling, and reads the router's `405` for its own call the same way, because it
+always calls with the method its contract declares. The router's `405` carries
+`details: { method, path, allow }`; a `METHOD_NOT_ALLOWED` a handler throws
+itself has no `allow` list and stays `METHOD_NOT_ALLOWED`.
+
+```ts
+try {
+  await api.search({ query })
+} catch (error) {
+  if (error instanceof ApiError && error.code === 'UNKNOWN_OPERATION') {
+    // error.details.operation === 'records.search' — this server predates it
+  }
+}
+```
+
+**The fingerprint says so before the call.** `contractFingerprint(contracts)`
+(`stitchkit/contract`) is a synchronous digest of the operations HTTP carries —
+method, route and the JSON Schemas of params, input, output and stream item —
+with one digest per operation under `operations['prefix.key']`. It is the same
+value in every process and runtime. A server answers its own through an
+ordinary contract it mounts by choice, and a client reads both sides in one
+call, over HTTP or a Unix socket alike:
+
+```ts
+// server: the list to mount, with the identity of exactly that list
+import { withContractIdentity } from 'stitchkit/server'
+createServer({ services: withContractIdentity(services) })
+
+// client
+import { readContractIdentity } from 'stitchkit'
+const { client, server } = await readContractIdentity(contracts, config)
+if (server === undefined) {
+  // the server does not answer its identity: it predates it or did not mount it
+} else if (server.operations['records.search'] === undefined) {
+  // this server has no `records.search`
+} else if (server.operations['records.get'] !== client.operations['records.get']) {
+  // `records.get` has another schema there: a missing field may be "not sent yet"
+}
+```
+
+Both fingerprints arrive as a value; a difference never throws. Stitchkit
+computes the two identities and compares nothing — what a mismatch means is the
+application's decision. The client's fingerprint is computed locally and is not
+sent to the server. The identity operation is public and lists operation names,
+which is why it is mounted explicitly. Routing alone cannot always tell the
+cases apart — a new `GET /records/search` reaches an older server's
+`GET /records/:name` and comes back `NOT_FOUND` — so a client that must know
+reads the fingerprint rather than inferring from a refusal.
+
+What the fingerprint covers is what constrains a value. An endpoint's `desc`, a
+field's `.describe()` or `.meta()` annotations, and the order of an object's
+fields do not move it; a type, a constraint, a required field, a method or a
+route does. It does not cover a stream's wire framing or format, `multipart`,
+`rawResponse` and `contentType`, and it cannot tell apart types JSON Schema has
+no word for — a `Date` and a `bigint` both read as "anything". Two different schemas registered
+under one `.meta({ id })` are refused by Zod's own conversion, here as in OpenAPI. The digest
+identifies, it does not authenticate: it is not a cryptographic hash.
+
 ## Auth events
 
 The HTTP client emits events your app can react to globally:
@@ -652,6 +721,8 @@ The browser-and-server entrypoint. Re-exports everything from
 | `RegistryScope` | _type_ | contract-scope union inferred from a scoped client registry value |
 | `createUrlBuilder` | function | build synchronous browser-native URLs for all HTTP endpoints; body methods accept URL-bound args only — [guide](../guide/client.md#contract-url-builders) |
 | `createUrlBuilders` | function | build one exact URL builder per contract in a registry |
+| `readContractIdentity` | function | read the server's contract fingerprint in one call and return it beside the client's own — [guide](../guide/client.md#which-contract-does-the-server-speak) |
+| `ContractIdentity` | _type_ | `{ client, server }` fingerprints; `server` is `undefined` when the server answers no identity |
 | `UrlBuilderConfig` | _type_ | explicit `{ baseUrl }` source for a URL builder |
 | `ClientConfig` | _type_ | config for `createClient`'s bare-fetch mode (2nd arg, no `HttpClient`) |
 | `ClientFetch` | _type_ | injectable Fetch-compatible transport used by framework and application-owned adapters |
@@ -704,6 +775,9 @@ The browser-and-server entrypoint. Re-exports everything from
 | `StreamLineLimitError` / `StreamTruncatedLineError` | class | a line past `maxLineBytes` (`limitBytes`, `lineBytes`; a `RangeError`) and a source ended inside a line under `require-newline` (`lineBytes`; a `SyntaxError`) |
 | `resumableIterator` | function | re-open a long-lived stream from the last delivered cursor, with jittered backoff, a caller-owned terminal item and prompt abort — [guide](../guide/client.md#resumable-streams) |
 | `createBackoff` | function | exponential backoff with subtractive jitter as a value: `next()` / `reset()` |
+| `contractFingerprint` | function | synchronous digest of the operations HTTP carries, whole and per `prefix.key` — [guide](../guide/client.md#which-contract-does-the-server-speak) |
+| `ContractFingerprintSchema` / `ContractFingerprint` | schema / _type_ | `{ fingerprint, operations }` — one digest for the set and one per operation |
+| `contractIdentityContract` | contract | the operation a server answers its fingerprint with; mount it with `withContractIdentity` |
 | `ContractStreamFrameSchema` / `ContractStreamFrame` | schema / _type_ | default on-the-wire `data` / safe `error` / `end` envelope of a contract-first stream |
 | `ContractStreamFraming` / `ContractStreamCompletion` | _types_ | opt-in item-vs-envelope framing and terminal-vs-stream-end completion policies |
 | `StreamFinalLinePolicy` | _type_ | permissive or newline-required final NDJSON line policy |

package/llms/stitchkit.txt

@@ -73,9 +73,9 @@ own, recorded as an ADR.
 | `stitchkit/cli` | server | stable | `createCli` / `createCliInvoker` — runtime and strict NodeNext declarations without MCP SDK / `ai` |
 | `stitchkit/cli/publish` | build and release tooling (Bun or Node, POSIX) | evolving | `publishCli` — commit a verified CLI distribution and move its public manifest last; see [CLI guide](cli.md#publishing-a-complete-version) |
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
-| `stitchkit/process` | server (Bun or Node, POSIX) | evolving | finite native commands, byte sinks, bounded capture, process-group cancellation and opt-in Linux/Darwin owner-loss cleanup |
+| `stitchkit/process` | server (Bun or Node, POSIX) | evolving | finite native commands, byte sinks, bounded capture, process-group cancellation and opt-in Linux/Darwin owner-loss cleanup; contract operations executed in one-call child processes |
 | `stitchkit/process/owner-loss` | bundled server entry (Bun, POSIX) | evolving | narrow bootstrap that keeps the process runner lazy while carrying its owner-loss guard in a single-file bundle |
-| `stitchkit/files/packaging` | build time (Bun or Node) | evolving | installed native asset graph, integrity, Bun packaging plugin and the artifact loader check; no runtime install policy |
+| `stitchkit/files/packaging` | build time (Bun or Node) | evolving | installed native asset graph, integrity, Bun packaging plugin and the artifact loader check; a client bundled into one self-contained, hashed and verified file; no runtime install policy |
 | `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
 | `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification, send-failure classification, one outbound budget per bot token with weighted albums and per-chat 429 pauses, resumable broadcasts, the operator channel with dedupe, a Bot API transport that separates a request that never left from an unknown outcome, local Bot API files, webhook ownership and durable webhook update intake |
 | `stitchkit/telegram/grammy` | server (Bun or Node) | evolving | the token's outbound budget as one grammY client transformer — a 429 that comes back as a response pauses its chat, and a cancelled wait is a request that never left |
@@ -92,13 +92,13 @@ own, recorded as an ADR.
 | `stitchkit/xlsx` | browser **and** server | evolving | a workbook from rows and typed columns, with no dependency; text never runs as a formula |
 | `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 67 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 68 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, the managed-resource conformance kit and manual time for schedules and retries |
 | `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/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
 | `stitchkit/react/keyboard/testing` | server (Bun or Node) | evolving | the keyboard layers and zones without a DOM — fakes for the window, elements and key events beside the two engines, to test the order of layers, `scope`/`inert` and the edges of a zone in milliseconds |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 26 of the 67 minors since 0.56.2, most recently 0.121.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 26 of the 68 minors since 0.56.2, most recently 0.121.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 |
@@ -110,7 +110,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 14 of the 67 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 68 minors since 0.56.2, most recently 0.110.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

@@ -135,7 +135,7 @@ presentation envelope. `invokeOrThrow` returns validated data and throws the
 runner's normalized `AppError` on failure, preserving an application error's
 code, status, message, details and hint without reconstructing it from the
 model-safe envelope. Unexpected throws remain scrubbed. An unknown name throws
-`AppError('NOT_FOUND')` before the runner because there is no operation identity
+`AppError('UNKNOWN_OPERATION')` before the runner because there is no operation identity
 against which hooks could run. Duplicate and provider-invalid names fail when
 the invoker is created.
 

package/llms/{upgrading-0.106.0-0.122.0.txt → upgrading-0.106.0-0.123.0.txt}

@@ -1,14 +1,61 @@
-# Upgrading 0.106.0 → 0.122.0 — stitchkit docs slice
+# Upgrading 0.106.0 → 0.123.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.106.0 → 0.122.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.106.0 → 0.123.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.106.0 → 0.122.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.106.0 → 0.123.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.123.0
+
+### unknown-operation
+
+**Who must act:** HTTP callers and `onError` code maps that read `NOT_FOUND` to mean "no such
+route", callers of `createCliInvoker`, `--wait` and `createToolInvoker` that read `NOT_FOUND` for
+an unknown command or tool name, and contract-client callers that branch on the router's
+`METHOD_NOT_ALLOWED`.
+
+A call no surface can route is answered `UNKNOWN_OPERATION`; `NOT_FOUND` is left to handlers.
+
+- The server answers an unmatched route `404 UNKNOWN_OPERATION` with `details: { method, path }`.
+- A contract client reports both routing refusals of its own call — that `404` and the router's
+  `405` — as `UNKNOWN_OPERATION` with `details.operation`. A `405` thrown by a handler is
+  unchanged.
+- `createCliInvoker().invoke`, an unknown `--wait` target and `createToolInvoker` answer
+  `UNKNOWN_OPERATION` for a name they do not have. The CLI exit code for it is `4`, as it was for
+  `NOT_FOUND`.
+
+```ts
+// before
+if (error.code === 'NOT_FOUND') showMissingPage()
+
+// after
+if (error.code === 'UNKNOWN_OPERATION') showMissingPage()   // no such route, command or tool
+if (error.code === 'NOT_FOUND') showMissingRecord()         // the handler's own answer
+```
+
+A `createErrorHook` `codeMap` that spells `NOT_FOUND` for clients adds
+`UNKNOWN_OPERATION: 'not_found'` to keep the previous wire code.
+
+### cli-schema-option
+
+**Who must act:** applications whose CLI exposes a command with an input field named `schema`.
+
+`--schema` is a framework option that prints a command's JSON Schema, so a command field of that
+name can no longer receive a value. A contract command declaring it fails at startup; a
+runtime-catalogue command becomes unavailable with the reason in help. Rename the field.
+
+```ts
+// before
+input: z.object({ schema: z.string() })     // app export --schema public
+
+// after
+input: z.object({ schemaName: z.string() }) // app export --schema-name public
+```
+
 ## Released migration: 0.122.0
 
 ### read-view-refusal

package/llms/upgrading.txt

@@ -11,7 +11,7 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.106.0 → 0.122.0: `llms/upgrading-0.106.0-0.122.0.txt`
+- 0.106.0 → 0.123.0: `llms/upgrading-0.106.0-0.123.0.txt`
 - 0.96.0 → 0.105.0: `llms/upgrading-0.96.0-0.105.0.txt`
 - 0.69.0 → 0.95.0: `llms/upgrading-0.69.0-0.95.0.txt`
 - 0.55.0 → 0.68.0: `llms/upgrading-0.55.0-0.68.0.txt`