stitchkit 0.103.12 → 0.104.0

package/llms/cli.2.txt

@@ -5,7 +5,146 @@
 
 Parts of this slice:
 - `llms/cli.txt`: Guide: CLI  (docs/guide/cli.md)
-- `llms/cli.2.txt`: API reference: `stitchkit/cli`  (docs/api/reference.md)
+- `llms/cli.2.txt`: Guide: CLI  (docs/guide/cli.md) · API reference: `stitchkit/cli`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: CLI  (docs/guide/cli.md)  (continued)
+==============================================================================
+
+## Commands discovered from a running server
+
+A CLI compiled from contracts carries the surface of the build it was compiled
+from. One built from discovery carries the surface the server has *right now* —
+which matters, because a long-lived MCP client freezes schemas at connect time
+and then refuses the server's own newer fields:
+
+```ts
+const discovered = await mountConnections([
+  defineMcpClientConnection({
+    name: 'api',
+    transport: { url },
+    token: () => key,
+    transports: ['CLI'],   // the opt-in: this server's tools are commands
+    limits: {
+      discovery: { timeoutMs: 30_000, maxResponseBytes: 4 * 1024 * 1024 },
+      call: { timeoutMs: 120_000 },
+    },
+  }),
+])
+await createCli({ name: 'myapp', version, runtimeTools: discovered, commands: [...] })
+```
+
+`transports` is where the opt-in belongs: a whole server becomes a set of
+commands, and a connection without it still contributes nothing to the CLI —
+exposure stays explicit, as it is everywhere else in the framework.
+
+One unconvertible schema no longer takes the connection down with it. The tool
+is skipped and **named** (`onSkippedTool`, or a stderr line by default), so a
+surface of two hundred tools is not lost to one.
+
+MCP connection limits follow the operation phase. `initialize`, the initialized
+notification, `tools/list` and legacy endpoint discovery use `limits.discovery`;
+`tools/call` uses `limits.call`. A mounted call's handshake still uses discovery
+limits. Each logical operation has one deadline, including initial transport
+negotiation and response-body reading. Legacy endpoint readiness has a discovery
+deadline; the lifetime of an established SSE stream does not.
+
+Omitted phase fields inherit the existing connection-level `timeoutMs` and
+`maxResponseBytes`, whose defaults are 30 seconds and 1 MiB. Values must be positive
+safe integers; `timeoutMs` must also fit the runtime timer range. The byte ceiling
+counts raw UTF-8 body bytes, including SSE framing, regardless of `Content-Length`.
+Pending legacy calls also count comments and wrong-id frames. `budget.maxTools`
+and `budget.maxSchemaBytes` remain separate mount limits.
+
+Only the initial `initialize` can negotiate HTTP-to-legacy fallback on 400, 404
+or 405. A failed `tools/call` is not replayed. Caller cancellation preserves its
+original reason for in-process observers.
+
+Expected local failures produce safe tool errors: `CONNECTION_TIMEOUT` (exit 7),
+`CONNECTION_RESPONSE_TOO_LARGE` (exit 1), `UNAUTHORIZED` (exit 2), `FORBIDDEN`
+(exit 3) or `CONNECTION_REQUEST_FAILED` (exit 1). Deadline and response-limit
+failures include fixed `operation`/`phase`, the applicable bound and measured
+`observedReadBytes`. The public `ConnectionTimeoutError` and
+`ConnectionResponseTooLargeError` classes carry the same diagnostics. Raw URL,
+credential, body, identity and stack stay with the original in-process cause in
+`onToolError` / `afterToolCall`; tool errors produce no process console dump.
+Unknown throws remain `INTERNAL_SERVER_ERROR`. A timeout is not proof that a
+write did not happen: verify the remote outcome before repeating an operation.
+
+**A remote refusal keeps its code.** A failed `tools/call` used to become a
+one-sentence `Error` with the result discarded, which cost three things at once:
+the code (so `exitCodes` had nothing to map and every remote failure exited `1`),
+the message the operator needed, and the error's own class — a plain `Error` is
+an *unexpected* error to the runner, so it printed a code frame of the framework
+bundle before the JSON failure and was then scrubbed to `INTERNAL_SERVER_ERROR`.
+A structured `{ error, details }` body is now relayed as the contract error it
+is, on every transport; anything else fails as `UPSTREAM_TOOL_ERROR` carrying
+what the server did send. Not `INTERNAL_SERVER_ERROR`, because nothing of ours
+broke.
+
+**On the CLI a discovered command prints the answer, not the envelope.**
+`tools/call` returns `{ content: [...], structuredContent? }`, and an agent mount
+needs exactly that — the parts are what a model is shown. The CLI is different in
+kind, because the handler's value is what gets printed, piped and aggregated:
+handed the envelope, `--count-by status` groups the *content parts* and answers
+`no record carries the field "status" — available: text, type`. So the CLI
+transport unwraps, and only it: `structuredContent` when the server sent one, a
+lone text part when it parses as JSON, its text when it does not, and `null` when
+there are no parts at all — a tool without an output contract answers that way,
+and the `_meta` beside an empty `content` is protocol metadata, never the answer.
+Several parts, an image or audio pass through whole — picking one of many would
+be inventing an answer.
+
+## Auth parity
+
+A scoped command is guarded by the same `createAuthHook` your HTTP server uses —
+pass it as `lifecycle`, and inject the identity through `context` so
+`resolveFromContext` can read it:
+
+```ts
+const authHook = createAuthHook({ /* resolve, resolveFromContext, rules */ })
+
+await createCli({
+  name: 'myapp',
+  version: '1.0.0',
+  resolveAuth: () => resolveIdentityFromToken(process.env.MYAPP_TOKEN),
+  context: (identity) => ({ user: identity }),   // resolveFromContext reads this
+  lifecycle: { beforeHandle: authHook },          // same policy; HTTP wires it as authorize
+  services,
+})
+```
+
+Without `lifecycle`, a scoped command runs **unguarded** — the scope check lives
+entirely inside the `createAuthHook` result, so with no hook wired in there is
+nothing to enforce a method's `scope`. This matches the MCP / agent surfaces
+exactly ([ADR 0014](../decisions/0014-tool-http-parity.md)): on every tool
+transport the auth gate is opt-in, so a contract with scoped methods **must** be
+given a `lifecycle` (and `context` identity) to be protected. The gate only
+*fails closed* once the hook **is** present but `resolveFromContext` is missing —
+then a scoped call has no identity and is rejected.
+
+## Typed context
+
+Use `createToolkit<AppContext>()` to type the injected `context` against your
+app's context shape — the tool-side mirror of `createImplement`
+([ADR 0017](../decisions/0017-typed-tool-context.md)):
+
+```ts
+const tools = createToolkit<{ user: User }>()
+await tools.createCli({
+  name: 'myapp',
+  version: '1.0.0',
+  services,
+  context: (identity) => ({ user: identity }),   // checked against { user: User }
+})
+```
+
+## Remaining boundary
+
+File-upload (`multipart`) contract endpoints remain CLI-invisible, the same as
+on MCP/Agent: their wire body is not a JSON tool form. Model file-oriented
+application behavior as a managed pathless command, or binary-only behavior as
+a native command. Streaming (SSE) output is not yet piped to stdout.
 
 ==============================================================================
 # API reference: `stitchkit/cli`  (docs/api/reference.md)
