# ADR 0274: A Telegram token has one outbound budget

> Source: https://github.com/max-listov/stitchkit/blob/master/docs/decisions/0274-a-telegram-token-has-one-outbound-budget.md

---

# ADR 0274 — A Telegram token has one outbound budget

## Context

Telegram counts a bot's bulk messages per token. A bot sends through several
paths: a marketing campaign, a reply in a handler, an operator note, a retry
after a rate limit. Each path can be paced below the limit on its own and the
sum can still be over it, so the limit has to be counted once for the token.

Two ways of counting existed in consuming applications. One kept a token bucket
per token with a full initial bucket and a refill: it released a saved burst at
start and again after a 429 pause, which is exactly when the next message is
most expensive. The other paced one broadcast run at a fixed rate and left every
other sender alone. Neither expressed the unit that Telegram counts — an album
of N media is N messages, a `copyMessages` of N ids is N messages, and the call
to action after an album is one more.

The primitive is provider-specific: the budget belongs to a Telegram token, the
cost belongs to Bot API methods, and the pause comes from Telegram's
`parameters.retry_after`. It is not a durable job queue and not a cross-process
lock. This ADR replaces only the token-wide part of ADR 0201's position that a
429 on a bot's own replies stays the application's; the application still owns
the retry policy and the wording a person reads.

## Decision

**`stitchkit/telegram` owns one outbound budget per bot token.** A
`telegramOutboundBudget({ token, messagesPerSecond })` returns one object for
that token in the process. A second call for the same token returns the same
object; a call with different options is refused, because two policies for one
credential is the defect this exists to prevent. Another token is another
budget. The registry keeps a 128-bit identity of the token from the existing
`argumentsDigest`, never the credential; `stats()` and every refusal are
token-free.

**The schedule is strict, not a bucket with a burst.** The first call after idle
is immediate; after that each call occupies `cost / messagesPerSecond` of the
timeline. The budget keeps one `nextGrantAt` and one `pausedUntil`:

```text
at = max(now, nextGrantAt, pausedUntil)
grant head at at
nextGrantAt = at + cost * 1000 / messagesPerSecond
```

A classic bucket with capacity 24 would release 24 saved messages at start and
again on resume. That is the stampede a shared budget exists to prevent, so the
burst is one and the sustained rate is the declared rate. An album is weighted,
not one: `sendMediaGroup` and `sendPaidMedia` cost their media length,
`copyMessages` and `forwardMessages` cost their ids, and every other
message-producing method costs one. A non-message method (`getMe`, `getFile`,
an edit, a delete) costs nothing.

**A 429 pauses every sender of the token.** The pause is
`max(pausedUntil, now + retry_after)`; a second, shorter instruction never
shortens it. Telegram's number is used when present; when it is absent the
caller's declared `retryAfterFallbackMs` is a local policy, not a provider fact.
After the pause the next grant is at the deadline and the following one is one
interval later — the queue is not released as a batch. `waitUntilResumed` lets
an edit or delete retry share the pause without taking a message slot.

**The primitive paces; it does not retry.** `budget.run(method, payload, signal,
send)` is the narrow adapter a client transformer calls around its existing
send. It waits for the weighted slot, checks the signal, calls `send` once, and
rethrows. A 429 pauses and is rethrown. A network failure or a 5xx is rethrown
unchanged and does not pause the token: repeating a send whose external outcome
is unknown is the caller's decision, and a primitive that retried it would turn
one unknown message into two. A cancelled waiter leaves the queue without
spending a slot and without calling the provider. A granted call whose send is
then aborted owns its slot; the outcome is unknown, not a definite failure.

**The budget is process-local.** It does not coordinate two processes or two
machines that hold the same token. That is the application's deployment
boundary, and pretending otherwise would be a second distributed lock. The
primitive also owns no job state: a resumable broadcast keeps its own journal
and per-run pacing; the operator channel keeps its per-chat pacing. Those are
caps of their own jobs, not a second token quota. A product that uses one of
those senders wraps its `send` with the same `budget.run`, and removes its old
limiter rather than running both.

## Alternatives

