stitchkit 0.113.3 → 0.114.1

package/llms/stitchkit.txt

@@ -75,7 +75,8 @@ own, recorded as an ADR.
 | `stitchkit/process/owner-loss` | bundled server entry (Bun, POSIX) | evolving | narrow bootstrap that keeps the process runner lazy while carrying its owner-loss guard in a single-file bundle |
 | `stitchkit/files/packaging` | build time (Bun or Node) | evolving | installed native asset graph, integrity, Bun packaging plugin and the artifact loader check; no runtime install policy |
 | `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
-| `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification, send-failure classification, resumable broadcasts, the operator channel with dedupe, a Bot API transport that separates a request that never left from an unknown outcome, local Bot API files, webhook ownership and durable webhook update intake |
+| `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification, send-failure classification, one outbound budget per bot token with weighted albums and shared 429 pauses, resumable broadcasts, the operator channel with dedupe, a Bot API transport that separates a request that never left from an unknown outcome, local Bot API files, webhook ownership and durable webhook update intake |
+| `stitchkit/telegram/grammy` | server (Bun or Node) | evolving | the token's outbound budget as one grammY client transformer — a 429 that comes back as a response pauses the token, and a cancelled wait is a request that never left |
 | `stitchkit/telegram/html` | browser and server | evolving | Telegram's HTML as a tree — clean any markup to what Telegram accepts, cut long text into valid parts by what the reader sees, check markup before it is sent |
 | `stitchkit/telegram/screens` | server (Bun or Node) | evolving | a bot's menus as declared screens over grammY — typed paths, actions and input, message reconciliation, state in any `StorageAdapter`, a test chat |
 | `stitchkit/tracking` | browser **and** server | evolving | visitor-tracking mechanics — `createTrackingClient`, the tab-shared outbox, the page-leave beacon, attribution, the contract factory; no event vocabulary, no React |
@@ -85,12 +86,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 58 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 59 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/agent-runtime` | server | evolving<br>_redefined in 24 of the 58 minors since 0.56.2, most recently 0.113.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `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/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 |
@@ -102,7 +104,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 58 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 59 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 |
@@ -215,6 +217,7 @@ map — feature → packages:
 | MCP Apps UI widgets | `@modelcontextprotocol/ext-apps` |
 | React data layer (`stitchkit/react`) | `@tanstack/react-query` `react-query-kit` |
 | Keyboard layers and list zones (`stitchkit/react/keyboard`) | `react` |
+| Keyboard test bed (`stitchkit/react/keyboard/testing`) | — (peer-free) |
 | MaxMind GeoIP (`stitchkit/geo`) | `maxmind` |
 | Browser OAuth client (`stitchkit/oauth`) | — |
 | Google OIDC verifier (`stitchkit/google`) | `google-auth-library` |
@@ -224,6 +227,7 @@ map — feature → packages:
 | grammY lifecycle adapters (`stitchkit/application/grammy`) | `grammy` |
 | Telegram platform primitives (`stitchkit/telegram`) | — (peer-free) |
 | Telegram message markup (`stitchkit/telegram/html`) | — (peer-free) |
+| Telegram grammY client transformer (`stitchkit/telegram/grammy`) | `grammy` (types only; the bot brings it) |
 | Telegram screens (`stitchkit/telegram/screens`) | `grammy` (types only; the bot brings it) |
 | OpenTelemetry gauges (`stitchkit/application/opentelemetry`) | `@opentelemetry/api` |
 
@@ -789,121 +793,3 @@ const tenantApi = createClients({ users, posts }, http, {
 Every method now requires `tenantId`, and the callback sees it as a `string`.
 The batch form delegates to the same single-contract client runtime, including
 HTTP exposure filtering, multipart, raw responses and output validation.
-
-## Chunked uploads
-
-A file larger than one request goes as three calls of the application's own
-contract — open, parts, finish — driven by `uploadInChunks` on the client and
-held by `createChunkSpool` (`stitchkit/files`) on the server. The contract stays
-the application's: its fields, its limits, what happens to the finished file.
-
-```ts
-// shared: one part size for both halves
-export const CHUNK_BYTES = 4 * 1024 * 1024
-
-// contract
-init: {
-  method: 'POST', path: '/uploads', desc: 'Open an upload',
-  input: z.object({ uploadId: z.string(), totalBytes: z.number(), chunkCount: z.number(), name: z.string() }),
-  output: z.object({ finished: Accepted.optional() }),
-},
-chunk: {
-  method: 'PUT', path: '/uploads/:uploadId/chunks/:index', desc: 'Send one part',
-  params: z.object({ uploadId: z.string(), index: z.coerce.number() }),
-  multipart: { files: { bytes: {} } },
-  output: z.object({ state: z.enum(['stored', 'repeated']) }),
-},
-finalize: {
-  method: 'POST', path: '/uploads/:uploadId/finalize', desc: 'Assemble the file',
-  params: z.object({ uploadId: z.string() }),
-  output: Accepted,
-},
-```
-
-```ts
-// server
-import { createChunkSpool } from 'stitchkit/files'
-
-const spool = createChunkSpool({
-  directory: env.UPLOAD_SPOOL_DIR,
-  chunkBytes: CHUNK_BYTES,
-  maxFileBytes: 1024 * 1024 * 1024,
-  meta: z.object({ name: z.string() }),
-})
-
-implement(contract, {
-  init: async ({ input, ctx }) => {
-    const done = await findFinished(input.uploadId) // the app's own record
-    if (done) return { finished: done }
-    await spool.open({ owner: ctx.user.id, ...input, meta: { name: input.name } })
-    return {}
-  },
-  chunk: async ({ params, files, ctx }) => ({
-    state: await spool.put({ owner: ctx.user.id, ...params, bytes: files.bytes }),
-  }),
-  finalize: async ({ params, ctx }) => {
-    const key = { owner: ctx.user.id, uploadId: params.uploadId }
-    const file = await spool.assemble(key) // file.stream(), file.chunkPaths, file.meta
-    const accepted = await store(file)
-    await spool.discard(key)
-    return accepted
-  },
-})
-```
-
-```ts
-// client — Bun, Node, a browser or React Native
-import { uploadInChunks } from 'stitchkit'
-
-const accepted = await uploadInChunks({
-  file,
-  chunkBytes: CHUNK_BYTES,
-  signal,
-  onProgress: ({ sentBytes, totalBytes }) => draw(sentBytes / totalBytes),
-  init: async (start, options) => {
-    const opened = await api.uploads.init.withOptions({ ...start, name: file.name }, options)
-    return opened.finished ? { finished: opened.finished } : undefined
-  },
-  chunk: (part, options) => api.uploads.chunk.withOptions(part, options),
-  finalize: (upload, options) => api.uploads.finalize.withOptions(upload, options),
-})
-```
-
-The rules the two halves share:
-
-- **The client mints the upload id** (default `crypto.randomUUID()`, fresh per
-  call), so a repeated `init` is the same upload. The spool keys it by `owner`
-  too — the same id from another owner is another upload. To resume after the
-  app restarts instead of sending the file again, pass a stable `uploadId` —
-  the id of the app's own job or attempt.
-- **The file is anything with `size` and `slice(start, end)`** (`ChunkSource`).
-  A `Blob` is one; so is a platform file that is not a DOM `Blob`, such as an
-  Expo `File`, passed without a cast. A part's `bytes` is what `slice`
-  returns, so the part call hands it to the client as the multipart file.
-- **A part is idempotent.** The spool keeps a size+sha256 receipt per index:
-  the same bytes again answer `'repeated'`, other bytes `UPLOAD_CONFLICT`
-  (409). So the driver repeats `init` and a part on a failure that may pass — no
-  answer (network, timeout), `429`, `5xx` — up to `retries` times (default 3)
-  with a doubling pause from `retryDelayMs` (default 1 s). A refusal is final.
-- **`finalize` is never repeated.** After it the application owns the file and
-  the parts are gone; a lost answer is recovered by `init` returning
-  `{ finished }`, which the driver hands back without sending a byte.
-- **Cancellation is checked between parts**, so a cancelled upload never
-  reaches `finalize`.
-- **Every part but the last is exactly `chunkBytes`** and `chunkCount` must add
-  up; the spool refuses anything else with a 4xx `AppError`
-  (`ChunkSpoolErrorCode`), which a handler can let through as the client's
-  typed error. An application that maps error codes onto its own must map
-  these too — `isChunkSpoolErrorCode` / `CHUNK_SPOOL_ERROR_CODES` from
-  `stitchkit/files` — or a refusal reaches its client as an unknown 500.
-- **Progress counts file bytes**, inside a part too — the driver passes
-  `onUploadProgress` into the part call, so the [upload
-  progress](#upload-progress) route of the client applies. A repeated part
-  counts again from its start.
-- The first writer of a part wins across processes: its data file is named by
-  its hash and its receipt is published by an exclusive link. `sweep()` removes
-  uploads untouched for `staleAfterMs` (default 24 h); run it on a schedule.
-
-Part size is a latency decision: every part costs a round trip, so on a
-200 ms link a smaller part buys smoother progress at the price of a slower
-upload.

package/llms/telegram-grammy.txt

@@ -0,0 +1,22 @@
+# stitchkit/telegram/grammy — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/telegram/grammy`  (docs/api/reference.md)
+
+==============================================================================
+# API reference: `stitchkit/telegram/grammy`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/telegram/grammy`
+
+The token's outbound budget as one grammY client transformer. Server-only, Bun
+or Node; `grammy` appears in the declarations and is never imported at run time —
+the bot brings it. → ADR 0274 — [guide](../guide/telegram.md#one-token-one-outbound-budget)
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `telegramBudgetTransformer` | function | `bot.api.config.use(telegramBudgetTransformer(budget))`: every Bot API call runs under the token's `telegramOutboundBudget`; a 429 that comes back as a response pauses the token, a cancellation before the request was handed on throws `TelegramNotDispatchedError`, a cancellation in flight stays the client's own error; it never retries |
+
+---

package/llms/telegram.txt

@@ -86,6 +86,79 @@ The error line contract, for whatever recognises a failure from the journal: a
 line whose `level` is `50` or more is an error. There is no separate `fatal`;
 an unrecoverable end is an `error` line followed by a non-zero exit.
 
+## One token, one outbound budget
+
+Telegram counts a bot's bulk messages per token, not per campaign, handler or
+module. `telegramOutboundBudget` is that budget once: every alias of one token
+in the process gets the same object, another token gets another, and every send
+through it spends its weight. → [ADR 0274](../decisions/0274-a-telegram-token-has-one-outbound-budget.md).
+
+```ts
+import { telegramOutboundBudget } from 'stitchkit/telegram'
+import { telegramBudgetTransformer } from 'stitchkit/telegram/grammy'
+
+const budget = telegramOutboundBudget({
+  token: env.BOT_TOKEN,
+  messagesPerSecond: 24,
+})
+
+// The one transformer of the bot's client. No second limiter, no second
+// scheduler: campaigns, replies and every other send of this token share it.
+bot.api.config.use(telegramBudgetTransformer(budget))
+```
+
+`telegramBudgetTransformer` is the whole wiring for grammY. Without it the
+adapter is `budget.run(method, payload, signal, () => previous(method, payload, signal))`
+inside your own `config.use` closure; that works too, but grammY types its signal
+as the `abort-controller` polyfill's, so the closure has to pass `undefined` or
+cast, and a send cancelled in the queue then waits for its slot and fails as
+`unknown`. The transformer takes grammY's signal as it is.
+
+- **The token is the identity, not the sender.** Two bot objects built from one
+  token share the budget; two different tokens do not. The registry keeps a
+  128-bit identity, never the credential, and `stats()` contains no token.
+- **A message is the unit.** `sendMediaGroup` and `sendPaidMedia` cost their
+  media length, `copyMessages` and `forwardMessages` cost their message ids, and
+  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.
+- **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
+  is released at the deadline and the queue continues one interval at a time,
+  never as a stampede.
+- **It paces; it does not retry.** `run` calls the send once. A 429 pauses the
+  token for Telegram's `retry_after` (or `retryAfterFallbackMs` when Telegram
+  gave none) and rethrows; the caller's retry policy decides what happens next.
+  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
+  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.
+- **A wait can be cancelled.** `run`/`acquire` take an `AbortSignal`; a
+  cancelled waiter spends no slot and calls no provider. Through
+  `telegramBudgetTransformer` a send cancelled before it was handed to the client
+  throws `TelegramNotDispatchedError` (`classifyTelegramSendFailure` says
+  `not-dispatched`, safe to repeat); a send cancelled after it was handed on is
+  the client's own error — not evidence that Telegram did not accept it — so
+  keep the outcome unknown rather than retrying it as a definite failure.
+- **Non-send retries wait without spending.** An edit or delete retry that got
+  a 429 first records the pause with `budget.pauseAfter(error)` (the `run` path
+  does this itself), then uses `await budget.waitUntilResumed(signal)`; it shares
+  the token's pause but does not take a message slot.
+
+`telegramBroadcastSender` and `telegramOperatorSender` still send through
+`callTelegramBotApi`; they are not a second budget. Their returned function does
+not expose the method and payload, so a product that uses one wraps the concrete
+`sendMessage`/`copyMessage` call in `budget.run` where it knows both, or passes
+its own sender. There is no generic wrapper around the opaque sender.
+`runTelegramBroadcast` keeps its per-run `ratePerSecond` and the operator
+channel keeps its per-chat `minIntervalMs`; those are caps of their own jobs,
+not another token quota. The token budget is the binding shared cap.
+
 ## The operator channel
 
 The chat where people read about new users, payments and failures is not the
@@ -519,7 +592,7 @@ can read its media.
 Peer-free server-only Telegram platform primitives — the Bot API's own
 protocols and the jobs every bot rewrote around them. Importing this resolves no
 bot library; `stitchkit/application/grammy` remains the lifecycle adapter for an
-injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
+injected grammY bot. → ADR 0143, ADR 0201, ADR 0274 — [guide](../guide/telegram.md)
 
 | Export | Kind | Summary |
 |--------|------|---------|
@@ -534,7 +607,8 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 | `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 |
+| `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 |
 | `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/{upgrading-0.103.13-0.113.0.txt → upgrading-0.104.0-0.114.0.txt}

@@ -1,14 +1,56 @@
-# Upgrading 0.103.13 → 0.113.0 — stitchkit docs slice
+# Upgrading 0.104.0 → 0.114.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.103.13 → 0.113.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.104.0 → 0.114.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.103.13 → 0.113.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.104.0 → 0.114.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.114.0
+
+**Who must act:** code with an exhaustive `switch` or `Record` over
+`TelegramSendFailureReason` or `TELEGRAM_SEND_FAILURE_REASONS`. Code that only
+reads `retryable` and `recipientUnreachable` needs no change.
+
+`classifyTelegramSendFailure` now returns `reason: 'bot-to-bot-disabled'` for a
+`400 USER_BOT_TO_BOT_DISABLED` ([ADR 0274](../decisions/0274-a-telegram-token-has-one-outbound-budget.md)).
+It is permanent for that send, so it is not retried; it is **not**
+`recipientUnreachable`, because Telegram disables bot-to-bot messaging when
+either bot has not enabled its Bot to Bot setting, and the missing setting may
+be the sender's.
+
+1. Add the reason to every exhaustive mapping:
+
+   ```ts
+   // before
+   const code: Record<TelegramSendFailureReason, string> = { /* … */ unknown: 'E_UNKNOWN' }
+   // after
+   const code: Record<TelegramSendFailureReason, string> = {
+     /* … */ 'bot-to-bot-disabled': 'E_BOT_TO_BOT', unknown: 'E_UNKNOWN',
+   }
+   ```
+
+   Search pattern: `TelegramSendFailureReason`, `TELEGRAM_SEND_FAILURE_REASONS`
+   and every `switch` over a send-failure reason.
+2. Type-check: the exhaustive table without the new member fails to compile.
+3. If the application wants one outbound budget per bot token, opt in at the
+   one transformer that already owns its Bot API calls:
+
+   ```ts
+   import { telegramOutboundBudget } from 'stitchkit/telegram'
+
+   const budget = telegramOutboundBudget({ token: env.BOT_TOKEN })
+   api.config.use((previous, method, payload, signal) =>
+     budget.run(method, payload, signal, () => previous(method, payload, signal)),
+   )
+   ```
+
+   Remove the old limiter rather than running it beside this one. See the
+   [Telegram guide](telegram.md#one-token-one-outbound-budget).
+
 ## Released migration: 0.113.0
 
 **Who must act:** custom `AgentRuntimeStoreDriver` adapters and custom `AgentRuntimeStore` implementations of `seedConversationInput`. The built-in memory and SQLite stores already implement the contract.
@@ -814,84 +856,3 @@ signals to `createCli` / `createCliInvoker` and cooperative handlers observe `ct
 `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
-
-**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.
-bun build src/native.ts --target=bun --outfile=dist/native.js
-# After: retain every output, with its relative path.
-bun build src/native.ts --target=bun --outdir=dist --entry-naming=native.js
-```
-
-For `Bun.build`, copy **all** `result.outputs`, not just the JS entry or `outputs[0]`.
-A single-file JS distribution cannot embed a native `.node` addon automatically.
-An archive may contain JS plus companion assets, materialized together before execution.
-Custom output layout uses the evolving build-only packaging contract in the
-[native IO guide](native-io.md#public-native-packaging).
-
-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 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
-
-**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.