stitchkit 0.113.3 → 0.114.0

package/CHANGELOG.md

@@ -15,6 +15,19 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.114.0] - 2026-10-30
+
+### ⚠️ Breaking changes
+
+**Who must act:** code with an exhaustive `switch` or `Record` over `TelegramSendFailureReason` or `TELEGRAM_SEND_FAILURE_REASONS`, or a consumer table that must handle every reason. Code that only reads `retryable` and `recipientUnreachable` needs no change.
+
+- `stitchkit/telegram` — **`TelegramSendFailureReason` gains `bot-to-bot-disabled`.** A `400 USER_BOT_TO_BOT_DISABLED` is now a permanent refusal instead of `unknown`; it is not retried and does not mark the recipient unreachable, because Telegram reports it when either bot has not enabled Bot to Bot messaging. Before: the reason was `unknown` and an exhaustive table compiled. After: add the reason and decide how to report it (`retryable: false`, `recipientUnreachable: false`). → ADR 0274
+  **Affects:** `stitchkit/telegram` TelegramSendFailureReason, TELEGRAM_SEND_FAILURE_REASONS, classifyTelegramSendFailure(reason)
+
+### Added
+
+- `stitchkit/telegram` — `telegramOutboundBudget` gives one bot token one process-wide outbound budget: aliases of the token share it, different tokens are independent, `sendMediaGroup`/`sendPaidMedia` cost their media length, `copyMessages`/`forwardMessages` cost their message ids, and a 429 pauses every sender of the token. `budget.run(method, payload, signal, send)` is the transformer adapter; it paces, never retries and leaves a network/5xx outcome to the caller. The `stitchkit/telegram` surface ceiling rises from 98 to 102 names for the function and its three public types.
+
 ## [0.113.3] - 2026-10-30
 
 ### Fixed

package/dist/entrypoints/telegram/screens.js

@@ -4,7 +4,7 @@ import {
 } from "../../index-m38ej7e5.js";
 import {
   classifyTelegramEditRefusal
-} from "../../index-xvj9h8yh.js";
+} from "../../index-hs35ss3p.js";
 import {
   checkTelegramHtml2
 } from "../../index-rz3z13e9.js";

package/dist/entrypoints/telegram.d.ts

