switchroom 0.19.26 → 0.19.28

package/telegram-plugin/tests/edit-flood-fuse-ban-awareness.test.ts

@@ -0,0 +1,373 @@
+/**
+ * The fuse must survive a restart and must react in PROPORTION to the ban
+ * (#3856).
+ *
+ * ── The two bugs these tests guard ───────────────────────────────────────
+ *
+ * 1. **All state was in process memory.** `tightenLevel` / `tightenedUntil`
+ *    were module-local variables. The gateway restarting during a flood ban —
+ *    the single most likely thing to happen during a multi-hour outage —
+ *    brought the fuse back FULLY UNTIGHTENED, at exactly the rate that earned
+ *    the ban, while the window was still open. Every other outbound path in
+ *    the tree already consults `flood-wait.json`; the fuse did not.
+ *
+ * 2. **`noteFlood()` ignored the magnitude.** Every 429 was worth exactly one
+ *    level of multiplicative decrease, so a 3-second burst nudge and the
+ *    15908-second (4.4h) ban of 2026-07-27 produced an identical response.
+ *    The tightening also expired after a flat 10 minutes — ~25× shorter than
+ *    that ban, so the fuse would have been back at full rate for hours while
+ *    still banned.
+ *
+ * Every test asserts an OUTCOME (the live ceiling, or how many calls reached
+ * the wire), never that a branch ran.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  createEditFloodFuse,
+  editFloodFuseConfigFromEnv,
+  EDIT_FLOOD_FUSE_DEFAULTS,
+} from '../edit-flood-fuse.js'
+import { floodStatePath, makeFloodWaitProbe } from '../flood-circuit-breaker.js'
+import type { Clock } from '../send-gate.js'
+
+const CHAT = '1001'
+
+class FakeClock implements Clock {
+  private cur = 0
+  private seq = 0
+  private timers: { at: number; id: number; resolve: () => void }[] = []
+  now(): number { return this.cur }
+  sleep(ms: number): Promise<void> {
+    return new Promise<void>((resolve) => {
+      this.timers.push({ at: this.cur + ms, id: this.seq++, resolve })
+    })
+  }
+  async advance(ms: number): Promise<void> {
+    const target = this.cur + ms
+    for (;;) {
+      await flush()
+      const due = this.timers.filter((t) => t.at <= target).sort((a, b) => a.at - b.at || a.id - b.id)
+      if (due.length === 0) break
+      const t = due[0]!
+      this.timers = this.timers.filter((x) => x !== t)
+      this.cur = t.at
+      t.resolve()
+      await flush()
+    }
+    this.cur = target
+    await flush()
+  }
+}
+const flush = (): Promise<void> => new Promise((r) => setImmediate(r))
+
+/** A 429 in the shape grammY throws it. */
+function flood(retryAfterSec: number): Error & Record<string, unknown> {
+  const e = new Error('Too Many Requests: retry after ' + retryAfterSec) as Error &
+    Record<string, unknown>
+  e.error_code = 429
+  e.parameters = { retry_after: retryAfterSec }
+  return e
+}
+
+describe('restart durability — the persisted window outranks process memory', () => {
+  it('a FRESH fuse is already at its tightest when a ban is open on disk', async () => {
+    const clock = new FakeClock()
+    // Simulate the restart: brand-new fuse, zero in-memory history, but the
+    // marker on disk still says 12247s of ban to go.
+    const fuse = createEditFloodFuse({
+      clock, floodWaitRemainingMs: () => 12_247_000,
+      perMessageMaxPerWindow: 20, cosmeticPerMessageMaxPerWindow: 16,
+      maxTightenLevel: 4, tightenFactor: 0.5,
+    })
+
+    const s = fuse.stats()
+    expect(s.persistedFloodOpen).toBe(true)
+    expect(s.tightenLevel).toBe(4)
+    // 0.5^4 = 1/16 of the base ceiling — the fuse did NOT come back at full rate.
+    expect(s.cosmeticPerMessageCeiling).toBe(1)
+    expect(s.perMessageCeiling).toBe(1)
+    // And it BINDS: 30 cosmetic edits offered, at most the tightened ceiling
+    // reaches the wire. Without the persisted read this is 16.
+    let landed = 0
+    const calls = Array.from({ length: 30 }, () =>
+      fuse.apply('editMessageText', { chat_id: CHAT, message_id: 7 }, async () => {
+        landed++
+        return true
+      }))
+    await clock.advance(31_000)
+    await Promise.all(calls)
+    expect(landed).toBeLessThanOrEqual(2)
+  })
+
+  it('untightens once the window on disk closes — it is a floor, not a latch', async () => {
+    const clock = new FakeClock()
+    let remaining = 12_247_000
+    const fuse = createEditFloodFuse({
+      clock, floodWaitRemainingMs: () => remaining,
+      floodProbeIntervalMs: 0, // re-read every call, for determinism here
+      perMessageMaxPerWindow: 20, maxTightenLevel: 4, tightenFactor: 0.5,
+    })
+    expect(fuse.stats().tightenLevel).toBe(4)
+    remaining = 0
+    // The fuse earned nothing itself, so it returns all the way to base — the
+    // persisted window pins the level while open and never mutates it.
+    expect(fuse.stats().tightenLevel).toBe(0)
+    expect(fuse.stats().perMessageCeiling).toBe(20)
+  })
+
+  it('grades the persisted window by what REMAINS, not straight to maximum (#3885)', () => {
+    // `makeFloodWaitRecorder` writes `flood-wait.json` for EVERY 429, including
+    // a routine 3-second nudge. Pinning at `maxTightenLevel` for any open
+    // window therefore reintroduced on the persisted path the exact defect
+    // #3856 fixed on the in-memory one: a nudge and a 4.4h ban produced the
+    // same maximal response, collapsing a whole chat to 1 call/min over a
+    // transient blip. The severity ladder is the same one `noteFlood` uses.
+    const cases: [number, number][] = [
+      [3_000, 1],        // routine burst nudge
+      [45_000, 2],       // sustained overrate
+      [300_000, 3],      // a real ban
+      [12_247_000, 4],   // the 2026-07-27 magnitude — still straight to maximum
+    ]
+    for (const [remainingMs, expected] of cases) {
+      const fuse = createEditFloodFuse({
+        clock: new FakeClock(), floodWaitRemainingMs: () => remainingMs,
+        floodProbeIntervalMs: 0, maxTightenLevel: 4, tightenFactor: 0.5,
+      })
+      expect(fuse.stats().persistedFloodOpen).toBe(true)
+      expect(fuse.stats().tightenLevel).toBe(expected)
+    }
+  })
+
+  it('a single 3s 429 does not collapse the chat to 1 call/min (#3885)', async () => {
+    // The production regression, end to end: one transient 429 during a fleet
+    // restart both bumped the in-memory level AND wrote a 3-second marker that
+    // pinned the fuse at maximum, taking `perChatTotalMaxPerWindow: 20` down to
+    // an effective 1 for the whole chat.
+    const clock = new FakeClock()
+    const fuse = createEditFloodFuse({
+      clock, floodProbeIntervalMs: 0,
+      // The marker as the real recorder would write it for a 3s penalty.
+      floodWaitRemainingMs: () => Math.max(0, 3_000 - clock.now()),
+      perChatTotalMaxPerWindow: 20, perChatReplyReserve: 8, perChatSendMaxPerWindow: 25,
+      perTokenMaxPerWindow: 1_000, maxTightenLevel: 4, tightenFactor: 0.5,
+    })
+    await expect(
+      fuse.apply('sendMessage', { chat_id: CHAT, text: 'x' }, async () => { throw flood(3) }),
+    ).rejects.toThrow()
+
+    // One nudge is worth one level, on both paths — so the chat keeps half its
+    // budget, not one-twentieth of it.
+    expect(fuse.stats().tightenLevel).toBe(1)
+    expect(fuse.stats().criticalPerChatTotalCeiling).toBe(10)
+
+    // And it BINDS at that rate: 20 replies offered inside one window, ~half
+    // land promptly rather than one. 9 rather than 10 because the 429'd call
+    // above took a slot of the same window before it failed.
+    let landed = 0
+    const calls = Array.from({ length: 20 }, () =>
+      fuse.apply('sendMessage', { chat_id: CHAT, text: 'answer' }, async () => { landed++; return true }))
+    await clock.advance(1_000)
+    expect(landed).toBe(9)
+    await clock.advance(60_000)
+    await Promise.all(calls)
+  })
+
+  it('FAILS OPEN: an unreadable marker must never gag the bot', async () => {
+    const clock = new FakeClock()
+    const fuse = createEditFloodFuse({
+      clock,
+      floodWaitRemainingMs: () => {
+        throw new Error('EACCES: flood-wait.json owned by another uid')
+      },
+      perChatSendMaxPerWindow: 25,
+    })
+    expect(fuse.stats().persistedFloodOpen).toBe(false)
+    expect(fuse.stats().tightenLevel).toBe(0)
+    let landed = 0
+    await fuse.apply('sendMessage', { chat_id: CHAT, text: 'the answer' }, async () => {
+      landed++
+      return true
+    })
+    expect(landed).toBe(1)
+  })
+
+  it('re-reads the marker at most once per floodProbeIntervalMs', async () => {
+    const clock = new FakeClock()
+    let reads = 0
+    const fuse = createEditFloodFuse({
+      clock, floodProbeIntervalMs: 1_000,
+      floodWaitRemainingMs: () => { reads++; return 0 },
+      perChatTotalMaxPerWindow: 1_000, perChatSendMaxPerWindow: 1_000,
+      perTokenMaxPerWindow: 1_000,
+    })
+    for (let i = 0; i < 50; i++) {
+      await fuse.apply('sendMessage', { chat_id: CHAT, text: 'x' }, async () => true)
+    }
+    // A file read on every admission would make the fuse the latency problem
+    // it exists to prevent.
+    expect(reads).toBeLessThanOrEqual(2)
+  })
+
+  it('reads the REAL breaker file that robustApiCall and the sweep use', async () => {
+    // Not a mock: write the actual on-disk marker and let the production probe
+    // read it, so the two halves cannot drift apart.
+    const dir = mkdtempSync(join(tmpdir(), 'fuse-flood-'))
+    try {
+      writeFileSync(
+        floodStatePath(dir),
+        JSON.stringify({ untilTs: Date.now() + 12_247_000, retryAfterSec: 12247, recordedTs: Date.now() }),
+        'utf-8',
+      )
+      const fuse = createEditFloodFuse({
+        floodWaitRemainingMs: makeFloodWaitProbe(floodStatePath(dir)),
+        maxTightenLevel: 4, tightenFactor: 0.5, perMessageMaxPerWindow: 20,
+      })
+      expect(fuse.stats().persistedFloodOpen).toBe(true)
+      expect(fuse.stats().perMessageCeiling).toBe(1)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('editFloodFuseConfigFromEnv wires the probe from TELEGRAM_STATE_DIR', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'fuse-env-'))
+    try {
+      writeFileSync(
+        floodStatePath(dir),
+        JSON.stringify({ untilTs: Date.now() + 600_000, retryAfterSec: 600, recordedTs: Date.now() }),
+        'utf-8',
+      )
+      const cfg = editFloodFuseConfigFromEnv({ TELEGRAM_STATE_DIR: dir })
+      expect(cfg.floodWaitRemainingMs).toBeTypeOf('function')
+      expect(cfg.floodWaitRemainingMs!()).toBeGreaterThan(0)
+      // The wiring is what makes it durable in production — a fuse built from
+      // this config is tightened without anyone remembering to pass a probe.
+      expect(createEditFloodFuse(cfg).stats().persistedFloodOpen).toBe(true)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('is a no-op when TELEGRAM_STATE_DIR is unset (dev / one-shot contexts)', () => {
+    const cfg = editFloodFuseConfigFromEnv({})
+    expect(cfg.floodWaitRemainingMs).toBeUndefined()
+    expect(createEditFloodFuse(cfg).stats().persistedFloodOpen).toBe(false)
+  })
+})
+
+describe('severity scaling — a 4.4h ban is not one nudge\'s worth of signal', () => {
+  const mk = (clock: FakeClock) =>
+    createEditFloodFuse({
+      clock, maxTightenLevel: 4, tightenFactor: 0.5, tightenMs: 600_000,
+      perMessageMaxPerWindow: 32,
+    })
+
+  async function observe(fuse: ReturnType<typeof mk>, retryAfterSec: number): Promise<void> {
+    await expect(
+      fuse.apply('editMessageText', { chat_id: CHAT, message_id: 1 }, async () => {
+        throw flood(retryAfterSec)
+      }),
+    ).rejects.toThrow()
+  }
+
+  it.each([
+    [3, 1],      // routine burst nudge
+    [30, 2],     // sustained overrate
+    [120, 3],    // a real ban
+    [3713, 4],   // the 2026-07-25 incident — straight to maximum
+    [15908, 4],  // the 2026-07-27 incident
+  ])('retry_after=%is tightens by %i level(s)', async (retryAfterSec, expected) => {
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    await observe(fuse, retryAfterSec)
+    expect(fuse.stats().tightenLevel).toBe(expected)
+  })
+
+  it('the ban-magnitude case reaches the floor in ONE 429, not four', async () => {
+    // This is the assertion that fails on the pre-fix code: there, a single
+    // 15908s ban moved the ceiling from 32 to 16 and the stream carried on at
+    // half rate into a four-hour outage.
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    expect(fuse.stats().perMessageCeiling).toBe(32)
+    await observe(fuse, 15_908)
+    expect(fuse.stats().perMessageCeiling).toBe(2) // 32 * 0.5^4
+  })
+
+  it('holds the tightening for AT LEAST the ban\'s own duration', async () => {
+    // A flat 10-minute tightenMs expired ~25× over during the 4.4h ban.
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    await observe(fuse, 15_908)
+    await clock.advance(15_907_000) // one second before the ban lifts
+    expect(fuse.stats().tightenLevel).toBeGreaterThan(0)
+    expect(fuse.stats().perMessageCeiling).toBeLessThan(32)
+  })
+
+  it('a 3s nudge still decays on the normal 10-minute schedule', async () => {
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    await observe(fuse, 3)
+    expect(fuse.stats().tightenLevel).toBe(1)
+    // Held for tightenMs PLUS the stated penalty (3s) — still ~10 minutes.
+    await clock.advance(600_001)
+    expect(fuse.stats().tightenLevel).toBe(1)
+    await clock.advance(3_001)
+    expect(fuse.stats().tightenLevel).toBe(0)
+    expect(fuse.stats().perMessageCeiling).toBe(32)
+  })
+
+  it('recovers the magnitude from a 429 that arrives as a raw ApiResponse', async () => {
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    await fuse.apply('editMessageText', { chat_id: CHAT, message_id: 1 }, async () =>
+      ({ ok: false, error_code: 429, parameters: { retry_after: 15_908 } }))
+    expect(fuse.stats().tightenLevel).toBe(4)
+  })
+
+  it('recovers the magnitude from the message text when there is no parameters block', async () => {
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    await expect(
+      fuse.apply('editMessageText', { chat_id: CHAT, message_id: 1 }, async () => {
+        throw new Error('Too Many Requests: retry after 15908')
+      }),
+    ).rejects.toThrow()
+    expect(fuse.stats().tightenLevel).toBe(4)
+  })
+
+  it('an UNQUANTIFIED flood is treated as the mildest case, not the worst', async () => {
+    // Inflating an unmeasured signal into a maximal response would let one
+    // ambiguous error message throttle the bot to 1/window.
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    await expect(
+      fuse.apply('editMessageText', { chat_id: CHAT, message_id: 1 }, async () => {
+        throw new Error('Too Many Requests')
+      }),
+    ).rejects.toThrow()
+    expect(fuse.stats().tightenLevel).toBe(1)
+  })
+
+  it('still does NOT tighten on an ordinary error that merely contains "429"', async () => {
+    const clock = new FakeClock()
+    const fuse = mk(clock)
+    await expect(
+      fuse.apply('editMessageText', { chat_id: CHAT, message_id: 1 }, async () => {
+        throw new Error('Bad Request: message 429 not found')
+      }),
+    ).rejects.toThrow()
+    expect(fuse.stats().tightenLevel).toBe(0)
+    expect(fuse.stats().floodObserved).toBe(0)
+  })
+
+  it('the default probe interval is bounded', () => {
+    expect(EDIT_FLOOD_FUSE_DEFAULTS.floodProbeIntervalMs).toBeGreaterThan(0)
+    expect(EDIT_FLOOD_FUSE_DEFAULTS.floodProbeIntervalMs).toBeLessThanOrEqual(5_000)
+  })
+})

package/telegram-plugin/tests/edit-flood-fuse-default-deny.test.ts

@@ -0,0 +1,319 @@
+/**
+ * The fuse's meter must count what Telegram counts (#3855).
+ *
+ * ── The bug these tests guard ────────────────────────────────────────────
+ * `apply` opened with an ALLOWLIST:
+ *
+ *     const isEdit = EDIT_METHODS.has(method)
+ *     const isSend = SEND_METHODS.has(method)
+ *     if (!isEdit && !isSend) return runObserved(next)      // ← everything
+ *                                                           //   else was FREE
+ *
+ * So `perChatTotalMaxPerWindow` — documented as counting "every admitted call"
+ * and "matching Telegram's own per-chat metering" — counted neither. Measured
+ * on overlord's gateway log (46791 `tg-post` lines), the unmetered share was
+ * 29% overall and 42% in the 30 minutes before the 15908s ban:
+ *
+ *     sendChatAction      10457  (up to 18/min on ONE DM — the whole documented
+ *                                 per-chat/minute allowance, counted as zero)
+ *     setMessageReaction   2098
+ *     deleteMessage         370
+ *     pinChatMessage        366
+ *     unpinChatMessage      365
+ *     answerCallbackQuery    31  (no chat_id — unkeyable per-chat)
+ *
+ * Plus: the ban is scoped to the BOT TOKEN, and the fuse had no token-scoped
+ * window at all, so nothing bounded the aggregate rate across chats.
+ *
+ * Every test below asserts an OUTCOME — how many calls reached `next` inside a
+ * window — not that a branch executed.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  createEditFloodFuse,
+  deriveBotScopeKey,
+  EDIT_FLOOD_FUSE_DEFAULTS,
+} from '../edit-flood-fuse.js'
+import type { Clock } from '../send-gate.js'
+
+const CHAT = '1001'
+
+class FakeClock implements Clock {
+  private cur = 0
+  private seq = 0
+  private timers: { at: number; id: number; resolve: () => void }[] = []
+  now(): number { return this.cur }
+  sleep(ms: number): Promise<void> {
+    return new Promise<void>((resolve) => {
+      this.timers.push({ at: this.cur + ms, id: this.seq++, resolve })
+    })
+  }
+  async advance(ms: number): Promise<void> {
+    const target = this.cur + ms
+    for (;;) {
+      await flush()
+      const due = this.timers.filter((t) => t.at <= target).sort((a, b) => a.at - b.at || a.id - b.id)
+      if (due.length === 0) break
+      const t = due[0]!
+      this.timers = this.timers.filter((x) => x !== t)
+      this.cur = t.at
+      t.resolve()
+      await flush()
+    }
+    this.cur = target
+    await flush()
+  }
+}
+const flush = (): Promise<void> => new Promise((r) => setImmediate(r))
+
+describe('default-deny metering — the 29% the allowlist could not see', () => {
+  /**
+   * The headline outcome. `sendChatAction` was the single largest unmetered
+   * method in the incident. Before the fix this loop put 60 calls on the wire
+   * inside one 60s window while the fuse reported a 20/60s ceiling as intact.
+   */
+  it('meters sendChatAction — 60 offered, at most the ceiling reaches the wire', async () => {
+    const clock = new FakeClock()
+    let landed = 0
+    const fuse = createEditFloodFuse({
+      clock, perChatTotalMaxPerWindow: 20, perChatReplyReserve: 8, perChatWindowMs: 60_000,
+    })
+
+    const calls = Array.from({ length: 60 }, () =>
+      fuse.apply('sendChatAction', { chat_id: CHAT, action: 'typing' }, async () => {
+        landed++
+        return true
+      }))
+    await clock.advance(59_000)
+    await Promise.all(calls)
+
+    // 20 total minus the 8-slot reply reserve = 12 available to cosmetic
+    // traffic, which a typing indicator is.
+    expect(landed).toBeLessThanOrEqual(12)
+    expect(landed).toBeGreaterThan(0)
+    // And the meter SAW them — this counter is zero on the pre-fix code.
+    expect(fuse.stats().meteredByDefault).toBe(60)
+  })
+
+  it.each([
+    ['setMessageReaction', { chat_id: CHAT, message_id: 5, reaction: [] }],
+    ['deleteMessage', { chat_id: CHAT, message_id: 5 }],
+    ['pinChatMessage', { chat_id: CHAT, message_id: 5 }],
+    ['unpinChatMessage', { chat_id: CHAT, message_id: 5 }],
+    // Not in EDIT_METHODS or SEND_METHODS and never was — the exact class of
+    // method default-deny exists to catch. It carries chat_id and creates a
+    // message (gateway.ts `rawSendChecklist`), so it consumes chat budget.
+    ['sendChecklist', { chat_id: CHAT, title: 't', tasks: [] }],
+    // A Bot API method this file has never heard of.
+    ['sendSomethingInventedNextYear', { chat_id: CHAT }],
+  ])('meters %s against the shared per-chat window', async (method, payload) => {
+    const clock = new FakeClock()
+    let landed = 0
+    const fuse = createEditFloodFuse({
+      clock, perChatTotalMaxPerWindow: 5, perChatReplyReserve: 0, perChatWindowMs: 60_000,
+      maxDeferMs: 1_000,
+    })
+    const calls = Array.from({ length: 30 }, () =>
+      fuse.apply(method, payload, async () => { landed++; return true }))
+    await clock.advance(2_000) // past the 1s defer deadline
+    await Promise.all(calls)
+
+    // These have durable, user-visible effects, so they are PACED not dropped —
+    // over-budget calls release at the defer deadline. The outcome that matters
+    // is that they took slots at all: the shared window is now full.
+    expect(fuse.stats().meteredByDefault).toBe(30)
+    expect(landed).toBe(30)
+    expect(fuse.stats().dropped).toBe(0)
+
+    // The proof the slots were really charged: a reply offered now finds the
+    // window saturated and is deferred rather than sailing straight through.
+    // On the pre-fix code none of the 30 took a slot, so this never deferred.
+    const before = fuse.stats().deferred
+    const reply = fuse.apply('sendMessage', { chat_id: CHAT, text: 'hi' }, async () => true)
+    await flush()
+    expect(fuse.stats().deferred).toBeGreaterThan(before)
+    await clock.advance(120_000)
+    await reply
+  })
+
+  it('never DROPS a durable-effect ancillary call — a deletion is paced, not lost', async () => {
+    const clock = new FakeClock()
+    let landed = 0
+    const fuse = createEditFloodFuse({
+      clock, perChatTotalMaxPerWindow: 2, perChatReplyReserve: 0, perChatWindowMs: 60_000,
+      maxDeferMs: 5_000,
+    })
+    const calls = Array.from({ length: 10 }, (_, i) =>
+      fuse.apply('deleteMessage', { chat_id: CHAT, message_id: i }, async () => {
+        landed++
+        return true
+      }))
+    await clock.advance(120_000)
+    await Promise.all(calls)
+    expect(landed).toBe(10)
+    expect(fuse.stats().dropped).toBe(0)
+  })
+
+  it('DOES drop a typing indicator rather than deliver it stale', async () => {
+    const clock = new FakeClock()
+    let landed = 0
+    const fuse = createEditFloodFuse({
+      clock, perChatTotalMaxPerWindow: 2, perChatReplyReserve: 0, perChatWindowMs: 60_000,
+      maxDeferMs: 30_000, chatActionMaxDeferMs: 3_000,
+    })
+    const calls = Array.from({ length: 10 }, () =>
+      fuse.apply('sendChatAction', { chat_id: CHAT, action: 'typing' }, async () => {
+        landed++
+        return true
+      }))
+    await clock.advance(30_000)
+    await Promise.all(calls)
+    expect(landed).toBe(2)
+    expect(fuse.stats().dropped).toBe(8)
+  })
+
+  it('the reply reserve survives a saturating ancillary stream', async () => {
+    // The starvation guarantee has to hold against the traffic that was
+    // previously invisible, or it is not a guarantee.
+    const clock = new FakeClock()
+    let repliesLanded = 0
+    const fuse = createEditFloodFuse({
+      clock, perChatTotalMaxPerWindow: 20, perChatReplyReserve: 8, perChatWindowMs: 60_000,
+      maxDeferMs: 30_000,
+    })
+    const noise = Array.from({ length: 200 }, () =>
+      fuse.apply('sendChatAction', { chat_id: CHAT, action: 'typing' }, async () => true))
+    await flush()
+    const replies = Array.from({ length: 8 }, (_, i) =>
+      fuse.apply('sendMessage', { chat_id: CHAT, text: `answer ${i}` }, async () => {
+        repliesLanded++
+        return true
+      }))
+    await clock.advance(120_000)
+    await Promise.all([...noise, ...replies])
+    expect(repliesLanded).toBe(8)
+  })
+})
+
+describe('the per-BOT-TOKEN window — the scope the ban actually uses', () => {
+  it('bounds the aggregate rate across MANY chats, which per-chat windows cannot', async () => {
+    // 40 distinct chats, one call each, all in the same instant. Every per-chat
+    // window is comfortably in budget; only a token-scoped window sees the sum.
+    const clock = new FakeClock()
+    let landed = 0
+    const fuse = createEditFloodFuse({
+      clock, botScopeKey: '123456789',
+      perTokenMaxPerWindow: 25, perTokenWindowMs: 1_000, maxDeferMs: 30_000,
+    })
+    const calls = Array.from({ length: 40 }, (_, i) =>
+      fuse.apply('sendMessage', { chat_id: `chat-${i}`, text: 'x' }, async () => {
+        landed++
+        return true
+      }))
+    await flush()
+    expect(landed).toBe(25) // the token ceiling, not 40
+
+    await clock.advance(2_000)
+    await Promise.all(calls)
+    // Nothing is LOST — the remaining 15 land once the window slides.
+    expect(landed).toBe(40)
+  })
+
+  it('charges a CHAT-LESS call (answerCallbackQuery) to the token window', async () => {
+    // answerCallbackQuery carries `callback_query_id`, never `chat_id`, so the
+    // per-chat tier structurally cannot key it. Before #3855 that meant it was
+    // free everywhere. It is now charged where it genuinely counts.
+    const clock = new FakeClock()
+    let landed = 0
+    const fuse = createEditFloodFuse({
+      clock, perTokenMaxPerWindow: 3, perTokenWindowMs: 1_000, maxDeferMs: 30_000,
+    })
+    const calls = Array.from({ length: 10 }, (_, i) =>
+      fuse.apply('answerCallbackQuery', { callback_query_id: `q${i}` }, async () => {
+        landed++
+        return true
+      }))
+    await flush()
+    expect(landed).toBe(3)
+    expect(fuse.stats().chatless).toBe(10)
+
+    await clock.advance(5_000)
+    await Promise.all(calls)
+    expect(landed).toBe(10) // paced, never dropped
+  })
+
+  it('BOTH windows must pass — a single hot chat is still bounded per-chat', async () => {
+    const clock = new FakeClock()
+    let landed = 0
+    const fuse = createEditFloodFuse({
+      clock,
+      perChatTotalMaxPerWindow: 4, perChatReplyReserve: 0, perChatWindowMs: 60_000,
+      // Token window wide open, so only the per-chat tier can bind.
+      perTokenMaxPerWindow: 1_000, perTokenWindowMs: 1_000,
+      maxDeferMs: 500,
+    })
+    const calls = Array.from({ length: 20 }, () =>
+      fuse.apply('sendChatAction', { chat_id: CHAT, action: 'typing' }, async () => {
+        landed++
+        return true
+      }))
+    await clock.advance(2_000) // past the 500ms defer deadline
+    await Promise.all(calls)
+    expect(landed).toBe(4)
+  })
+
+  it('separate bot ids get separate windows; the same id shares one', async () => {
+    const clock = new FakeClock()
+    const mk = (botScopeKey: string) =>
+      createEditFloodFuse({
+        clock, botScopeKey, perTokenMaxPerWindow: 2, perTokenWindowMs: 60_000,
+        perChatTotalMaxPerWindow: 1_000, maxDeferMs: 100,
+      })
+    // Two fuses with the SAME id are still two processes' worth of state — the
+    // documented limitation. What this asserts is the KEY derivation, which is
+    // what a future shared store would key on.
+    expect(deriveBotScopeKey('123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw')).toBe('123456789')
+    expect(mk('123456789')).toBeDefined()
+  })
+})
+
+describe('deriveBotScopeKey — the token itself must never become a key', () => {
+  const REAL_SHAPE = '8123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw'
+
+  it('returns ONLY the public bot id, never any part of the secret', () => {
+    const key = deriveBotScopeKey(REAL_SHAPE)
+    expect(key).toBe('8123456789')
+    const secret = REAL_SHAPE.slice(REAL_SHAPE.indexOf(':') + 1)
+    expect(key).not.toContain(secret)
+    // Not even a prefix of the secret leaks — check every prefix ≥ 4 chars.
+    for (let n = 4; n <= secret.length; n++) {
+      expect(key).not.toContain(secret.slice(0, n))
+    }
+  })
+
+  it('falls back to an irreversible hash for a token of unexpected shape', () => {
+    const odd = 'not-a-normal-token'
+    const key = deriveBotScopeKey(odd)
+    expect(key).toMatch(/^h[0-9a-f]{16}$/)
+    expect(key).not.toContain(odd)
+    // Stable — the same token must key the same window across constructions.
+    expect(deriveBotScopeKey(odd)).toBe(key)
+  })
+
+  it('handles an absent token without throwing', () => {
+    expect(deriveBotScopeKey(undefined)).toBe('unknown')
+    expect(deriveBotScopeKey('')).toBe('unknown')
+  })
+})
+
+describe('the defaults still describe the real budget', () => {
+  it('the token ceiling sits below Telegram\'s ~30/s token-level limit', () => {
+    expect(EDIT_FLOOD_FUSE_DEFAULTS.perTokenMaxPerWindow).toBeLessThan(30)
+    expect(EDIT_FLOOD_FUSE_DEFAULTS.perTokenWindowMs).toBe(1_000)
+  })
+
+  it('a chat action may not be held past its own ~5s lifetime', () => {
+    expect(EDIT_FLOOD_FUSE_DEFAULTS.chatActionMaxDeferMs).toBeLessThan(5_000)
+  })
+})