stitchkit 0.114.2 → 0.116.0

package/llms/{upgrading-0.79.0-0.103.13.txt → upgrading-0.84.0-0.104.0.txt}

@@ -1,14 +1,135 @@
-# Upgrading 0.79.0 → 0.103.13 — stitchkit docs slice
+# Upgrading 0.84.0 → 0.104.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.79.0 → 0.103.13  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.84.0 → 0.104.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.79.0 → 0.103.13  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.84.0 → 0.104.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.104.0
+
+JS bundles carrying Darwin native capabilities also need the
+[delivery migration first affected in 0.103.13](#released-migration-010313).
+Consumers upgrading from 0.103.12 or earlier must apply it even if their TypeScript API is unchanged.
+
+### CLI runtime-tool construction
+
+**Who must act:** callers writing a schema-dependent handler or MCP/AI `present` directly
+inside an annotated `CliConfig.runtimeTools` or `CliInvokerConfig.runtimeTools` object.
+Native `commands` and values returned by `defineRuntimeTool` / `createRuntimeToolFactory`
+remain valid. Execution, auth, validation and the invocation result envelope keep their behavior.
+
+Construct a CLI-only managed definition with the neutral schema-aware type before registration:
+
+```ts
+import type { CliInvokerConfig, RuntimeToolExecutionWithOutput } from 'stitchkit/cli'
+import { z } from 'zod'
+
+const input = z.object({ text: z.string() })
+const output = z.object({ size: z.number() })
+// Before: handler receives the heterogeneous registry context.
+const config: CliInvokerConfig = {
+  name: 'app',
+  runtimeTools: [{
+    name: 'measure', description: 'Measure text',
+    identity: { serviceName: 'text', action: 'measure', method: 'POST' },
+    transports: ['CLI'], input, output,
+    handler: ({ input }) => ({ size: String(input.text).length }),
+  }],
+}
+// After: handler input and output derive from the construction schemas.
+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>
+const nextConfig: CliInvokerConfig = { name: 'app', runtimeTools: [measure] }
+```
+
+For a shared MCP/AI tool, construct the definition with `defineRuntimeTool` from
+`stitchkit/tools`, including its typed SDK `present` callbacks, then pass the returned value
+to `runtimeTools`. Install the corresponding SDK peers for that integration. A CLI-only
+consumer needs `stitchkit`, `zod` and its ordinary Node type tooling.
+
+`RuntimeToolExecution` names the heterogeneous registration contract. Call a registered
+operation through `createCli` or `createCliInvoker`; its erased handler input is `never`
+because the managed runner owns schema validation before execution. For a managed void
+definition, use `RuntimeToolDefinitionWithoutOutput<typeof input>`.
+
+### MCP construction, state stores and delivery
+
+**Who must act:** schema-dependent runtime tool literals written directly inside MCP mount
+configuration, MCP presenters returning malformed content or metadata, custom `StateStore`
+implementations, file-store consumers using retired lock
+options, broadcast consumers reading `halt` or retrying unknown send outcomes, and consumers
+that validate HTTP error envelopes with a closed schema. Applications collecting raw tool
+causes from `console.error` must configure an internal tool hook sink.
+
+MCP-only code can import the existing server factories from `stitchkit/tools/mcp` and
+construct its schema-aware tool before heterogeneous registration:
+
+```ts
+import { buildMcpServer, type RuntimeMcpToolDefinitionWithOutput } from 'stitchkit/tools/mcp'
+import { z } from 'zod'
+const input = z.object({ value: z.number() })
+const output = z.object({ doubled: z.number() })
+// Before: runtimeTools: [{ input, output, handler, present }]
+const double = {
+  name: 'double', description: 'Double a number',
+  identity: { serviceName: 'numbers', action: 'double', method: 'POST' },
+  input, output,
+  handler: ({ input }) => ({ doubled: input.value * 2 }),
+  present: { mcp: ({ doubled }) => ({ content: [{ type: 'text', text: String(doubled) }] }) },
+} satisfies RuntimeMcpToolDefinitionWithOutput<typeof input, typeof output>
+const server = buildMcpServer({ serverInfo: { name: 'numbers', version: '1' }, services: [], runtimeTools: [double] })
+```
+
+Full MCP/AI integrations keep `defineRuntimeTool` from `stitchkit/tools`; those typed values
+remain accepted by the MCP leaf and CLI. The leaf requires the MCP SDK and Zod, with no AI peer.
+
+`RuntimeMcpPresentation` preserves the official SDK's required `content` and typed `_meta`
+fields. A presenter returning `{}` must return `{ content: [] }`; text blocks require string
+text, and metadata must be an object. `structuredContent` and `isError` remain framework-owned.
+This restores SDK checks that an indexed mapped type previously erased.
+
+Unexpected tool causes remain in `hooks.onToolError` and the `error` field of
+`hooks.afterToolCall`. Protocol stderr carries safe errors. MCP resolver failures use those
+same observers without executing the handler or its lifecycle again. HTTP's default
+unexpected-error logging retains its behavior.
+
+A custom state adapter's `update` must invoke `transition(current, context)` while it still
+owns the serialized transaction. `context.assertHeld()` checks the actual transaction or lock
+generation and refuses after completion, rollback or ownership loss. A no-op guard cannot
+satisfy this contract. Existing transition callbacks may keep one parameter. For the owning
+file adapter, replace `{ staleLockMs, retryMs, lockTimeoutMs }` with `{ lockTimeoutMs }`:
+the remaining budget controls acquisition waiting, never expiry of a live transaction.
+Unknown legacy PID locks and historical temporary files are preserved; recover them only
+after independently proving their owner is gone.
+
+Broadcast consumers change `report.halt.reason` checks to the closed `halt.kind` union:
+`retry-after`, `transient`, `permanent` or `ambiguous`. A custom MTProto adapter can classify
+an acknowledged flood refusal as `{ kind: 'retry-after', retryAfterMs: wait }`; the exact
+provider wait is respected. A wait over `maxRetryDelayMs` halts with the recipient pending.
+Unknown write outcome becomes `uncertain`; restarting the same broadcast does not send it
+again. A retry classification must certify that the attempt did not apply the external effect.
+
+HTTP errors gain optional boolean `error.retryable`; framed contract streams use the same
+field. Update closed consumer schemas before producers declaring it. `false` on 502 and
+`true` on 409 remain explicit recommendations through the remote tool path. An absent field
+retains prior status-derived defaults; the field does not change the HTTP client's retry policy.
+The existing seventh `ApiError` constructor argument remains `ErrorOptions`; retryability is
+the new eighth argument.
+
+Caller cancellation now reaches `implementRemote`'s existing HTTP call. Applications bind
+signals to `createCli` / `createCliInvoker` and cooperative handlers observe `ctx.signal`.
+`REQUEST_ABORTED` is nonretryable and exits 130. A disconnected caller does not prove that
+an origin ignoring cancellation or an external provider stopped; keep resource leases until
+that work actually completes.
+
 ## Released migration: 0.103.13
 
 ### Darwin native assets in JS distributions
@@ -884,181 +1005,3 @@ The workspace root is not asked about — it is the boundary the tools already o
 **3. The policy is called more often.** A path of depth N costs N+1 calls (`.`, then each ancestor,
 then the leaf), outermost first, stopping at the first refusal. A policy that logs or meters will
 see a different sequence, and will no longer see the leaf once an ancestor has refused.
-
-## Released migration: 0.83.0
-
-Two things, both mechanical, and only if you touch an observability sink.
-
-```bash
-rg -n "createObservability|createApplicationEventSink|createApplicationSnapshotSink|createAgentRuntimeEventSink|createAgentObservability"
-```
-
-**1. `flush()` returns `Promise<boolean>`.** `await sink.flush()` needs no
-change. Only a declared type does:
-
-```ts
-// before
-const flushAudit: () => Promise<void> = observability.flush
-// after
-const flushAudit: () => Promise<boolean> = observability.flush
-```
-
-**2. `ObservabilityDrainReport` carries `drained`.** The framework builds it, so
-reading code is unchanged. A hand-built report — a test double, or one persisted
-and re-parsed through `ObservabilityDrainReportSchema` — needs the field:
-
-```ts
-// before
-{ request, tools, total, durationMs }
-// after
-{ request, tools, total, durationMs, drained: true }
-```
-
-Then take the thing this release exists for. Every drain now accepts
-`{ timeoutMs?, signal? }`, so a shutdown can give the audit drain the same
-deadline it gives every other step:
-
-```ts
-const report = await observability.close({ timeoutMs: 5_000 })
-if (!report.drained) {
-  logger.warn('audit drain incomplete', {
-    unwritten: report.total.received - report.total.filtered - report.total.completed,
-  })
-}
-```
-
-The bound ends the **waiting**, not the writes: a sink's `write` is handed no
-cancellation, so an outstanding one keeps running against whatever you close
-next. Racing `close()` against your own timer looks equivalent and is not — it
-discards the report along with the wait.
-
-## Released migration: 0.82.0
-
-One thing, and only if you mount MCP or agent tools from a `createTrackingContract` contract.
-
-```bash
-rg -n "createTrackingContract"
-```
-
-The event ingest (`track`, `POST /events`) is now `expose: ['HTTP']`, which is
-what its sibling `bootstrap` always declared. Before, it declared nothing — and
-an endpoint with no `expose` is a tool on MCP and AGENT by default, so the
-mounted surface carried a `track_<prefix>` tool. Since this contract is built
-inside the framework, an application that had made every tool opt-in for the
-endpoints *it* authors could not have opted this one out.
-
-**If you pin a tool-surface digest or count**, it moves by one; re-record it.
-**If you assert on tool names**, `track_<prefix>` is gone. **If nothing in your
-project mounts tools from this contract**, there is nothing to do — the HTTP
-routes, the client and the schemas are unchanged.
-
-Un-declaring the tool was never the intent, so there is no option to keep it. If
-an agent in your system genuinely needs to record something, give it your own
-endpoint with your own schema: the browser ingest trusts a client-minted event
-id and a visit lease, and an agent holds neither.
-
-## Released migration: 0.81.0
-
-**Path literals own string params.**
-
-An endpoint whose path contains `:id` or a terminal `*rest` no longer needs a
-duplicate `params: z.object({ …string() })` declaration. Remove schemas that do
-nothing beyond repeating path names:
-
-```ts
-// before
-{ path: '/projects/:projectId/*filePath',
-  params: z.object({ projectId: z.string(), filePath: z.string() }) }
-
-// after
-{ path: '/projects/:projectId/*filePath' }
-```
-
-Keep an explicit schema when it validates or coerces. It must cover every name
-in the path — an explicit schema that misses one now fails at `defineContract`
-with the path and the missing field named. Client calls and handler contexts
-infer the string fields from the literal, so a call that omitted one becomes a
-compile error instead of building a URL with an unresolved segment. Measured
-across three consuming applications before release (373 endpoints with path
-segments), no explicit schema missed a field: the migration is deleting
-schemas that only repeated the path, or nothing.
-
-## Released migration: 0.80.0
-
-One thing, and only if you parse an async-operation snapshot.
-
-```bash
-rg -n "createAsyncOperationSnapshotSchema"
-```
-
-`progress` on a parsed snapshot used to be `unknown`. The factory built its
-object shapes with a conditional spread, and the narrowing inside it widened
-your schema back to a bare `ZodType`, so the emitted declaration threw the type
-argument away. It is now the output of the schema you configured.
-
-```ts
-const schema = createAsyncOperationSnapshotSchema({
-  progress: z.object({ done: z.number(), total: z.number() }),
-  failure: z.object({ code: z.string() }),
-})
-const snap = schema.parse(body)
-if (snap.phase === 'running') {
-  // before: `snap.progress` was `unknown` — this needed a cast or a narrow
-  // after:  it is `{ done: number; total: number } | undefined`
-  console.log(snap.progress?.done)
-}
-```
-
-**If you cast it**, delete the cast — it was working around the erased type.
-**If you assigned something else to it**, the compiler now refuses, and it was
-already a value the schema rejected at run time.
-
-**If you pass explicit type arguments**, the no-progress form takes one now, not
-two: the factory is two overloads. Pass none.
-
-```ts
-// before: createAsyncOperationSnapshotSchema<undefined, typeof Failure>({ failure: Failure })
-// after:  createAsyncOperationSnapshotSchema({ failure: Failure })
-```
-
-Nothing about parsing moves. A snapshot configured without `progress` still
-strips an unexpected `progress` rather than refusing it — that behaviour is why
-this is overloads and not one normalised key.
-
-**If you compile with `skipLibCheck: false`**, this is also the release that
-makes `stitchkit/tools/contract` compile at all: it carried five `TS2344`
-errors, one per phase, from the same conditional spread.
-
-## Released migration: 0.79.0
-
-One thing, and only if you assert on the whole snapshot.
-
-```bash
-rg -n "getSnapshot\(\)|projectApplicationStatus|status\(\)" --glob '*.test.ts' --glob '*.spec.ts'
-```
-
-`ApplicationSnapshot` and `ApplicationStatusProjection` each gained a
-`restarting` field — ids in the snapshot, a count in the projection. A reader
-that names the fields it wants is unaffected. A test that compares the whole
-object with `toEqual` fails until it adds the field:
-
-```ts
-// before
-expect(body).toEqual({ id, lifecycle: 'ready', /* … */ resources: { total: 1, ready: 1, degraded: 0, failed: 0 } })
-// after
-expect(body).toEqual({ id, lifecycle: 'ready', /* … */ resources: { total: 1, ready: 1, degraded: 0, failed: 0 }, restarting: 0 })
-```
-
-It is zero except while a restart is running, and then it names the subtree being
-replaced. That is the point: a snapshot taken mid-restart used to be
-indistinguishable from a resource that had failed on its own, so a dashboard read
-a planned replacement as an outage.
-
-**If you watch a hub across a restart**, nothing to change, but the behaviour is
-different and better: closing a hub now tells its subscribers `unavailable` /
-`source-unavailable` instead of dropping them, so a page stops showing a value
-that will never update again.
-
-**If you need a tool contract in a browser**, `stitchkit/tools/contract` now
-carries the async-operation helpers, its schemas and the view-file input/output
-without the runtime. `stitchkit/tools` still exports all of them.

package/llms/upgrading.txt

@@ -11,10 +11,10 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.104.0 → 0.114.0: `llms/upgrading-0.104.0-0.114.0.txt`
-- 0.79.0 → 0.103.13: `llms/upgrading-0.79.0-0.103.13.txt`
-- 0.62.0 → 0.78.0: `llms/upgrading-0.62.0-0.78.0.txt`
-- 0.44.0 → 0.61.0: `llms/upgrading-0.44.0-0.61.0.txt`
+- 0.105.0 → 0.116.0: `llms/upgrading-0.105.0-0.116.0.txt`
+- 0.84.0 → 0.104.0: `llms/upgrading-0.84.0-0.104.0.txt`
+- 0.63.0 → 0.83.0: `llms/upgrading-0.63.0-0.83.0.txt`
+- 0.44.0 → 0.62.0: `llms/upgrading-0.44.0-0.62.0.txt`
 - 0.37.0 → 0.44.0: `llms/upgrading-0.37.0-0.44.0.txt`
 
 # Upgrading stitchkit

package/llms-full.txt

@@ -78,13 +78,13 @@ 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 59 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 61 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, the managed-resource conformance kit and manual time for schedules and retries |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
 | `stitchkit/react/keyboard/testing` | server (Bun or Node) | evolving | the keyboard layers and zones without a DOM — fakes for the window, elements and key events beside the two engines, to test the order of layers, `scope`/`inert` and the edges of a zone in milliseconds |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 24 of the 59 minors since 0.56.2, most recently 0.113.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 25 of the 61 minors since 0.56.2, most recently 0.115.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 |
@@ -96,7 +96,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 59 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 61 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -5658,17 +5658,27 @@ approval input fails the run with a private diagnostic rather than starting a fr
 `read_output`. Every call passes a required host authorization callback. An optional async/sync
 `authorizePath({ path })` is the one operation-independent policy for direct file access and
 discovery: direct read/write/edit refuses a denied path, while listing, glob and search omit it.
-Denial is recursive on every surface — direct access and discovery base paths ask about `.` and each
-ancestor, outermost first, stopping at the first refusal, so denying `credentials` denies everything
+Denial is recursive on every surface — direct access asks about each named ancestor and the file,
+outermost first, stopping at the first refusal; discovery rooted at `.` also asks about `.`.
+Thus denying `credentials` denies everything
 under it. The comparison is segment-wise, so it does not deny `credentials-backup`, and a path of
-depth N costs N+1 questions. Directory decisions happen before descent; file decisions and
+depth N costs N questions for direct access. Directory decisions happen before descent; file decisions and
 `search_files.include` happen before opening content. Requested paths use `/`: a backslash is
 refused rather than normalised, because the workspace walk reads it as a separator and every
 authorization callback would otherwise be asked about a different decomposition than the one opened. File paths are relative, bounded and contained after
-descriptor-relative resolution: each ancestor is opened without following symlinks and remains
-pinned through authorization and the filesystem effect. Reads revalidate the pinned file identity;
+descriptor-relative resolution: each ancestor is opened without following symlinks. Reads and edits
+stay pinned through authorization; `write_file` plans before it and opens the parent after, because
+the parent it creates does not exist yet. Reads revalidate the pinned file identity;
 writes and patches revalidate the pinned parent identity; search and resource discovery descend
-only through opened directories. Linux traverses `/proc/self/fd`; macOS uses the package's
+only through opened directories. A path that changed during authorization refuses with `CONFLICT`.
+A path spelled differently from the name stored on disk refuses before any policy reads it, so on a
+case-insensitive volume a rule on `credentials` cannot be passed by asking for `CREDENTIALS`.
+NUL bytes are refused before either host policy sees a path.
+Reads and edits open file candidates without blocking on special files, then require a regular
+file. A writerless FIFO therefore refuses instead of occupying a filesystem worker. `write_file`
+supplies the exact missing-directory plan as `createsDirectories` to host authorization; the
+descriptor walk may create only those entries. An ancestor that disappears after approval refuses
+with `CONFLICT`, without expanding that plan. Linux traverses `/proc/self/fd`; macOS uses the package's
 architecture-specific Node-API `openat` backend. Unsupported platforms, including FreeBSD until a
 real backend is qualified, fail closed. The package needs no install-time compiler or script.
 Other platforms fail these filesystem operations closed because Node exposes no equivalent
@@ -9072,8 +9082,8 @@ a static loader enters a bundle.
 
 Only these calls load the addon, and only on macOS: process identity (`observeProcessInstance`
 and `probeProcessOwner`), every exclusive lock (`withExclusiveLock` and what is built on it, such
-as the file state store and the diagnostic journal) and the contained file operations of the Agent
-coding tools. Without the addon a lock still works, but it cannot record or check its owner's
+as the file state store and the diagnostic journal), the contained file operations of the Agent
+coding tools and `--output-dir` downloads of `stitchkit/cli`. Without the addon a download refuses, and a lock still works, but it cannot record or check its owner's
 identity, so a lock held by a crashed owner is not reclaimed. The managed file boundary
 (`createManagedFileBoundary` and the transfer tools built on it), atomic writes and the chunk
 spool never load it, on any operating system. The package is free of import side effects