@@ -33,6 +172,7 @@ SDK nor the `ai` peer.
 | `checkCliUpdate` | function | bounded, interval-limited, never-throwing check for a newer published build |
 | `applyCliUpdate` | function | download, verify the decompressed digest and replace the binary by rename |
 | `assertCliPublishable` | function | refuse republishing one version from a different commit — takes one manifest or every manifest already published, because the promise a version makes does not stop at a channel boundary |
+| `publishCli` / `CliPublicationOptions` / `CliPublicationPhase` / `CliPublicationResult` | function / _type_ | optional bounded builder/admission over one immutable name/version/commit stamp; commit verified assets before the manifest pointer, recover exact completed versions, retain verified history; existing signatures/installer/updater own the wire contract |
 | `rollbackCliUpdate` / `CliRollbackConfig` / `RolledBackCliUpdate` | function / _types_ | put the kept previous build back, digest-checked first and written by the same atomic rename the update uses |
 | `signCliManifest` / `verifyCliManifest` / `cliManifestSigningPayload` | function | Ed25519 over `{name, version, commit, builtAt, assets[]}` — every asset's digest included, so the chain closes on the file that executes |
 | `cliSignatureAccepted` / `CliSignatureVerdict` | function / _type_ | `valid` \| `unenforced` \| `missing` \| `unknown-key` \| `invalid`; `unenforced` keeps an unpinned build updating while making the absence of a check visible |
@@ -64,6 +204,9 @@ SDK nor the `ai` peer.
 | `CliConfig` | _type_ | config for `createCli`; `defaultCommand`, `globalOptions`, `optionAliases` and `positionals` define the shared command presentation policy |
 | `CliPresentationPolicyConfig` | _type_ | shared command presentation-policy subset of `CliConfig` |
 | `CliSurfaceSource` | _type_ | static service/runtime array or identity-dependent factory |
+| `RuntimeToolExecution` | _type_ | neutral heterogeneous runtime-tool registration; handlers execute through the schema-validating managed runner |
+| `RuntimeToolExecutionWithOutput` | _type_ | strict neutral managed definition with schema-derived handler input/output; construct before adding to CLI `runtimeTools` |
+| `RuntimeToolDefinitionWithoutOutput` | _type_ | strict neutral managed void definition without an output contract or transport presenters |
 | `CliCommandDefinition` | _type_ | native command definition union |
 | `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
 | `CliCommandDefinitionWithOutput` | _type_ | native command with validated declared output and typed optional `present` / successful `exitCode` callbacks |

package/llms/cli.txt

@@ -6,7 +6,7 @@
 
 Parts of this slice:
 - `llms/cli.txt`: Guide: CLI  (docs/guide/cli.md)
-- `llms/cli.2.txt`: API reference: `stitchkit/cli`  (docs/api/reference.md)
+- `llms/cli.2.txt`: Guide: CLI  (docs/guide/cli.md) · API reference: `stitchkit/cli`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: CLI  (docs/guide/cli.md)
@@ -26,6 +26,46 @@ It exists for what the other three surfaces cannot do: a generation kicked off
 with `Bash(run_in_background)` that notifies on exit, a `SKILL.md` that shells
 out in one line, a pipeable terminal command.
 
+## Installation and types
+
+Install `stitchkit` and `zod` for a CLI. The public `stitchkit/cli` runtime and
+declarations do not require `ai`, the MCP SDK or Bun globals. Node consumers can
+use strict `NodeNext` resolution with `skipLibCheck: false` and ordinary Node
+types; the package keeps its required dependencies separate from optional SDKs.
+
+CLI runtime tools use the shared executable contract: identity, input and output
+schemas, handler, and explicit CLI exposure. SDK presenters belong to the MCP/AI
+definitions in `stitchkit/tools`, which require the corresponding peers. A typed
+definition returned by `defineRuntimeTool` or `createRuntimeToolFactory` can be
+passed directly to both CLI and SDK mounts.
+
+Keep transport-specific `present` on that typed SDK definition, rather than on
+an inline object in `CliConfig.runtimeTools`. CLI never executes those presenters;
+its neutral configuration does not validate SDK presentation. Native CLI command
+presentation remains on `defineCliCommand({ present })` and retains its inferred
+output type.
+
+For a CLI-only managed tool, use the neutral generic construction contract to
+infer the handler from its schemas:
+
+```ts
+import type { RuntimeToolExecutionWithOutput } from 'stitchkit/cli'
+import { z } from 'zod'
+
+const input = z.object({ text: z.string() })
+const output = z.object({ size: z.number() })
+const measure = {
+  name: 'measure', description: 'Measure text',
+  identity: { serviceName: 'text', action: 'measure', method: 'POST' },
+  transports: ['CLI'], input, output,
+  handler: ({ input }) => ({ size: input.text.length }),
+} satisfies RuntimeToolExecutionWithOutput<typeof input, typeof output>
+```
+
+Pass `measure` to `runtimeTools`. The heterogeneous registration type preserves
+the definition without inventing a common handler input; execute it through
+`createCli` or `createCliInvoker` so validation remains on the canonical path.
+
 ## Exposure is opt-in
 
 Unlike MCP and agent — where an endpoint with no `expose` is a tool by default —
@@ -206,6 +246,16 @@ there stays a positional, and `--` makes a literal `false` one too. The same
 holds for a short alias, a framework flag such as `--json false` and an
 application option.
 
+Every declared non-array option is single-use, including framework and
+application globals. Bare, separate-value, inline, negative and short-alias
+forms of a command option count as the same name: `--active=false --active`,
+`--active false --no-active` and `-f --active` are argument errors even when
+the values agree. Duplicates are refused before command execution. Array
+options accumulate across long and short forms; unknown non-dotted passthrough
+options retain their raw-list grammar. Tokens after `--` are literal data.
+Command `--help` and `-h` keep their diagnostic precedence over malformed
+operation arguments; application globals are validated before routing.
+
 Without presentation configuration, positional arguments fill non-boolean
 fields in declaration order, so `myapp generate "a fox"` is
 `--prompt "a fox"`. A piped value fills the first required unset field:
@@ -656,6 +706,88 @@ manifest URL is configuration you wrote, while an asset URL arrives inside a
 document the endpoint served, and a document is exactly what an SSRF boundary
 exists to distrust.
 
+### Publishing a complete version
+
+`publishCli` is an opt-in publisher for a local application-owned distribution
+directory. It commits every target and its version manifest before atomically
+replacing the public `manifest.json`. Your application selects the CLI source
+identity and admits that snapshot at each phase:
+
+```ts
+import { publishCli } from 'stitchkit/cli'
+
+const result = await publishCli({
+  storageRoot: '/srv/myapp/cli',
+  name: 'myapp', version: cliVersion, commit: selectedCliCommit,
+  baseUrl: 'https://downloads.example.com/cli/',
+  targets: [{ platform: 'linux', arch: 'x64' }],
+  signal,
+  admit: ({ phase, identity, signal }) => assertSelectedSource({ phase, identity, signal }),
+  build: ({ target, stamp, signal }) => compileSelectedSource({ target, stamp, signal }),
+})
+// result.outcome: 'published' | 'existing'; result.manifest is ready to serve.
+```
+
+The builder returns `Uint8Array` or `ReadableStream<Uint8Array>` containing the
+executable. Every target receives the same immutable `{ version, commit,
+builtAt }` stamp; carry it inside the binary. The publisher owns staging,
+gzip assets, paths and manifests. Callbacks receive the cancellation signal and
+run under the publication lock. Admission phases are `prepare`, each target's
+`build`, `commit`, and `promote`; validate the selected source through commit
+and promotion. A backend release can explicitly select an unchanged older CLI
+identity. The helper never substitutes a different commit or rebuilds an
+existing version under a new identity.
+
+Assets live at `<version>/<name>-<platform>-<arch>.gz`, with an immutable
+`<version>/manifest.json` and a public `manifest.json`. A verified repeat keeps
+the exact bytes and `builtAt`, requires the same target set and base URL, and
+returns `existing` without invoking the builder. A version committed before a
+failed promotion is recovered and promoted without rebuilding. Conflicting
+same-version commits, downgrades, unsafe components, corrupt manifests and
+assets are refused. Version/name/target components are validated before any
+build; `storageRoot` is absolute and its existing parent must be trusted.
+
+All limits are finite positive safe integers; `limits` overrides these defaults:
+
+| Field | Default | Enforced boundary |
+| --- | --- | --- |
+| `maxTargets` | 16 | Requested and verified target count |
+| `maxManifestBytes` | 256 KiB | Read and written manifest bytes |
+| `maxAssetBytes` | 256 MiB | Builder and decompressed executable bytes |
+| `maxCompressedBytes` | 256 MiB | Archived asset bytes |
+| `maxDirectoryEntries` | 128 | Version layout, root scan and commit space |
+| `maxStoredVersions` | 16 | Verified publisher-owned history |
+| `lockTimeoutMs` | 10,000 | Wait to acquire the lock |
+| `timeoutMs` | 600,000 | Whole publication deadline |
+
+`retention` defaults to 2 and keeps the current and previous published versions.
+It must be at least 2 and less than `maxStoredVersions` (at least 3), leaving a
+recovery slot. Older versions are pruned only after their own identity, exact
+layout, raw size and digest are verified. Runtime folders and foreign semver
+directories remain untouched. A full or unverifiable store refuses further
+publication; repeated completed candidates stay inside the owned history cap.
+Cancelled or failed incomplete staging is removed only while its root and
+directory generations still match. The shared asynchronous gzip decoder also
+bounds updater expansion by the declared raw size and configured byte cap.
+
+The publisher rejects symlink roots/versions/assets, non-regular files and
+multiply linked files, and checks held-lock, root and prior-pointer generations
+before commit and promotion. This is cooperative publication under a trusted
+parent directory. Portable path checks do not provide an atomic comparison with
+a hostile process replacing ancestors between syscalls. Durability uses file
+and directory sync on POSIX; Windows publication is refused. A deadline stops
+callback/stream waits and blocks late promotion; trusted callbacks remain
+responsible for cancelling their own subprocesses and external effects.
+
+A failure after an immutable commit reports that the publication outcome must
+be checked. A failure after public-pointer rename may already have published;
+`AtomicFilePublicationError.published` remains available when the atomic writer
+reports that boundary. Read the durable manifest and retry the admitted same
+identity to recover; an error does not promise rollback. Optional `signing` and
+`trust` reuse the Ed25519 contract below. The generated shell installer checks
+raw digest and size; the updater checks manifest authorship when given a trust
+root.
+
 ### Proving who built it — signing the manifest
 
 The asset digest proves the bytes that arrived are the bytes the manifest named.
@@ -879,106 +1011,3 @@ asked.
 What stays yours: what makes a repeat safe (an idempotency key derived from the
 line id), which operations a batch may contain, and how much of it runs at once.
 That is product knowledge, and the framework has no business guessing it.
-
-## Commands discovered from a running server
-
-A CLI compiled from contracts carries the surface of the build it was compiled
-from. One built from discovery carries the surface the server has *right now* —
-which matters, because a long-lived MCP client freezes schemas at connect time
-and then refuses the server's own newer fields:
-
-```ts
-const discovered = await mountConnections([
-  defineMcpClientConnection({
-    name: 'api',
-    transport: { url },
-    token: () => key,
-    transports: ['CLI'],   // the opt-in: this server's tools are commands
-  }),
-])
-await createCli({ name: 'myapp', version, runtimeTools: discovered, commands: [...] })
-```
-
-`transports` is where the opt-in belongs: a whole server becomes a set of
-commands, and a connection without it still contributes nothing to the CLI —
-exposure stays explicit, as it is everywhere else in the framework.
-
-One unconvertible schema no longer takes the connection down with it. The tool
-is skipped and **named** (`onSkippedTool`, or a stderr line by default), so a
-surface of two hundred tools is not lost to one.
-
-**A remote refusal keeps its code.** A failed `tools/call` used to become a
-one-sentence `Error` with the result discarded, which cost three things at once:
-the code (so `exitCodes` had nothing to map and every remote failure exited `1`),
-the message the operator needed, and the error's own class — a plain `Error` is
-an *unexpected* error to the runner, so it printed a code frame of the framework
-bundle before the JSON failure and was then scrubbed to `INTERNAL_SERVER_ERROR`.
-A structured `{ error, details }` body is now relayed as the contract error it
-is, on every transport; anything else fails as `UPSTREAM_TOOL_ERROR` carrying
-what the server did send. Not `INTERNAL_SERVER_ERROR`, because nothing of ours
-broke.
-
-**On the CLI a discovered command prints the answer, not the envelope.**
-`tools/call` returns `{ content: [...], structuredContent? }`, and an agent mount
-needs exactly that — the parts are what a model is shown. The CLI is different in
-kind, because the handler's value is what gets printed, piped and aggregated:
-handed the envelope, `--count-by status` groups the *content parts* and answers
-`no record carries the field "status" — available: text, type`. So the CLI
-transport unwraps, and only it: `structuredContent` when the server sent one, a
-lone text part when it parses as JSON, its text when it does not, and `null` when
-there are no parts at all — a tool without an output contract answers that way,
-and the `_meta` beside an empty `content` is protocol metadata, never the answer.
-Several parts, an image or audio pass through whole — picking one of many would
-be inventing an answer.
-
-
-## Auth parity
-
-A scoped command is guarded by the same `createAuthHook` your HTTP server uses —
-pass it as `lifecycle`, and inject the identity through `context` so
-`resolveFromContext` can read it:
-
-```ts
-const authHook = createAuthHook({ /* resolve, resolveFromContext, rules */ })
-
-await createCli({
-  name: 'myapp',
-  version: '1.0.0',
-  resolveAuth: () => resolveIdentityFromToken(process.env.MYAPP_TOKEN),
-  context: (identity) => ({ user: identity }),   // resolveFromContext reads this
-  lifecycle: { beforeHandle: authHook },          // same policy; HTTP wires it as authorize
-  services,
-})
-```
-
-Without `lifecycle`, a scoped command runs **unguarded** — the scope check lives
-entirely inside the `createAuthHook` result, so with no hook wired in there is
-nothing to enforce a method's `scope`. This matches the MCP / agent surfaces
-exactly ([ADR 0014](../decisions/0014-tool-http-parity.md)): on every tool
-transport the auth gate is opt-in, so a contract with scoped methods **must** be
-given a `lifecycle` (and `context` identity) to be protected. The gate only
-*fails closed* once the hook **is** present but `resolveFromContext` is missing —
-then a scoped call has no identity and is rejected.
-
-## Typed context
-
-Use `createToolkit<AppContext>()` to type the injected `context` against your
-app's context shape — the tool-side mirror of `createImplement`
-([ADR 0017](../decisions/0017-typed-tool-context.md)):
-
-```ts
-const tools = createToolkit<{ user: User }>()
-await tools.createCli({
-  name: 'myapp',
-  version: '1.0.0',
-  services,
-  context: (identity) => ({ user: identity }),   // checked against { user: User }
-})
-```
-
-## Remaining boundary
-
-File-upload (`multipart`) contract endpoints remain CLI-invisible, the same as
-on MCP/Agent: their wire body is not a JSON tool form. Model file-oriented
-application behavior as a managed pathless command, or binary-only behavior as
-a native command. Streaming (SSE) output is not yet piped to stdout.

package/llms/contract.txt

@@ -570,7 +570,7 @@ from the root `stitchkit`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `AppError` | class | the framework error — `code` / `status` / `details` / `hint` |
-| `ErrorEnvelope` | _type_ | the JSON shape of an error response |
+| `ErrorEnvelope` | _type_ | the JSON shape of an error response, preserving optional declared boolean `error.retryable` without changing HTTP retry policy |
 | `notFound` | function | throw `404 NOT_FOUND` — [guide](../guide/auth-and-errors.md#throwing-errors) |
 | `badRequest` | function | throw `400 BAD_REQUEST` |
 | `unauthorized` | function | throw `401 UNAUTHORIZED` |

package/llms/process.txt

@@ -15,7 +15,7 @@ description: Native IO для Bun и Node, с явно выбранной durabi
 type: guide
 status: active
 created: 2026-10-01 20:44 +07:00
-updated: 2026-10-03 13:36 +07:00
+updated: 2026-10-04 09:40 +07:00
 participants:
   - role: authored
     harness: Codex
@@ -29,6 +29,10 @@ participants:
     harness: Codex
     model: GPT-6
     at: 2026-10-03 13:36 +07:00
+  - role: implemented
+    harness: Codex
+    model: GPT-6
+    at: 2026-10-04 09:21 +07:00
 ---
 
 # Native IO
@@ -256,10 +260,35 @@ version: carry their reachable relative `.d.ts` closure, rather than emitting re
 instead emit declarations for only that DTO contract. Keep the library's manifest at runtime
 `dependencies: {}` and `peerDependencies: { zod: ... }` when that is its declared promise.
 
-Darwin consumers need the published native binaries at the bundled loader's relative native
-directory. A JS-only bundle is not portable evidence. Qualify the packed library outside its
-build tree in Bun and Node, test its declarations, and check that importing an unbundled
-Stitchkit leaf fails there. A separate schema-only entry must not import the native entry.
+The packaged Darwin loader has static references to both architecture addons. Bun compilation
+embeds the matching `.node` asset; ordinary Bun bundling emits native assets alongside its JS
+output. Publish **every output returned by `Bun.build`**, preserving relative paths. Copying only
+the JS file drops its native dependency. No runtime Stitchkit installation or manually chosen
+native path is required for these bundled artifacts.
+
+```sh
+bun build src/native.ts --target=bun --minify --outdir=dist
+bun build src/native.ts --compile --bytecode --format=esm --outfile=dist/native
+```
+
+For a JS build that previously used `--outfile=dist/native.js`, use
+`--outdir=dist --entry-naming=native.js` instead: the output can now include native assets.
+The standalone executable still uses `--outfile` because those assets are embedded inside it.
+
+Qualify the complete output outside its build tree and installed dependency graph. Test process
+identity, live-owner refusal, dead-owner recovery and contained file operations in the resulting
+JS bundle and standalone executable. Bun and Node package imports retain the same lazy loader;
+importing a portable leaf does not load a Darwin addon on another OS. Test declarations too,
+and check that importing an unbundled Stitchkit leaf fails in a deliberately isolated library
+distribution. A separate schema-only entry must not import the native entry.
+
+If the Darwin backend cannot load, `observeProcessInstance` still returns `unavailable`.
+Its backend `Error` preserves the original `cause`; JSON serialization carries only the stable
+`DARWIN_BACKEND_UNAVAILABLE` code, architecture, safe message and failure stage
+(`architecture`, `resolve`, `load` or `surface`), plus a recognized native error code when present.
+It excludes stack, paths and nested cause. This backend diagnosis does not reclassify kernel
+failures or turn unavailable identity into proof that an owner is dead. If a runtime provides
+no recognized native error code, the stage stays `load`; the loader never infers errno from text.
 
 This delivery removes a runtime kernel installation; it does not remove the build-time
 Stitchkit installation or create an independent lightweight npm package.

package/llms/server.4.txt

@@ -547,12 +547,15 @@ 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`,
-`CONFLICT`, `RATE_LIMITED`, `VALIDATION_ERROR`, `FILE_INVALID_PATH`,
+`CONFLICT`, `RATE_LIMITED`, `REQUEST_ABORTED`, `REQUEST_TIMEOUT`,
+`VALIDATION_ERROR`, `FILE_INVALID_PATH`,
 `FILE_OUTSIDE_ROOT`, `FILE_NOT_FOUND`, `FILE_NOT_REGULAR`,
 `FILE_INSPECTION_REJECTED`, `FILE_TOO_LARGE`, `FILE_EXISTS`,
 `REALTIME_CONTRACT_VIOLATION`, `APPLICATION_NOT_ACCEPTING`, `NOT_IMPLEMENTED`,
 `WAIT_TIMEOUT`,
 `WAIT_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`,
 `STREAM_TERMINAL_MISSING`, `STREAM_LIFETIME_EXCEEDED`,
 `GRAMMY_WEBHOOK_NOT_ACCEPTING`, `SANDBOX_UNAVAILABLE`, `SANDBOX_INSUFFICIENT`,

