switchroom 0.17.6 → 0.18.3

package/telegram-plugin/tests/permission-rearm-wiring.test.ts

@@ -0,0 +1,175 @@
+/**
+ * Source-text wiring pins for the approval-card re-arm feature (#2861 / #2859).
+ *
+ * gateway.ts and bridge.ts have top-level side effects and aren't
+ * unit-importable; the decision logic is unit-tested in permission-rearm.test.ts
+ * and permission-ledger.test.ts. These pins lock the wiring that connects those
+ * primitives so the two failure modes can't silently regress:
+ *   R1 — gateway restart orphans pending approvals (boot-sweep stripped them).
+ *   R2 — bridge dropped permission requests while the gateway IPC was down.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const read = (p: string) => readFileSync(resolve(__dirname, '..', p), 'utf8')
+const GATEWAY = read('gateway/gateway.ts')
+const BRIDGE = read('bridge/bridge.ts')
+const IPC_CLIENT = read('bridge/ipc-client.ts')
+
+function slice(src: string, header: string, span = 2400): string {
+  const start = src.indexOf(header)
+  expect(start, `expected to find ${header}`).toBeGreaterThan(-1)
+  return src.slice(start, start + span)
+}
+
+// ─── Bridge: outstanding-request ledger (R2) ──────────────────────────────
+
+describe('bridge ledger wiring', () => {
+  it('imports and instantiates the outstanding-permission ledger', () => {
+    expect(BRIDGE).toMatch(/from '\.\/permission-ledger\.js'/)
+    expect(BRIDGE).toMatch(/createOutstandingPermissionLedger\(\)/)
+  })
+
+  it('records every permission_request in the ledger BEFORE the connect check', () => {
+    const handler = slice(BRIDGE, "method: z.literal('notifications/claude/channel/permission_request')", 2600)
+    const addIdx = handler.indexOf('outstandingPermissions.add(')
+    const connIdx = handler.indexOf('!ipc.isConnected()')
+    expect(addIdx, 'ledger.add must be present in the handler').toBeGreaterThan(-1)
+    expect(connIdx, 'connect check must be present').toBeGreaterThan(-1)
+    expect(addIdx, 'ledger.add must precede the connect check so a disconnected request is retained')
+      .toBeLessThan(connIdx)
+  })
+
+  it('the early-return no longer DROPS unconditionally — it buffers on reconnect', () => {
+    const handler = slice(BRIDGE, "method: z.literal('notifications/claude/channel/permission_request')", 2600)
+    // The old drop path was a bare `if (!ipc || !ipc.isConnected()) { log; return }`
+    // with no ledger/buffer. Pin the new buffer semantics instead.
+    expect(handler).toMatch(/buffered.*re-send on reconnect/i)
+    // Structural anti-regression: the legacy standalone drop message must only
+    // appear behind the kill-switch fallback, never as the sole behavior.
+    expect(handler).toMatch(/permissionRearmEnabled/)
+  })
+
+  it('deletes from the ledger when a verdict is delivered (onPermission)', () => {
+    const onPerm = slice(BRIDGE, 'function onPermission(msg: PermissionEvent)', 900)
+    expect(onPerm).toMatch(/outstandingPermissions\.delete\(msg\.requestId\)/)
+  })
+
+  it('flushes outstanding requests on every IPC (re)connect', () => {
+    expect(BRIDGE).toMatch(/function flushOutstandingPermissionRequests/)
+    expect(BRIDGE).toMatch(/onConnect:\s*flushOutstandingPermissionRequests/)
+    const flush = slice(BRIDGE, 'function flushOutstandingPermissionRequests', 900)
+    expect(flush).toMatch(/outstandingPermissions\.all\(\)/)
+    expect(flush).toMatch(/sendPermissionRequest/)
+  })
+
+  it('honours the SWITCHROOM_PERMISSION_REARM kill switch', () => {
+    expect(BRIDGE).toMatch(/SWITCHROOM_PERMISSION_REARM\s*!==\s*'0'/)
+  })
+})
+
+// ─── IPC client: onConnect hook ───────────────────────────────────────────
+
+describe('ipc-client onConnect hook', () => {
+  it('exposes an onConnect option', () => {
+    expect(IPC_CLIENT).toMatch(/onConnect\?:\s*\(\)\s*=>\s*void/)
+  })
+  it('invokes onConnect from the socket open() handler (after register)', () => {
+    const open = slice(IPC_CLIENT, 'open(sock)', 900)
+    const regIdx = open.indexOf('sendRegister()')
+    const connIdx = open.indexOf('onConnect(')
+    expect(connIdx, 'open() must call onConnect').toBeGreaterThan(-1)
+    expect(regIdx).toBeLessThan(connIdx)
+  })
+})
+
+// ─── Gateway: dedupe + re-arm (R1) ────────────────────────────────────────
+
+describe('gateway re-arm wiring', () => {
+  it('imports the pure re-arm helpers', () => {
+    expect(GATEWAY).toMatch(/from '\.\/permission-rearm\.js'/)
+    expect(GATEWAY).toMatch(/classifyPermissionRequest/)
+    expect(GATEWAY).toMatch(/computeBootSweepStripTargets/)
+  })
+
+  it('onPermissionRequest dedupes / re-arms before posting a card', () => {
+    const fn = slice(GATEWAY, 'onPermissionRequest(_client: IpcClient, msg: PermissionRequestForward)', 5200)
+    expect(fn).toMatch(/isPermissionRearmEnabled\(\)/)
+    expect(fn).toMatch(/classifyPermissionRequest/)
+    // duplicate → return (no second card); rearm → restore from store.
+    expect(fn).toMatch(/disposition === 'duplicate'/)
+    expect(fn).toMatch(/disposition === 'rearm'/)
+    expect(fn).toMatch(/rearmPermissionFromStore\(/)
+    // The dedup/re-arm block must sit before the card-post (formatPermissionCardBody).
+    const rearmIdx = fn.indexOf('classifyPermissionRequest')
+    const postIdx = fn.indexOf('formatPermissionCardBody')
+    expect(postIdx).toBeGreaterThan(-1)
+    expect(rearmIdx).toBeLessThan(postIdx)
+  })
+
+  it('re-arm preserves the ORIGINAL startedAt (TTL clock, not Date.now())', () => {
+    const fn = slice(GATEWAY, 'function rearmPermissionFromStore', 1800)
+    // startedAt is derived from the persisted entries, never re-stamped.
+    expect(fn).toMatch(/c\.startedAt/)
+    expect(fn).toMatch(/startedAt,/)
+    expect(fn).not.toMatch(/startedAt:\s*Date\.now\(\)/)
+    expect(fn).toMatch(/pendingPermissions\.set\(requestId/)
+  })
+
+  it('re-arm re-attaches the keyboard on the EXISTING message(s) via editMessageText', () => {
+    const fn = slice(GATEWAY, 'function rearmPermissionFromStore', 1800)
+    expect(fn).toMatch(/buildPermissionActionRow\(requestId/)
+    expect(fn).toMatch(/editMessageText\(/)
+    // Re-arm edits existing messages; it must NOT post a brand-new card.
+    expect(fn).not.toMatch(/sendRichMessage/)
+  })
+
+  it('never auto-answers — no dispatchPermissionVerdict inside re-arm (no-self-escalation)', () => {
+    const fn = slice(GATEWAY, 'function rearmPermissionFromStore', 1800)
+    expect(fn).not.toMatch(/dispatchPermissionVerdict/)
+  })
+})
+
+// ─── Gateway: grace-period boot-sweep (R1) ────────────────────────────────
+
+describe('gateway boot-sweep grace period', () => {
+  it('defers the strip when re-arm is enabled, keeps immediate strip as the kill-switch path', () => {
+    const sweep = slice(GATEWAY, 'Boot-sweep for permission cards from a prior gateway session', 4200)
+    expect(sweep).toMatch(/if \(!isPermissionRearmEnabled\(\)\)/)
+    // legacy immediate path still strips everything + clears the store
+    expect(sweep).toMatch(/permCardStore\.clear\(\)/)
+    // grace path: setTimeout + grace-ms knob + live-pending filter
+    expect(sweep).toMatch(/setTimeout\(/)
+    expect(sweep).toMatch(/permissionRearmGraceMs\(\)/)
+    // Preserve anything currently live in pendingPermissions — covers both
+    // re-armed AND fresh-during-grace cards (reviewer-caught blocker fix).
+    expect(sweep).toMatch(/new Set\(pendingPermissions\.keys\(\)\)/)
+    expect(sweep).toMatch(/computeBootSweepStripTargets\(remaining, liveRequestIds\)/)
+  })
+
+  it('the grace path removes only stripped request_ids, not the whole store', () => {
+    const sweep = slice(GATEWAY, 'Boot-sweep for permission cards from a prior gateway session', 4200)
+    // Per-request removal (preserves re-armed live entries) inside the deferred block.
+    expect(sweep).toMatch(/distinctRequestIds\(toStrip\)/)
+    expect(sweep).toMatch(/permCardStore\.remove\(id\)/)
+  })
+})
+
+// ─── Gateway: re-arm re-holds the #2840 inbound gate ──────────────────────
+
+describe('re-armed pending card re-holds the inbound gate (#2840)', () => {
+  it('turnInFlightForGate counts pending approvals', () => {
+    const gate = slice(GATEWAY, 'function turnInFlightForGate()', 1200)
+    expect(gate).toMatch(/pendingPermissions\.size > 0/)
+  })
+  it('re-arm restores a pendingPermissions entry → gate held automatically', () => {
+    // The gate reads pendingPermissions.size; rearmPermissionFromStore sets an
+    // entry, so a re-armed card holds the gate with no extra wiring.
+    const fn = slice(GATEWAY, 'function rearmPermissionFromStore', 1800)
+    expect(fn).toMatch(/pendingPermissions\.set\(requestId/)
+  })
+})

package/telegram-plugin/tests/permission-rearm.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Unit tests for the pure permission-card re-arm helpers (#2861 / #2859).
+ *
+ * These cover the discriminable decision logic extracted from gateway.ts
+ * (which has top-level side effects and isn't unit-importable):
+ *   - classifyPermissionRequest — duplicate / rearm / fresh
+ *   - computeBootSweepStripTargets — grace-period strip filtering
+ *   - isPermissionRearmEnabled / permissionRearmGraceMs — kill switch + knob
+ *   - distinctRequestIds
+ *
+ * The gateway/bridge WIRING that consumes these is pinned separately in
+ * permission-rearm-wiring.test.ts.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  classifyPermissionRequest,
+  computeBootSweepStripTargets,
+  isPermissionRearmEnabled,
+  permissionRearmGraceMs,
+  distinctRequestIds,
+  PERMISSION_REARM_GRACE_MS,
+} from '../gateway/permission-rearm.js'
+import type { PersistedPermCard } from '../gateway/permission-card-store.js'
+
+function card(requestId: string, messageId: number): PersistedPermCard {
+  return {
+    requestId,
+    chatId: '-100123',
+    messageId,
+    startedAt: 1_000,
+    toolName: 'mcp__brevo__post',
+    cardText: 'Marko wants to post to Brevo',
+  }
+}
+
+describe('classifyPermissionRequest', () => {
+  it('already-live request → duplicate (ignore, no second card)', () => {
+    expect(classifyPermissionRequest({ hasPending: true, persistedCount: 0 })).toBe('duplicate')
+    // hasPending wins even if the store also has it
+    expect(classifyPermissionRequest({ hasPending: true, persistedCount: 2 })).toBe('duplicate')
+  })
+
+  it('gone from memory but persisted → rearm', () => {
+    expect(classifyPermissionRequest({ hasPending: false, persistedCount: 1 })).toBe('rearm')
+    expect(classifyPermissionRequest({ hasPending: false, persistedCount: 3 })).toBe('rearm')
+  })
+
+  it('unknown request → fresh (post a new card)', () => {
+    expect(classifyPermissionRequest({ hasPending: false, persistedCount: 0 })).toBe('fresh')
+  })
+})
+
+describe('computeBootSweepStripTargets', () => {
+  it('strips only entries whose request_id is NOT currently live', () => {
+    const stale = [card('aaaaa', 10), card('bbbbb', 11), card('ccccc', 12)]
+    const live = new Set(['bbbbb']) // bbbbb re-armed / still pending
+    const targets = computeBootSweepStripTargets(stale, live)
+    expect(targets.map(t => t.requestId)).toEqual(['aaaaa', 'ccccc'])
+  })
+
+  it('a re-armed (live) entry survives the deadline (empty strip)', () => {
+    const stale = [card('aaaaa', 10)]
+    const live = new Set(['aaaaa'])
+    expect(computeBootSweepStripTargets(stale, live)).toEqual([])
+  })
+
+  it('a dead-session entry (no live pending) is stripped at the deadline', () => {
+    const stale = [card('aaaaa', 10)]
+    const live = new Set<string>()
+    expect(computeBootSweepStripTargets(stale, live).map(t => t.requestId)).toEqual(['aaaaa'])
+  })
+
+  it('a FRESH card born during the grace window (live but not in the boot set) survives', () => {
+    // Regression for the reviewer-caught blocker: a new approval posted after
+    // boot writes its own persisted row, so it appears in `remaining` at the
+    // deadline. It's live in pendingPermissions, so it must NOT be stripped —
+    // otherwise a legitimately-suspended turn gets re-wedged.
+    const remaining = [card('dead0', 10), card('fresh', 20)]
+    const live = new Set(['fresh']) // 'fresh' posted during grace, still pending
+    const targets = computeBootSweepStripTargets(remaining, live)
+    expect(targets.map(t => t.requestId)).toEqual(['dead0'])
+  })
+
+  it('keeps ALL fan-out messages for a dead-session request', () => {
+    // Same request_id, two operator surfaces → two persisted rows.
+    const stale = [card('aaaaa', 10), card('aaaaa', 20)]
+    const targets = computeBootSweepStripTargets(stale, new Set())
+    expect(targets).toHaveLength(2)
+    expect(targets.map(t => t.messageId).sort()).toEqual([10, 20])
+  })
+})
+
+describe('distinctRequestIds', () => {
+  it('dedupes request_ids across fan-out rows', () => {
+    const cards = [card('aaaaa', 10), card('aaaaa', 20), card('bbbbb', 30)]
+    expect(distinctRequestIds(cards).sort()).toEqual(['aaaaa', 'bbbbb'])
+  })
+})
+
+describe('isPermissionRearmEnabled (kill switch)', () => {
+  it('enabled by default (unset)', () => {
+    expect(isPermissionRearmEnabled({})).toBe(true)
+  })
+  it('enabled for any value other than "0"', () => {
+    expect(isPermissionRearmEnabled({ SWITCHROOM_PERMISSION_REARM: '1' })).toBe(true)
+    expect(isPermissionRearmEnabled({ SWITCHROOM_PERMISSION_REARM: 'on' })).toBe(true)
+  })
+  it('disabled only for the exact "0" kill value', () => {
+    expect(isPermissionRearmEnabled({ SWITCHROOM_PERMISSION_REARM: '0' })).toBe(false)
+  })
+})
+
+describe('permissionRearmGraceMs', () => {
+  it('defaults to PERMISSION_REARM_GRACE_MS when unset', () => {
+    expect(permissionRearmGraceMs({})).toBe(PERMISSION_REARM_GRACE_MS)
+  })
+  it('honours a finite non-negative override (test collapse)', () => {
+    expect(permissionRearmGraceMs({ SWITCHROOM_PERMISSION_REARM_GRACE_MS: '0' })).toBe(0)
+    expect(permissionRearmGraceMs({ SWITCHROOM_PERMISSION_REARM_GRACE_MS: '250' })).toBe(250)
+  })
+  it('falls back to the default on garbage / negative', () => {
+    expect(permissionRearmGraceMs({ SWITCHROOM_PERMISSION_REARM_GRACE_MS: 'nope' })).toBe(PERMISSION_REARM_GRACE_MS)
+    expect(permissionRearmGraceMs({ SWITCHROOM_PERMISSION_REARM_GRACE_MS: '-5' })).toBe(PERMISSION_REARM_GRACE_MS)
+  })
+})

package/telegram-plugin/tests/quota-watch.test.ts

@@ -696,12 +696,11 @@ import {
 } from "../quota-watch.js";
 
 describe("resolveQuotaWatchTuning", () => {
-  it("defaults: stale gate 60min, late-recovery 6h, dedup on, probe-fail send off", () => {
+  it("defaults: stale gate 60min, late-recovery 6h, dedup on", () => {
     const t = resolveQuotaWatchTuning({});
     expect(t.maxStaleMs).toBe(DEFAULT_QUOTA_WATCH_MAX_STALE_MS);
     expect(t.lateRecoveryMs).toBe(DEFAULT_QUOTA_WATCH_LATE_RECOVERY_MS);
     expect(t.fleetDedup).toBe(true);
-    expect(t.sendOnProbeFail).toBe(false);
   });
 
   it("each knob is individually kill-switchable", () => {
@@ -709,12 +708,10 @@ describe("resolveQuotaWatchTuning", () => {
       SWITCHROOM_QUOTA_WATCH_MAX_STALE_MS: "0",
       SWITCHROOM_QUOTA_WATCH_LATE_RECOVERY_MS: "0",
       SWITCHROOM_QUOTA_WATCH_FLEET_DEDUP: "0",
-      SWITCHROOM_QUOTA_WATCH_SEND_ON_PROBE_FAIL: "1",
     });
     expect(t.maxStaleMs).toBe(0);
     expect(t.lateRecoveryMs).toBe(0);
     expect(t.fleetDedup).toBe(false);
-    expect(t.sendOnProbeFail).toBe(true);
   });
 
   it("garbage numeric values fall back to defaults", () => {

package/telegram-plugin/tests/rapid-fire-delivery-ordering.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  decideInboundDelivery,
+  reserveInboundDelivery,
+} from '../gateway/inbound-delivery-gate.js'
+
+/**
+ * #2917 — rapid-fire DM: replies emitted late & out of order.
+ *
+ * Root cause: the #1556 delivery gate is documented as a LIVE read
+ * ("evaluated at delivery time — not a receipt-time snapshot"), but on the
+ * concurrent `handleInbound` path the gate decision and the busy-mark that
+ * records "a turn is in flight for this chat" were separated by an `await`
+ * (attachment download, composer-clear). Two same-chat inbounds each read
+ * "idle" during the other's async lead-in, both passed the gate, and both
+ * were delivered to the bridge — so the replies came back reordered.
+ *
+ * The fix couples the deliver decision with a synchronous RESERVE
+ * (`reserveInboundDelivery`): a fresh-turn deliver reserves the chat's busy
+ * key BEFORE any await, so a concurrent same-chat inbound observes the
+ * reservation on the live gate and buffers behind it — restoring per-chat
+ * FIFO without dropping anything (a buffered inbound drains on turn-complete
+ * / idle exactly as before).
+ */
+describe('reserveInboundDelivery — fresh-turn reservation flag', () => {
+  it('reserves a fresh-turn deliver (idle, non-steering, non-interrupt)', () => {
+    const r = reserveInboundDelivery({ turnInFlight: false, isSteering: false, isInterrupt: false })
+    expect(r.decision).toBe('deliver')
+    expect(r.reserve).toBe(true)
+  })
+
+  it('does NOT reserve a buffered (mid-turn) inbound', () => {
+    const r = reserveInboundDelivery({ turnInFlight: true, isSteering: false, isInterrupt: false })
+    expect(r.decision).toBe('buffer-until-idle')
+    expect(r.reserve).toBe(false)
+  })
+
+  it('does NOT reserve a steering deliver (amends the running turn)', () => {
+    const r = reserveInboundDelivery({ turnInFlight: true, isSteering: true, isInterrupt: false })
+    expect(r.decision).toBe('deliver')
+    expect(r.reserve).toBe(false)
+  })
+
+  it('does NOT reserve an interrupt deliver (amends the running turn)', () => {
+    const r = reserveInboundDelivery({ turnInFlight: true, isSteering: false, isInterrupt: true })
+    expect(r.decision).toBe('deliver')
+    expect(r.reserve).toBe(false)
+  })
+
+  it('decision stays byte-identical to decideInboundDelivery across the matrix', () => {
+    for (const turnInFlight of [false, true]) {
+      for (const isSteering of [false, true]) {
+        for (const isInterrupt of [false, true]) {
+          const input = { turnInFlight, isSteering, isInterrupt }
+          expect(reserveInboundDelivery(input).decision).toBe(decideInboundDelivery(input))
+        }
+      }
+    }
+  })
+})
+
+/**
+ * A minimal model of the gateway's concurrent same-chat delivery path. Each
+ * inbound handler:
+ *   1. reads the LIVE gate off the shared busy set,
+ *   2. yields at an `await` (the composer-clear / attachment lead-in),
+ *   3. on a reserving deliver, marks the chat busy and appends to the wire.
+ *
+ * This reproduces the ordering race deterministically: two same-chat handlers
+ * whose async lead-ins overlap. The `syncReserve` flag toggles the fix — when
+ * off (legacy: mark busy only AFTER the await), both handlers deliver and the
+ * wire order is decided by the await race; when on (#2917: reserve BEFORE the
+ * await), the second handler sees the reservation and buffers, preserving FIFO.
+ */
+interface WireResult {
+  delivered: string[]
+  buffered: string[]
+}
+
+async function runTwoConcurrentInbounds(opts: {
+  syncReserve: boolean
+  /** ms the first handler's lead-in await takes vs the second's. First is
+   *  SLOWER so, without the fix, the second overtakes it on the wire. */
+  firstLeadInMs: number
+  secondLeadInMs: number
+}): Promise<WireResult> {
+  const busy = new Set<string>()
+  const key = 'chatDM:_'
+  const delivered: string[] = []
+  const buffered: string[] = []
+
+  const handle = async (id: string, leadInMs: number): Promise<void> => {
+    // Step 1 — live gate read.
+    const gate = reserveInboundDelivery({
+      turnInFlight: busy.size > 0,
+      isSteering: false,
+      isInterrupt: false,
+    })
+    if (gate.decision === 'buffer-until-idle') {
+      buffered.push(id)
+      return
+    }
+    // Step 2 — the fix reserves synchronously BEFORE the await.
+    let reserved = false
+    if (opts.syncReserve && gate.reserve) {
+      busy.add(key)
+      reserved = true
+    }
+    // Step 3 — the async lead-in (composer-clear / attachment download).
+    await new Promise((r) => setTimeout(r, leadInMs))
+    // Step 4 — legacy marks busy only now, after the await.
+    if (!reserved) busy.add(key)
+    delivered.push(id)
+  }
+
+  await Promise.all([
+    handle('msg1', opts.firstLeadInMs),
+    handle('msg2', opts.secondLeadInMs),
+  ])
+  return { delivered, buffered }
+}
+
+describe('rapid-fire same-chat delivery ordering (#2917)', () => {
+  it('LEGACY (mark-after-await): the faster second inbound overtakes the first — reorder', async () => {
+    // msg1's lead-in is slower, so with the busy-mark deferred until after the
+    // await BOTH pass the idle gate and BOTH deliver, with msg2 landing first.
+    const { delivered, buffered } = await runTwoConcurrentInbounds({
+      syncReserve: false,
+      firstLeadInMs: 20,
+      secondLeadInMs: 1,
+    })
+    expect(buffered).toEqual([]) // nothing buffered — the bug
+    expect(delivered).toEqual(['msg2', 'msg1']) // out of order
+  })
+
+  it('FIX (sync reserve): the second inbound sees the reservation and buffers — FIFO preserved', async () => {
+    const { delivered, buffered } = await runTwoConcurrentInbounds({
+      syncReserve: true,
+      firstLeadInMs: 20,
+      secondLeadInMs: 1,
+    })
+    // msg1 reserved synchronously; msg2's live gate sees busy → buffers.
+    expect(delivered).toEqual(['msg1'])
+    expect(buffered).toEqual(['msg2'])
+    // msg2 is not lost — it is held for the turn-complete / idle drain, which
+    // re-delivers it in order after msg1's turn ends.
+  })
+})