- **Keep pacing in each product.** Rejected: the limit is per token, so each
  product either duplicates the arithmetic or gets the sum wrong. A product that
  shares its token with a campaign is the ordinary case, not an edge.
- **A generic rate limiter in the core.** Rejected: the unit is a Telegram
  message, the pause field is `retry_after`, and the weighted methods are the
  Bot API's. A provider-neutral limiter would push the only interesting part
  back into every caller.
- **A cross-process budget in Redis or a database.** Rejected for this
  primitive: it is a second distributed coordination mechanism, and the
  deployment that needs it already owns a durable queue. The SDK states the
  process-local boundary instead.
- **A full token bucket with capacity 24.** Rejected: it produces the initial
  burst and the post-429 stampede the shared budget is meant to remove. A
  caller that wants a small burst can build it above this primitive, where the
  policy is visible.

## Consequences

- A product's one Bot API client installs one transformer; the old limiter and
  its retry are deleted in the same cutover. The standard senders remain
  per-run/per-chat paced; wrapping their `send` is the documented way to share
  the token budget.
- `telegramOutboundBudget` is an evolving `stitchkit/telegram` export. The
  five consuming products migrate in their own release waves after the SDK
  publication; this repository does not claim their cutover.
- `USER_BOT_TO_BOT_DISABLED` becomes `bot-to-bot-disabled`: permanent for the
  send, not recipient-unreachable, because Telegram reports it when either bot
  has not enabled Bot to Bot messaging. The new union member is a breaking
  change for exhaustive consumer tables and carries the usual migration.
- `stats()` reports granted calls, weighted messages, queue depth and the
  remaining pause. It is diagnostic, not a billing or delivery receipt.
- Cross-process budgets, durable campaign state and the retry policy stay
  outside this primitive.

Serves **I8** (one owner for the token's outbound budget), **I9** (every
declared option is load-bearing), **I10** (finite waits and a bounded queue at
the provider boundary), **I13** (only observed facts: no invented wait, no
unknown outcome retried as a definite failure) and **I14** (the new reason is a
marked, migrated break).

## Amendment (0.114.1): a refusal arrives as a response, and grammY's wiring is one transformer

The first release read a 429 only from the exception `send()` threw. A grammY
client transformer never sees one: `callApi` receives the Bot API's
`{ ok: false, error_code: 429, parameters: { retry_after } }` as the **value**
the transformer chain returns and builds the `GrammyError` after the chain has
finished. The documented wiring therefore paced and never paused, and the
tests, which threw an error from `send`, could not tell. A consuming project
measured it: the first send got a 429 with `retry_after: 2` and the next send,
to another chat, left 40 ms later.

- **`run` reads both shapes.** A `send` that resolves with a record whose `ok` is
  `false` is classified exactly as a thrown refusal is: a rate limit pauses the
  token for the stated `retry_after` or the declared fallback, any other answer
  does nothing, and the response is returned unchanged. The mechanism is fixed in
  the one owner, so every client already wired through `run` is repaired without
  a change of its own.
- **The grammY wiring is one function, in its own entrypoint.**
  `stitchkit/telegram/grammy` exports `telegramBudgetTransformer(budget)`. The
  type that grammY gives a transformer (`Transformer`) names its response per
  method, which a structural type cannot express without a cast at the call
  site; naming it in `stitchkit/telegram` would make that peer-free entrypoint
  depend on `grammy`. The new entrypoint follows `stitchkit/telegram/screens`:
  grammY in the declarations, never imported at run time.
- **A cancelled wait is a request that never left.** grammY types the signal it
  passes a transformer as the `abort-controller` polyfill's, so a hand-written
  closure passed `undefined` and a send cancelled in the queue waited for its
  slot and failed as `unknown`. The transformer bridges the signal and throws
  `TelegramNotDispatchedError` when the cancellation arrives before the request
  was handed to the client — in the queue, or in the instant after the grant,
  when the slot is spent and nothing was sent. A cancellation after the request
  was handed on stays the client's own error and the outcome stays unknown.
  `run` itself still rejects with `signal.reason`: that contract is unchanged.

The test that pins this uses grammY's own `Api` over a `fetch` that answers 429
the way Telegram does. A test that throws from `send` proved only the path
nobody takes.
