stitchkit 0.113.3 → 0.114.1

package/llms-full.txt

@@ -67,7 +67,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 |
@@ -77,12 +78,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 |
@@ -94,7 +96,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 |
@@ -207,6 +209,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` |
@@ -216,6 +219,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` |
 
@@ -11928,6 +11932,37 @@ deleted payload without guessing. The same resolved detail key drives the
 `isFresh` echo guard. Shape checks also leave neighbouring detail caches alone
 when a list key is intentionally used as a partial query-key prefix.
 
+### When only a new row needs an order
+
+`compare` is the order the row itself determines: the array is sorted again after
+every create and update, so a rename that moves a row moves it in the cache too.
+Some lists are ordered by facts the row does not carry — the projects a person
+owns first, then the ones they administer, then the rest by name, where the role
+is not in the row for a platform administrator who belongs to none of them. No
+`compare` can reproduce that, and sorting every row with a wrong one scrambles
+the list the server ordered.
+
+`insertCompare` answers a smaller question: where does a row that is *entering*
+the list go?
+
+```ts
+list: {
+  key: ['projects'],
+  shape: 'array',
+  createAt: 'end',
+  updateMissing: 'insert',
+  insertCompare: (incoming, existing) => incoming.name.localeCompare(existing.name),
+}
+```
+
+A new row goes before the first row it sorts ahead of; a tie goes by `createAt`
+(`'start'`: before equal rows, `'end'`: after them). On a list already in that
+order the result is the one `compare` would give. On a list that is not, no other
+row moves, and a row that is already in the list is replaced where it stands.
+A paged list places the row within the page `createAt` selects, and leaves the
+other pages as they were. `compare` and `insertCompare` are two answers to one
+question: a list takes one of them, and `createEntityCacheHandlers` refuses both.
+
 The helper deliberately does **not** flatten pages, infer filter semantics,
 derive a sort order or replace arbitrary `setQueryData` logic. Those remain
 declared application policies; Stitchkit applies their generic cache mechanics.
@@ -12949,6 +12984,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:
@@ -15259,6 +15299,8 @@ key hears it first — a widget's own `onKeyDown`, a text field, a popover that
 closes on Escape — and keeps it with `preventDefault()` or `stopPropagation()`.
 A layer only gets what nobody nearer wanted, so third-party components keep
 working unchanged.