@@ -10415,6 +10425,29 @@ myapp generate "a fox" --wait --output-dir ./out
 myapp generate "a fox" --wait --json > result.json &
 ```
 
+### Download filesystem boundary
+
+`--output-dir` resolves the explicitly configured root once before fetching and pins that
+one directory for the whole batch. An initial root alias (including a symbolic link) selects
+its canonical directory; missing components are created through pinned parents. The root
+capability continues to name the same directory if another actor renames it or replaces its
+pathname. The original spelling printed in `saved` is a display path, not a re-open of the root.
+
+Each media name becomes a direct child. Downloads atomically replace an existing file,
+symbolic link (including a dangling link), or hard link without changing the inode a link
+points to. An existing directory refuses replacement. Ordinary files retain their permission
+bits; new files use `0666 & ~umask`. Replacing writes a new file beside the old one, so it needs
+write permission on the directory, gives the file to the process user, replaces a read-only
+file, and refuses a bind-mounted one. Symlinks inside a contained parent path are never followed.
+The successful operation's JSON remains on stdout when a download fails; per-file diagnostics
+go to stderr and any failed file makes the exit non-zero. Already saved files remain saved.
+
+This filesystem protection supports Linux and macOS. On Linux it uses directory descriptors;
+on macOS it uses the packaged native backend. A bundled or compiled macOS CLI must use
+[`createNativePackaging`](./native-io.md) from `stitchkit/files/packaging` at build
+time. Missing native support and unsupported platforms, including Windows, refuse the download;
+CLI commands without downloads continue to work. There is no weaker path-based fallback.
+
 ## Aggregate views
 
 The CLI's audience is agents, scripts and `jq`, so output is JSON. That settles
@@ -10450,16 +10483,27 @@ myapp item_list --sort messages --top 5 --json                # the same five, a
 myapp item_list --sort name --ascending                       # ordered the other way
 ```
 
-Groups come back largest first for the same reason. A record that carries no
+Groups come back largest first for the same reason, in the printed bytes even when a key looks
+like a number; a reader that parses them into a JavaScript object reorders such keys itself.
+A string equal to `null` or `(absent)` is quoted, so it stays apart from the missing value. A record that carries no
 value for the sort field sorts **last in both directions**: it is not the
 smallest, it is not on the scale at all, and letting it lead an ascending list
 would answer a question nobody asked.
 
-Three rules worth knowing before you rely on them:
+Rules worth knowing before you rely on them:
 
-- **A field the result does not carry is a presentation error.** A group of zero
+- **A field no record carries in a nonempty collection is a presentation error.** A group of zero
   over a misspelled field is indistinguishable from a true empty answer, and the
   caller reads it as data. The message names the fields that *are* there.
+  Plain and dotted field paths read own properties only at every segment; inherited
+  properties are not record data. Own keys named `constructor`, `prototype` or `toString`
+  are ordinary fields.
+- **An empty collection is a successful answer.** Count and grouped sums return `{}`,
+  an ungrouped sum returns `0`, and sorted records return `[]`. Tables keep their header
+  and separator without data rows. This applies both to a direct `[]` and to the single
+  array field of an envelope such as `{ items: [], total: 0 }`. With no records, field
+  presence cannot be checked, so a misspelled field answers empty too; malformed paths, unsafe
+  `__proto__` segments and a field of the envelope itself (`--sum total` here) still refuse.
 - **An aggregate needs a collection** — the result itself when it is an array,
   or the single array field of a result object. An aggregate over a scalar, or
   over an object with two array fields, is refused rather than guessed.
@@ -15342,6 +15386,17 @@ together, only `scope` tells the stack which one is inside.
 **`active`** (default `true`) switches a layer off without unmounting it;
 becoming active again puts it on top of its kind.
 
+Layers register, adopt options and clean up in the browser's layout-effect phase.
+Call the hook before a layout effect that dispatches a key: that effect sees the
+committed `active`, handler and scope immediately, without waiting for passive
+effects. Rendering alone never changes the stack; an abandoned render leaves the
+last committed layer intact. A Suspense boundary that hides committed content
+disconnects its layout effects, so a layer behind the fallback goes quiet and
+returns to its place on reveal. The same lifecycle backs `useEscapeLayer` and a
+zone's outside-key layer. Server rendering installs no listener and does not
+access `window`. The browser phase is chosen when the module loads, so a test
+that installs a DOM does so before it imports these hooks.
+
 **Fields keep their keys.** Keys pressed in an input, a text area, a select, an
 editable region, a combobox, a slider or any area marked `data-local-keys` do not
 reach layers — except Escape, which a field that wants it keeps with
@@ -15393,6 +15448,11 @@ function ChatList({ chats, openId, open }) {
 | `ignore(event)` | — | a key that is the application's own right now — return `true` and the zone leaves it whole; see [dragging](#a-zone-inside-a-drag-and-drop-list) |
 | `onReveal(id)` | — | focus went to an item with no element yet — a row of a virtualized list outside the rendered range; scroll it in, and focus lands on it when it mounts |
 
+`role: 'none'` adds neither a container/item role nor `aria-orientation` or
+`aria-selected`; native links and buttons keep their semantics. The orientation
+still controls which arrows move focus. Only listbox and tablist zones emit
+`aria-orientation` (vertical by default).
+
 The callbacks return `false` to leave the key to the page, anything else takes
 it. A key the zone does not take bubbles on to the layers — in a vertical list
 ← and → are not the list's keys, so the section switch above hears them.
@@ -15858,6 +15918,13 @@ cast, and a send cancelled in the queue then waits for its slot and fails as
   a follow-up call to action after an album costs one more. Reads and edits
   (`getMe`, `getFile`, `editMessage*`, `deleteMessage`, `sendChatAction`) do not
   spend the budget.
+- **Two lanes share one rate.** A call is `interactive` by default; a campaign passes
+  `{ lane: 'bulk' }` to `run` or `acquire`, or installs
+  `telegramBudgetTransformer(budget, { lane: 'bulk' })` on its own `Api`. A waiting
+  interactive call is granted first, so a reply never queues behind recipients;
+  the wait it can still see is the interval of the grant before it, up to one
+  album. Bulk runs at whatever rate replies leave, and the sum never exceeds
+  `messagesPerSecond`.
 - **The first send after idle is immediate; the rest are spaced.** This is a
   strict budget, not a bucket that saves a burst: at 24/s the next send is due
   one interval later. A 429 pauses the whole token; when it resumes, one send
@@ -15869,8 +15936,8 @@ cast, and a send cancelled in the queue then waits for its slot and fails as
   The refusal may be thrown or returned: a client transformer sits below the
   place where grammY turns Telegram's `{ ok: false, error_code: 429, … }` body into
   a `GrammyError`, so `run` reads that body too and hands it back unchanged.
-  A 429 from an edit or a read is still a fact about the token and pauses later
-  sends too. A network failure is rethrown unchanged and stays `unknown`; a 5xx
+  A 429 from an edit or a read concerns that call and pauses nothing; `budget.pauseAfter`
+  remains for a caller who decides otherwise. A network failure is rethrown unchanged and stays `unknown`; a 5xx
   is rethrown unchanged and stays `server-error`. Neither is retried by the
   budget or pauses the token — repeating a send whose outcome is unknown is a
   decision, not a primitive's silent guess.
@@ -16728,6 +16795,88 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.116.0
+
+### send-only-telegram-pause
+
+**Who must act:** code that relied on a 429 from `editMessage*`, `deleteMessage` or a read to stop a
+token's sends. Code that only sends needs no change.
+
+`run` pauses the token only on a method that spends the budget
+([ADR 0277](../decisions/0277-a-telegram-budget-serves-replies-first.md)). Where an edit must still stop
+the sends, say so:
+
+```ts
+// before
+await budget.run('editMessageText', payload, signal, send)
+// after
+await budget.run('editMessageText', payload, signal, send).catch((error) => {
+  budget.pauseAfter(error)
+  throw error
+})
+```
+
+Search pattern: `budget.run` next to edit and read methods.
+
+## Released migration: 0.115.0
+
+### contained-cli-downloads
+
+**Who must act:** a CLI that uses `--output-dir` on Windows, from a macOS bundle or compiled binary
+built without `createNativePackaging`, into a directory it cannot write or over bind-mounted files;
+a coding-tools host that allows `edit` but refuses `read` for a path; and code or CSS that reads
+`aria-orientation` of a `role: 'none'` zone. A CLI writing into its own directory on Linux or
+unbundled macOS, and every CLI command without a download, need no change.
+
+`--output-dir` now writes through a pinned directory descriptor
+([ADR 0276](../decisions/0276-a-download-writes-through-its-root-capability.md)). There is no
+path-based fallback, so a platform without that backend refuses the download: the operation still
+succeeds, its result stays on stdout, stderr names the refusal and the exit is non-zero.
+
+1. On macOS, build a bundled or compiled CLI with the native packaging plugin:
+
+   ```ts
+   // before
+   await Bun.build({
+     entrypoints: ['src/cli.ts'],
+     compile: { target: 'bun-darwin-arm64', outfile: 'dist/cli' },
+   })
+   // after
+   import { createNativePackaging } from 'stitchkit/files/packaging'
+
+   const native = createNativePackaging({
+     platform: 'darwin', architecture: 'arm64', delivery: 'embedded',
+   })
+   if (native.state !== 'ready') throw new Error(native.code)
+   await Bun.build({
+     entrypoints: ['src/cli.ts'],
+     compile: { target: 'bun-darwin-arm64', outfile: 'dist/cli' },
+     plugins: [native.plugin],
+   })
+   ```
+
+   A JS bundle uses `delivery: 'companion'`; every shape is in the [native I/O guide](./native-io.md). Search pattern:
+   `createCli` with a `download` option in a project that runs `bun build` for macOS.
+2. On Windows, run the download through Linux or macOS, or read the URLs from the operation's
+   JSON result and fetch them yourself. Stitchkit offers no weaker path on that platform.
+3. A download now replaces a file rather than rewriting it. Give the process write permission on
+   the output directory, and do not point it at a bind-mounted file: that refuses with `EBUSY`. A
+   replaced file belongs to the process user, and a read-only file is replaced like any other.
+4. Read the orientation you configured. A zone with `role: 'none'` has no attribute, and a default
+   would silently turn a horizontal zone vertical:
+
+   ```ts
+   // before
+   const axis: ZoneOrientation = zone.zoneProps['aria-orientation']
+   // after
+   const axis: ZoneOrientation = options.orientation ?? 'vertical'
+   ```
+
+   Search pattern: `aria-orientation` next to `useNavZone`, and `[aria-orientation]` in CSS and
+   test selectors. Type-check: a read typed as `ZoneOrientation` fails to compile.
+5. In a coding-tools `authorize`, answer `read` for every path you answer `edit` for. `edit_file`
+   asks both, `read` first.
+
 ## Released migration: 0.114.0
 
 **Who must act:** code with an exhaustive `switch` or `Record` over
@@ -23711,7 +23860,7 @@ injected grammY bot. → ADR 0143, ADR 0201, ADR 0274 — [guide](../guide/teleg
 | `TelegramFetch` / `TelegramBotTransportOpen` / `TelegramBotTransportResolve` / `TelegramBotTransportSocket` | _types_ | the `(url, init) => Promise<Response>` the senders take; the transport's socket factory, resolver and the structural socket it needs (a Node `net.Socket` or `tls.TLSSocket` fits) |
 | `TelegramNotDispatchedError` / `TelegramNotDispatchedStage` | class / _type_ | a request that provably never left (`lookup`, `connect` or `request`), so repeating it cannot duplicate a message |
 | `TelegramSendFailureReason` / `TELEGRAM_SEND_FAILURE_REASONS` | _type_ / constant | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `bot-to-bot-disabled` / `rate-limited` / `message-invalid` / `server-error` / `not-dispatched` / `unknown`, and the same as a list; a `Record<TelegramSendFailureReason, …>` over them fails to compile when a reason is added |
-| `telegramOutboundBudget` / `TelegramOutboundBudget` / `TelegramOutboundBudgetConfig` / `TelegramOutboundBudgetStats` | function / _type_ | one token-wide outbound budget: one object per token in the process, strict 24 messages/s by default, weighted albums and multi-message copies, `run(method, payload, signal, send)` as the transformer adapter (a 429 pauses the token whether `send` throws it or resolves with the Bot API's `{ ok: false, … }` body), `pause`/`pauseAfter` for 429, `waitUntilResumed` for non-send retries and `stats`; it paces and never retries, and no public value carries the token |
+| `telegramOutboundBudget` / `TelegramOutboundBudget` / `TelegramOutboundBudgetConfig` / `TelegramOutboundBudgetStats` / `TelegramOutboundCallOptions` / `TelegramOutboundLane` | function / _type_ | one token-wide outbound budget: one object per token in the process, strict 24 messages/s by default, weighted albums and multi-message copies, an `interactive` lane granted before `bulk`, `run(method, payload, signal, send, { lane })` as the transformer adapter (a 429 on a send pauses the token whether `send` throws it or resolves with the Bot API's `{ ok: false, … }` body), `pause`/`pauseAfter` for 429, `waitUntilResumed` for non-send retries and `stats`; it paces and never retries, and no public value carries the token |
 | `runTelegramBroadcast` | function | a resumable broadcast by `name` under a state `directory`: audience and journal durably recorded, pacing at `ratePerSecond` (25), exact retry delays within the finite declared budget, injected classifier, uncertain send outcomes never replayed, `dryRun`, one fenced runner per name |
 | `TelegramBroadcastConfig` / `TelegramBroadcastSend` / `TelegramBroadcastReport` / `TelegramBroadcastRunOutcome` / `TelegramBroadcastOutcome` / `TelegramBroadcastRecipient` | _type_ | `name`, `directory`, `recipients()`, `send({ recipient, attempt })`, `maxAttempts`, `signal`, `onProgress`; counts `delivered` / `unreachable` / `failed` / `uncertain` / `pending` and `finished` / `stopped` / `halted` / `dry-run` |
 | `TelegramBroadcastFailureSchema` / `TelegramBroadcastFailure` | schema / _type_ | injected `classify` answers retry-after/transient/permanent/ambiguous; exact provider delay is bounded by `maxRetryDelayMs` without shortening, unknown outcome remains uncertain and is never replayed |
@@ -24193,9 +24342,9 @@ no component, no styles, no router — see the [keyboard guide](../guide/keyboar
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `useKeyLayer` | hook | put a layer on the window's one key stack — asked `overlay` → `local` → `route` → `zone` → `global`, innermost first within a kind |
+| `useKeyLayer` | hook | put a layer on the window's one key stack; registration, options and cleanup follow the browser layout-effect phase, before later layout effects in the caller; asked `overlay` → `local` → `route` → `zone` → `global`, innermost first within a kind |
 | `useEscapeLayer` | hook | an `overlay`, `local` or `route` layer for Escape: one press closes one level |
-| `useNavZone` | hook | a list zone — roving tab stop, arrows move DOM focus, select, highlight or focus mode, cross-axis enter/exit, boundaries, `ignore` for a key the application is using; props carry no key without a value |
+| `useNavZone` | hook | a list zone — roving tab stop, arrows move DOM focus, select, highlight or focus mode, cross-axis enter/exit, boundaries, `ignore` for a key the application is using; props carry no key without a value; `role: 'none'` omits roles, `aria-orientation` and `aria-selected`, preserving native link/button semantics |
 | `nextZoneIndex` | function | where a move lands in a list of a given length: an index, `'before-start'` or `'after-end'` |
 | `isKeyFieldTarget` | function | whether a key was pressed in a field or a `data-local-keys` area, the test layers use |
 | `KeyLayerOptions` | _type_ | `kind`, `onKey`, `active`, `scope`, `fields`, `phase` — `'capture'` is for a `local` layer only: it hears a key before the element that has focus does, as a menu over a text field must, and a key it takes goes no further |