stitchkit 0.104.2 → 0.105.1

package/llms/cli-publish.txt

@@ -0,0 +1,29 @@
+# stitchkit/cli/publish — 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: API reference: `stitchkit/cli/publish`  (docs/api/reference.md)
+
+Also read:
+- see `llms/cli.txt` for the CLI guide
+
+==============================================================================
+# API reference: `stitchkit/cli/publish`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/cli/publish`
+
+Build and release tooling, evolving. Publishes a CLI distribution into a local
+application-owned directory; the manifest, signatures, installer and updater it
+writes for stay in `stitchkit/cli` — [guide](../guide/cli.md#publishing-a-complete-version),
+[ADR 0245](../decisions/0245-cli-publication-is-an-evolving-leaf.md).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `publishCli` | function | 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 |
+| `CliPublicationOptions` | _type_ | identity, storage root, base URL, targets, limits, retention, the `admit` and `build` callbacks, optional signing and trust |
+| `CliPublicationPhase` | _type_ | the step `admit` is asked about — `prepare`, `build`, `commit` or `promote` |
+| `CliPublicationResult` | _type_ | `published` or `existing`, with the manifest ready to serve |
+
+---

package/llms/cli.2.txt

@@ -38,7 +38,7 @@ await createCli({ name: 'myapp', version, runtimeTools: discovered, commands: [.
 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
+One unconvertible schema does not take the connection down. 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.
 
@@ -71,13 +71,12 @@ credential, body, identity and stack stay with the original in-process cause in
 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
+**A remote refusal keeps its code.** A failed `tools/call` must keep three things:
+the code (so `exitCodes` can map it instead of every remote failure exiting `1`),
+the message the operator needs, and the error's own class — a plain `Error` is
+an *unexpected* error to the runner, which would print a code frame of the framework
+bundle before the JSON failure and scrub it to `INTERNAL_SERVER_ERROR`.
+A structured `{ error, details }` body is 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.
@@ -172,7 +171,6 @@ 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 |
@@ -204,8 +202,8 @@ 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` |
+| `RuntimeToolDefinition` | _type_ | neutral heterogeneous runtime-tool registration; an inline handler is contextually typed, and handlers execute through the schema-validating managed runner |
+| `RuntimeToolDefinitionWithOutput` | _type_ | strict neutral managed definition with schema-derived handler input/output, the same declaration `stitchkit/tools` constructs with presenters |
 | `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 |

package/llms/cli.txt

@@ -33,9 +33,10 @@ 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
+CLI runtime tools use the one runtime-tool declaration: identity, input and output
+schemas, handler, and explicit CLI exposure. SDK presenters are the adapter's extension
+of that declaration (the fourth type argument of `RuntimeToolDefinitionWithOutput`, or
+`defineRuntimeTool` in `stitchkit/tools`), which requires the corresponding peers. A typed
 definition returned by `defineRuntimeTool` or `createRuntimeToolFactory` can be
 passed directly to both CLI and SDK mounts.
 
@@ -49,7 +50,7 @@ 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 type { RuntimeToolDefinitionWithOutput } from 'stitchkit/cli'
 import { z } from 'zod'
 
 const input = z.object({ text: z.string() })
@@ -59,12 +60,14 @@ const measure = {
   identity: { serviceName: 'text', action: 'measure', method: 'POST' },
   transports: ['CLI'], input, output,
   handler: ({ input }) => ({ size: input.text.length }),
-} satisfies RuntimeToolExecutionWithOutput<typeof input, typeof output>
+} satisfies RuntimeToolDefinitionWithOutput<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.
+Pass `measure` to `runtimeTools`. `RuntimeToolDefinition`, the heterogeneous
+registration type, accepts it unchanged, and types an inline handler written directly
+in `runtimeTools` by the parsed object (use the construction type above to type the
+input from the schema). Execute it through `createCli` or `createCliInvoker` so
+validation remains on the canonical path.
 
 ## Exposure is opt-in
 
@@ -254,7 +257,9 @@ 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.
+operation arguments; application globals are validated before routing. Help is a
+request, not a setting, so repeating it in any spelling (`-h -h`, `-h --help`) asks once
+and never errors.
 
 Without presentation configuration, positional arguments fill non-boolean
 fields in declaration order, so `myapp generate "a fox"` is
@@ -481,8 +486,10 @@ Declared aliases render beside their canonical options, for example
 The argument table and `Application options:` show bounds from their JSON Schema,
 for example `<integer> [>=1, <=50]`, `<string> [length >=1, length <=12]`, and
 `<value…> [items >=2, items <=4]`. Numeric `>` and `<` are exclusive, while `>=`
-and `<=` include the endpoint; a zero limit is displayed too. Unbounded fields
-keep just their type and description. Bounds on an array's items are not bounds
+and `<=` include the endpoint; a zero limit is displayed too. Only limits the
+schema declares are shown: the safe-integer range every `z.int()` carries is the
+type, not a bound, so a bare integer prints `<integer>`, `.min(1)` prints `>=1` and
+`.positive()` prints `>0`. Unbounded fields keep just their type and description. Bounds on an array's items are not bounds
 on the array itself.
 
 Composed schemas retain their meaning: `any of:` and `one of:` separate
@@ -710,11 +717,16 @@ exists to distrust.
 
 `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:
+replacing the public `manifest.json`. It ships from its own evolving entrypoint,
+`stitchkit/cli/publish`: release infrastructure follows how distributions are
+published, so it is not held to the stable promise of `stitchkit/cli`
+([ADR 0245](../decisions/0245-cli-publication-is-an-evolving-leaf.md)). The
+manifest, signatures, installer and updater it writes for stay in
+`stitchkit/cli`. Your application selects the CLI source identity and admits
+that snapshot at each phase:
 
 ```ts
-import { publishCli } from 'stitchkit/cli'
+import { publishCli } from 'stitchkit/cli/publish'
 
 const result = await publishCli({
   storageRoot: '/srv/myapp/cli',

package/llms/declaration.txt

@@ -9,15 +9,6 @@ Contains: Guide: Project declaration  (docs/guide/declaration.md) · API referen
 # Guide: Project declaration  (docs/guide/declaration.md)
 ==============================================================================
 
----
-title: Project declaration
-description: One machine-readable statement a repository makes about itself — identity, roles, build, requirements, release steps and the names of the values a deployment supplies.
-type: architecture
-status: active
-created: 2026-08-25
-updated: 2026-08-30
----
-
 # Project declaration
 
 > **Maturity: evolving.** This surface is still finding its shape and may be

package/llms/files-packaging.txt

@@ -16,19 +16,29 @@ Also read:
 
 `stitchkit/files/packaging` owns `createNativePackaging` and the types
 `NativePackagingOptions`, `NativePackagingAsset`, `NativePackagingPlugin`, `NativePackagingResult`.
-It resolves the installed package's target/version and original addon SHA256.
-`platform`, `architecture`, `delivery`, `entryPath` and `assetPath` are explicit public inputs.
-The result is `ready` with assets and a structural Bun plugin, or `unsupported`/`missing` with a safe code.
-Malformed options/metadata and other filesystem errors fail rather than masquerade as missing.
+It resolves the installed package's target/version, reads each selected addon once and checks it
+against the `size` and `sha256` published in the package's `native-assets.json` (`formatVersion: 2`,
+written when Stitchkit is built). Call it once per build and reuse the result.
+`platform`, `architecture`, `delivery`, `entryPath` and `assetPath` are explicit public inputs;
+`assetPath` accepts one template, `[hash]`, replaced by the first 16 hex digits of the addon's
+published SHA256;
+`platform` is the closed set `'darwin'`, and another name is a type error and a schema refusal.
+The result is `ready` with verified assets and a structural Bun plugin, or `unsupported` /
+`missing` / `mismatch` with the safe code `NATIVE_TARGET_UNSUPPORTED`, `NATIVE_ASSET_MISSING` or
+`NATIVE_ASSET_DIGEST_MISMATCH`. A `mismatch` names the first differing `architecture` with
+`expected` (published) and `actual` (installed) `{ size, sha256 }`.
+Malformed options, a manifest of another `formatVersion` and other filesystem errors throw rather
+than masquerade as missing.
 Companion accepts a single `architecture` string with an `assetPath` string, or an architecture
 array with an exact per-architecture `assetPath` map. `NativePackagingOptions<true>` and
 `NativePackagingResult<true>` describe the array form; default types preserve single-target signatures.
 A ready array-form result carries the architecture array; `NativePackagingAsset<true>` identifies
-each asset architecture. Default asset types and single-target runtime objects retain their three fields.
+each asset architecture. A single-target asset has four fields: `outputPath`, the verified `bytes`,
+and the published `size` and `sha256`.
 Targets must be unique; entry and all asset paths must be disjoint. One lazy loader chooses only
 the actual runtime architecture, with no fallback.
-Companion mode places external addons relative to the emitted entry; embedded mode lets
-Bun compile retain the matching addon. Keep JS builds without splitting, preserve every output,
-and copy each original asset to its `outputPath` after verifying `sha256`.
+Companion mode places external addons relative to the emitted entry; embedded mode gives
+Bun compile the verified bytes of the matching addon. Keep JS builds without splitting, preserve
+every output, and write each asset's `bytes` to its `outputPath`.
 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).

package/llms/files.txt

@@ -29,8 +29,10 @@ available from `stitchkit/contract`.
 | `ManagedFileError` / `ManagedFileErrorCode` | class / _type_ | stable boundary failures; registered `FILE_*` mistakes are caller-safe while `FILE_IO_ERROR` remains internal |
 | `ManagedFileInspector` | _type_ | bounded-prefix read/write inspection callback with a finite cancellation signal that cannot own path or size |
 | `ManagedFileInspectionInput` / `ManagedFileInspection` | _type_ | inspector prefix/name/declared media/signal input and validated metadata-only result |
-| `writeFileAtomic` / `writeFileAtomicSync` / `WriteFileAtomicOptions` | function / _type_ | replace a file atomically: a random staging name created exclusively (never through a planted link), the mode set on the descriptor before the file is visible (default `0o600`, not masked by the umask), `fsync`, rename; a failure leaves the target and no staging file. The asynchronous form keeps the event loop running |
-| `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time and nullable kernel process identity); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; an ownerless lock only after `ownerlessGraceMs` (default 5000 ms, `null` disables age-based reclaim including guards); exact `mode` is independent of umask; shared readers need a common group and traversable directories |
+| `writeFileAtomic` / `writeFileAtomicSync` / `WriteFileAtomicOptions` | function / _type_ | replace a file atomically: a random staging name created exclusively (never through a planted link), the mode set on the descriptor before the file is visible (default `0o600`, not masked by the umask), `fsync`, rename; a failure leaves the target and no staging file. The asynchronous form keeps the event loop running. A process killed before publication leaves its staging file; sweeping it is the caller's job |
+| `isAtomicStagingName` | function | true for a staging file name of an atomic write of this library (`.stitchkit-<24 lowercase hex>.tmp`, also used by the managed writer and the chunk spool); the form is a stable contract, and changing it is a breaking change ([ADR 0242](../decisions/0242-atomic-staging-name-is-a-public-contract.md)) |
+| `sweepAtomicStaging` / `SweepAtomicStagingOptions` | function / _type_ | remove abandoned staging files from one `directory`: only regular files matching `isAtomicStagingName` and older than the required `olderThanMs`, never following a symlink or entering a subdirectory; stops on `signal`; returns the removed names, `[]` for a `directory` that does not exist |
+| `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time and nullable kernel process identity); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; the lock is published with its owner already recorded (temporary file plus hard link), so a stalled holder is never displaced; a legacy empty lock file is taken by age only when `ownerlessGraceMs` is a number (default `null`: never; an abandoned empty reclaim guard is taken after 5 000 ms unless a value is set); exact `mode` is independent of umask; shared readers need a common group and traversable directories |
 | `ExclusiveLockError` | class | `LOCK_TIMEOUT` naming the resource and its holder, or `LOCK_ABORTED` with the signal's reason |
 | `createChunkSpool` | function | the server half of a chunked upload: parts on disk under `owner` + client-minted `uploadId`, each with a size+sha256 receipt; idempotent `open` and `put`, the first writer of a part wins across processes, `assemble` in order once every part is in, `sweep` of untouched uploads — [guide](../guide/client.md#chunked-uploads) |
 | `ChunkSpool` / `ChunkSpoolConfig` / `ChunkSpoolKey` / `ChunkSpoolOpen` / `ChunkSpoolPart` / `ChunkSpoolAssembly` | _type_ | the spool, its directory, part size, file limit, meta schema and age; an upload's key; its declaration; one part; the assembled parts with a concatenating `stream()` |

package/llms/geo.txt

@@ -9,15 +9,6 @@ Contains: Guide: GeoIP  (docs/guide/geo.md) · API reference: `stitchkit/geo`  (
 # Guide: GeoIP  (docs/guide/geo.md)
 ==============================================================================
 
----
-title: GeoIP
-description: A server-only managed GeoIP reader with three observable states and last-known-good generation reloads.
-type: guide
-status: active
-created: 2026-09-06
-updated: 2026-09-06
----
-
 # GeoIP
 
 `stitchkit/geo` is a server-only, evolving entrypoint for reading local GeoIP

package/llms/live.txt

@@ -9,15 +9,6 @@ Contains: Guide: Live data  (docs/guide/live.md) · API reference: `stitchkit/li
 # Guide: Live data  (docs/guide/live.md)
 ==============================================================================
 
----
-title: Live data — announcements, watched reads, keyspaces and the trust fence
-description: How to declare events beside the operation contract, share one server-side read between every browser asking the same question, keep authoritative memory in front of a durable backend, and refuse a request whose authority you never agreed to answer on.
-type: guide
-status: active
-created: 2026-09-02
-updated: 2026-09-02
----
-
 # Live data
 
 Four things an application builds by hand the second time it needs them.
@@ -429,11 +420,11 @@ Every refusal answers the same bare 403. A response that said *which* rule
 refused would let a caller learn your trusted list one guess at a time; the
 reason goes to `onRefused` and the log, where you are.
 
-### One thing that changed
+### Group hooks
 
-A route group can no longer declare `onRequest`. It never worked — the framework
-dispatched only the server-level hook — and it could not be made to work without
-matching group prefixes a second time, ahead of the real router. Use the
+A route group cannot declare `onRequest`: the framework dispatches only the
+server-level hook, and a group hook would need group prefixes matched a second
+time, ahead of the real router. Use the
 server-level `hooks.onRequest` to refuse before dispatch, or the group's
 `authorize` to gate once the endpoint is known.
 

package/llms/observability.txt

@@ -303,6 +303,32 @@ Without an `observability` the work still runs inside a context, so trace ids,
 decision from having a context. `traceparent` continues the trace of whatever
 scheduled the work, instead of starting an unrelated one.
 
+### CPU is not attributed to work
+
+Request rows, `runUnitOfWork` rows and schedule status carry durations and
+counts, never CPU. One JavaScript thread interleaves every operation, so a
+`process.cpuUsage()` delta across an operation's start and end measures
+everything the process ran in that time — a long wait reads as the CPU of the
+timers that fired during it. The correct basis is the synchronous segment, and
+Bun gives no callback when a continuation is entered or left
+([ADR 0244](../decisions/0244-cpu-is-not-attributed-to-operations.md)).
+
+Process CPU per window is the number you can observe:
+
+```ts
+let last = process.cpuUsage()
+setInterval(() => {
+  const now = process.cpuUsage() // cumulative { user, system } in µs
+  logger.info('cpu', { cpuUserUs: now.user - last.user, cpuSystemUs: now.system - last.system })
+  last = now
+}, 60_000)
+```
+
+If you build attribution yourself: credit an operation only the CPU of the
+synchronous segments it ran, never its waiting time; put everything outside those
+segments into `unattributed`; never credit a window to the one operation in
+flight — that operation is usually the one waiting.
+
 ### Write the calls that changed something
 
 `auditChanges` is the filter most projects end up writing, shipped so they do not
@@ -377,8 +403,8 @@ needed:
 createServer({ services, logging, observability: observability.request })
 ```
 
-`wrapInRequestContext` remains available for a custom fetch pipeline that does
-not use `createHandler`; it is no longer part of built-in HTTP audit wiring:
+`wrapInRequestContext` serves a custom fetch pipeline that does not use
+`createHandler`; built-in HTTP audit wiring does not use it:
 
 ```ts
 Bun.serve({ fetch: wrapInRequestContext(customFetch) })
@@ -715,9 +741,9 @@ which the built-in **tool** row does not read: a tool event takes
 `errorCode` / `errorMessage` / `errorDetail` from the `ToolResult`, and only
 identity and `dimensions` from the context. Calling it in `onToolError` would
 leave the tool row exactly as scrubbed as before. It is right for the **HTTP**
-path, where the request *is* the record. (Since ADR 0045 a tool call runs in its
-own context, so it can no longer write into the enclosing `/mcp` request's row
-either — the call is simply not where that helper belongs.)
+path, where the request *is* the record. (A tool call runs in its own context, ADR 0045,
+so it cannot write into the enclosing `/mcp` request's row either — the call is
+simply not where that helper belongs.)
 
 ### One row that names the cause
 

package/llms/primitives.txt

@@ -9,15 +9,6 @@ Contains: Guide: Generic application primitives  (docs/guide/primitives.md) · A
 # Guide: Generic application primitives  (docs/guide/primitives.md)
 ==============================================================================
 
----
-title: Generic application primitives
-description: Declare lifecycle, access, exact values, audit, delivery and exports without moving application infrastructure into Stitchkit.
-type: guide
-status: active
-created: 2026-09-01
-updated: 2026-10-01 21:03 +07:00
----
-
 # Generic application primitives
 
 `stitchkit/primitives` is an optional browser-safe leaf. It declares values and policies; it does
@@ -120,18 +111,44 @@ const bytes = canonicalJson({ '2': 'two', '10': 'ten', optional: undefined, nest
 // Native crypto or browser WebCrypto hashes these same UTF-8 bytes.
 ```
 
-`canonicalJson` использует единый serializer исторических digest: object keys в UTF-16 code-unit
-order, включая integer-like keys; array order сохраняется. Optional object members с undefined
-опускаются. Top-level/array undefined, sparse arrays, functions/symbols/BigInt, non-finite numbers,
-negative zero, cycles, user prototypes, accessors, non-enumerable/symbol members отказаны до
-serialization. Приложение валидирует свою schema первым; canonical boundary не заменяет её.
+`canonicalJson` is the one serializer behind the digests: object keys sort by UTF-16 code unit,
+integer-like keys included; array order is kept; object members that are `undefined` are omitted.
+It refuses, before serializing, a top-level or array `undefined`, sparse arrays, functions, symbols,
+BigInt, non-finite numbers, negative zero, cycles, user prototypes, accessors and non-enumerable or
+symbol members. Validate your own schema first; the canonical boundary does not replace it.
+
+Defaults: depth 100 (the maximum), nodes 100 000, UTF-8 bytes 1 MiB. Invalid options throw a Zod
+validation error. A refused value throws `CanonicalJsonError`, a `TypeError` whose `reason` is a
+`CanonicalJsonRefusal`; branch on the reason, never on the message:
+
+| `reason` | Meaning |
+|---|---|
+| `depth` | The value is nested deeper than `maxDepth`. |
+| `nodes` | The value has more nodes than `maxNodes`. |
+| `bytes` | The output is longer than `maxBytes` in UTF-8. |
+| `cycle` | The value contains a cycle. |
+| `negative-zero` | The value contains `-0`, which JSON cannot carry. |
+| `not-json` | The value is not bounded plain JSON: sparse arrays, non-finite numbers, non-plain objects, accessors. |
+
+`depth`, `nodes` and `bytes` are the caller's limits being exceeded; the other three say the value is
+not JSON data at all.
+
+```ts
+import { CanonicalJsonError, canonicalJson } from 'stitchkit/primitives'
+
+try {
+  canonicalJson(payload, { maxBytes: 4096 })
+} catch (error) {
+  if (error instanceof CanonicalJsonError && error.reason === 'bytes') {
+    // too large: reject the request
+  } else throw error
+}
+```
 
-Defaults: depth 100 (maximum 100), nodes 100 000, UTF-8 bytes 1 MiB. Превышение или не-JSON data —
-TypeError; неверные options — Zod validation error. Это browser-safe leaf без Node/Bun/crypto,
-agent-runtime/testing или optional peers. Native и browser используют один algorithm; hashing
-остаётся platform adapter. Переносите только serializer recursion, сохраняя proof schemas и
-verification boundary. Существующие внутренние historical normalization/digest fixtures не меняются;
-новый public boundary сознательно отказывает неоднозначным values вместо фиктивной совместимости.
+The leaf is browser-safe: no Node, Bun or crypto, no `agent-runtime/testing`, no optional peers. Native
+and browser code run the same algorithm; hashing stays a platform adapter. A consumer that needs the
+same bytes moves only the serializer recursion and keeps its own proof schemas and verification
+boundary.
 
 ==============================================================================
 # API reference: `stitchkit/primitives`  (docs/api/reference.md)
@@ -186,3 +203,4 @@ schedules, transports and file generation remain application-owned.
 |---|---|---|
 | `canonicalJson` | function | bounded plain JSON, UTF-16 key sort, optional object members omitted |
 | `CanonicalJsonOptions` | type | inferred depth/node/UTF-8 bytes limits |
+| `CanonicalJsonError` / `CanonicalJsonRefusal` | class / _type_ | the `TypeError` of a refusal and its `reason`: `cycle`, `negative-zero`, `depth`, `nodes`, `bytes` or `not-json` |