package/telegram-plugin/tests/render/parse-torture.test.ts

@@ -0,0 +1,136 @@
+// Cross-check the new markdown->IR parser (render/parse.ts) against the
+// existing adversarial torture-fixture set (formatting-torture-set.ts).
+//
+// This does NOT exercise the renderer or chunker (out of scope for the
+// parser+IR increment) — it feeds each fixture's raw `input` straight into
+// `parse()` and walks the resulting IR tree collecting a flat entity list,
+// then asserts every entity the fixture's `expect` block calls for is
+// present in that list. This is a structural cross-check independent of the
+// existing gateway-pipeline oracle: it proves the new parser captures the
+// same intent the current hand-rolled pipeline is required to preserve.
+import { describe, it, expect } from 'vitest'
+import { parse } from '../../render/parse.js'
+import type { Block, Inline } from '../../render/ir.js'
+import { TORTURE_SET, type ExpectEntity } from '../formatting-torture-set.js'
+import type { EntityType } from '../rich-markdown-oracle.js'
+
+interface FlatEntity {
+  type: EntityType
+  text: string
+  url?: string
+  lang?: string
+}
+
+function textOf(nodes: Inline[]): string {
+  return nodes
+    .map((n) => {
+      switch (n.type) {
+        case 'plain':
+        case 'code':
+          return n.text
+        default:
+          return textOf(n.children)
+      }
+    })
+    .join('')
+}
+
+function walkInline(node: Inline, out: FlatEntity[]) {
+  switch (node.type) {
+    case 'bold':
+      out.push({ type: 'bold', text: textOf(node.children) })
+      node.children.forEach((c) => walkInline(c, out))
+      break
+    case 'italic':
+      out.push({ type: 'italic', text: textOf(node.children) })
+      node.children.forEach((c) => walkInline(c, out))
+      break
+    case 'strike':
+      out.push({ type: 'strikethrough', text: textOf(node.children) })
+      node.children.forEach((c) => walkInline(c, out))
+      break
+    case 'code':
+      out.push({ type: 'code', text: node.text })
+      break
+    case 'link':
+      out.push({ type: 'link', text: textOf(node.children), url: node.href })
+      node.children.forEach((c) => walkInline(c, out))
+      break
+    case 'plain':
+      break
+    case 'underline':
+    case 'spoiler':
+    case 'highlight':
+      // No dedicated oracle EntityType for these Bot API 10.1 constructs yet;
+      // recurse so any nested bold/italic/code/link inside them is still
+      // collected for the cross-check.
+      node.children.forEach((c) => walkInline(c, out))
+      break
+  }
+}
+
+function walkBlock(node: Block, out: FlatEntity[]) {
+  switch (node.type) {
+    case 'paragraph':
+    case 'heading':
+      node.children.forEach((c) => walkInline(c, out))
+      break
+    case 'blockquote':
+      node.children.forEach((c) => walkBlock(c, out))
+      break
+    case 'code-block':
+      out.push({ type: 'pre', text: node.text, lang: node.language ?? undefined })
+      break
+    case 'list':
+      for (const item of node.items) item.children.forEach((c) => walkBlock(c, out))
+      break
+    case 'table':
+      for (const row of [node.header, ...node.rows]) {
+        for (const cell of row.cells) cell.children.forEach((c) => walkInline(c, out))
+      }
+      break
+    case 'thematic-break':
+      break
+  }
+}
+
+function flatten(input: string): FlatEntity[] {
+  const doc = parse(input)
+  const out: FlatEntity[] = []
+  doc.blocks.forEach((b) => walkBlock(b, out))
+  return out
+}
+
+function matches(found: FlatEntity[], want: ExpectEntity): boolean {
+  return found.some(
+    (f) =>
+      f.type === want.type &&
+      f.text === want.text &&
+      (want.url === undefined || f.url === want.url) &&
+      (want.lang === undefined || f.lang === want.lang),
+  )
+}
+
+describe('parse: torture-fixture cross-check', () => {
+  for (const fixture of TORTURE_SET) {
+    if (fixture.expect.length === 0) {
+      // No entity assertions for this fixture — just prove parse() doesn't
+      // throw and returns at least one block (structure-only fixtures).
+      it(`${fixture.name}: parses without throwing`, () => {
+        const doc = parse(fixture.input)
+        expect(doc.blocks.length).toBeGreaterThan(0)
+      })
+      continue
+    }
+
+    it(`${fixture.name}: IR captures every expected entity`, () => {
+      const found = flatten(fixture.input)
+      for (const want of fixture.expect) {
+        expect(
+          matches(found, want),
+          `expected a ${want.type} entity with text ${JSON.stringify(want.text)} in fixture "${fixture.name}"; found: ${JSON.stringify(found)}`,
+        ).toBe(true)
+      }
+    })
+  }
+})