+One kind of layer may ask for the opposite: a menu over a text field takes the
+arrows before the field does — see [A menu over a text field](#a-menu-over-a-text-field).
 
 ## Shortcuts and Escape
 
@@ -15338,7 +15380,7 @@ function ChatList({ chats, openId, open }) {
 | Option | Default | Meaning |
 |---|---|---|
 | `items`, `value`, `onChange` | — | the ids in order, the chosen one, and the report of a choice; the zone never holds the value |
-| `mode` | `'select'` | `'select'`: an arrow chooses (`onChange(id, 'arrow')`). `'highlight'`: an arrow only moves focus, Enter chooses (`onChange(id, 'confirm')`) |
+| `mode` | `'select'` | `'select'`: an arrow chooses (`onChange(id, 'arrow')`). `'highlight'`: an arrow only moves focus, Enter chooses (`onChange(id, 'confirm')`). `'focus'`: an arrow only moves focus and the items choose for themselves — see [below](#links-and-buttons-that-choose-for-themselves) |
 | `orientation` | `'vertical'` | which arrows move; the other axis enters and exits |
 | `role` | `'listbox'` | `'listbox'` of options or `'tablist'` of tabs, marked `aria-selected`; `'none'` keeps the items' own semantics (links, buttons) and marks the chosen one `aria-current` |
 | `loop` | `false` | wrap past the ends instead of calling `onBoundary` |
@@ -15347,6 +15389,8 @@ function ChatList({ chats, openId, open }) {
 | `onBoundary(side)` | — | a move past `'start'` or `'end'`: hand focus to the neighbouring zone |
 | `active` | `true` | whether arrows pressed outside every zone land here |
 | `label` | — | the zone's accessible name |
+| `outside` | `'focus'` | what the first arrow does when focus is in no zone: `'focus'` puts focus on the current item and nothing else; `'move'` moves from it and, in select mode, chooses the neighbour — see [below](#the-first-arrow-from-outside-a-zone) |
+| `ignore(event)` | — | a key that is the application's own right now — return `true` and the zone leaves it whole; see [dragging](#a-zone-inside-a-drag-and-drop-list) |
 | `onReveal(id)` | — | focus went to an item with no element yet — a row of a virtualized list outside the rendered range; scroll it in, and focus lands on it when it mounts |
 
 The callbacks return `false` to leave the key to the page, anything else takes
@@ -15359,6 +15403,256 @@ axis puts focus on the active zone's current item. To move between zones
 (sidebar → table), call `zone.focus(id?)` of the other zone from `onEnter` or
 `onBoundary`. `zone.element` is the zone's element, for a layer scoped to it.
 
+## Links and buttons that choose for themselves
+
+In `select` and `highlight` mode the zone reports a choice, and in `highlight` it takes
+Enter for it. A list of `<a>` and `<button>` elements has a choice built in: Enter
+clicks the focused one. Taking Enter would replace that with a handler you must
+write to click the element yourself.
+
+`mode: 'focus'` is for those lists — a menu, a toolbar, a row of tabs that are
+links. The arrows move focus; Enter, and Space on a button, stay with the focused
+element; the zone reports nothing, so there is no `onChange`. `value` is optional
+and only marks the page you are on (`aria-current` with `role: 'none'`).
+
+```tsx
+function Toolbar({ actions }) {
+  const zone = useNavZone({
+    items: actions.map((action) => action.id),
+    mode: 'focus',
+    role: 'none',
+    orientation: 'horizontal',
+    label: 'Formatting',
+  })
+  return (
+    <div {...zone.zoneProps}>
+      {actions.map((action) => (
+        <button key={action.id} type="button" onClick={action.run} {...zone.itemProps(action.id)}>
+          {action.label}
+        </button>
+      ))}
+    </div>
+  )
+}
+```
+
+In a focus zone Enter is never taken, even when `onEnter` is set: `onEnter` is
+the cross-axis key (→ in a vertical zone).
+
+## Props, refs and other libraries
+
+Spread the zone's props **last** on an element another library also configures, so
+the roving `tabIndex` is the one that counts. A prop without a value is absent, not
+`undefined`: `role` is there only for a listbox or a tablist, `aria-selected` only
+outside `role: 'none'`, `aria-label` only with a `label`. A `role="button"` the
+element carries from another library, or an `aria-label` you wrote before the
+spread, survives it.
+
+`ref` is the one prop two libraries both need. `mergeRefs` makes one callback of
+several refs; spread the zone's props, then replace `ref`:
+
+```tsx
+import { mergeRefs, useNavZone } from 'stitchkit/react/keyboard'
+
+function Row({ id, zone }) {
+  const sortable = useSortable({ id })
+  const own = zone.itemProps(id)
+  return (
+    <li
+      {...sortable.attributes}
+      {...sortable.listeners}
+      {...own}
+      ref={mergeRefs(own.ref, sortable.setNodeRef)}
+    >
+      {id}
+    </li>
+  )
+}
+```
+
+The same goes for `zone.zoneProps.ref` beside a scroll container's or a measuring
+hook's ref. `mergeRefs` returns a new function on every call and React re-attaches a
+callback ref whose identity changed; a component that renders often keeps the
+result in `useMemo`.
+
+`useNavZone` also returns a new object on every render. An effect that should run
+when a menu *opens* depends on that, not on `zone`; keep the latest zone in a ref.
+
+## A zone inside a drag-and-drop list
+
+A sortable list is a zone whose rows can also be lifted with the keyboard: Space
+lifts a row, the arrows move it, Space drops it. The arrows are then the drag's,
+not the zone's, and a zone that also moves focus on them makes the focus ring jump
+from row to row while the row moves.
+
+`ignore` hands the zone a question about every key it would act on. dnd-kit marks
+the lifted activator `aria-pressed="true"` for the length of the drag:
+
+```tsx
+const zone = useNavZone({
+  items: order,
+  mode: 'focus',
+  role: 'none',
+  ignore: (event) =>
+    event.target instanceof Element && event.target.closest('[aria-pressed="true"]') !== null,
+})
+```
+
+The zone leaves an ignored key entirely: it does not move, does not take the key and
+does not call `preventDefault`, whether the key came from inside the zone or from
+a page whose focus is in no zone. The test is the application's on purpose. A
+toggle button also carries `aria-pressed="true"`, and a toolbar of toggles must
+keep its arrows; only the application knows whether a pressed element is a drag.
+
+## A menu or a popover opened by the pointer
+
+A script's `focus()` shows the focus ring when the element that had focus before it
+was showing one — and when nothing had. A menu opened by a right click, with focus
+on `body`, would put a ring on its first item although nobody pressed a key. Decide
+at the moment of opening: in the handler that opens the menu, before anything moves
+focus, ask `openedByKeyboard()`.
+
+```tsx
+const byKeyboard = useRef(false)
+const container = useRef<HTMLDivElement>(null)
+
+function show() {
+  byKeyboard.current = openedByKeyboard() // before the menu takes focus
+  setOpen(true)
+}
+
+useLayoutEffect(() => {
+  if (!open) return
+  if (byKeyboard.current) zone.focus() // the first item, with its ring
+  else container.current?.focus() // the menu itself
+}, [open])
+```
+
+`openedByKeyboard()` is whether the element with focus right now matches
+`:focus-visible`; it is `false` on a server and in a browser without that selector.
+Give the container `outline: none`: it only holds focus, and a browser may count a
+focus that starts on `body` as keyboard focus. The first arrow with focus on the
+zone's own element lands on the current item, not one step beyond it, so the menu
+opened by a click is a normal menu from the first key.
+
+A focus manager that also puts initial focus on opening fights this for the first
+item. Floating UI's `FloatingFocusManager` documents `initialFocus={-1}` as "ignore
+the initial focus" and `initialFocus={refs.floating}` as focusing the container;
+either leaves the first item to the handler above. (This repository's browser probe
+covers the pattern with a plain element, not Floating UI.)
+
+## The first arrow from outside a zone
+
+With focus in no zone — right after a click on the page, or on the empty part of a
+screen — the first arrow on an active zone's axis puts focus on its current item.
+That is the safe answer: the person sees where they are before anything changes,
+and a zone whose arrows choose does not change the choice on a key that only
+announced the list.
+
+A list that has always answered the first arrow with a change (a chat list whose
+arrows open the next chat) can say so: `outside: 'move'` acts as if focus were
+already on the current item, so the arrow moves from it and, in `select` mode,
+calls `onChange` for the neighbour. It is opt-in and per zone; `ignore` is asked
+first in both.
+
+## A panel that keeps its keys around a zone
+
+`data-local-keys` marks an area whose keys belong to it rather than to the page:
+layers skip keys pressed inside it, so a section switch on ← and → leaves a
+dropdown panel alone. A zone inside such a panel still has its arrows. The zone is
+the part of the area that handles them, so only a field *inside the zone* — an
+input in one of its rows — keeps its keys from the zone; an area that contains the
+zone, or the zone's own element carrying the mark, does not. ← and → are not a
+vertical zone's keys, so they bubble on to the layers, which skip them in that
+panel: the zone moves, the section does not.
+
+## A menu over a text field
+
+A layer hears a key after everything closer to it, and a text field is as close as
+it gets: the field acts on an arrow or Enter first. A menu that hangs over the
+field — slash commands, quick replies — keeps focus in the field and needs those
+keys *before* it does, and the field's own Enter (send the message) must not also
+run.
+
+`phase: 'capture'` is for that, and for a `local` layer only (any other kind
+refuses it when it mounts): the layer is asked before the element that has focus,
+and a key it takes — `preventDefault` and `stopPropagation` — reaches nothing
+nearer.
+
+```tsx
+function CommandMenu({ open, items, pick }) {
+  const menu = useRef<HTMLDivElement>(null)
+  const [index, setIndex] = useState(0)
+  useKeyLayer({
+    kind: 'local',
+    phase: 'capture',
+    fields: 'include', // the key is pressed in the field
+    scope: menu, // heard only while the menu is on the page
+    active: open,
+    onKey: (event) => {
+      if (event.key === 'ArrowDown') setIndex((i) => Math.min(i + 1, items.length - 1))
+      else if (event.key === 'ArrowUp') setIndex((i) => Math.max(i - 1, 0))
+      else if (event.key === 'Enter') pick(items[index])
+      else return false // typing, Backspace, everything else stays the field's
+      return true
+    },
+  })
+  return open ? <div ref={menu} role="listbox">…</div> : null
+}
+```
+
+`fields: 'include'` is needed because the default skips keys pressed in a field;
+`scope` and `active` keep the layer from taking keys when there is no menu. An
+`overlay` above still stops it: a live overlay is a barrier for layers of either
+phase. In `createKeyboardTestBed`, `press` runs the capture phase first and
+stops there when a layer took the key (`event.propagationStopped`).
+
+## Moving from a stack of zones of your own
+
+A hand-written zone stack and `stitchkit/react/keyboard` name the same ideas
+differently:
+
+| Yours | Here |
+|---|---|
+| a flag that arrows choose at once (`instant`) | `mode: 'select'`; `'highlight'` when choosing is expensive |
+| wrapping (often the default) | `loop` — `false` by default; set it on the lists that wrapped |
+| the current section | `active` for which zone takes the first arrow, `scope` for which layer is live |
+| one shared "highlighted id" | each zone's own focused item; read `zone.current` |
+| an attribute that marks areas with their own keys | `data-local-keys` |
+| Escape closing the innermost thing | `useEscapeLayer` — one Escape closes one level |
+
+## Testing without a DOM
+
+`stitchkit/react/keyboard/testing` has no React and no DOM in it: a window that
+remembers its listener, elements with a parent, `inert` and visibility, and key
+events with `preventDefault`. A test adds the layers a screen declares, presses
+keys on elements and reads who heard what.
+
+```ts
+import { createKeyboardTestBed } from 'stitchkit/react/keyboard/testing'
+
+test('Escape closes the dialog and not the page behind it', () => {
+  const bed = createKeyboardTestBed()
+  const heard: string[] = []
+  const page = bed.element()
+  const dialog = bed.element()
+  bed.stack.add({ kind: 'route', scope: () => page, onKey: () => (heard.push('page'), true) })
+  bed.stack.add({ kind: 'overlay', scope: () => dialog, onKey: () => (heard.push('dialog'), true) })
+  bed.press('Escape')
+  expect(heard).toEqual(['dialog'])
+  page.inert = true // the page behind a dialog
+  dialog.hidden = true
+  bed.press('Escape')
+  expect(heard).toEqual(['dialog'])
+})
+```
+
+`createNavZone` is the zone without React: build it with the items' fake elements
+(`bed.element({ zone: true })` and its `child()` rows count `focus()` and scrolling),
+call `zone.keyDown(bed.key('ArrowDown', { target: row }), zoneElement)`. A real
+focus ring, scrolling and screen readers are a browser's: this is for the order of
+layers, `scope`/`inert` and the edges of a zone.
+
 ## What stays in the application
 
 The URL, the router, sections and which screen is open. A layer calls the
@@ -15528,6 +15822,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
@@ -16361,6 +16728,48 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## 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.
@@ -23286,7 +23695,7 @@ available from `stitchkit/contract`.
 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 |
 |--------|------|---------|
@@ -23301,7 +23710,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 |
@@ -23335,6 +23745,18 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.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 |
+
+---
+
 ## `stitchkit/telegram/html`
 
 Telegram's HTML parse mode as a tree: any markup in, markup Telegram accepts
@@ -23734,7 +24156,7 @@ Browser- and server-render-safe React data-layer helpers. Needs the
 | `EntityCacheHandlers` | _type_ | the `{ created, updated, deleted }` handlers it returns |
 | `EntityCacheEvent` | _type_ | discriminated created/updated/deleted input for dynamic cache keys |
 | `EntityCacheKey` | _type_ | static `QueryKey` or event-aware key factory |
-| `EntityCacheListConfig` | _type_ | list shape, scoped key, insertion/missing-update policy and comparator |
+| `EntityCacheListConfig` | _type_ | list shape, scoped key, insertion/missing-update policy and one ordering: `compare` (the whole array is sorted again after a create or update) or `insertCompare` (only a row entering the list is placed; every other row stays, and an updated row keeps its place) |
 | `EntityCacheListShape` | _type_ | `array \| paginated \| infinite-array \| infinite-paginated` |
 | `DeletedPayload` | _type_ | a `deleted` event payload — the entity or a bare `{ id }` |
 | `CursorQueryConfig` | _type_ | config for `createCursorQuery` |
@@ -23773,13 +24195,19 @@ no component, no styles, no router — see the [keyboard guide](../guide/keyboar
 |--------|------|---------|
 | `useKeyLayer` | hook | put a layer on the window's one key stack — asked `overlay` → `local` → `route` → `zone` → `global`, innermost first within a kind |
 | `useEscapeLayer` | hook | an `overlay`, `local` or `route` layer for Escape: one press closes one level |
-| `useNavZone` | hook | a list zone — roving tab stop, arrows move DOM focus, select or highlight mode, cross-axis enter/exit, boundaries |
+| `useNavZone` | hook | a list zone — roving tab stop, arrows move DOM focus, select, highlight or focus mode, cross-axis enter/exit, boundaries, `ignore` for a key the application is using; props carry no key without a value |
 | `nextZoneIndex` | function | where a move lands in a list of a given length: an index, `'before-start'` or `'after-end'` |
 | `isKeyFieldTarget` | function | whether a key was pressed in a field or a `data-local-keys` area, the test layers use |
-| `KeyLayerOptions` | _type_ | `kind`, `onKey`, `active`, `scope`, `fields` |
+| `KeyLayerOptions` | _type_ | `kind`, `onKey`, `active`, `scope`, `fields`, `phase` — `'capture'` is for a `local` layer only: it hears a key before the element that has focus does, as a menu over a text field must, and a key it takes goes no further |
+| `KeyLayerPhase` | _type_ | `'bubble' \| 'capture'` |
 | `KeyLayerKind` | _type_ | `'overlay' \| 'local' \| 'route' \| 'zone' \| 'global'` |
 | `EscapeLayerOptions` | _type_ | `kind`, `onEscape`, `active`, `scope` |
-| `NavZoneOptions` | _type_ | `items`, `value`, `onChange`, `mode`, `orientation`, `role`, `loop`, `onEnter`, `onExit`, `onBoundary`, `active`, `label`, `onReveal` |
+| `NavZoneOptions` | _type_ | `items`, `value`, `onChange`, `mode` (`select` or `highlight`), `orientation`, `role`, `loop`, `onEnter`, `onExit`, `onBoundary`, `active`, `outside` (`'focus'` or `'move'`: what the first arrow does when focus is in no zone), `label`, `onReveal`, `ignore` |
+| `FocusZoneOptions` | _type_ | the options of a zone whose items choose for themselves: `mode: 'focus'`, no `onChange`, an optional `value`; the arrows move focus and Enter stays with the focused element |
+| `ZoneOptions` | _type_ | `NavZoneOptions` or `FocusZoneOptions` — what `useNavZone` takes |
+| `ZoneKeyEvent` | _type_ | the key an `ignore` callback is asked about: `key`, modifiers, `target`, `repeat`, `isComposing`, `defaultPrevented` |
+| `mergeRefs` | function | one ref callback for several refs — the zone's `ref` beside a drag handle's or your own; spread the zone's props, then set `ref: mergeRefs(props.ref, other)` |
+| `openedByKeyboard` | function | whether the element with focus right now shows a focus ring — call it in the handler that opens a menu, before focus moves, to decide whether the first item takes focus |
 | `NavZone` | _type_ | what `useNavZone` returns — `zoneProps`, `itemProps(id)`, `element`, `current`, `focus(id?)` |
 | `NavZoneProps` / `NavZoneItemProps` | _type_ | the props spread on the zone's element and on each item |
 | `NextZoneIndexInput` | _type_ | `length`, `index`, `move`, `loop` |
@@ -23788,6 +24216,20 @@ no component, no styles, no router — see the [keyboard guide](../guide/keyboar
 | `ZoneMove` | _type_ | `'next' \| 'previous' \| 'first' \| 'last'` |
 | `ZoneOrientation` | _type_ | `'vertical' \| 'horizontal'` |
 
+## `stitchkit/react/keyboard/testing`
+
+Keyboard layers and zones without a DOM, a browser or React: fakes for the
+window, elements and key events, and the two engines the hooks are made of.
+Peer-free. A test builds the layers a screen declares, presses keys on elements
+and reads who heard what — see the [keyboard guide](../guide/keyboard.md#testing-without-a-dom).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createKeyboardTestBed` | function | a fresh stack, window, element factory and key factory: `stack.add(layer)`, `press(key, { target })`, `element({ parent, field, zone, inert, hidden })`, `key(name)` for a zone, and `listening` |
+| `KeyboardTestBed` / `TestElement` / `TestElementInit` / `TestKeyEvent` / `TestKeyInit` | _type_ | the test bed, an element (also a zone item: it counts `focus()` and scrolling), what builds one, and a key event with `defaultPrevented` |
+| `createKeyLayerStack` / `KeyLayerStack` / `KeyLayerHandle` / `KeyLayerState` / `KeyListenerTarget` / `LayerKeyEvent` / `LayerScope` | function / _type_ | the layer stack the hooks put on the window, over any listener target and elements that have `contains`, `closest`, `isConnected` |
+| `createNavZone` / `NavZoneController` / `ZoneItemElement` | function / _type_ | a zone controller without React: `keyDown`, `keyFromOutside`, `focused`, `focus`, `update`, `current`, `pointedItem`, `subscribe` |
+
 ## `stitchkit/agent-runtime/sandbox`
 
 Optional server-only namespace sandbox. Exports: