stitchkit 0.122.2 → 0.123.0

package/llms-full.txt

@@ -65,9 +65,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 |
@@ -84,13 +84,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 |
@@ -102,7 +102,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 |
@@ -970,7 +970,10 @@ Six intrinsic HTTP-only forms intersect an **implicit factory default** with HTT
 responses and `HEAD`. Under `['HTTP', 'CLI']` they receive `['HTTP']`; under
 `['CLI']` or `[]` they receive `[]`, not an implicitly reopened HTTP route.
 An **explicit** non-HTTP exposure on any of them is a definition error, not a
-silent downgrade. `safelistedBody` only changes HTTP parsing and remains
+silent downgrade — with one exception: a streaming response may list `'CLI'`
+(`['HTTP', 'CLI']`, or `['CLI']` for a feed only a terminal reads) and then runs
+as a [command printing a line per item](./cli.md#a-contract-stream-as-a-command).
+It is still never an MCP or agent tool. `safelistedBody` only changes HTTP parsing and remains
 multi-transport. A factory policy applies only to contracts authored through
 that factory, not to contracts another helper builds internally.
 
@@ -3491,6 +3494,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:
@@ -4000,7 +4072,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.
 
@@ -9240,6 +9312,65 @@ refused there and nothing is stopped after its leader exits. A command whose gro
 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
 
 An atomic-file wrapper becomes one `writeFileAtomic` call with the chosen options. A bounded
@@ -9602,6 +9733,45 @@ A missing or corrupt companion at runtime yields the native `unavailable` result
 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.
 
+## A client as one self-contained file
+
+A package that owns a server usually ships a typed client for it, and the client's consumers
+must not inherit the server's dependencies. `buildClientArtifact` (`stitchkit/files/packaging`)
+bundles one entry module into a single file, publishes its SHA-256 beside it and can prove an
+npm archive of it:
+
+```ts
+import { buildClientArtifact } from 'stitchkit/files/packaging'
+
+const artifact = await buildClientArtifact({
+  entry: 'src/api-client.ts',
+  outFile: 'dist/api-client.js',              // + dist/api-client.js.sha256
+  forbiddenModules: ['chalk', '@acme/terminal-ui', 'src/terminal/', /providers\//],
+  package: {
+    name: '@acme/api-client', version: '1.4.0', outDir: 'dist',
+    exports: ['createApiClient'],
+  },
+})
+// artifact.file, artifact.sha256, artifact.bytes, artifact.modules, artifact.package.tarball
+```
+
+- **`forbiddenModules`** refuses a bundle whose module graph reaches a listed module with a
+  `ForbiddenModuleError` naming the module and what imports it. A bare or scoped name
+  (`'chalk'`, `'@scope/pkg'`) is a package: it is matched by the specifier that imports it, so a
+  linked or workspace package is caught wherever it really lives, and by its installed path. A
+  string with a slash matches a fragment of the project's own source path; a `RegExp` is tested
+  against each module's absolute path. Nothing is left at `outFile` when the build is refused.
+- **`package`** packs the file as an npm archive, installs it into an empty directory, imports
+  it by name and checks every name in `exports`. A client that still reaches for the building
+  package's `node_modules` fails there, before it reaches a consumer; a failed proof removes the
+  file and its hash again.
+- **`runtime`** is the platform the file is built for — `node` by default, which Bun also runs,
+  or `bun` or `browser`; a module the platform does not have fails the build.
+
+The build, the pack and the verification each run Bun as a bounded command: `timeoutMs`
+(default 120 s) is the deadline of each step, `signal` cancels, and `executable` names the Bun
+binary when it is not `bun` on `PATH`.
+
 ## Qualification boundaries
 
 Native command cleanup owns the child before launch subscriptions are installed. Setup
@@ -10382,6 +10552,49 @@ result on stdout and reports `CLI_PRESENTATION_FAILED` separately, as described
 under [Aggregate views](#aggregate-views). Void native commands cannot declare
 either callback.
 
+### The same policy for a managed command
+
+A command that comes from a contract or a runtime tool declares the same two
+callbacks where the CLI is mounted — `CliConfig.results`, keyed by command name.
+A client and a server print nothing, so the policy belongs to the CLI, not to
+the contract. `defineCliResult` types both callbacks against the operation's
+output schema:
+
+```ts
+import { createCli, defineCliResult } from 'stitchkit/cli'
+
+await createCli({
+  name: 'myapp',
+  version: '1.0.0',
+  services: [recordService],
+  results: {
+    lookup: defineCliResult(LookupOutput, {
+      present: ({ result, options }) =>
+        options.json ? `${JSON.stringify(result)}\n` : `${result.location ?? 'not found'}\n`,
+      exitCode: (result) => (result.found ? 0 : 1),
+    }),
+  },
+})
+```
+
+The guarantees are the native ones, because one function applies both: the
+callbacks run only after the operation's output is validated, `present` is
+called with and without `--json` — honouring it is the presenter's — and
+returns the exact stdout bytes, a throwing `present` reports
+`CLI_PRESENTATION_FAILED`, and a throwing or out-of-range `exitCode` becomes
+`INTERNAL_SERVER_ERROR`.
+
+The schema handed to `defineCliResult` is the command's own output schema — the
+object the contract declares, or the item schema of a stream. A policy typed
+against any other schema is a startup error, as is a key naming no managed
+command or naming a native one.
+
+The policy speaks for the command's own result only. An
+[aggregate view](#aggregate-views) (`--table`, `--count-by`, …) answers a
+different question, and after `--wait` the result is the polled command's, so
+both print without the policy. `createCliInvoker` applies `exitCode` — the
+in-process code equals the printed one — and never calls `present`.
+
 `--version`, a selected native command and its command help run before
 `resolveAuth`, services, context or runtime-tool factories. Top-level help is
 also credential-free when managed surfaces are static. A dynamic factory must
@@ -10580,6 +10793,7 @@ same Zod schema an HTTP or MCP call does.
 | `--output-dir <dir>`  | Download result media into a directory                     |
 | `--quiet`             | Suppress non-essential stderr output                       |
 | `--dry-run`           | Print the resolved call without executing                  |
+| `--schema`            | One JSON line: the JSON Schema of a command's input and output |
 | `--help`, `-h`        | Usage — top-level or per-command flag table                |
 | `--help <text>`       | List only the commands matching a substring                |
 | `--count-by <field>`  | Count records per distinct value — see [Aggregate views](#aggregate-views) |
@@ -10595,9 +10809,32 @@ newline-terminated JSON record on its respective stream; progress and CLI usage
 diagnostics remain ordinary stderr text. This keeps stdout pipeable and
 `2>/dev/null` clean. The process exit code carries the error class (`0` ok,
 `VALIDATION_ERROR → 1`, `UNAUTHORIZED → 2`, `FORBIDDEN → 3`, `NOT_FOUND → 4`,
+`UNKNOWN_OPERATION → 4`, `TIMEOUT → 7`, `STREAM_LIFETIME_EXCEEDED → 7`,
 `CLI_PRESENTATION_FAILED → 8`,
 …) — override per app with `exitCodes`.
 
+### The schema of a command — `--schema`
+
+`myapp <command> --schema` prints one line of JSON and exits `0` without
+validating arguments or calling anything:
+
+```json
+{"command":"lookup","input":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"output":{"type":"object","properties":{"found":{"type":"boolean"}},"required":["found"]}}
+```
+
+`input` is the schema the command's arguments are read by — the one `--help`
+renders — and `output` is the JSON Schema of the result, both derived from the
+operation's Zod schemas and both in JSON Schema draft-07, so a script or another
+program can hold a command to its schema without a copy. A command without a
+declared output carries no `output`; a
+[stream command](#a-contract-stream-as-a-command) carries `item` instead.
+Managed and native commands answer alike. Like `--help`, the answer needs no
+identity when the managed surface is static; a surface built by a
+`services` or `runtimeTools` function resolves identity first to learn its
+commands. `schema` is a reserved option name: a command field called `schema`
+is a startup error for a contract command and makes a runtime-catalogue command
+unavailable, like every other reserved name.
+
 ### A narrower question than "all of them"
 
 On a discovered surface `--help` is the only way to learn what exists, and that
@@ -10682,7 +10919,7 @@ reason in `details.message` on stderr; the default exit code is 1. `--json`
 compacts the error as usual; `exitCodes` and `errorHint` apply. The refusal precedes
 command argument parsing, stdin, context, hooks and the handler; `--dry-run` cannot
 turn it into success. A known unavailable `--wait` target returns the same refusal;
-an unknown target keeps `NOT_FOUND`.
+an unknown target answers `UNKNOWN_OPERATION`.
 
 This isolates only reserved/global **field** conflicts in `runtimeTools`.
 Native commands and contract-defined `services` still fail at startup for those
@@ -11224,6 +11461,59 @@ your server. A channel is two documents at two addresses — which of them a bui
 consults is your decision, and `assertCliPublishable` is told about all of them
 rather than taught the shape of any.
 
+## A contract stream as a command
+
+A streaming endpoint whose `expose` lists `'CLI'` is a command that prints one
+line per item — `['HTTP', 'CLI']` for a stream both carry, `['CLI']` for a feed
+only a terminal reads:
+
+```ts
+watch: {
+  method: 'POST', path: '/watch', desc: 'Follow record events',
+  expose: ['HTTP', 'CLI'],
+  input: z.object({ record: z.string() }),
+  stream: { item: RecordEvent },
+}
+```
+
+```sh
+myapp watch_record --record main | head -n 5
+```
+
+The command is named from the contract prefix and the endpoint key
+(`records.watch` → `watch_record`); a stream takes no `tool` group, so it has no
+`tool.name`. `optionAliases` and `positionals` apply as to any command.
+
+The call opens through the same runner as every command — validation, the
+`lifecycle.beforeHandle` gate, hooks — and the handler's async iterable is read
+by the loop the HTTP response uses: each item is validated against
+`stream.item` (`STREAM_ITEM_INVALID` otherwise), a declared `terminal` item
+completes the command, and a stream that ends before it fails with
+`STREAM_TERMINAL_MISSING`. A stream proxied by `implementRemote` is a stream
+here too. Without a policy an item is one compact JSON line;
+`results[command].present` formats each item instead. A presenter that throws
+ends the feed with `CLI_PRESENTATION_FAILED` after the lines already printed.
+`exitCode` is refused for a stream at startup — a feed has no single result to
+classify.
+
+How a feed ends:
+
+| End | stdout / stderr | Exit |
+| --- | --- | --- |
+| the stream completes | every item | `0` |
+| stdout is closed (`head`, a pager that quit) | the items read so far | `0` |
+| `CliConfig.signal` aborts | nothing more, no error | `130` (`REQUEST_ABORTED`) |
+| `stream.lifetimeMs` passes | `STREAM_LIFETIME_EXCEEDED` on stderr | `7` |
+| the source or an item fails | the error on stderr | by its code |
+
+In every case the handler's `ctx.signal` aborts and the source is asked to
+close. The command does not wait for a source that ignores its signal: the
+deadline and the cancellation are the command's, not the source's.
+
+`--wait`, `--output-dir` and aggregate views do not apply to a stream and exit
+`2`; a stream command is not reachable through `createCliInvoker`, whose answer
+is one result per line.
+
 ## One operation per line — `createCliInvoker`
 
 The most common way an agent drives a CLI is not one command: it is a stream —
@@ -11276,7 +11566,7 @@ await createCliInvoker({ name: 'myapp', services, commands: [describe] })
 ```
 
 A command that declares `output?: never` prints itself and returns nothing, so
-there is no result to hand back; it answers `NOT_FOUND` and stays on the command
+there is no result to hand back; it answers `UNKNOWN_OPERATION` and stays on the command
 line, where stdout exists. Your stream command is one of these, which is why a
 stream still cannot invoke itself.
 
@@ -13559,7 +13849,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`,
@@ -13569,7 +13860,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
@@ -13597,7 +13889,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',
@@ -13723,7 +14016,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',
   },
@@ -17322,6 +17616,53 @@ charts, no merged cells and no streaming: an application that needs them takes a
 
 # Upgrading stitchkit
 
+## 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
@@ -22683,6 +23024,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 |
@@ -22735,6 +23078,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 |
@@ -23043,6 +23389,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 |
@@ -25165,6 +25512,7 @@ SDK nor the `ai` peer.
 |--------|------|---------|
 | `createCli` | function | build and run a CLI from contracts; a runtime catalogue field conflicting with reserved/global argv options disables only that entry, retained in help with its reason; invocation returns `CLI_COMMAND_UNAVAILABLE` before side effects — [guide](../guide/cli.md#when-one-runtime-command-cannot-be-represented-in-argv) |
 | `defineCliCommand` | function | define one Zod-typed CLI-only executable command with optional validated-result presentation/exit policy |
+| `defineCliResult` | function | type a managed command's `present` / `exitCode` policy against its output schema, for `CliConfig.results` — [guide](../guide/cli.md#the-same-policy-for-a-managed-command) |
 | `parseCliArgs` | function | argv → typed tool args against a schema; inline `--field:=JSON` assigns a whole JSON value, including null, while ordinary string flags remain lexical; named array options together with bare positionals require an explicit `positionals` policy (advanced) |
 | `routeCliArgv` | function | select the command out of argv without duplicating the global-option grammar (advanced) |
 | `extractCliGlobalOptions` | function | lift the application's own global options out of argv before routing (advanced) |
@@ -25215,6 +25563,7 @@ SDK nor the `ai` peer.
 | `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
 | `CliCommandDefinitionWithOutput` | _type_ | native command with validated declared output and typed optional `present` / successful `exitCode` callbacks |
 | `CliCommandDefinitionWithoutOutput` | _type_ | native void command without an output contract |
+| `CliResultPolicy` | _type_ | `present` / successful `exitCode` callbacks of one command, typed against its validated result; `CliConfig.results` holds one per managed command |
 | `CliCommandContext` | _type_ | parsed input, framework run options, the application's `globals` and stdout/stderr writers |
 | `CliRunOptions` | _type_ | parsed global flags (`--json` compacts success/error records, `--wait`, …) |
 | `ParsedCliArgs` | _type_ | result of `parseCliArgs` |
@@ -25387,6 +25736,13 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 | Export | Kind | Purpose |
 |---|---|---|
 | `runNativeCommand` | function | caller-lifetime streaming or explicitly bounded binary capture |
+| `createOperationProcesses` | function | run contract operations in one-call child processes: `unary` / `stream` return contract handlers bounded by `maxConcurrent`, `maxResponseBytes` and `timeoutMs` — [guide](../guide/native-io.md#a-contract-operation-in-a-process-of-its-own) |
+| `runOperationProcess` | function | the child side: read one call from stdin, run it against `implement(contract, handlers)` services, write the answer |
+| `OperationProcessesConfig` | _type_ | the child command and the three bounds of `createOperationProcesses` |
+| `OperationProcesses` | _type_ | `unary(contract, key)`, `stream(contract, key)` and the `active` count |
+| `OperationCallContext` | _type_ | what a process-operation handler reads of its call: `params`, `input` and the caller's `signal` |
+| `OperationProcessService` | _type_ | what `runOperationProcess` reads of a service; the result of `implement` fits |
+| `OperationProcessIo` | _type_ | injectable call source, writer and stop signal of `runOperationProcess` |
 | `streamNativeCommand` | function | starts a command under the same group ownership, stop policy and bounds as `runNativeCommand` and returns `stdout` / `stderr` as `ReadableStream<Uint8Array>`, `result` and `stop()`; a slow reader slows the child, a cancelled stream drops its bytes, a failed command errors both streams |
 | `NativeCommandStream` | type | what `streamNativeCommand` returns: `stdout`, `stderr`, `result` (its buffers are empty) and `stop()` |
 | `NativeCommandStreamOptions` | type | `NativeCommandOptions` without `capture`, `onOutput` and `stdio`, which the streams own |
@@ -25446,6 +25802,16 @@ without splitting, preserve every output, and write each asset's `bytes` to its
 This evolving entrypoint is a build dependency; runtime imports do not reach it.
 The detailed recipe is in [native IO](../guide/native-io.md#public-native-packaging).
 
+It also owns the build of a client into one self-contained file:
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `buildClientArtifact` | function | bundle a client entry into one self-contained file with its SHA-256, refuse forbidden modules in the graph, optionally pack and verify an npm archive — [guide](../guide/native-io.md#a-client-as-one-self-contained-file) |
+| `ClientArtifactOptions` | _type_ | entry, output file, runtime, forbidden modules and the optional package to pack and verify |
+| `ClientArtifact` | _type_ | the built file, its SHA-256 and size, the bundled modules and the verified archive |
+| `ForbiddenModule` | _type_ | a package name, a source path fragment or a `RegExp` over module paths |
+| `ForbiddenModuleError` | class | the refusal of a bundle that reaches a forbidden module: `module` and `importedBy` |
+
 ## `stitchkit/http`
 
 An HTTP-only entrypoint for browsers, React Native/Hermes and servers. It exports the same `createClient`, `createClients`, `createHttpClient`, URL builders, client configuration types and `ApiError` as the root, without loading its optional Socket.IO graph. Import shared contracts from `stitchkit/contract`.

package/llms.txt

@@ -9,7 +9,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 Load the slice for each entrypoint your code imports — `import … from 'stitchkit/server'` → `llms/server.txt`; the root `stitchkit` import → `llms/stitchkit.txt`. A slice holds that entrypoint's API reference section and the guide pages whose home it is; every guide lives in exactly one slice, and a slice that needs another's guide names it under "Also read". Each file is at most 50.0 KB; a longer one continues in numbered parts, each naming the next at its top. Moving across versions: load `llms/upgrading.txt` and the range slices it lists between your version and the target. `llms-full.txt` inlines everything; it is far larger than a context window, so do not read it whole.
 
 ## Entrypoint slices
-- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 44.6 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 43.1 KB
+- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 44.8 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 47.4 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.2 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.7 KB
 - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 22.7 KB
@@ -21,12 +21,12 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/tools/contract**: [llms/tools-contract.txt](llms/tools-contract.txt) 0.2 KB
 - **stitchkit/tools/invoker**: [llms/tools-invoker.txt](llms/tools-invoker.txt) 0.2 KB
 - **stitchkit/tools/connections**: [llms/tools-connections.txt](llms/tools-connections.txt) 3.9 KB
-- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 37.8 KB → [llms/cli.2.txt](llms/cli.2.txt) 36.4 KB
+- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 40.9 KB → [llms/cli.2.txt](llms/cli.2.txt) 39.0 KB
 - **stitchkit/cli/publish**: [llms/cli-publish.txt](llms/cli-publish.txt) 1.5 KB
 - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
-- **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 33.8 KB
+- **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 34.1 KB
 - **stitchkit/primitives**: [llms/primitives.txt](llms/primitives.txt) 13.2 KB
-- **stitchkit/server**: [llms/server.txt](llms/server.txt) 44.2 KB → [llms/server.2.txt](llms/server.2.txt) 23.1 KB → [llms/server.3.txt](llms/server.3.txt) 47.0 KB → [llms/server.4.txt](llms/server.4.txt) 38.6 KB → [llms/server.5.txt](llms/server.5.txt) 23.5 KB
+- **stitchkit/server**: [llms/server.txt](llms/server.txt) 44.2 KB → [llms/server.2.txt](llms/server.2.txt) 23.1 KB → [llms/server.3.txt](llms/server.3.txt) 47.0 KB → [llms/server.4.txt](llms/server.4.txt) 38.7 KB → [llms/server.5.txt](llms/server.5.txt) 23.7 KB
 - **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 46.9 KB
 - **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 5.7 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 44.1 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 42.5 KB → [llms/agent-runtime.4.txt](llms/agent-runtime.4.txt) 45.2 KB → [llms/agent-runtime.5.txt](llms/agent-runtime.5.txt) 11.8 KB
 - **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.6 KB
@@ -64,15 +64,15 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/node**: [llms/node.txt](llms/node.txt) 3.1 KB
 - **stitchkit/agent-runtime/react**: [llms/agent-runtime-react.txt](llms/agent-runtime-react.txt) 1.0 KB
 - **stitchkit/agent-runtime/realtime**: [llms/agent-runtime-realtime.txt](llms/agent-runtime-realtime.txt) 2.6 KB
-- **stitchkit/process**: [llms/process.txt](llms/process.txt) 44.7 KB → [llms/process.2.txt](llms/process.2.txt) 4.3 KB
+- **stitchkit/process**: [llms/process.txt](llms/process.txt) 46.8 KB → [llms/process.2.txt](llms/process.2.txt) 9.1 KB
 - **stitchkit/process/owner-loss**: [llms/process-owner-loss.txt](llms/process-owner-loss.txt) 0.9 KB
-- **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 3.5 KB
+- **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 4.3 KB
 - **stitchkit/http**: [llms/http.txt](llms/http.txt) 0.9 KB
 - **stitchkit/realtime**: [llms/realtime.txt](llms/realtime.txt) 1.4 KB
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 12.7 KB
-- **Upgrading 0.106.0 → 0.122.0**: [llms/upgrading-0.106.0-0.122.0.txt](llms/upgrading-0.106.0-0.122.0.txt) 34.4 KB
+- **Upgrading 0.106.0 → 0.123.0**: [llms/upgrading-0.106.0-0.123.0.txt](llms/upgrading-0.106.0-0.123.0.txt) 36.3 KB
 - **Upgrading 0.96.0 → 0.105.0**: [llms/upgrading-0.96.0-0.105.0.txt](llms/upgrading-0.96.0-0.105.0.txt) 45.8 KB
 - **Upgrading 0.69.0 → 0.95.0**: [llms/upgrading-0.69.0-0.95.0.txt](llms/upgrading-0.69.0-0.95.0.txt) 46.6 KB
 - **Upgrading 0.55.0 → 0.68.0**: [llms/upgrading-0.55.0-0.68.0.txt](llms/upgrading-0.55.0-0.68.0.txt) 47.0 KB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.122.2",
+  "version": "0.123.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",