@@ -6,6 +6,7 @@ export { createTelegramLocalFiles, TelegramLocalFileError, type TelegramLocalFil
 export { TelegramNotDispatchedError, type TelegramNotDispatchedStage, } from '../telegram/not-dispatched.js';
 export { createTelegramOperatorChannel, type TelegramChatId, type TelegramOperatorChannel, type TelegramOperatorChannelConfig, type TelegramOperatorDrop, type TelegramOperatorMessage, type TelegramOperatorSenderConfig, telegramOperatorSender, } from '../telegram/operator-channel.js';
 export { createTelegramOperatorDedupe, type TelegramOperatorDedupe, type TelegramOperatorDedupeVerdict, } from '../telegram/operator-dedupe.js';
+export { type TelegramOutboundBudget, type TelegramOutboundBudgetConfig, type TelegramOutboundBudgetStats, telegramOutboundBudget, } from '../telegram/outbound-budget.js';
 export { classifyTelegramSendFailure, TELEGRAM_SEND_FAILURE_REASONS, type TelegramSendFailure, type TelegramSendFailureReason, } from '../telegram/send-failure.js';
 export { createTelegramBotTransport, type TelegramBotTransportOpen, type TelegramBotTransportOptions, type TelegramBotTransportResolve, type TelegramBotTransportSocket, type TelegramFetch, } from '../telegram/transport.js';
 export { createTelegramUpdateIntake, type TelegramUpdateAttemptContext, type TelegramUpdateAttemptIntakeConfig, type TelegramUpdateEnvelope, type TelegramUpdateExhaustion, type TelegramUpdateExhaustionFailure, type TelegramUpdateFailure, type TelegramUpdateIntake, type TelegramUpdateIntakeConfig, type TelegramUpdateIntakeOptions, TelegramUpdateOwnershipLostError, type TelegramUpdateStoreStep, } from '../telegram/update-intake.js';

package/dist/entrypoints/telegram.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telegram.d.ts","sourceRoot":"","sources":["../../src/entrypoints/telegram.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"telegram.d.ts","sourceRoot":"","sources":["../../src/entrypoints/telegram.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,0BAA0B,EAC1B,KAAK,kBAAkB,EACvB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,oBAAoB,EACpB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,EAClC,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,wBAAwB,EAC7B,8BAA8B,GAC/B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,4BAA4B,EACjC,KAAK,6BAA6B,EAClC,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,GAC9B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,0BAA0B,EAC1B,KAAK,0BAA0B,GAChC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,6BAA6B,EAC7B,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,4BAA4B,EACjC,sBAAsB,GACvB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,4BAA4B,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,GACnC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,sBAAsB,GACvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,2BAA2B,EAC3B,6BAA6B,EAC7B,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,GAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,0BAA0B,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,aAAa,GACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,0BAA0B,EAC1B,KAAK,4BAA4B,EACjC,KAAK,iCAAiC,EACtC,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,+BAA+B,EACpC,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,EAChC,gCAAgC,EAChC,KAAK,uBAAuB,GAC7B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,yBAAyB,EACzB,KAAK,oBAAoB,EACzB,KAAK,8BAA8B,EACnC,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,6BAA6B,EAClC,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,EACL,KAAK,iCAAiC,EACtC,2BAA2B,EAC3B,iCAAiC,EACjC,KAAK,qBAAqB,GAC3B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,KAAK,+BAA+B,EACpC,yBAAyB,EACzB,KAAK,sBAAsB,GAC5B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EACL,KAAK,0BAA0B,EAC/B,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,6BAA6B,EAClC,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,yBAAyB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/entrypoints/telegram.js

@@ -11,7 +11,7 @@ import {
   isTelegramNotDispatchedError,
   TELEGRAM_SEND_FAILURE_REASONS2,
   classifyTelegramSendFailure2
-} from "../index-xvj9h8yh.js";
+} from "../index-hs35ss3p.js";
 import {
   TELEGRAM_TEXT_LIMIT2,
   truncateTelegramHtml2
@@ -35,6 +35,9 @@ import {
 import {
   untilAborted
 } from "../index-a5qr2rj6.js";
+import {
+  argumentsDigest
+} from "../index-r7a7r7ha.js";
 import {
   isRecord,
   transportResult
@@ -898,6 +901,242 @@ function telegramOperatorSender(config) {
     ...config.fetch && { fetch: config.fetch }
   });
 }
+// src/telegram/outbound-budget.ts
+import { z as z5 } from "zod";
+var DEFAULT_MESSAGES_PER_SECOND = 24;
+var DEFAULT_RETRY_AFTER_FALLBACK_MS = 1000;
+var TOKEN = z5.string().min(1, "token must not be empty");
+var MESSAGES_PER_SECOND = z5.number().positive().max(1000);
+var RETRY_AFTER_FALLBACK_MS = z5.number().int().nonnegative().max(MAX_TIMER_MS);
+var SEND_METHODS = new Set([
+  "sendMessage",
+  "sendPhoto",
+  "sendAudio",
+  "sendDocument",
+  "sendVideo",
+  "sendAnimation",
+  "sendVoice",
+  "sendVideoNote",
+  "sendPaidMedia",
+  "sendMediaGroup",
+  "sendLocation",
+  "sendVenue",
+  "sendContact",
+  "sendPoll",
+  "sendChecklist",
+  "sendDice",
+  "sendMessageDraft",
+  "sendSticker",
+  "sendInvoice",
+  "sendGame",
+  "sendGift",
+  "sendGiveaway",
+  "sendLivePhoto",
+  "sendRichMessage",
+  "copyMessage",
+  "copyMessages",
+  "forwardMessage",
+  "forwardMessages",
+  "answerWebAppQuery"
+]);
+var WEIGHTED_METHODS = new Map([
+  ["sendMediaGroup", "media"],
+  ["sendPaidMedia", "media"],
+  ["copyMessages", "message_ids"],
+  ["forwardMessages", "message_ids"]
+]);
+function sendCost(method, payload) {
+  if (!SEND_METHODS.has(method))
+    return 0;
+  const field = WEIGHTED_METHODS.get(method);
+  if (field === undefined || !isRecord(payload))
+    return 1;
+  const value = payload[field];
+  return Array.isArray(value) ? Math.max(1, value.length) : 1;
+}
+function createBudget(rate, fallback, now, sleepFor) {
+  const interval = 1000 / rate;
+  const queue = [];
+  let nextGrantAt = now();
+  let pausedUntil = Number.NEGATIVE_INFINITY;
+  let granted = 0;
+  let messages = 0;
+  let draining = false;
+  let wake;
+  const wait = async (milliseconds, signal) => {
+    const delay = Math.min(MAX_TIMER_MS, Math.max(0, milliseconds));
+    if (delay <= 0)
+      return;
+    const pending = sleepFor(delay, signal);
+    if (signal)
+      await raceAbort(pending, signal);
+    else
+      await pending;
+  };
+  const wakeWaiting = () => {
+    const current = wake;
+    wake = undefined;
+    current?.abort();
+  };
+  const remove = (waiter) => {
+    const index = queue.indexOf(waiter);
+    if (index === -1)
+      return;
+    queue.splice(index, 1);
+    if (index === 0)
+      wakeWaiting();
+  };
+  const drain = async () => {
+    if (draining)
+      return;
+    draining = true;
+    try {
+      while (queue.length > 0) {
+        const head = queue[0];
+        if (head === undefined)
+          break;
+        if (head.signal?.aborted) {
+          remove(head);
+          continue;
+        }
+        const current = now();
+        const at = Math.max(current, nextGrantAt, pausedUntil);
+        if (at > current) {
+          const controller = new AbortController;
+          wake = controller;
+          try {
+            await wait(at - current, controller.signal);
+          } catch (error) {
+            if (!controller.signal.aborted) {
+              for (const waiter of queue.splice(0)) {
+                if (waiter.onAbort)
+                  waiter.signal?.removeEventListener("abort", waiter.onAbort);
+                waiter.reject(error);
+              }
+              return;
+            }
+          } finally {
+            if (wake === controller)
+              wake = undefined;
+          }
+          continue;
+        }
+        queue.shift();
+        if (head.onAbort)
+          head.signal?.removeEventListener("abort", head.onAbort);
+        nextGrantAt = at + head.cost * interval;
+        granted += 1;
+        messages += head.cost;
+        head.resolve();
+      }
+    } finally {
+      draining = false;
+      if (queue.length > 0)
+        drain();
+    }
+  };
+  const acquire = (cost, signal) => {
+    if (!Number.isSafeInteger(cost) || cost < 1) {
+      return Promise.reject(new RangeError("cost must be an integer of at least one message"));
+    }
+    if (signal?.aborted)
+      return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+      const waiter = { cost, resolve, reject, ...signal && { signal } };
+      if (signal) {
+        const onAbort = () => {
+          remove(waiter);
+          reject(signal.reason);
+        };
+        waiter.onAbort = onAbort;
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      queue.push(waiter);
+      drain();
+    });
+  };
+  const pauseFor = (milliseconds) => {
+    if (Number.isNaN(milliseconds) || milliseconds < 0) {
+      throw new RangeError("pause must be a non-negative number of milliseconds");
+    }
+    const duration = Number.isFinite(milliseconds) ? milliseconds : Number.MAX_SAFE_INTEGER;
+    pausedUntil = Math.max(pausedUntil, now() + duration);
+    wakeWaiting();
+  };
+  const pauseAfter = (error) => {
+    const failure = classifyTelegramSendFailure2(error);
+    if (failure.reason !== "rate-limited")
+      return;
+    pauseFor(failure.retryAfterSeconds === undefined ? fallback : failure.retryAfterSeconds * 1000);
+  };
+  const waitUntilResumed = async (signal) => {
+    while (true) {
+      if (signal?.aborted)
+        throw signal.reason;
+      const remaining = pausedUntil - now();
+      if (remaining <= 0)
+        return;
+      await wait(Math.min(remaining, MAX_TIMER_MS), signal);
+    }
+  };
+  const run = async (method, payload, signal, send) => {
+    if (signal?.aborted)
+      throw signal.reason;
+    const cost = sendCost(method, payload);
+    if (cost > 0)
+      await acquire(cost, signal);
+    if (signal?.aborted)
+      throw signal.reason;
+    try {
+      return await send();
+    } catch (error) {
+      pauseAfter(error);
+      throw error;
+    }
+  };
+  const budget = {
+    run,
+    acquire,
+    pause: pauseFor,
+    pauseAfter,
+    waitUntilResumed,
+    stats: () => ({
+      granted,
+      messages,
+      queued: queue.length,
+      messagesPerSecond: rate,
+      pausedForMs: Math.max(0, pausedUntil - now())
+    })
+  };
+  return budget;
+}
+var budgets = new Map;
+function keyOf(token) {
+  return `telegram-outbound:${argumentsDigest({ token })}`;
+}
+function telegramOutboundBudget(config) {
+  const token = TOKEN.parse(config.token);
+  const rate = MESSAGES_PER_SECOND.parse(config.messagesPerSecond ?? DEFAULT_MESSAGES_PER_SECOND);
+  const fallback = RETRY_AFTER_FALLBACK_MS.parse(config.retryAfterFallbackMs ?? DEFAULT_RETRY_AFTER_FALLBACK_MS);
+  const key = keyOf(token);
+  const existing = budgets.get(key);
+  if (existing) {
+    const same = existing.rate === rate && existing.fallback === fallback && existing.nowOption === config.now && existing.sleepOption === config.sleep;
+    if (!same) {
+      throw new Error("a Telegram outbound budget already exists for this token with different options");
+    }
+    return existing.budget;
+  }
+  const budget = createBudget(rate, fallback, config.now ?? (() => performance.now()), config.sleep ?? sleep);
+  budgets.set(key, {
+    budget,
+    rate,
+    fallback,
+    nowOption: config.now,
+    sleepOption: config.sleep
+  });
+  return budget;
+}
 // src/telegram/transport-connect.ts
 import { lookup } from "node:dns/promises";
 import { connect as connectTcp, isIP } from "node:net";
@@ -2609,6 +2848,7 @@ export {
   sqliteTelegramUpdateStore,
   telegramBroadcastSender,
   telegramOperatorSender,
+  telegramOutboundBudget,
   telegramWebhookUrl,
   verifyTelegramInitData
 };

package/dist/{index-xvj9h8yh.js → index-hs35ss3p.js}

@@ -32,6 +32,10 @@ var BY_DESCRIPTION = [
   [/user is deactivated|account is deactivated/i, "user-deactivated"],
   [/can'?t initiate conversation|need to start a conversation/i, "not-started"],
   [/chat not found|peer_id_invalid|user not found/i, "chat-not-found"],
+  [
+    /bot_to_bot_disabled|bot-to-bot messaging is disabled|bot to bot.*disabled/i,
+    "bot-to-bot-disabled"
+  ],
   [/too many requests|retry later|flood/i, "rate-limited"],
   [
     /message is too long|can'?t parse entities|message text is empty|wrong file identifier|button_url_invalid/i,
@@ -43,6 +47,7 @@ var TRAITS = {
   "user-deactivated": { retryable: false, recipientUnreachable: true },
   "chat-not-found": { retryable: false, recipientUnreachable: true },
   "not-started": { retryable: false, recipientUnreachable: true },
+  "bot-to-bot-disabled": { retryable: false, recipientUnreachable: false },
   "rate-limited": { retryable: true, recipientUnreachable: false },
   "message-invalid": { retryable: false, recipientUnreachable: false },
   "server-error": { retryable: true, recipientUnreachable: false },
@@ -82,13 +87,16 @@ function retryAfterOf(value, depth = 0) {
   return nested === value ? undefined : retryAfterOf(nested, depth + 1);
 }
 function descriptionOf(value, depth = 0) {
+  if (depth > 4)
+    return "";
   if (typeof value === "string")
     return value;
   if (value instanceof Error) {
-    const nested = isRecord(value) ? descriptionOf(value.cause, depth + 1) : "";
-    return `${value.message} ${nested}`.trim();
+    const own = isRecord(value) && typeof value.description === "string" ? value.description : "";
+    const nested = descriptionOf(value.cause, depth + 1);
+    return [own, value.message, nested].filter(Boolean).join(" ");
   }
-  if (!isRecord(value) || depth > 4)
+  if (!isRecord(value))
     return "";
   const own = typeof value.description === "string" ? value.description : "";
   const message = typeof value.message === "string" ? value.message : "";

package/dist/telegram/outbound-budget.d.ts

@@ -0,0 +1,99 @@
+/**
+ * One outbound budget for one Telegram bot token.
+ *
+ * Telegram counts a bot's bulk messages per token, not per subsystem. A bot
+ * that sends a marketing campaign, answers a person and posts an operator note
+ * through three senders has one limit, and three separate pacemakers cannot
+ * keep it: each of them is below the limit on its own and the sum is not.
+ *
+ * This is the one place that counts. The token names the budget; every alias
+ * of the same token in the process gets the same object, and another token is
+ * another budget. The unit is a Telegram message: `sendMediaGroup` and
+ * `sendPaidMedia` cost their media length, `copyMessages` and
+ * `forwardMessages` cost their message ids, and the follow-up call to action
+ * after an album is one more message.
+ *
+ * **It paces; it does not retry.** A 429 pauses every sender of the token for
+ * the wait Telegram stated (or a declared fallback when it stated none). A
+ * network failure or a 5xx is returned to the caller unchanged: 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.
+ *
+ * The schedule is a strict token budget, not a bucket with a full burst: the
+ * first call after an idle period is immediate, and every later call occupies
+ * its own `cost / messagesPerSecond` interval. A full bucket would release a
+ * saved burst at start and again after a 429 pause, which is exactly the
+ * stampede a shared budget exists to prevent.
+ */
+export interface TelegramOutboundBudgetConfig {
+    /** The bot token whose sends share this budget. It is never returned or logged. */
+    readonly token: string;
+    /** Telegram messages per second. Default 24. */
+    readonly messagesPerSecond?: number;
+    /**
+     * How long a 429 without `retry_after` pauses the token. Default 1000 ms.
+     * Telegram's own `retry_after` is always used instead when present.
+     */
+    readonly retryAfterFallbackMs?: number;
+    /**
+     * Test seam: the monotonic clock. Default `performance.now`. A wall clock can
+     * jump backwards and turn a pause into a burst, so the default is monotonic.
+     */
+    readonly now?: () => number;
+    /**
+     * Test seam: how a wait is taken. Default the shared abortable sleep. A
+     * custom sleeper must reject with `signal.reason` when the signal aborts.
+     */
+    readonly sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+}
+/** What the budget has done, with no token and no message ids. */
+export interface TelegramOutboundBudgetStats {
+    /** Calls admitted by `acquire` or `run`. */
+    readonly granted: number;
+    /** Weighted messages admitted: an album of three counts as three. */
+    readonly messages: number;
+    /** Calls waiting for their turn. */
+    readonly queued: number;
+    readonly messagesPerSecond: number;
+    /** How much of the current 429 pause is still ahead, in milliseconds. */
+    readonly pausedForMs: number;
+}
+/**
+ * A token's outbound budget. `run` is the narrow adapter a client transformer
+ * calls around its own send; it gates, pauses on 429 and never retries.
+ */
+export interface TelegramOutboundBudget {
+    /**
+     * Run one Bot API call under the budget. A non-send method passes through
+     * without spending a message. A 429 pauses every sender of the token; the
+     * original error is rethrown and the call is not repeated.
+     */
+    run<T>(method: string, payload: unknown, signal: AbortSignal | undefined, send: () => Promise<T>): Promise<T>;
+    /**
+     * Wait until `cost` messages fit. The wait rejects with `signal.reason`
+     * without spending a token; a granted call owns its slots even if its later
+     * send is aborted, which the caller must not repeat as a definite failure.
+     */
+    acquire(cost: number, signal?: AbortSignal): Promise<void>;
+    /** Pause every sender of this token for at least `milliseconds`. Never shortens an existing pause. */
+    pause(milliseconds: number): void;
+    /** Pause the token after a rate-limited refusal; another failure does nothing. */
+    pauseAfter(error: unknown): void;
+    /**
+     * Wait out the current pause without spending a token. For a retry path that
+     * is not a send (edit, delete) and does not go through `acquire`.
+     */
+    waitUntilResumed(signal?: AbortSignal): Promise<void>;
+    /** Measured counters. It never contains the token. */
+    stats(): TelegramOutboundBudgetStats;
+}
+/**
+ * The one budget for `config.token`, created on first use.
+ *
+ * Two aliases of one token share it; two tokens never do. A second call for a
+ * token already in use must agree on the options, otherwise the process has
+ * two incompatible policies for one credential and the call is refused. The
+ * refusal never contains the token.
+ */
+export declare function telegramOutboundBudget(config: TelegramOutboundBudgetConfig): TelegramOutboundBudget;
+//# sourceMappingURL=outbound-budget.d.ts.map

package/dist/telegram/outbound-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-budget.d.ts","sourceRoot":"","sources":["../../src/telegram/outbound-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAwEH,MAAM,WAAW,4BAA4B;IAC3C,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED,kEAAkE;AAClE,MAAM,WAAW,2BAA2B;IAC1C,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,GAAG,CAAC,CAAC,EACH,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,sGAAsG;IACtG,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,kFAAkF;IAClF,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,gBAAgB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,sDAAsD;IACtD,KAAK,IAAI,2BAA2B,CAAC;CACtC;AAmMD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,4BAA4B,GACnC,sBAAsB,CAsCxB"}

package/dist/telegram/send-failure.d.ts

@@ -30,8 +30,13 @@
  * user who never pressed Start needs an invitation rather than a retry, and a
  * chat Telegram does not know is usually a bad identifier on our side — a
  * defect in our data, not a fact about a person.
+ *
+ * `bot-to-bot-disabled` is permanent for this send but does not accuse the
+ * recipient: Telegram disables bot-to-bot messaging when *either* bot has not
+ * enabled its Bot to Bot setting, so the missing setting may be the sender's.
+ * It is never retried, and it never marks the recipient unreachable.
  */
-export type TelegramSendFailureReason = 'blocked-by-user' | 'user-deactivated' | 'chat-not-found' | 'not-started' | 'rate-limited' | 'message-invalid' | 'server-error' | 'not-dispatched' | 'unknown';
+export type TelegramSendFailureReason = 'blocked-by-user' | 'user-deactivated' | 'chat-not-found' | 'not-started' | 'bot-to-bot-disabled' | 'rate-limited' | 'message-invalid' | 'server-error' | 'not-dispatched' | 'unknown';
 export interface TelegramSendFailure {
     reason: TelegramSendFailureReason;
     /** Telegram's `error_code`, when the failure carried one. */

package/dist/telegram/send-failure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"send-failure.d.ts","sourceRoot":"","sources":["../../src/telegram/send-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,gBAAgB,GAChB,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,yBAAyB,CAAC;IAClC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,WAAW,GAAG,MAAM,CAAC;CAC1E;AA+CD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,yBAAyB,EAC7B,CAAC;AAyClD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CA4D/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,OAAO,CAAC;AAeZ,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAM/E"}
+{"version":3,"file":"send-failure.d.ts","sourceRoot":"","sources":["../../src/telegram/send-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,aAAa,GACb,qBAAqB,GACrB,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,gBAAgB,GAChB,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,yBAAyB,CAAC;IAClC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,WAAW,GAAG,MAAM,CAAC;CAC1E;AAoDD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,yBAAyB,EAC7B,CAAC;AA4ClD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CA4D/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,OAAO,CAAC;AAeZ,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAM/E"}

package/llms/server.4.txt

@@ -391,6 +391,11 @@ and our payload is wrong, which is the case a list of substrings quietly counts
 against the user. An unrecognised refusal leaves the recipient reachable: losing
 a working subscriber forever costs more than one wasted send.
 
+`bot-to-bot-disabled` is permanent but deliberately not `recipientUnreachable`:
+Telegram returns it when either bot has not enabled Bot to Bot messaging, so the
+missing setting may be the sender's. Do not retry it, and do not close the
+recipient's row on it.
+
 `TELEGRAM_SEND_FAILURE_REASONS` lists every reason. A table keyed by
 `TelegramSendFailureReason` — error codes, the text a person reads — fails to
 compile when a release adds one, instead of falling through to a default:

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 |