stitchkit 0.106.1 → 0.108.0

package/llms/telegram.txt

@@ -234,8 +234,8 @@ and pacing/progress intervals must fit native timers. The optional
 when the signal aborts if a custom sleeper ignores it. A send already in flight
 finishes and is recorded before stopping.
 
-Without `classify`, known Bot API 429, unreachable-recipient, malformed-message
-and server-error behavior remains. Unknown/no-status failures now halt as
+Without `classify`, known Bot API 429, unreachable-recipient, malformed-message,
+server-error and not-dispatched behavior remains. Unknown/no-status failures now halt as
 uncertain, rather than being automatically retried. Existing custom `send`
 implementations that relied on those retries must supply an explicit classifier
 for proven pre-effect failures. `report.halt` now carries
@@ -254,6 +254,36 @@ The installed
 fixture checks injected rate limits, ambiguity/no resend, wait budgets and abort
 on Bun and Node without a client SDK.
 
+## A transport that knows whether a request left
+
+`fetch` folds establishing the connection and waiting for the answer into one failure. From that
+failure nobody can say whether Telegram saw the message, so the senders above treat every network
+failure as unknown: a broadcast records the recipient `uncertain` and the operator channel drops
+the message rather than risk a duplicate. On a route that sometimes fails to connect at all, that
+loses messages that never left.
+
+`createTelegramBotTransport()` connects first and writes the request only on an established
+connection. Every failure before the first byte is written is `TelegramNotDispatchedError`
+(`stage`: `lookup`, `connect` or `request`), and `classifyTelegramSendFailure` reads it as
+`not-dispatched` — `retryable`, with `evidence: 'transport'`. A broadcast retries it as
+`transient`; the operator channel sends it again. A failure after the request was written stays
+an outcome nobody can know.
+
+```ts
+import { createTelegramBotTransport, telegramOperatorSender } from 'stitchkit/telegram'
+
+const transport = createTelegramBotTransport()
+const send = telegramOperatorSender({ token: env.BOT_TOKEN, fetch: transport })
+```
+
+Pass it as `fetch` to `callTelegramBotApi`, `telegramBroadcastSender`, `telegramOperatorSender`
+or the webhook calls. Addresses come in the system resolver's order with no family forced; the
+next address starts 250 ms later (Happy Eyeballs), and a round with no connection is repeated
+with new sockets inside `connectBudgetMs` (default 5 s, which also bounds the address lookup; each
+round waits `connectAttemptMs`, default 2 s). The answer must arrive within `responseTimeoutMs` (default 30 s) and fit
+`maxResponseBytes` (default 1 MiB). It speaks HTTP/1.1 over `https:`, and over `http:` for a
+local Bot API server, and it uses no proxy: where the network needs one, keep `fetch`.
+
 ## Message markup
 
 `stitchkit/telegram/html` is Telegram's HTML parse mode as a tree, with no peer
@@ -453,7 +483,10 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 | `TelegramInitDataRefusal` | _type_ | `missing-hash` / `signature-mismatch` / `malformed` / `expired` — an expired string is not a forged one |
 | `classifyTelegramSendFailure` | function | name a refused Bot API send and separate "retry this send" from "stop addressing this recipient" |
 | `TelegramSendFailure` | _type_ | reason, `status`, Telegram-stated `retryAfterSeconds`, `retryable`, `recipientUnreachable` and which evidence produced the answer |