package/llms/server.5.txt

@@ -57,6 +57,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `respondJson` | function | a raw route's JSON response (`204` for null/undefined) |
 | `errorResponse` | function | any thrown value → the framework error envelope + `x-request-id` |
 | `normalizeError` | function | any thrown value → an `AppError` (`ZodError` → `VALIDATION_ERROR` 400 with structured `details.issues`, else generic 500) — the framework's canonical classification, for a bespoke `onError` |
+| `NormalizeErrorOptions` | _type_ | `logUnexpected` defaults to logging the raw server-side cause; tool adapters disable process dumps while their existing observers retain that cause |
 | `errorCode` | function | the stable error code for a thrown value (side-effect-free — for log attribution) |
 | `formatZodError` | function | a `ZodError` → a readable, field-summarised string |
 | `zodIssues` | function | a `ZodError` → structured `{ path, code, message }[]` — the machine-readable sibling of `formatZodError` |

package/llms/stitchkit.2.txt

@@ -710,6 +710,13 @@ URLs.
 
 ## `ApiError`
 
+On native Bun, both client paths disable Bun's separate socket idle timer while preserving
+the framework deadline and caller signal. A long declared deadline therefore remains the
+request policy. Explicit or patched fetch implementations, including Next, keep their own
+transport behavior; Node and browsers receive no Bun-specific fetch options. Raw responses
+and contract streams retain their existing header timeout and caller-owned body lifetime.
+See [Bun's idle timeout contract](https://bun.sh/reference/globals/BunFetchRequestInit/timeout).
+
 A non-2xx response is thrown as an `ApiError`:
 
 ```ts
@@ -724,6 +731,7 @@ try {
     err.message  // 'Note not found'
     err.details  // structured details, if any
     err.hint     // optional hint
+    err.retryable // optional explicit recommendation, true or false
     err.traceId  // x-request-id — correlate this failure with backend logs
     err.cause    // concrete injected transport failure, when delivery failed
   }
@@ -737,6 +745,12 @@ browser code can read it through Stitchkit's default CORS expose list; a custom
 
 The error model is shared with the server — see [Auth & errors](./auth-and-errors.md).
 
+`retryable` preserves an explicit boolean in the server error envelope; an absent declaration
+remains absent. This metadata does not change the HTTP transport retry policy. The existing
+seventh constructor argument remains `ErrorOptions`, including `cause`; the optional
+retryability argument is eighth. Closed error/frame schemas must accept the new optional
+field before their producer declares it.
+
 ## Auth events
 
 The HTTP client emits events your app can react to globally:

package/llms/stitchkit.txt

@@ -63,10 +63,11 @@ own, recorded as an ADR.
 | `stitchkit/server` | server (Bun) | stable | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
 | `stitchkit/node` | server (Node ≥ 22) | stable | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
 | `stitchkit/tools` | server | stable | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
+| `stitchkit/tools/mcp` | server (Bun or Node) | evolving | the canonical MCP HTTP/stdio server, schemas and typed MCP presenters; only Zod and the MCP server SDK peers |
 | `stitchkit/tools/contract` | browser + server | evolving | the shapes a tool surface speaks — async-operation contract, snapshot and cancel schemas, view-file input/output — without the runtime that serves them |
 | `stitchkit/tools/invoker` | server | stable | peer-free `createToolInvoker` over the canonical contract tool runner |
 | `stitchkit/tools/connections` | server (Bun or Node) | evolving | consume external MCP servers and a bounded OpenAPI subset — typed reauthorization, a per-request host fence and per-call credentials |
-| `stitchkit/cli` | server | stable | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
+| `stitchkit/cli` | server | stable | `createCli` / `createCliInvoker` — runtime and strict NodeNext declarations without MCP SDK / `ai` |
 | `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 and process-group cancellation |
 | `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
@@ -80,12 +81,12 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `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 48 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 49 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, plus the managed-resource conformance kit |
 | `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/agent-runtime` | server | evolving<br>_redefined in 22 of the 48 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 49 minors since 0.56.2, most recently 0.97.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 |
@@ -98,7 +99,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 11 of the 48 minors since 0.56.2, most recently 0.103.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 12 of the 49 minors since 0.56.2, most recently 0.104.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 |