stitchkit 0.113.2 → 0.114.0

package/llms/stitchkit.txt

@@ -75,7 +75,7 @@ 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/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 +85,12 @@ 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/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 +102,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 |

package/llms/telegram.txt

@@ -86,6 +86,67 @@ 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'
+
+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.
+api.config.use((previous, method, payload, signal) =>
+  budget.run(method, payload, signal, () => previous(method, payload, signal)),
+)
+```
+
+- **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.
+  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. A granted send that is
+  then aborted is not evidence that Telegram did not accept it — 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 +580,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 +595,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, `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.