-| `TelegramSendFailureReason` / `TELEGRAM_SEND_FAILURE_REASONS` | _type_ / constant | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `rate-limited` / `message-invalid` / `server-error` / `unknown`, and the same as a list; a `Record<TelegramSendFailureReason, …>` over them fails to compile when a reason is added |
+| `createTelegramBotTransport` / `TelegramBotTransportOptions` | function / _type_ | a `fetch` for the Bot API senders that connects before it writes, so a failure before the first byte is `TelegramNotDispatchedError`; connection attempt and budget, answer timeout and size, injectable resolver and socket factory — [guide](../guide/telegram.md#a-transport-that-knows-whether-a-request-left) |
+| `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` / `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 |
 | `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 |

package/llms/testing.txt

@@ -223,6 +223,50 @@ The suite in `packages/core/tests` is the working reference for testing each
 piece. Its size changes with the public surface, so the guide does not pin a
 count that can drift independently from the test runner.
 
+### Manual time for schedules and retries
+
+`createManualClock()` from `stitchkit/testing` stands time still until the test moves it. It is
+the `clock` of `createManagedSchedule`, a durable sleep, a revision signal or bounded admission,
+and the `schedule` a retrier of your own takes:
+
+```ts
+import { createManagedSchedule } from 'stitchkit/application'
+import { createManualClock } from 'stitchkit/testing'
+
+const clock = createManualClock()
+const schedule = createManagedSchedule({ id: 'sweep', everyMs: 1_000, clock, run })
+// …start and activate it…
+await clock.advance(3_500) // runs at 1 s, 2 s and 3 s of manual time; the test takes milliseconds
+```
+
+Only one `advance` (or `until`) runs at a time; a second one started before the first settled is
+refused, because two interleaved moves would run time backwards.
+
+Due timers fire in deadline order, ties in scheduling order. After each firing the clock yields
+real event-loop turns, not just microtasks: a continuation that arms the next retry after an
+already-readable socket or another macrotask has armed it before the clock moves on, so
+`advance(10_000)` does not skip a retry armed at the fifth second. Real work of unknown length —
+a request to a fake server, a hash in the thread pool — outruns any number of turns; the test
+wraps the dependency it injects in a `hold`:
+
+```ts
+const request = async (body) => {
+  const held = clock.hold('upload to the fake server')
+  try {
+    return await fakeServer.send(body)
+  } finally {
+    held.release()
+  }
+}
+```
+
+Time does not move while a hold is open; past `holdLimitMs` of real time (default 5 s)
+`advance` fails with `ManualClockError` `MANUAL_CLOCK_HOLD_TIMEOUT`, naming every open hold. A
+held operation that waits for the clock itself — a request timing out on a deadline — `park`s
+its hold so the deadline can come. `until(done)` moves from deadline to deadline until `done()`
+holds and fails with `MANUAL_CLOCK_LIMIT` past `limitMs` of manual time; `pending()` counts the
+timers still waiting, so a timer leaked past `close()` shows as a number, not as a hang.
+
 ### Managed-resource conformance
 
 Consumer-owned resource adapters can run the framework's deterministic
@@ -617,6 +661,9 @@ handler pipeline without opening a TCP port.
 |--------|------|---------|
 | `createHandlerTestClient` | function | one contract client backed by an in-process `FetchHandler` |
 | `createHandlerTestClients` | function | exact contract-registry batch form |
+| `createManualClock` / `ManualClock` | function / _type_ | manual time for schedules, retries and deadlines: `now`, `wallNow`, `schedule`, `advance(ms)` firing due timers in order with real event-loop yields between them, `until`, `pending` and `hold`; a `ManagedScheduleClock`, `DurabilityClock`, `RevisionSignalClock` and `BoundedAdmissionClock` — [guide](../guide/testing-and-deployment.md#manual-time-for-schedules-and-retries) |
+| `ManualClockOptions` / `ManualClockUntilOptions` / `ManualClockTimer` / `ManualClockHold` | _types_ | start and wall instants, event-loop turns per firing and the real-time hold limit; `until` step and manual limit; a cancellable timer; a hold that is released or parked |
+| `ManualClockError` / `ManualClockErrorCode` | class / _type_ | `MANUAL_CLOCK_HOLD_TIMEOUT` naming the open holds, or `MANUAL_CLOCK_LIMIT` when `until` runs out |
 | `runManagedResourceConformance` | function | run the canonical deterministic lifecycle matrix against a fresh consumer-owned `ManagedResource` fixture; resolves `void` or throws `ManagedResourceConformanceError` with a stable scenario ID and normalized trace |
 | `ManagedResourceConformanceScenarioIdSchema` / `ManagedResourceConformanceScenarioId` | schema / _type_ | stable clean, rollback, readiness/completion, activation, shutdown-race and forced-cleanup scenario vocabulary |
 | `ManagedResourceConformanceScenarioSchema` / `ManagedResourceConformanceScenario` | schema / _type_ | discriminated scenario record including whether the controlled resource is required |

package/llms/{upgrading-0.96.0-0.106.0.txt → upgrading-0.100.0-0.108.0.txt}

@@ -1,14 +1,102 @@
-# Upgrading 0.96.0 → 0.106.0 — stitchkit docs slice
+# Upgrading 0.100.0 → 0.108.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.96.0 → 0.106.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.100.0 → 0.108.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.96.0 → 0.106.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.100.0 → 0.108.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.108.0
+
+### a request that never left is its own send outcome
+
+**Who must act:** code with an exhaustive `switch` or `Record` over `TelegramSendFailureReason` or
+over `TelegramSendFailure['evidence']` (`stitchkit/telegram`). Code that reads `retryable` and
+`recipientUnreachable` needs no change.
+
+`classifyTelegramSendFailure` now returns `reason: 'not-dispatched'` with `evidence: 'transport'`
+for a `TelegramNotDispatchedError`: the request never left, so it is `retryable` and repeating it
+cannot duplicate a message
+([ADR 0253](../decisions/0253-a-telegram-request-that-never-left-is-safe-to-repeat.md)). Only
+`createTelegramBotTransport` throws that error; with the default `fetch` nothing changes at run time.
+
+1. Add the reason and the evidence to every exhaustive mapping:
+
+   ```ts
+   // before
+   const code: Record<TelegramSendFailureReason, string> = { /* … */ unknown: 'E_UNKNOWN' }
+   // after
+   const code: Record<TelegramSendFailureReason, string> = {
+     /* … */ 'not-dispatched': 'E_NOT_SENT', unknown: 'E_UNKNOWN',
+   }
+   ```
+
+   Search pattern: `TelegramSendFailureReason`, `TELEGRAM_SEND_FAILURE_REASONS` and `evidence ===`.
+2. Type-check: a `Record` or an exhaustive `switch` without the new members fails to compile.
+3. To use the distinction, pass `fetch: createTelegramBotTransport()` to the senders that need it
+   (see the [Telegram guide](telegram.md#a-transport-that-knows-whether-a-request-left)).
+
+### a packaging plugin packages only its own installation
+
+**Who must act:** builds that call `createNativePackaging` (`stitchkit/files/packaging`) from a
+`stitchkit` installation other than the one the bundled entry imports — typically a build tool that
+carries its own copy. Builds whose entry and plugin come from one installation are unchanged.
+
+Such a build used to succeed and ship the other installation's default Darwin loader, which refuses
+the addon on macOS at run time. It now fails, naming both versions and roots
+([ADR 0254](../decisions/0254-a-packaging-plugin-owns-one-loader-and-names-what-it-finds.md)).
+
+1. Create the plugin from the `stitchkit` the entry resolves, not from the build tool's copy:
+
+   ```ts
+   // before: the build tool's own stitchkit
+   import { createNativePackaging } from 'stitchkit/files/packaging'
+   // after: resolved from the project that owns the entry
+   const { createNativePackaging } = await import(
+     Bun.resolveSync('stitchkit/files/packaging', projectRoot)
+   )
+   ```
+
+   Search pattern: `createNativePackaging` in build tooling that is installed apart from the project.
+2. Check the artifact with `inspectNativeArtifact`: a correct build reads `packaged`. An artifact
+   built by 0.107.0 or earlier carries no loader marker and reads `no-loader` whatever it holds, so
+   rebuild before relying on the check; a test of `=== 'unpackaged'` alone passes such an artifact.
+
+## Released migration: 0.107.0
+
+### embedded native packaging names no paths
+
+**Who must act:** builds that call `createNativePackaging` (`stitchkit/files/packaging`) with
+`delivery: 'embedded'`. Companion delivery is unchanged.
+
+A standalone executable carries the Darwin addon inside itself, so the embedded form takes only
+`platform`, `architecture` and `delivery`. `entryPath` and `assetPath` were required before but
+changed nothing in the executable; passing them now is a type error and a schema refusal. The
+ready result names the embedded addon by `NativePackagingEmbeddedAsset` (`bytes`, `size`,
+`sha256`), without `outputPath`, since nothing is written beside the executable.
+
+1. Drop the two paths from the embedded call:
+
+   ```ts
+   // before
+   createNativePackaging({
+     platform: 'darwin', architecture: 'arm64', delivery: 'embedded',
+     entryPath: 'cli.js', assetPath: 'native/darwin-arm64.node',
+   })
+   // after
+   createNativePackaging({ platform: 'darwin', architecture: 'arm64', delivery: 'embedded' })
+   ```
+
+   Search pattern: `delivery: 'embedded'`.
+2. Code that read `asset.outputPath` from an embedded result reads `bytes`, `size` and `sha256`
+   only; an annotation `NativePackagingOptions` / `NativePackagingResult` on an embedded call
+   becomes `NativePackagingEmbeddedOptions` / `NativePackagingEmbeddedResult`.
+3. Rebuild every artifact made without the plugin by 0.105.0–0.106.1: it carries the build
+   machine's package path (see [Darwin native assets in JS distributions](#darwin-native-assets-in-js-distributions)).
+
 ## Released migration: 0.106.0
 
 ### a stopped leader settles as stopped
@@ -609,13 +697,27 @@ 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`. 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.
+`bun build` carries the addon without a plugin. Later releases load it from a bundle only when
+the build uses `createNativePackaging` (`delivery: 'companion'` for JS, `'embedded'` for a
+compiled executable). Without the plugin, Bun may still copy the addon's bytes into a compiled
+executable, but the loader never uses them, so their presence proves nothing.
+
+What an unpackaged bundle does depends on the release:
+
+- **0.105.0–0.106.1:** the bundle carries the absolute path of the package on the build machine,
+  because the loader read `__dirname`. It looks for the addon there, so it works only on that
+  machine, and the path itself leaks into a distributed artifact. Rebuild with a later release.
+- **0.107.0 and later:** no build path is in the artifact, and the first call that needs the
+  addon reports the Darwin backend `unavailable` with stage `packaging`.
+
+Only macOS is affected, and only process identity (`observeProcessInstance`,
+`probeProcessOwner`), exclusive locks and contained Agent file operations load the addon. The
+managed file boundary, atomic writes and the chunk spool never do. The
+[native IO guide](native-io.md#libraries-with-a-zod-only-runtime) is the canonical recipe and
+shows how to check an artifact by its loader without running it on a Mac. 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
 
@@ -798,137 +900,3 @@ recovery refuses rather than treating unknown ownership as death. From 0.100.1 a
 Linux kernel without time namespaces (before 5.6) records the PID namespace alone
 instead of null, so its locks recover like any other. Existing
 `refuse` policy and the separately configured ownerless-file grace are unchanged.
-
-## Released migration: 0.99.0
-
-### structural alternatives in flattened tool schemas
-
-**Who must act:** applications using `flattenUnionInput: true` with schema
-walkers, snapshots or provider restrictions that assume there is no nested
-`anyOf`. Applications without that assumption need only update the dependency.
-
-Colliding object/array fields retain their complete structural alternatives:
-
-```ts
-// Before: loses both field vocabulary and array items.
-{ type: ['object', 'array'] }
-// After: structural alternatives live inside the property schema.
-{ anyOf: [
-  { type: 'array', items: {
-    type: 'object', properties: { id: { type: 'string' } }, required: ['id'],
-  } },
-  { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
-] }
-```
-
-Alternatives come in kind order, independent of variant order. The same shape
-covers every collision of different kinds, scalars included: `string` against
-`string[]` becomes `{ anyOf: [{ type: 'array', items: { type: 'string' } }, { type:
-'string' }] }`. A nullable field keeps `null` in each alternative's `type`, and
-differing nested object unions remain nested `anyOf` inside the alternatives. Update
-snapshots to this order.
-
-Traverse each nested alternative when inspecting schemas and regenerate schema
-snapshots. Verify the actual manifest with the chosen provider. Keep flatten
-enabled when a top-level discriminated union needs to be advertised as an
-object; do not erase `items` or introduce consumer-specific schema patches.
-The root object, discriminator enum, requiredness hints and strict runtime
-contract validation are unchanged. See ADR 0205.
-
-## Released migration: 0.98.0
-
-### automatic stdin availability
-
-**Who must act:** CLI applications or scripts relying on automatic stdin routing
-from a producer that can take more than 250 ms to write its first byte.
-
-Automatic routing now probes for the first byte for 250 ms. An empty open pipe
-leaves the required field unset and normal validation reports its name. Once
-data arrives, the entire stream is read until EOF without a total deadline.
-
-```sh
-# before: may now fail if the producer starts late
-slow-producer | myapp generate
-# after: provide the value explicitly after the producer completes
-myapp generate --prompt "$(slow-producer)"
-```
-
-For large input that should stay in a pipe, supply a `CliConfig.stdin` reader
-that waits for the producer and EOF; this existing hook is not wrapped in the
-availability probe. A custom reader owns its limits and error handling.
-`-` remains literal data. TTY and empty EOF produce ordinary validation errors;
-explicit arguments skip stdin. JSONL stream/batch commands, MCP/serve and
-long-running handlers have no new deadline. See ADR 0203.
-
-## Released migration: 0.97.0
-
-### schedule delivery
-
-**Who must act:** consumers of `createAgentScheduleService`, exhaustive switches on
-`AgentSchedule.state`, and operators opening existing agent-runtime SQLite stores.
-
-- Stop old scheduler processes and back up SQLite before startup. The store migrates
-  transactionally to v4; old binaries cannot open it. Rollback uses the backup.
-- Handle `failed` as a terminal schedule state. To refuse future delivery (including
-  recurring delivery), return `{ status: 'terminal', reason: 'destination closed' }`.
-  The occurrence remains unadvanced; `schedule/failed` carries `terminal: true`.
-- A throw or `{ status: 'retry', reason: 'temporarily unavailable' }` retries the same
-  key after 1, 2, 4, 8, 16, 32, then 60 seconds. `nextAt` remains the original due time;
-  `retryAt`, `attempts` and `lastError` expose retry diagnostics. Success clears them.
-- Resolve `void` only after durable consumer admission. Honor the supplied `signal`:
-  dispatch has a 30-second deadline and a 60-second lease. Durable deduplication by
-  `idempotencyKey` is required even after abort or crash; do not implement sleeps in dispatch.
-- Stale/cancelled attempts emit no `schedule/fired` or `schedule/late`. Observe the
-  cancellation event instead of relying on a synthetic cancelled firing.
-
-```ts
-// before
-async function dispatch(request) {
-  if (await destinationClosed(request.conversationId)) throw new Error('closed')
-  await admit(request)
-}
-// after: use this callback as createAgentScheduleService({ dispatch, ... })
-async function dispatch(request) {
-  if (await destinationClosed(request.conversationId)) {
-    return { status: 'terminal', reason: 'destination closed' }
-  }
-  await admit({ ...request, signal: request.signal }) // durably deduplicates idempotencyKey
-}
-```
-
-## Released migration: 0.96.0
-
-### resource-context-admission
-
-One breaking change in `stitchkit/application`: `ManagedResourceContext` gains a
-required `admission`. Every context the kernel hands a resource already carries
-it; only a context built by hand needs it.
-
-1. **Give a hand-built resource context an `admission`.** **Who must act:** a
-   project whose tests call a resource's phase directly with a context object
-   they wrote themselves (`resource.close?.({ applicationId, signal, … })`).
-   The type checker names each one:
-
-   ```ts
-   // before
-   await resource.close?.({ applicationId: 'test', signal, now, reportHealth, use })
-   // after
-   await resource.close?.({
-     applicationId: 'test',
-     signal,
-     now,
-     reportHealth,
-     use,
-     admission: { acquire: () => null, acquireWhenAccepting: () => new Promise(() => {}) },
-   })
-   ```
-
-   A test that needs real admission starts the resource inside
-   `createApplication` instead.
-
-2. **Nothing to do for grammY polling, but know what changed.** **Who must
-   act:** nobody. `grammyPollingResource` now admits updates by batch: it does
-   not fetch while the application is not accepting, and finishes the batch in
-   hand before `bot.stop()`. A project that wrote its own `getUpdates`
-   transformer for this (waiting on `app.admission` before returning a batch)
-   deletes it; keeping both waits twice and is harmless.

package/llms/{upgrading-0.37.0-0.53.0.txt → upgrading-0.37.0-0.58.0.txt}

@@ -1,14 +1,220 @@
-# Upgrading 0.37.0 → 0.53.0 — stitchkit docs slice
+# Upgrading 0.37.0 → 0.58.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.37.0 → 0.53.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.37.0 → 0.58.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.37.0 → 0.53.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.37.0 → 0.58.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.58.0
+
+### The default history projection rejects invalid chronology
+
+`projectAgentHistory` no longer forwards records a provider contract cannot
+accept. A completed assistant record before the first user message, and an
+assistant record whose tool calls have no matching results, are omitted with an
+inspectable decision instead of being sent upstream:
+
+```ts
+// before — a leading assistant record was forwarded as-is
+projectAgentHistory(messages)
+// after — opt in explicitly, and only where the provider contract permits it
+projectAgentHistory(messages, { leadingAssistant: 'allow' })
+```
+
+Two consequences the changelog does not spell out. First, the projection can now
+return **fewer** messages than the history holds, so any assertion or metric
+that compared projected length against stored length will move; read the
+detailed projection instead — it reports what was omitted and why, which is the
+supported way to see the difference. Second, the omission is silent to the
+provider but not to you: if a conversation suddenly loses its leading context,
+the decision record is where that shows up, not the transcript.
+
+### Operator events redact `internalCause` by default
+
+Raw provider and tool failures no longer travel in operator events unless the
+sink asks for them:
+
+```ts
+// before — internalCause was present
+createAgentObservability({ write })
+// after — an explicit operator-only opt-in
+createAgentObservability({ write, includeInternalCause: true })
+```
+
+The consequence to check before upgrading: any dashboard, alert or log
+processor keyed on `internalCause` goes blind the moment you upgrade, and it
+goes blind quietly — the field is absent, not empty. Set the flag on the
+operator sink you own. Product delivery stays redacted regardless of the flag;
+this option cannot widen what reaches a user.
+
+## Released migration: 0.57.0
+
+### Duplicate admission results carry the complete identity
+
+Custom `AgentRuntimeStore` adapters must persist and return the input and
+assistant identities associated with an idempotency key:
+
+```ts
+// before
+return { outcome: 'duplicate', runId, snapshot }
+
+// after
+return { outcome: 'duplicate', input, inputMessageId, runId, assistantMessageId, snapshot }
+```
+
+Prefer replacing the custom aggregate reducer with `createAgentRuntimeStore()`;
+its admission record and transaction driver implement this contract
+automatically. Historical note: 0.59.0 reshaped this driver again, so an adapter
+crossing both versions should read that section first and migrate once.
+
+### `AgentRuntimeEvent` adds a post-commit `admission` variant
+
+Add it to any exhaustive publisher switch. Its `assistant` is either the pending
+placeholder for a new assignment or the canonical persisted assistant for a
+duplicate:
+
+```ts
+case 'admission':
+  await persistProductProjection(event.input, event.run, event.assistant)
+  break
+```
+
+The consequence for an exhaustive switch written without a `default` branch is a
+compile error, which is the point. The consequence for a switch that *has* a
+`default` is worse and silent: post-commit admissions fall into it and are
+projected as an unknown event. Grep for publisher switches before upgrading.
+
+## Released migration: 0.56.0
+
+### Surface manifests are version 2
+
+`operation.tools` could not describe a role-selected MCP surface, a different
+Agent or CLI selection, or an advertised `extend` schema, so projections moved
+out of the canonical operation:
+
+```ts
+// before
+manifest.operations[0].tools.MCP
+// after
+manifest.toolSurfaces.find((s) => s.transport === 'MCP' && s.surface === null)?.tools
+
+// before
+buildSurfaceManifest({ mcpSurfaces: { admin: { services, extend } } })
+// after
+buildSurfaceManifest({ mcpSurfaces: { admin: { services } }, mcpPreparation: { extend } })
+```
+
+A committed snapshot is regenerated once, deliberately: `manifestVersion` is
+`2`, and `ConformanceTransport` gained `REALTIME`, so any exhaustive
+`Record<ConformanceTransport, …>` must handle it.
+
+### `FILE_*` codes joined the error registry
+
+`StitchErrorCode` gained `FILE_INVALID_PATH`, `FILE_OUTSIDE_ROOT`,
+`FILE_NOT_FOUND`, `FILE_NOT_REGULAR`, `FILE_INSPECTION_REJECTED`,
+`FILE_TOO_LARGE` and `FILE_EXISTS`. Only exhaustive maps break:
+
+```ts
+// before — compiled while the registry had no file codes
+const copy: Record<StitchErrorCode, string> = { …, RATE_LIMITED: '…' }
+// after — add the seven managed-file codes (or use Partial<Record<…>>)
+```
+
+Unexpected IO stays scrubbed as `INTERNAL_SERVER_ERROR`: the new codes are the
+caller-safe ones only.
+
+### `ScopedAuthHook` is nominal
+
+A hand-written function shaped like an auth hook is no longer assignable —
+identity now comes from the factory, so scope ownership and the inferred
+context cannot drift apart:
+
+```ts
+// before — a structural stand-in
+const auth: ScopedAuthHook<Scopes> = async (ctx, endpoint) => { … }
+// after — create it, then compose domains
+const auth = createAuthHook({ resolve, rules })
+const composed = composeAuthHooks({ hooks: [auth, billingAuth], defaultScope: 'public' })
+```
+
+### Managed-file inspectors also run on reads
+
+An inspector is no longer write-only, and it has a finite default deadline
+(15 s). Make it read-aware and idempotent — a read carries no
+`declaredMediaType`:
+
+```ts
+// before
+inspect: ({ declaredMediaType }) => inspectDeclaredType(declaredMediaType!)
+// after
+inspect: ({ prefix, declaredMediaType, signal }) =>
+  inspectBytes(prefix, { declaredMediaType, signal })
+```
+
+Set `inspectionTimeoutMs` explicitly when 15 seconds is the wrong budget.
+
+### Direct async-operation binding needs a wire-stable ID
+
+A direct binding reuses the start output as the follow-up wire input, so the ID
+schema must parse to itself (`z.input` equals `z.output`, no transform,
+coercion, default or overwrite). Anything else is parsed twice:
+
+```ts
+// before — a transform silently ran on start and again on every follow-up
+defineAsyncOperationContract({ binding: 'direct', id: z.string().transform(Number) })
+// after — keep the wire shape, adapt explicitly
+defineAsyncOperationContract({
+  binding: 'adapted',
+  id,
+  adapters: { idFromStart, inputFor },
+})
+```
+
+## Released migration: 0.55.0
+
+### Peer-free `implementRemote`
+
+`implementRemote` now has one canonical, optional-peer-free owner. This keeps
+MCP SDK and AI SDK modules out of CLI bundles that only proxy HTTP calls:
+
+```ts
+// before
+import { implementRemote } from 'stitchkit/tools'
+// after
+import { implementRemote } from 'stitchkit/remote'
+```
+
+### Managed file boundary and strict auth returns
+
+Create one boundary during application bootstrap and pass the capability, never
+a per-call directory or host path:
+
+```ts
+import { createManagedFileBoundary } from 'stitchkit/files'
+
+const files = await createManagedFileBoundary({ root: '/srv/app-files' })
+
+// before
+defineDownloadTool({ defaultDir: '/srv/app-files', resolveUrl, ...common })
+defineUploadTool({ upload: (path) => provider.uploadFile(path), ...common })
+defineViewFileTool({ baseDir: '/srv/app-files', ...common })
+
+// after
+defineDownloadTool({ files, resolveUrl, ...common })
+defineUploadTool({ files, upload: ({ bytes }) => provider.upload(bytes), ...common })
+defineViewFileTool({ files, ...common })
+```
+
+Downloaded `path` is now relative to the boundary and MIME metadata is named
+`mediaType`. Update raw `mountDownload`/`mountUpload`/`mountViewFile` configs the
+same way. Auth predicates must explicitly return `true`, `false`, or a plain
+object of context fields; replace accidental `undefined` fallthroughs with the
+intended boolean.
+
 ## Released migration: 0.53.0
 
 ### Realtime `emit` returns `boolean` instead of `void`