stitchkit 0.104.1 → 0.105.0

package/llms/agent-runtime-realtime.txt

@@ -15,11 +15,20 @@ Also read:
 
 ## `stitchkit/agent-runtime/realtime`
 
-Optional evolving Socket.IO server binding. `bindAgentHarnessRealtime` takes `(harness, socket, config)` and returns `close()` for its subscriptions and control connections, without closing
-socket or harness. `AgentHarnessRealtimeConfig` requires `authorize({ identity, request,
-signal })`: return `{ context }` after verifying the session principal, conversation,
-operation, files and metadata, or `null`. Identity is `socket.data` from the application's
-verified handshake. Every request and event delivery is authorized. Observe access does
+Optional evolving Socket.IO server binding, experimental: no committed consumer yet.
+`bindAgentHarnessRealtime` takes `(harness, socket, config)` and returns an
+`AgentHarnessRealtimeBinding`: `close()` for its subscriptions and control connections, without closing
+socket or harness, and `revoke(conversationId, matches?)`. `AgentHarnessRealtimeConfig` requires
+`authorize({ identity, request, source, signal })`: return `{ context }` after verifying the session
+principal, conversation, operation, files and metadata, or `null`. Identity is `socket.data` from the
+application's verified handshake. Every request is authorized on arrival. The events of an
+attached conversation are delivered under the grant the latest successful request created, so a
+token stream costs no authorization call per event. `revoke` drops the grant of every matching
+socket; the next event is re-authorized (`source: 'delivery'`, an `operation: 'snapshot'` request),
+and a refusal or failure detaches the conversation and sends an `access-denied` delivery, which
+turns the browser controller into an `error` state. Without a `revoke` call a grant lasts until the socket disconnects or the conversation
+is detached; this fail-open default is deliberate, so call `revoke` whenever access to a conversation may
+have been withdrawn. An authorization that began before a `revoke` never restores the grant. Observe access does
 not grant mutation; controller leases and approval policy still belong to the harness.
 
 `maxPendingEvents` and `maxPendingAttachments` forward to the canonical control server;

package/llms/agent-runtime-sandbox.txt

@@ -12,17 +12,6 @@ Also read:
 # Guide: Optional process sandbox  (docs/guide/sandbox.md)
 ==============================================================================
 
----
-title: Optional process sandbox
-description: Linux namespace isolation, durable workspaces and a host credential gateway.
-updated: 2026-10-03 14:47 +07:00
-participants:
-  - role: implemented
-    harness: Codex
-    model: GPT-6
-    at: 2026-10-03 14:47 +07:00
----
-
 # Optional process sandbox
 
 `stitchkit/agent-runtime/sandbox` is a server-only, evolving API. Existing coding
@@ -86,6 +75,9 @@ access the same workspace through the host's contained-file implementation;
 commands run inside the namespace with `/workspace` as their root. The host-only
 `handle.coding` binding never belongs in model input or persisted state.
 Unsupported backends omit the binding and the factory refuses explicitly.
+When the adapter's `probe()` or `prepare()` fails, the agent gets `SANDBOX_UNAVAILABLE` with a
+fixed reason; the adapter's own error is the refusal's `cause`, delivered to the mount's
+`hooks.onToolError`, which is where an application logs it.
 
 Stop also kills coding commands. Both launch paths share the configured
 `maxConcurrentCommands` admission limit (default 8); an occupied slot gives

package/llms/agent-runtime.3.txt

@@ -97,7 +97,7 @@ Server-only optional application runtime. See the
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `AgentConversationArchiveSchema` / `AgentConversationArchive` / `encodeAgentConversationArchive` / `decodeAgentConversationArchive` / `canonicalAgentJson` | schema / _type_ / functions | canonical validated conversation archive with exact ledger events, recovery projection and durable spill payloads |
+| `AgentConversationArchiveSchema` / `AgentConversationArchive` / `encodeAgentConversationArchive` / `decodeAgentConversationArchive` / `canonicalAgentJson` | schema / _type_ / functions | canonical validated conversation archive (`canonicalAgentJson` is `canonicalJson` with the node and byte limits at their maximum, reading `-0` as `0` like `z.json()`) with exact ledger events, recovery projection and durable spill payloads |
 | `AgentStoreEventEnvelopeSchema` / `AgentStoreEventEnvelope` / `AgentStoreEventKindSchema` / `AgentStoreEventKind` / `AgentStoreEventPageSchema` / `AgentStoreEventPage` | schema / _type_ | append-only event envelope, closed current vocabulary (including `provider/request` and `provider/response`) and bounded page |
 | `AppendAgentStoreEventSchema` / `AppendAgentStoreEvent` / `ReadAgentStoreEventsSchema` / `ReadAgentStoreEvents` | schema / _type_ | required append and bounded-read store contracts |
 | `AgentStoreTransitionSchema` / `AgentStoreTransition` / `AgentStoreEventDraft` / `AgentStoreEventDecodeAccepted` / `AgentStoreEventDecodeIgnored` / `AgentStoreEventDecodeResult` / `decodeAgentStoreEvent` | schema / _types_ / function | normalized runtime mutations, append drafts and strict current/ignorable future-event decoding outcomes |
@@ -107,7 +107,7 @@ Server-only optional application runtime. See the
 | `defineStateSlot` / `AgentStateSlotDefinition` / `AgentStateSlotStore` / `AgentStateSlotValue` / `AnyAgentStateSlot` / `createAgentStateSlotStore` / `renderAgentStateSlots` | functions / _types_ | typed durable state written as ledger events and injected on every provider request |
 | `agentGoalStateSlot` / `agentTodoStateSlot` / `createAgentStateTools` | constants / function | built-in goal/todo state and bound `goal_*` / `todo_write` Agent tools |
 | `AgentSandboxGradeSchema` / `AgentSandboxGrade` / `AgentSandboxRestrictionSchema` / `AgentSandboxRestriction` / `AgentProcessSandbox` | schema / _type_ | host-provided process sandbox capability and explicit restriction vocabulary |
-| `probeAgentProcessSandbox` / `missingSandboxRestrictions` / `recordAgentSandboxProbe` | functions | process-cached probe, fail-closed required-gap calculation and durable probe record |
+| `probeAgentProcessSandbox` / `missingSandboxRestrictions` / `recordAgentSandboxProbe` | functions | probe cached per sandbox object (keep the sandbox long-lived), fail-closed required-gap calculation and durable probe record; a probe that throws or returns no valid grade resolves to `unavailable` with a fixed reason, its cause emitted as a process warning (the coding tools instead carry it as the refusal's `cause` to the mount's `onToolError` hook) |
 | `AgentSandboxProcess` / `AgentSandboxOutputStream` | _types_ | structural child/output interface for optional lifecycle-owned `AgentProcessSandbox.spawn`, without Node ambient type dependencies |
 | `AgentEventSearchResultSchema` / `AgentEventSearchResult` / `createSqliteAgentEventSearch` / `createAgentEventSearchTools` | schema / _type_ / functions | authorized FTS5 search with exact event addresses and `session_*` tools |
 | `createSqliteAgentSpillStore` | function | durable content-address-checked artifact storage, bounded read/search, retention facts and archive participation |

package/llms/agent-runtime.txt

@@ -13,15 +13,6 @@ Parts of this slice:
 # Guide: Agent application runtime  (docs/guide/agent-runtime.md)
 ==============================================================================
 
----
-title: "Agent application runtime"
-description: Configure Stitchkit's optional durable history, stream loop, run coordination and managed-tool fencing.
-type: architecture
-status: active
-created: 2026-08-22
-updated: 2026-10-02 16:28 +07:00
----
-
 # Agent application runtime
 
 > **Maturity: evolving.** This surface is still finding its shape and may be

package/llms/application.2.txt

@@ -278,15 +278,6 @@ boundary is required. Send and projection callbacks own their external deadlines
 # Guide: Application migration recipes  (docs/guide/application-migration-recipes.md)
 ==============================================================================
 
----
-title: Application migration recipes
-description: Executable patterns for moving database, poller, queue and operational publishing lifecycle into the managed application kernel.
-type: architecture
-status: active
-created: 2026-08-24
-updated: 2026-10-04 13:28 +07:00
----
-
 # Application migration recipes
 
 These recipes are the migration companion to the
@@ -438,10 +429,10 @@ guard must refuse. Filesystem mutations made inside inbox transactions call
 `assertHeld` immediately before publication or cleanup.
 
 For `createFileStateStore`, remove `staleLockMs` and `retryMs` from configuration.
-`lockTimeoutMs` remains the acquisition budget. Timestamp age no longer revokes
+`lockTimeoutMs` is the acquisition budget. Timestamp age never revokes
 a live or unknown writer. Stop and verify old writers before recovering a legacy
-pid-only lock; do not invent owner metadata. Historical temporary files are no
-longer deleted by age. See the [durable intake contract](application-kernel.md#durable-process-facts-and-owner-notifications).
+pid-only lock; do not invent owner metadata. Temporary files are never
+deleted by age. See the [durable intake contract](application-kernel.md#durable-process-facts-and-owner-notifications).
 
 ## Long-running poller
 

package/llms/application.3.txt

@@ -36,7 +36,7 @@ cutovers are covered by the executable
 | `NotificationOutboxItem` / `NotificationOutboxReceipt` / `NotificationOutboxState` / `NotificationSend` / `NotificationFailureClassification` / `DroppedNotification` / `EnqueueNotification` | _type_ | versioned queue records, stable send identity and delivery decisions |
 | `notificationOutboxStateSchema` | function | strict persisted-state schema over an application payload schema |
 | `notificationOutboxResource` / `NotificationOutboxResource` / `NotificationOutboxResourceConfig` | function / _type_ | thin managed-resource scheduler over an outbox handle |
-| `createDirectoryInbox` (from `stitchkit/application/directory-inbox`) / `DirectoryInbox` / `DirectoryInboxConfig` / `DirectoryInboxDelivery` / `DirectoryInboxResource` | function / _type_ | one managed directory inbox for files or durable `accept({ source, key, entry })`; first payload wins, bounded capacity/bytes/receipts and renewable fenced leases; delivery begins after readiness and effects remain at least once |
+| `createDirectoryInbox` (from `stitchkit/application/directory-inbox`) / `DirectoryInbox` / `DirectoryInboxConfig` / `DirectoryInboxDelivery` / `DirectoryInboxResource` | function / _type_ | one managed directory inbox for files or durable `accept({ source, key, entry })` (`entry` is the schema's input, stored as given); a hard-linked file is set aside as `invalid`; first payload wins, bounded capacity/bytes/receipts and renewable fenced leases; delivery begins after readiness and effects remain at least once |
 | `DirectoryInboxIdentitySchema` / `DirectoryInboxIdentity` / `DirectoryInboxAccept` / `DirectoryInboxAcceptResultSchema` / `DirectoryInboxAcceptResult` | schema / _type_ | validated source/key, typed entry and durable accepted/duplicate result with filename; duplicates do not replace the first payload |
 | `StateStoreUpdateContext` | _type_ | real active protected transaction: `assertHeld()` refuses after ownership loss or completion; custom adapters supply this context to their transition |
 | `DirectoryInboxStateSchema` / `DirectoryInboxState` / `DirectoryInboxRejection` / `DirectoryInboxRejectionReasonSchema` / `DirectoryInboxRejectionReason` | schema / _type_ | the inbox's claims, receipts and rejections (`invalid`, `too-large`, `attempt-limit`) |
@@ -122,9 +122,10 @@ cutovers are covered by the executable
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createDiagnosticJournal` | function | create one schema-owned FIFO JSONL writer with bounded retained memory, exclusive local path ownership and finite rotation |
-| `DiagnosticJournalConfig` / `DiagnosticJournal` | _type_ | owner schema/path/limits/failure observer and the synchronous `submit`, bounded-wait `flush`/`close`, status handle |
+| `DiagnosticJournalConfig` / `DiagnosticJournal` | _type_ | owner schema/path/limits/failure observer, `startupScan` (`tails` by default, or `full`), `onStartupRefusal` (`quarantine` by default, or `fail`) and the synchronous `submit`, bounded-wait `flush`/`close`, status handle |
 | `DiagnosticJournalLimitsSchema` / `DiagnosticJournalLimits` | schema / _type_ | positive event, pending-item, pending-byte, file-byte and retained-file limits |
 | `DiagnosticJournalLockPolicySchema` / `DiagnosticJournalLockPolicy` | schema / _type_ | `refuse` (default) or `reclaim-stale`, which reclaims only a lock whose recorded owner is provably gone |
+| `DiagnosticJournalStartupScanSchema` / `DiagnosticJournalStartupScan` | schema / _type_ | how much of the retained generations opening a journal reads: `tails` (default) checks only the end of each file for a torn line, `full` parses every line |
 | `readDiagnosticJournalLockDiagnosis` / `DiagnosticJournalLockDiagnosis` | function / _type_ | why a `reclaim-stale` acquisition refused — attribution, PID liveness and optional process `identity` evidence (`matched`, `different-boot`, `reused-pid`, `pid-gone`, `legacy`, `unavailable`) — read off the thrown `EEXIST` |
 | `DiagnosticJournalSubmitResultSchema` / `DiagnosticJournalSubmitResult` | schema / _type_ | accepted epoch/sequence or explicit invalid, oversized, capacity, closed or failed refusal |
 | `DiagnosticJournalStatusSchema` / `DiagnosticJournalStatus` | schema / _type_ | state, limits, exact admission/write/failure counters, pending ownership, rotations, partial tails and last safe sequences |
@@ -137,8 +138,10 @@ cutovers are covered by the executable
 | `DiagnosticJournalWaitOptions` / `DiagnosticJournalFailure` | _type_ | caller wait signal/timeout and isolated internal failure callback record |
 | `DiagnosticJournalAnomalySchema` / `DiagnosticJournalAnomaly` | schema / _type_ | corrupt-row reason, file, zero-based byte offset, one-based line, tail/interior position and skipped bytes |
 | `createDiagnosticJournalReadResultSchema` / `DiagnosticJournalReadResult` | function / _type_ | owner-schema frame output or explicit anomaly; retains transformed event output types |
-| `DiagnosticJournalRecoveryStatusSchema` / `DiagnosticJournalRecoveryStatus` | schema / _type_ | bounded startup inspection counts and first/last anomaly locations |
-| `DiagnosticJournalRecoveryError` | class | torn single-file startup refusal carrying recovery observations, preserving evidence and releasing its lock |
+| `DiagnosticJournalRecoveryStatusSchema` / `DiagnosticJournalRecoveryStatus` | schema / _type_ | bounded startup inspection counts, first/last anomaly locations and every quarantined file beside the journal (`quarantined`, this open's moves first with their `reason`, at most 32; `quarantinedUnlisted` counts the rest); evolving and `.strict()`, so every shape change is a breaking changelog item |
+| `DiagnosticJournalStartupRefusalPolicySchema` / `DiagnosticJournalStartupRefusalPolicy` | schema / _type_ | `quarantine` (default) renames a file opening cannot keep in place to `<file>.quarantined-<epoch>` and starts; `fail` throws and moves nothing |
+| `DiagnosticJournalStartupRefusalReasonSchema` / `DiagnosticJournalStartupRefusalReason` | schema / _type_ | `torn-without-retention-slot \| not-a-regular-file \| unreadable` |
+| `DiagnosticJournalRecoveryError` / `DiagnosticJournalRecoveryErrorOptions` | class / _type_ | typed startup refusal (`reason`, `file`, optional `recovery`, `quarantineFailed`) thrown under `fail` or when moving a file aside failed; preserves evidence and releases its lock |
 
 `accepted` is bounded in-memory admission and `written` is completed append, not `fsync` or durable
 delivery. Its filesystem reader is in the diagnostic-journal leaf; there is no managed replay/upload API. See the

package/llms/application.txt

@@ -13,15 +13,6 @@ Parts of this slice:
 # Guide: Managed application kernel  (docs/guide/application-kernel.md)
 ==============================================================================
 
----
-title: Managed application kernel
-description: Compose process-local resources, schedules, readiness, drain and optional provider adapters without building a second job platform.
-type: architecture
-status: active
-created: 2026-08-23
-updated: 2026-10-04 13:28 +07:00
----
-
 # Managed application kernel
 
 > **Maturity: evolving.** This surface is still finding its shape and may be
@@ -205,9 +196,8 @@ lifecycle context; the application decides when a database/provider probe runs.
 
 **A `reportHealth` call inside `start` is kept.** A resource that says nothing
 is assumed healthy once it is ready; one that reports its own health has already
-answered the question, and the answer stands. (It used to be overwritten — and
-the example above hides that, because `healthy` is the same value that
-overwrote it.)
+answered the question, and the answer stands. The readiness default never
+overwrites it.
 
 **Reporting the same health again is not a change.** A resource may confirm its
 health on a timer; a report with the value it already reported publishes
@@ -703,9 +693,48 @@ The caller owns file selection and coordination with an active rotator.
 Writer startup inspects retained and active files under its lock. On damage,
 `journal.getStatus().recovery` contains counts and first/last anomaly locations, reconstructed
 again on restart from the preserved bytes. This describes startup observations, not live
-continuous inspection. `maxFiles: 1` cannot preserve a torn active file by rotation and throws
-`DiagnosticJournalRecoveryError` before removing any evidence; configure at least two slots.
-Normal rotation retains the existing finite eviction policy. → [ADR 0219](../decisions/0219-journal-damage-is-data-and-io-failure-is-failure.md).
+continuous inspection. Normal rotation retains the existing finite eviction policy.
+→ [ADR 0219](../decisions/0219-journal-damage-is-data-and-io-failure-is-failure.md).
+
+A file opening cannot keep in place — a torn active file with `maxFiles: 1`, a generation name
+that is not a regular file, a retained file it cannot read — is renamed to
+`<file>.quarantined-<epoch>` beside it, and the journal starts (`onStartupRefusal: 'quarantine'`,
+the default). Nothing is deleted; quarantined files are outside retention and yours to remove.
+Every open lists them in `getStatus().recovery.quarantined` until you do: the ones it moved
+first, with their `reason`, then the ones earlier runs left, without one — at most 32, and
+`quarantinedUnlisted` counts the rest.
+A journal whose damage must stop the process — one that is a source of truth, not diagnostics —
+declares `onStartupRefusal: 'fail'` and gets a typed `DiagnosticJournalRecoveryError`:
+
+```ts
+import { DiagnosticJournalRecoveryError } from 'stitchkit/application'
+
+// A diagnostic journal: start, then say what is set aside.
+const journal = await createDiagnosticJournal({ ...config })
+const { quarantined = [], quarantinedUnlisted = 0 } = journal.getStatus().recovery ?? {}
+for (const entry of quarantined) {
+  // `reason` is present only for a file this start moved; an earlier run's has none.
+  internalLogger.warn({ file: entry.file, movedTo: entry.quarantinedAs, reason: entry.reason })
+}
+if (quarantinedUnlisted > 0) internalLogger.warn({ quarantinedUnlisted })
+
+// A journal that is a source of truth: refuse to start over damage.
+try {
+  await createDiagnosticJournal({ ...config, onStartupRefusal: 'fail' })
+} catch (error) {
+  if (error instanceof DiagnosticJournalRecoveryError) {
+    // error.reason: 'torn-without-retention-slot' | 'not-a-regular-file' | 'unreadable'
+  }
+  throw error
+}
+```
+
+A quarantining journal writes, so the managed resource that owns it reports `healthy`, and its
+dependants read `recovery` from the value they `use()`. There is no degraded journal: the kernel
+degrades only optional resources, and a required resource cannot depend on one.
+`DiagnosticJournalRecoveryStatusSchema` is evolving and `.strict()`; if you embed it in your own
+protocol, every change to its shape is listed under breaking changes.
+→ [ADR 0240](../decisions/0240-a-diagnostic-journal-quarantines-what-it-cannot-keep.md).
 
 Shutdown performs one phase barrier at a time: stop admission everywhere,
 cancel future schedules, drain admitted work, then close in reverse stable

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,12 +16,27 @@ 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.
-Companion mode places an external addon 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`.
+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;
+`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. 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 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 |
+| `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