stitchkit 0.104.1 → 0.105.0

package/llms/{upgrading-0.81.0-0.104.0.txt → upgrading-0.95.0-0.105.0.txt}

@@ -1,14 +1,421 @@
-# Upgrading 0.81.0 → 0.104.0 — stitchkit docs slice
+# Upgrading 0.95.0 → 0.105.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.81.0 → 0.104.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.95.0 → 0.105.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.81.0 → 0.104.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.95.0 → 0.105.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.105.0
+
+### CLI publication has its own entrypoint
+
+**Who must act:** code that imports `publishCli`, `CliPublicationOptions`, `CliPublicationPhase` or
+`CliPublicationResult` from `stitchkit/cli`. Everything else in `stitchkit/cli` — `createCli`, the
+manifest schemas, signatures, `renderCliInstaller` and the updater — is unchanged.
+
+`publishCli` is release infrastructure, so it now ships from the evolving entrypoint
+`stitchkit/cli/publish` instead of the stable `stitchkit/cli`
+([ADR 0245](../decisions/0245-cli-publication-is-an-evolving-leaf.md)). Its options, result and
+behaviour are the same.
+
+1. Move the publication names to the new specifier; keep every other CLI import where it is:
+
+   ```ts
+   // before
+   import { publishCli, type CliPublicationOptions, verifyCliManifest } from 'stitchkit/cli'
+   // after
+   import { verifyCliManifest } from 'stitchkit/cli'
+   import { publishCli, type CliPublicationOptions } from 'stitchkit/cli/publish'
+   ```
+
+   Search pattern: `\b(publishCli|CliPublication(Options|Phase|Result))\b` in files that import
+   from `'stitchkit/cli'`.
+2. Type-check: an import left on `stitchkit/cli` fails with "has no exported member".
+3. `stitchkit/cli/publish` is evolving: read its breaking entries in each minor you upgrade across.
+
+### a command stops by its `stop` policy
+
+**Who must act:** callers of `runNativeCommand` (`stitchkit/process`) that pass `killGraceMs`.
+Callers that omit it need no change: the default stop is the same TERM to the group, 100 ms, KILL.
+
+1. Replace `killGraceMs: N` with a group stop of the same grace:
+
+   ```ts
+   // before
+   await runNativeCommand({ executable, args, signal, killGraceMs: 500 })
+   // after
+   await runNativeCommand({ executable, args, signal, stop: { target: 'group', graceMs: 500 } })
+   ```
+
+   Search pattern: `killGraceMs:\s*(\d[\d_]*)` → `stop: { target: 'group', graceMs: $1 }`.
+2. If your own wrapper signals only the leader and waits a long grace (cooperative cancellation),
+   replace it with `stop: { target: 'leader', signal: 'SIGINT', graceMs }` (up to one hour). Pass
+   `killOn` with your shutdown signal so an application that stops sooner kills the group first.
+3. The result of a stopped command rejects once the group is gone, up to `graceMs` plus
+   `cleanupTimeoutMs` after the abort; size your caller deadlines on that sum.
+
+### a command stops what its leader left
+
+**Who must act:** callers of `runNativeCommand` (`stitchkit/process`) whose command starts a helper
+in its own process group that must keep running after the command returns. A daemon that detaches
+with `setsid` (as `daemon(3)` does) is not in the group and needs
+no change.
+
+`descendants` now defaults to `'terminate-after-leader'`
+([ADR 0246](../decisions/0246-a-command-stops-its-descendants-by-default.md)): when the leader
+exits, the members it left in the group are stopped by the command's `stop` policy before the
+pipes drain.
+
+1. Find the commands that start a background helper on purpose (a `&` in a shell script, a spawned
+   child the leader does not wait for) and declare `'leave'` on them:
+
+   ```ts
+   // before
+   await runNativeCommand({ executable, args, timeoutMs })
+   // after
+   await runNativeCommand({ executable, args, timeoutMs, descendants: 'leave' })
+   ```
+
+2. Remove an explicit `descendants: 'terminate-after-leader'`, or keep it: it is now the default.
+3. A command whose helper inherited stdout or stderr used to wait for that helper until its
+   deadline. It now completes when the leader exits; drop a workaround that killed the helper from
+   `onLeaderSettled`.
+
+### native packaging verifies published digests
+
+**Who must act:** build scripts that call `createNativePackaging` (`stitchkit/files/packaging`) and
+read `asset.sourcePath`, hash the addon themselves, switch over the refusal `state`/`code`, pass a
+`platform` other than the literal `'darwin'`, or parse `node_modules/stitchkit/native-assets.json`.
+
+The package now publishes the `size` and SHA256 of each Darwin addon, computed when Stitchkit is
+built, in `native-assets.json` at `formatVersion: 2`. `createNativePackaging` reads each selected
+addon once, compares it with that digest and returns the verified bytes. An installed addon that
+differs refuses with `NATIVE_ASSET_DIGEST_MISMATCH`.
+
+1. Replace every read of `asset.sourcePath` with `asset.bytes`, and delete your own re-hash of the
+   addon: the result's `sha256` is the published digest and `bytes` already match it.
+
+   ```ts
+   // before
+   const bytes = readFileSync(asset.sourcePath)
+   if (createHash('sha256').update(bytes).digest('hex') !== asset.sha256) throw …
+   copyFileSync(asset.sourcePath, destination)
+   // after
+   writeFileSync(destination, asset.bytes)
+   ```
+
+2. Handle the third refusal. A `switch` over `result.state` gains `'mismatch'`
+   (`code: 'NATIVE_ASSET_DIGEST_MISMATCH'`); treat it as a failed build, never as a missing addon.
+   It carries the differing `architecture` with `expected` (published) and `actual` (installed)
+   `{ size, sha256 }`; log both pairs.
+3. Pass the target platform as the literal `'darwin'`. `platform` is a closed enum, so a free
+   string (a target name read from configuration, `process.platform`) no longer type-checks, and
+   another platform throws instead of returning `unsupported`. Skip packaging for non-Darwin
+   targets before the call:
+
+   ```ts
+   // before
+   const native = createNativePackaging({ platform: target.platform, architecture, … })
+   if (native.state === 'unsupported') return
+   // after
+   if (target.platform !== 'darwin') return
+   const native = createNativePackaging({ platform: target.platform, architecture, … })
+   ```
+
+   `unsupported` now means only an architecture the package has no addon for.
+4. Call `createNativePackaging` once per build and pass the result (its `assets` and `plugin`)
+   where it is needed. Each call reads and hashes the selected addons again.
+5. If you read `native-assets.json` directly, read `assets.<arch>.path`, `.size` and `.sha256`
+   instead of a bare path per architecture; an architecture with no entry is not published.
+
+### exclusive locks publish their owner first
+
+**Who must act:** callers of `withExclusiveLock` (`stitchkit/files`) that rely on a lock file with no
+readable owner being taken by age, and anything that puts lock files on a filesystem without hard
+links. Every other caller needs no change.
+
+A lock is now written to a private `.lock-<id>.tmp` file in the lock's directory, then hard-linked to
+the lock name. The name never exists without a complete owner record, so `ownerlessGraceMs` defaults
+to `null` instead of 5 000 ms: a lock file with no readable owner is never taken because of its age.
+
+1. If you depended on age-based reclaim of an empty lock file left by an older writer, opt in:
+
+   ```ts
+   // before: an empty lock older than 5 s was taken by default
+   await withExclusiveLock(path, run)
+   // after: say so; only legacy empty files need it
+   await withExclusiveLock(path, run, { ownerlessGraceMs: 5_000 })
+   ```
+
+2. Keep lock directories on a filesystem that supports hard links (local ext4, xfs, APFS and the
+   like). `link` failing with `EPERM` or `ENOTSUP` fails the acquisition.
+3. Expect a `.lock-*.tmp` sibling only after a holder was killed between writing its record and
+   publishing it. It is not a lock; the next reclaim in that directory removes the ones whose owner
+   is gone on this machine. Exclude the pattern from directory-size caps or backups if you have any.
+
+### one runtime-tool declaration
+
+**Who must act:** code that names `RuntimeToolExecution`, `RuntimeToolExecutionWithOutput`,
+`RuntimeMcpToolDefinition`, `RuntimeMcpToolDefinitionWithOutput` or `ToolSurfaceDefinition`; code
+that annotates a definition carrying `present` as `RuntimeToolDefinitionWithOutput<I, O>` from
+`stitchkit/tools`; imports of `stitchkit/agent-runtime/harness-tools`; code that compares agent
+control error codes; and callers that send a JSON array as text to a string-or-array tool field.
+Definitions returned by `defineRuntimeTool` / `createRuntimeToolFactory`, native CLI `commands` and
+contract tools need no change.
+
+A runtime tool now has one declaration, `RuntimeToolDefinitionWithOutput` /
+`RuntimeToolDefinitionWithoutOutput`, exported with the same name from `stitchkit/cli`,
+`stitchkit/tools` and `stitchkit/tools/mcp`. It carries no SDK type: the presenters are the adapter's
+extension, named as the fourth type argument. `RuntimeToolDefinition` is the one registration type.
+
+1. Replace each removed name.
+
+   | before | after |
+   |---|---|
+   | `RuntimeToolExecutionWithOutput<I, O>` (`stitchkit/cli`) | `RuntimeToolDefinitionWithOutput<I, O>` |
+   | `RuntimeToolExecution` (`stitchkit/cli`) | `RuntimeToolDefinition` |
+   | `RuntimeMcpToolDefinitionWithOutput<I, O>` (`stitchkit/tools/mcp`) | `RuntimeToolDefinitionWithOutput<I, O, undefined, RuntimeMcpToolPresenters<z.output<O>>>` |
+   | `RuntimeMcpToolDefinition` (`stitchkit/tools/mcp`) | `RuntimeToolDefinition` |
+   | `ToolSurfaceDefinition` (`stitchkit/tools`) | `ToolSurfaceProjection<RuntimeToolDefinition>` |
+
+2. In `stitchkit/tools`, a type that names a definition with presenters passes the presenter type:
+
+   ```ts
+   // before
+   const tool: RuntimeToolDefinitionWithOutput<typeof input, typeof output> = defineRuntimeTool({ …, present })
+   // after: let defineRuntimeTool infer it, or name the presenters
+   const tool = defineRuntimeTool({ …, present })
+   const named: RuntimeToolDefinitionWithOutput<typeof input, typeof output, undefined, RuntimeToolPresenters<z.output<typeof output>>> = tool
+   ```
+
+3. An inline handler in `runtimeTools: [...]` needs no wrapper: it is typed by the parsed object.
+   To type `input` from the schema, construct with `defineRuntimeTool` (or
+   `satisfies RuntimeToolDefinitionWithOutput<typeof input, typeof output>`) before registering.
+
+4. Replace `createAgentHarnessTools` (`stitchkit/agent-runtime/harness-tools`) with the call it made:
+
+   ```ts
+   // before
+   tools: createAgentHarnessTools(({ context }) => ({ services: [svc], context, lifecycle: auth }))
+   // after
+   import { composeToolLifecycle, mountAgent } from 'stitchkit/tools'
+   tools: ({ context, toolFenceLifecycle }) =>
+     mountAgent([svc], { context, lifecycle: composeToolLifecycle(auth, toolFenceLifecycle) })
+   ```
+
+5. Agent control codes: `ACCESS_DENIED` is `FORBIDDEN`, and `CONNECTION_CLOSED` is returned for a closed
+   connection. `AgentControlErrorCode` lists every code. `authorize` now runs once per request; after you
+   withdraw someone's access, call `binding.revoke(conversationId, matches?)` so an open stream is
+   re-authorized and ends with an `access-denied` delivery.
+
+6. A string-or-array field that receives `'["a","b"]'` now fails with `VALIDATION_ERROR` ("`paths` is a
+   list written as text"). Send the array itself. A string that is not a list the array member accepts
+   (`[preview].png`) is still one plain string.
+
+### flattened unions keep declaration order
+
+**Who must act:** consumers that use `flattenUnionInput: true` and keep snapshot tests, golden
+files or provider prompt caches of flattened tool schemas.
+
+A flattened union now lists its properties, enum values and branch labels in the order they first
+appear across the variants, not alphabetically. Declaration order often encodes priority, so the
+model now reads the order you wrote. Alternatives of different kinds (`anyOf`) keep their
+canonical order, independent of variant order.
+
+1. Regenerate every snapshot or golden file of a flattened tool listing (`buildToolManifest`,
+   `listToolNames`, MCP `tools/list`, Agent tool schemas) and review the diff: only ordering moves.
+2. Expect one provider prompt-cache miss per flattened tool after the upgrade.
+3. To keep an order you prefer, declare the variants and fields in that order.
+
+### connection limits are validated
+
+**Who must act:** callers that pass `timeoutMs` or `maxResponseBytes` to a connection and relied
+on an invalid value silently becoming the default.
+
+`stitchkit/tools/connections` throws a `RangeError` when `timeoutMs` is not a positive integer
+within timer range (at most 2 147 483 647) or `maxResponseBytes` is not a positive safe integer.
+Before 0.104.0 a value of 0, a negative number, a fraction or an out-of-range number fell back to
+the default without a message.
+
+```ts
+// Before: { timeoutMs: 0 } meant "use the default" by accident.
+// After: omit the option to take the default, or pass a real limit.
+{ timeoutMs: 30_000 }
+```
+
+### one canonical JSON serializer
+
+**Who must act:** tests that call `serializeSurfaceValue` from `stitchkit/testing`, and code that
+puts a value nested deeper than 100 levels into agent store events, archives or projections
+through `canonicalAgentJson`.
+
+`canonicalJson` from `stitchkit/primitives` is the package's one canonical serializer. It
+admits dense arrays, plain objects, strings, booleans, `null` and finite numbers; an `undefined`
+object member is omitted. It refuses everything else with a `CanonicalJsonError`, a `TypeError`
+whose `reason` says why: `'depth'`, `'nodes'` and `'bytes'` are the limits you set, while
+`'cycle'`, `'negative-zero'` and `'not-json'` say the value is not JSON data.
+
+`serializeSurfaceValue` is removed. It produced the same bytes without limits:
+
+```ts
+// Before
+import { serializeSurfaceValue } from 'stitchkit/testing'
+const text = serializeSurfaceValue(manifest)
+// After: the limits default to 100 levels, 100 000 nodes and 1 MiB; raise them for a large manifest
+import { canonicalJson } from 'stitchkit/primitives'
+const text = canonicalJson(manifest, { maxBytes: 16 * 1024 * 1024 })
+```
+
+`canonicalAgentJson` in `stitchkit/agent-runtime` is `canonicalJson` with the node and byte
+limits at their maximum. A value both accepted has the same bytes as before, so stored digests
+and archives still match: like `z.json()` before it, the store hashes `-0` as `0` and drops an
+own `__proto__` member (the public `canonicalJson` refuses `-0` and keeps `__proto__`). What
+changed is the refusal table: an `undefined` object member used to fail and is now omitted, and
+a value nested deeper than 100 levels is now refused.
+
+```ts
+// Before: canonicalAgentJson({ a: undefined }) threw a ZodError
+// After:  canonicalAgentJson({ a: undefined }) === '{}'
+//         canonicalAgentJson(nestedBeyond100Levels) throws CanonicalJsonError (reason 'depth')
+```
+
+### directory inbox entries
+
+**Who must act:** producers that drop hard links into an inbox directory, and callers that pass
+`accept` the output of a transforming schema.
+
+A file dropped into the inbox directory with more than one link is set aside as `invalid`
+(detail `managed file has multiple links`). Another name can still rewrite such a file after it
+was validated, so it is never trusted. Write each entry as its own regular file: a temporary
+name in the same directory, then a rename onto `<name>.json`.
+
+`accept` takes the schema's input type, stores that input as given and parses it with the
+schema on delivery. A schema without a transform has the same input and output type and needs
+no change. With a transform, pass the input:
+
+```ts
+const schema = z.object({ amount: z.string().transform(Number) })
+// Before: accept({ source, key, entry: { amount: 42 } })   // typed as the output; `z.string()` refused it
+// After:  accept({ source, key, entry: { amount: '42' } })  // delivered as { amount: 42 }
+```
+
+A name that is already in `rejected/` no longer stops the pass: identical bytes are the entry
+already set aside, different bytes are kept as `rejected/<name>.<16 hex digits>`.
+
+### journal startup scan
+
+**Who must act:** operators that read `status.recovery` right after `createDiagnosticJournal` to
+find damaged rows in the middle of a file.
+
+Opening a journal reads only the last line of the active file and of every retained
+generation (`startupScan: 'tails'`, the default). A crash tears the end of a file, so a torn tail
+is still reported and still rotated away, and opening no longer parses and validates every
+line of every generation. It still reads each file once in large blocks to count lines, so the time
+grows with the bytes retained, at read speed. Pass `startupScan: 'full'` to read and validate every line as before:
+
+```ts
+// Before: every open parsed every line of every generation.
+// After:  the same full scan, on request.
+const journal = await createDiagnosticJournal({ path, eventSchema, limits, startupScan: 'full' })
+```
+
+### journal startup quarantine
+
+**Who must act:** operators of a journal that is a source of truth and must not start over
+damaged retained files; code that constructs `DiagnosticJournalRecoveryError` or reads its
+`recovery`; protocols that embed `DiagnosticJournalRecoveryStatusSchema`, and their readers.
+A diagnostic journal needs no change.
+
+Opening a journal no longer refuses to start over a torn active file with `maxFiles: 1`, a
+generation name that is not a regular file or a retained file it cannot read. It renames the file
+to `<file>.quarantined-<epoch>` beside the journal, starts, and lists the move in
+`getStatus().recovery.quarantined`. Quarantined files are outside retention and never deleted;
+every later open lists them again, without a `reason`, until you remove them.
+
+1. A journal whose damage must stop the process declares the old behaviour:
+
+   ```ts
+   // Before: refusing was the only behaviour.
+   await createDiagnosticJournal({ path, eventSchema, limits })
+   // After:
+   await createDiagnosticJournal({ path, eventSchema, limits, onStartupRefusal: 'fail' })
+   ```
+
+2. Branch on the refusal's `reason` instead of its message or error class. Every startup refusal
+   about retained evidence is a `DiagnosticJournalRecoveryError`, including the former plain
+   `Error` for a non-file generation and the raw `EACCES` for an unreadable one (now in `cause`):
+
+   ```ts
+   // Before: catch (error) { if (error instanceof DiagnosticJournalRecoveryError) use(error.recovery) }
+   // After:
+   catch (error) {
+     if (error instanceof DiagnosticJournalRecoveryError && error.reason === 'torn-without-retention-slot') use(error.recovery)
+   }
+   ```
+
+   `recovery` is present only for `torn-without-retention-slot`. The constructor takes one
+   options object: `new DiagnosticJournalRecoveryError({ reason, file, recovery?, cause? })`.
+
+3. A protocol that embeds `DiagnosticJournalRecoveryStatusSchema` carries the new optional
+   `quarantined` array (at most 32 entries, `reason` optional) and `quarantinedUnlisted` count.
+   The schema is `.strict()`: upgrade every reader that parses it with its own copy before a
+   writer on this version sends a status with either field, or bump your protocol version.
+
+### error constructors take named options
+
+**Who must act:** code that constructs an `AppError` or an `ApiError` with anything beyond its
+code, and classes that extend `AppError` and call `super(code, message, status, …)`. Code that
+only throws the `notFound`, `badRequest`, `unauthorized`, `forbidden`, `conflict` and
+`rateLimited` helpers, or only reads `code`, `status`, `details`, `hint`, `traceId`,
+`retryable` and `cause` from a caught error, needs no change.
+
+`AppError` (`stitchkit/contract`, `stitchkit/server`, `stitchkit/node`) and `ApiError`
+(`stitchkit`) keep the code as the one positional argument. Every other value is a named
+option, so a call site reads without the signature open. `new AppError(code)` and
+`new ApiError(code)` are unchanged. The compiler finds every old call: a string or number
+in the second position is a type error.
+
+1. `AppError`: move `message`, `status`, `details`, `hint`, `traceId` and `retryable` into one
+   object after the code. `status` defaults to 500 and `message` to the code.
+
+   ```ts
+   // before
+   throw new AppError('CONFLICT', 'Selection is stale', 409, { revision: 7 })
+   throw new AppError('BUSY', 'Try later', 503, undefined, undefined, undefined, true)
+   // after
+   throw new AppError('CONFLICT', { message: 'Selection is stale', status: 409, details: { revision: 7 } })
+   throw new AppError('BUSY', { message: 'Try later', status: 503, retryable: true })
+   ```
+
+2. A subclass passes the same object to `super`:
+
+   ```ts
+   // before
+   super('FEATURE_LOCKED', 'locked', 403)
+   // after
+   super('FEATURE_LOCKED', { message: 'locked', status: 403 })
+   ```
+
+3. `ApiError`: the old order was `code, status, details, message, hint, traceId, errorOptions,
+   retryable`. Name each value; `status` defaults to 0 and the former `ErrorOptions` argument
+   is now the `cause` option.
+
+   ```ts
+   // before
+   new ApiError('RATE_LIMITED', 429, undefined, 'slow down', 'wait', 'trace-1', { cause }, true)
+   new ApiError('VALIDATION_ERROR', 0, { issues }, 'bad input')
+   // after
+   new ApiError('RATE_LIMITED', { status: 429, message: 'slow down', hint: 'wait', traceId: 'trace-1', retryable: true, cause })
+   new ApiError('VALIDATION_ERROR', { status: 0, details: { issues }, message: 'bad input' })
+   ```
+
+4. Both classes accept the standard `cause`, which `error.cause` returns; omit the option to
+   leave the property absent.
+
 ## Released migration: 0.104.0
 
 JS bundles carrying Darwin native capabilities also need the
@@ -134,10 +541,20 @@ that work actually completes.
 
 ### Darwin native assets in JS distributions
 
-**Who must act:** Bun JS builds using `--outfile`, copying only `outputs[0]`, custom
-single-file/archive packagers and installers delivering native process/files capabilities.
-First affected publication: **0.103.13**. It shipped as a patch; its changed delivery graph
-requires this migration despite unchanged API signatures.
+**Who must act:** Bun builds that import `stitchkit/server`, `stitchkit/files` or
+`stitchkit/process` (Linux-only server apps included) and use `--outfile`, copy only
+`outputs[0]`, or package a single file; custom single-file/archive packagers and installers
+delivering native process/files capabilities.
+First affected publication: **0.103.13**, through **0.104.2**. It shipped as a patch; its
+changed delivery graph requires this migration despite unchanged API signatures.
+
+In those versions every Bun bundle that reaches the lock or process-identity code,
+`stitchkit/server` included, carries both Darwin `.node` addons as extra outputs on every
+operating system. `bun build --outfile` then fails with
+`cannot write multiple output files without an output directory`, and `--outdir` writes the
+addons next to a Linux artifact. Releases after 0.104.2 resolve the default loader at run time,
+so these bundles are one JS file with no `.node` output again. The static loader exists only
+in a build that uses the `stitchkit/files/packaging` plugin.
 
 ```sh
 # Before: one JS file was assumed to be the entire distribution.
@@ -154,12 +571,39 @@ Custom output layout uses the evolving build-only packaging contract in the
 
 Three deliveries have different rules: an ordinary npm install retains the package's
 native assets; a JS distribution must ship its complete output graph; a Bun compiled
-executable embeds the matching addon and may still use `--outfile`.
+executable embeds the matching addon and may still use `--outfile`. In 0.103.13–0.104.2 a plain
+`bun build` carries the addon without a plugin; later releases carry it only when the build
+uses `createNativePackaging` (`delivery: 'companion'` for JS, `'embedded'` for a compiled
+executable).
 The [native IO guide](native-io.md#libraries-with-a-zod-only-runtime) is the canonical recipe.
 Check the resulting artifact offline outside the build tree and `node_modules`, including
 process identity, live-owner lock refusal, dead-owner recovery and contained IO.
 A missing or corrupt addon remains `unavailable`, never evidence that an owner died.
 
+### CLI: repeated options are refused
+
+**Who must act:** wrappers, aliases and scripts that append `--json`, `--profile X` or an
+application global to arguments the user may already have given, and anything that passes the
+same global twice.
+First affected publication: **0.103.13**. It shipped as a patch; the change in grammar needs
+this migration.
+
+A repeated option that is not an array field is an argument error:
+`--json --json` and `--profile a --profile b` fail with `--json was passed 2 times`. Before
+0.103.13 the last value won, for framework globals, application globals and repeated
+`kind: 'other'` fields alike. Array fields, and untyped passthrough fields that keep their
+raw-list grammar, still repeat.
+
+```sh
+# Before: a wrapper appended its default and the last value won.
+mytool deploy --profile staging "$@" --profile production
+# After: build the argument list once, so each option appears once.
+mytool deploy --profile "${PROFILE:-production}" "$@"
+```
+
+Dotted leaves such as `--filter.name` follow the same rule as their parent field. Declare a
+field as an array when repetition is meant.
+
 ## Released migration: 0.103.0
 
 ### Diagnostic journal startup preserves torn evidence and inspects archives
@@ -493,562 +937,3 @@ version loads unchanged — the new `unavailableAt` reads as `null`.
    drains; without it downtime is counted from the recorded stop. Call
    `recordReady()` when the run serves; a run stopped without it now ends
    `startup-failed`, not `clean`.
-
-## Released migration: 0.94.0
-
-One breaking minor that consolidates: tool options move into one group, and
-names that were exported from two entrypoints keep only their owner. Every step
-is an edit a type checker or `defineContract` points at; the few behaviour
-changes that need no edit are under Changed and Fixed in the changelog.
-
-1. **Move endpoint tool options into `tool`.** **Who must act:** every project
-   with an endpoint that sets `toolName`, `ui`, `annotations` or `mcp`. Run the
-   codemod from a checkout of this repository, then typecheck:
-
-   ```bash
-   bun packages/core/scripts/codemod-tool-group.ts --check path/to/your/src   # list
-   bun packages/core/scripts/codemod-tool-group.ts path/to/your/src           # rewrite
-   ```
-
-   ```ts
-   // before
-   { method: 'GET', path: '/', desc: 'List', toolName: 'user_list', mcp: { inputRequired } }
-   // after
-   { method: 'GET', path: '/', desc: 'List', tool: { name: 'user_list', mcp: { inputRequired } } }
-   ```
-
-   The codemod leaves two kinds of endpoint for a person and prints where: one
-   built with a spread (`{ ...base, toolName }`), and one exposed on HTTP only,
-   whose tool options never reached a tool — delete them there. Anything left
-   over fails at startup, by name — a key moved into the group under its old
-   name (`tool: { toolName }`) included:
-
-   ```text
-   Contract "users": endpoint "list" sets `toolName` — tool options live in `tool` since 0.94.0: use tool.name
-   ```
-
-   `expose` does not move. `MethodDef` — what hooks and runtime tools see — keeps
-   `toolName`, `ui`, `annotations` and `mcp` at the top level, so hook code does
-   not change. A tool view is declared only with `withToolView`, which now puts
-   it in `tool.view`.
-
-2. **Change imports of moved names.** **Who must act:** projects importing any
-   of these; the compiler lists every site.
-
-   | Name | From | To |
-   |---|---|---|
-   | `RuntimeToolTransport`, `ToolSurfaceTransport`, `ToolInvokerTransport` | `stitchkit/tools`, `stitchkit/tools/invoker`, `stitchkit/tools/connections` | `ToolTransport` from `stitchkit/contract` |
-   | `createCli`, `defineCliCommand`, `CliConfig`, `CliSurfaceSource`, `CliPresentationPolicyConfig`, `CliWaitConfig`, `ExitCodeMap`, `CliCommand*` | `stitchkit/tools` | `stitchkit/cli` |
-   | `parseSSE`, `ParseSSEOptions` | `stitchkit/server` | `stitchkit` |
-   | `runAgentStoreConformance`, `AgentStoreConformance*`, `createAgentRace*`, `AgentRace*` | `stitchkit/testing` | `stitchkit/agent-runtime/testing` |
-   | `createLocalStepDurability`, `LocalStepDurability`, `LocalStepDurabilityOptions`, `StepDurabilityLedger` | `stitchkit/agent-runtime` | `stitchkit/tools` |
-
-3. **Regenerate a surface snapshot only if it reports drift.** **Who must act:**
-   a project whose committed snapshot has an object with integer-like keys
-   (`"9"`, `"10"`) — they are now sorted like every other key. Every other
-   snapshot, CLI manifest signature and agent-store archive is byte-identical.
-
-## Released migration: 0.93.0
-
-1. **Regenerate every committed surface snapshot, once.** `manifestVersion` is
-   `3` and each operation row gained `mcp` — the rounds it declares before it
-   runs. Most rows get `null`, so the first diff is large and mechanical.
-   **Who must act:** anyone with a committed snapshot. A snapshot on the older
-   version is refused by name rather than failing a schema literal:
-
-   ```text
-   Surface snapshot is manifestVersion 2; this build writes 3. Regenerate it
-   and review the diff — the format changed, so the first regeneration is
-   expected to be large.
-   ```
-
-   ```ts
-   // before — a declared round left no trace, so declaring or removing one
-   // passed review invisibly
-   manifest.operations[0]
-   // after
-   manifest.operations[0].mcp
-   // null | { inputRequired: [{ key, message, schema }] }
-   //      | { inputRequired: 'resolved-per-call' }
-   ```
-
-   A project that kept its own test for "declared `inputRequired` implies a
-   configured state key" can drop it: the snapshot holds that link now.
-
-2. **Nothing else to do.** Native commands that declare `output` became
-   invokable in process; a name that answered `NOT_FOUND` from
-   `createCliInvoker` in 0.92.0 may now resolve. If an application relied on
-   native commands being unreachable there, stop passing them to the invoker.
-
-## Released migration: 0.92.0
-
-1. **`RequestEvent.method`, `path` and `statusCode` are optional.** Work that did
-   not arrive over a transport now records their **absence** instead of inventing
-   values — a background loop used to write `method: 'AGENT'`, which is not a
-   verb. **Who must act:** anyone whose `RequestEventSinkConfig.write` puts these
-   into NOT NULL columns, or whose filter reads `event.method`.
-
-   ```ts
-   // before
-   write: (event) => db.audit.create({ data: { method: event.method, path: event.path, status: event.statusCode } })
-   // after — a job has none of the three; `kind` says which kind of row it is
-   write: (event) => db.audit.create({ data: {
-     kind: event.kind,
-     name: event.name ?? null,
-     method: event.method ?? null,
-     path: event.path ?? null,
-     status: event.statusCode ?? null,
-   } })
-   ```
-
-   A filter written as `event.method !== 'GET'` keeps jobs (`undefined !== 'GET'`),
-   which is usually what you want. To exclude them deliberately:
-   `event.kind === 'request' && event.method !== 'GET'`.
-
-2. **`applyCliUpdate` needs the manifest when given a trust root.** The signature
-   covers the manifest and every asset digest together, so an asset alone cannot
-   be verified. **Who must act:** only callers adopting signature verification;
-   the unsigned call is unchanged.
-
-   ```ts
-   // before
-   await applyCliUpdate({ asset })
-   // after
-   await applyCliUpdate({ asset, manifest: check.manifest, trust })
-   ```
-
-3. **An MCP continuation minted before this release is refused once.** The signed
-   round state now carries a fingerprint of the question plan, checked on every
-   round, so a plan that moved between rounds is a refusal rather than a
-   different question asked under the previous one's key. A conversation already
-   in flight at deploy time has no fingerprint and gets
-   `INVALID_REQUEST_STATE`; the host re-asks and the second attempt succeeds.
-   **Who must act:** nobody — but expect a small number of these in the minutes
-   after a deploy, and do not read them as tampering.
-
-## Released migration: 0.91.0
-
-1. `STITCH_ERROR_STATUS` gained `NOT_IMPLEMENTED` (501). An **exhaustive** error
-   vocabulary must name it — without the row `defineErrors({ mapping: { exhaustive:
-   true } })` stops compiling and then throws at startup. Nothing else in this
-   release requires action.
-
-   ```ts
-   // before
-   map: { …, WAIT_TIMEOUT: 'timeout' }
-   // after
-   map: { …, NOT_IMPLEMENTED: 'not_implemented', WAIT_TIMEOUT: 'timeout' }
-   ```
-
-   The code is thrown only by the new dev-only `onMissingHandler: 'stub'` policy;
-   a vocabulary that is not exhaustive is unaffected.
-
-## Released migration: 0.90.0
-
-1. `stitchkit.watch.value` is a discriminated union on `kind` — `full`, `delta`,
-   `unchanged` — and every frame carries `fingerprint`. **Both ends must come from
-   the same major.** A client older than this release reads a `delta` frame as a
-   value of `undefined`, silently; upgrade the hub and the pages that talk to it
-   together, or set `deltaMemoryBytes: 0` on the hub until they are.
-
-   Applications using `createWatchClient` need no code change: it rebuilds the
-   value and hands the listener the whole answer as before. Code that reads
-   `WatchValueFrame.value` directly — a hand-written subscriber, a test double —
-   narrows on `kind` first.
-
-   ```ts
-   // before: frame.value
-   // after:
-   if (frame.kind === 'full') hold(frame.value);
-   else if (frame.kind === 'delta') hold(applyWatchDelta(held, frame.delta));
-   // 'unchanged' leaves what you hold standing
-   ```
-
-2. `AttachedWatcher.open` takes an optional third argument, `have`. A custom
-   server binding that forwards `stitchkit.watch.open` should pass the payload's
-   `have` through; omitting it costs a whole value on every reconnection and is
-   otherwise harmless.
-
-## Released migration: 0.89.0
-
-1. Custom `AgentRuntimeStore` adapters implement `seedConversationInput`; custom
-   `AgentRuntimeStoreDriver` adapters implement `seeds.load` and `seeds.create` together
-   with atomic, ordered history insertion. Use the maintained Prisma example and run
-   `runAgentStoreConformance` against the adapter. Built-in memory and SQLite
-   stores already implement the contract; SQLite migrates to schema version 3.
-2. OpenRouter usage normalization consumes each completed SDK step's `usage`, including
-   `raw`, rather than aggregate usage. Missing counters stay `unavailable`.
-
-   ```ts
-   // before: normalizeOpenRouterUsage(await result.usage, metadata)
-   // after:
-   for (const step of await result.steps) {
-     const usage = normalizeOpenRouterUsage(step.usage, step.providerMetadata);
-     // Persist the step's measured usage with its provenance.
-   }
-   ```
-
-3. Durable step bodies return lossless JSON. Convert dates explicitly, reject invalid
-   numbers upstream, and return `null` after an effect-only operation.
-
-   ```ts
-   await context.step('send', async () => {
-     await sendIdempotently();
-     return null;
-   });
-   ```
-
-   First execution, replay and concurrent callers receive detached values. Persistence
-   does not make external effects transactional; the host retains idempotency and recovery.
-
-
-How to move a consuming project from one stitchkit version to another — including
-across many versions at once (a project frozen on an old version, then jumped
-forward). The process is mechanical: stitchkit marks every breaking change in one
-place and one format, so you can recover the full migration from the version diff.
-
-## Released migration: 0.88.0
-
-Two mechanical edits, and only if your project builds these values rather than only reading them.
-
-A completed step event now carries the provider's response identity, and the field is required:
-
-```ts
-// before
-{ type: 'step-finished', step: 0, usage }
-
-// after
-{ type: 'step-finished', step: 0, usage, response: { id: generationId } }
-```
-
-Every event the runtime emits already has it, so a sink that only reads them needs no change. A
-fixture, a test double or a pipeline that re-validates events persisted by an earlier version does:
-give the older records a response identity, or keep parsing them with the schema they were written
-under.
-
-If you implement the whole `AgentRuntime` interface — usually a mock — add the new method:
-
-```ts
-// before
-const fake: AgentRuntime = { submit, interrupt, recover, close }
-
-// after
-const fake: AgentRuntime = { submit, interrupt, abandon, recover, close }
-```
-
-No data migration is involved, and nothing in the store changes shape.
-
-## Released migration: 0.87.0
-
-Only if your project implements `AgentConversationReader` itself. A message page
-now names which of its messages compaction removed:
-
-```ts
-// before
-return { items, ...(nextCursor && { nextCursor }) }
-
-// after
-return { items, compacted: [], ...(nextCursor && { nextCursor }) }
-```
-
-An empty array is the honest answer for a reader that pages only the active
-history; it is what the SQLite reader returns unless the caller asks for
-`includeCompacted`. Calling the reader needs no change, and no data migration is
-involved.
-
-## Released migration: 0.86.0
-
-Only if you branch on `AgentTerminalReason` or show it to a person. Three
-failures that used to arrive as `provider_failure` now arrive as themselves:
-
-```ts
-// before
-if (run.terminalReason === 'provider_failure') showOutage()
-
-// after
-switch (run.terminalReason) {
-  case 'provider_failure':
-    showOutage()
-    break
-  case 'storage_conflict':
-    // Another writer took this run's revision, or the store refused the write.
-    retryOrReport()
-    break
-  case 'output_rejected':
-    // Your own `protocol.acceptTerminal` refused the finished message.
-    reportRejectedAnswer()
-    break
-  case 'runtime_failure':
-    // The runtime, or a check the SDK ran on what it was handed, failed
-    // before the provider was reached.
-    reportInternal()
-    break
-}
-```
-
-A run that never reached the provider can no longer report `provider_failure`,
-so an alert keyed on that value stops firing for causes that were never the
-provider's.
-
-If you implement `AgentRuntimeStore` directly, add the event-ledger surface:
-
-```ts
-const store: AgentRuntimeStore = {
-  // existing normalized operations
-  appendEvent,
-  readEvents,
-  exportConversation,
-  importConversation,
-}
-```
-
-If you implement an `AgentRuntimeStoreDriver` (Prisma, Postgres, any external
-database), the ledger is yours to keep: `events` is a required member, and it
-needs a table.
-
-```ts
-// before
-const driver: AgentRuntimeStoreDriver<Tx> = { transaction, head, runs, admissions, history, scanRecoverable }
-
-// after
-const driver: AgentRuntimeStoreDriver<Tx> = {
-  transaction, head, runs, admissions, history, scanRecoverable,
-  events: {
-    // One row per event; `seq` is per conversation, starts at 1, and is
-    // assigned inside the caller's transaction so concurrent appends cannot
-    // share or skip a number.
-    append: async (tx, draft) => {
-      // Two transactions that both read max(seq) and both insert max + 1
-      // collide on the primary key; under SERIALIZABLE the snapshot predates
-      // any lock you take here. Treat a unique violation on this table as a
-      // serialization conflict and re-run the whole transaction — see
-      // `runTransaction` in examples/agent-store-prisma/adapter.ts.
-      const seq = (await tx.event.aggregate({ _max: { seq: true }, where: { conversationId: draft.conversationId } }))._max.seq ?? 0
-      await tx.event.create({ data: { ...draft, seq: seq + 1, payload: JSON.stringify(draft.payload) } })
-      return { ...draft, seq: seq + 1 }
-    },
-    // Ordered by `seq`, bounded by `fromSeq`/`toSeq`/`limit`; `nextSeq` when
-    // more remain.
-    list: async (tx, input) => { /* see examples/agent-store-prisma/adapter.ts */ },
-  },
-}
-```
-
-The table carries `eventId` (unique), `conversationId`, `seq`, `schemaVersion`,
-`kind`, `occurredAt`, `ignorable` and `payload`. `runAgentStoreConformance`
-from `stitchkit/testing` now exercises it — contiguous `seq` under twenty
-concurrent appends, bounded reads, the `ignorable` flag, a byte-stable export
-— so run it against your driver before deploying. Expect one more insert per
-run operation (`runtime/transition`) and one per model step
-(`provider/request`) on the hot path; there is no opt-out.
-
-If you operate a built-in SQLite store file:
-
-1. Back the file up. The first open by 0.86.0 migrates it to schema 2 in one
-   transaction and there is no way back: a 0.85.x package refuses a migrated
-   file with `Unsupported Stitchkit agent-runtime SQLite schema version 2`.
-2. Check the build for FTS5 before deploying:
-
-   ```sql
-   SELECT sqlite_compileoption_used('ENABLE_FTS5');
-   ```
-
-   A build without it is refused at open with `requires FTS5 support`. On the
-   machine this was verified, Bun 1.3 `bun:sqlite` and Node 24.18 `node:sqlite`
-   both carry it; verify your own build rather than assuming — the table of
-   supported runtimes says Node ≥ 22.5, and FTS5 there is not verified here.
-3. Know what the migration wrote. Each existing conversation becomes one
-   `runtime/baseline` event at `seq 1`, dated when the migration ran, with
-   `asOf` inside the payload naming the last message it describes. Event
-   search and projections address that conversation's pre-migration history as
-   one snapshot at `seq 1`; event-level precision begins with the first event
-   after the migration.
-
-If you subscribe to `AgentRuntimeEvent` and switch over `event.type`
-exhaustively, add the transient `attempt-reset` case — drop the run's
-transient text — or the reducer stops compiling; a reducer that ignores it
-keeps a failed attempt's partial text on screen.
-
-New in this release, not a migration: child runs cascade only when the manager
-is given to the runtime —
-`createAgentRuntime({ ...config, children: createSqliteAgentChildManager({ sqlite, spawn }) })`
-— and the SQLite companions take the store handle (`{ sqlite }`), whose
-`database` and `transaction` they share.
-
-## Released migration: 0.85.0
-
-Only if you implement `AgentRuntimeStore` directly. Add the new durable
-operation mutation beside the existing run mutations:
-
-```ts
-// before
-const store: AgentRuntimeStore = {
-  checkpointRunAssistant,
-  commitRunTerminal,
-  // ...
-}
-
-// after
-const store: AgentRuntimeStore = {
-  checkpointRunAssistant,
-  recordRunOperation,
-  commitRunTerminal,
-  // ...
-}
-```
-
-It must atomically replace `AgentRun.lastOperation`, increment the run revision
-and conversation snapshot version, and enforce the supplied owner, fencing
-token and expected revision. Adapters built with `createAgentRuntimeStore`
-already receive the reference implementation; no driver method is added.
-
-## Released migration: 0.84.0
-
-Only if you call `createAgentCodingTools`.
-
-```bash
-rg -n "createAgentCodingTools"
-```
-
-**1. Backslashes are refused.** If anything in your system hands the tools a Windows-style path,
-it now gets `FORBIDDEN`. Convert to `/` at the boundary:
-
-```ts
-// before: read_file({ path: 'src\\index.ts' })   // reached openat as two segments
-// after:  read_file({ path: 'src/index.ts' })
-```
-
-This is the half that matters most: until now a backslash bypassed your **required**
-`authorize({ operation, path })` callback, not just `authorizePath`. A rule denying
-`credentials/token.txt` refused that spelling and served — and overwrote — the same file spelled
-`credentials\token.txt`. If your policy denies specific files, re-read your audit logs for
-backslash spellings.
-
-**2. Denying a directory now denies everything under it — and a policy must admit every directory
-on the way to a file**, the way POSIX needs `+x` on each directory in a path.
-
-If your policy is a DENY-list, it now does what it read as:
-
-```ts
-authorizePath: ({ path }) => path !== 'credentials'
-// before: hid `credentials` from glob, served `credentials/token.txt` to read_file
-// after:  refuses `credentials/token.txt`, `credentials/nested/deep.txt` and writes under it
-```
-
-If you relied on the old behaviour — a directory hidden from discovery but readable directly — you
-were relying on a defect, and the two halves of one callback disagreeing. Name the paths you
-actually want reachable instead.
-
-If your policy is an ALLOW-list, widen it to the directories it leads through, or nothing under
-them is reachable:
-
-```ts
-// before: allowed src/index.ts, because only the leaf was ever asked
-authorizePath: ({ path }) => path.startsWith('src/')
-// after: `src` itself is asked first and refused, so the file is refused too
-authorizePath: ({ path }) => path === 'src' || path.startsWith('src/')
-```
-
-The workspace root is not asked about — it is the boundary the tools already own.
-
-**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.