switchroom 0.21.10 → 0.21.12

package/telegram-plugin/gateway/answer-route-overrides.ts

@@ -0,0 +1,163 @@
+/**
+ * answer-route-overrides.ts — a bounded, in-memory record of the reply router's
+ * EXPLICIT-THREAD OVERRIDES, so a later consumer can ask "was an answer the model
+ * addressed to topic N actually delivered somewhere else?".
+ *
+ * WHY THIS EXISTS. `resolveAnswerThreadWithLog` already computes this fact and
+ * logs it (`EXPLICIT_OVERRIDDEN(model→4,routed→635)`): the model named a topic
+ * on its `reply`, and the framework's topic authority overrode that with the
+ * origin/live turn's topic. The answer therefore lands under a DIFFERENT
+ * `thread_id` than the one the model was answering — invisible to any
+ * thread-keyed history query for the topic the model meant.
+ *
+ * The obligation-escalation staleness check is exactly such a query, and the
+ * override is the ONLY per-turn evidence that ties an answer delivered in topic
+ * B to a question asked in topic A. Recording it turns "an answer landed
+ * somewhere in this chat" (an unfalsifiable chat-wide guess) into "an answer the
+ * model addressed to THIS topic landed in that topic" — a specific, checkable
+ * claim. See `escalation-staleness.ts` for the consumer and the field evidence.
+ *
+ * Bounded by construction: at most `maxKeys` (chat, intended-thread) keys and
+ * `maxPerKey` recent routings each, evicted oldest-first. Losing an entry can
+ * only ever cost one over-escalation (the safe direction — an extra advisory,
+ * never a swallowed message).
+ */
+
+/** One observed override: the model meant `intendedThreadId`, it went here. */
+export interface AnswerRouteOverride {
+  /** Where the answer actually went. `null` = chat root / no topic (history
+   *  stores `thread_id IS NULL` for these — `recordOutbound` does `?? null`). */
+  routedThreadId: number | null
+  /** Wall-clock ms at which the routing decision was made. */
+  atMs: number
+}
+
+export interface NoteOverrideArgs {
+  chatId: string
+  /** `REPLY_TOPIC_AUTHORITY_ENABLED` — no authority, no override. */
+  enabled: boolean
+  /** The topic the model named on its reply, if any. */
+  explicitThreadId: number | undefined
+  /** Whether a framework anchor (origin or live turn) was present to override with. */
+  anchored: boolean
+  /** The thread the router actually resolved. `undefined` = chat root. */
+  routedThreadId: number | undefined
+  nowMs: number
+}
+
+export interface AnswerRouteOverrides {
+  /**
+   * Record the routing decision iff it WAS an explicit-thread override, and
+   * return whether it was — so the caller can use the same boolean for its
+   * telemetry instead of computing the predicate twice.
+   */
+  note(args: NoteOverrideArgs): boolean
+  /**
+   * Overrides recorded for `intendedThreadId` at or after `notBeforeMs`, one per
+   * distinct routed thread (the EARLIEST in-window record for that thread wins,
+   * so a consumer using `atMs` as a cutoff gets the widest correct one). Empty
+   * when no override was observed — which is the common case and means "no
+   * reason to look outside this topic".
+   *
+   * The caller MUST use each entry's `atMs` as the lower bound of whatever it
+   * looks up next, and MUST pass a `notBeforeMs` that bounds how old an override
+   * may be. An override only licenses a query for the answer THAT routing
+   * produced; it is not a standing licence to accept anything ever delivered in
+   * that thread. See `escalation-staleness.ts` for the incident that proves it.
+   */
+  routedOverridesSince(
+    chatId: string,
+    intendedThreadId: number | null | undefined,
+    notBeforeMs: number,
+  ): AnswerRouteOverride[]
+  /**
+   * The MOST RECENT override recorded for `intendedThreadId` at or after
+   * `notBeforeMs`, or `undefined` if there is none.
+   *
+   * Diagnostic-only, and deliberately separate from `routedOverridesSince`:
+   * that one returns the EARLIEST in-window record per routed thread because a
+   * consumer uses `atMs` as a history cutoff and wants the widest correct one.
+   * A consumer asking "did a record exist that my freshness bound rejected, and
+   * by how much?" wants the other end — the near-miss. Kept as its own method so
+   * answering that can never perturb the accept path's cutoff.
+   */
+  newestOverrideSince(
+    chatId: string,
+    intendedThreadId: number | null | undefined,
+    notBeforeMs: number,
+  ): AnswerRouteOverride | undefined
+  /** Live key count. Test/diagnostic surface. */
+  size(): number
+  /**
+   * Drop every recorded override. Test surface: the process-wide registry below
+   * is a module singleton, so without a reset one test's records leak into the
+   * next and a scenario silently depends on its neighbours' timestamps. Not
+   * called in production — the bounded eviction owns lifetime there.
+   */
+  clear(): void
+}
+
+function keyFor(chatId: string, threadId: number | null | undefined): string {
+  return `${chatId}:${threadId ?? '_'}`
+}
+
+export function createAnswerRouteOverrides(maxKeys = 64, maxPerKey = 8): AnswerRouteOverrides {
+  // Insertion-ordered Map; eviction is oldest-INSERTED-first (FIFO), not
+  // least-recently-used — entries are not re-inserted on read.
+  const byKey = new Map<string, AnswerRouteOverride[]>()
+  return {
+    note(args: NoteOverrideArgs): boolean {
+      const overridden =
+        args.enabled &&
+        args.explicitThreadId != null &&
+        args.anchored &&
+        args.routedThreadId !== args.explicitThreadId
+      if (!overridden) return false
+      const key = keyFor(args.chatId, args.explicitThreadId)
+      const list = byKey.get(key) ?? []
+      list.push({ routedThreadId: args.routedThreadId ?? null, atMs: args.nowMs })
+      while (list.length > maxPerKey) list.shift()
+      byKey.set(key, list)
+      while (byKey.size > maxKeys) {
+        const oldest = byKey.keys().next().value
+        if (oldest === undefined) break
+        byKey.delete(oldest)
+      }
+      return true
+    },
+    routedOverridesSince(chatId, intendedThreadId, notBeforeMs): AnswerRouteOverride[] {
+      const list = byKey.get(keyFor(chatId, intendedThreadId))
+      if (list == null) return []
+      const out: AnswerRouteOverride[] = []
+      for (const e of list) {
+        if (e.atMs < notBeforeMs) continue
+        if (out.some((seen) => seen.routedThreadId === e.routedThreadId)) continue
+        out.push({ ...e })
+      }
+      return out
+    },
+    newestOverrideSince(chatId, intendedThreadId, notBeforeMs): AnswerRouteOverride | undefined {
+      const list = byKey.get(keyFor(chatId, intendedThreadId))
+      if (list == null) return undefined
+      let newest: AnswerRouteOverride | undefined
+      for (const e of list) {
+        if (e.atMs < notBeforeMs) continue
+        if (newest == null || e.atMs > newest.atMs) newest = e
+      }
+      return newest == null ? undefined : { ...newest }
+    },
+    size(): number {
+      return byKey.size
+    },
+    clear(): void {
+      byKey.clear()
+    },
+  }
+}
+
+/**
+ * Process-wide registry. The gateway is a single process and the router is the
+ * only writer; obligation-wiring is the only reader. Injected as a value into
+ * the pure decision functions so tests never touch this instance.
+ */
+export const answerRouteOverrides = createAnswerRouteOverrides()

package/telegram-plugin/gateway/answer-thread-resolve.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect } from 'vitest'
-import { resolveAnswerThreadId, type AnswerThreadInput } from './answer-thread-resolve.js'
+import {
+  resolveAnswerThreadId,
+  isCrossChatAnchor,
+  type AnswerThreadInput,
+} from './answer-thread-resolve.js'
 
 // Distinct symbolic thread ids so an output's provenance is unambiguous (no two
 // tiers share a value): explicit=70, origin=50, live=30, lastEnded=90.
@@ -107,6 +111,143 @@ describe('resolveAnswerThreadId — legacy (frameworkTopicAuthority:false)', ()
   })
 })
 
+// ── Cross-chat anchor guard (bug c, 2026-08-13) ─────────────────────────────
+//
+// The live failure: a reply into chat A resolved its thread from an anchor turn
+// owned by forum supergroup B, so B's topic id rode along on the send into A and
+// Telegram answered `400 Bad Request: message thread not found`. The retry
+// fallback resent threadless and succeeded, so the symptom was a guaranteed-
+// failed FIRST API call rather than a lost message. Each case below asserts the
+// RESOLVED THREAD, not that a branch ran.
+const CHAT_A = '12345678' // a DM — the reply target
+const CHAT_B = '-1001234567890' // a forum supergroup — where the anchor lives
+
+describe('resolveAnswerThreadId — cross-chat anchor guard', () => {
+  it("THE bug: a live turn in supergroup B must not lend its topic to a reply into chat A", () => {
+    expect(
+      resolveAnswerThreadId({
+        targetChatId: CHAT_A,
+        originResolved: false,
+        liveTurnPresent: true,
+        liveThreadId: 635, // B's topic — the id Telegram rejected
+        liveChatId: CHAT_B,
+      }),
+    ).toBeUndefined() // → no thread; the send into A is threadless and succeeds
+  })
+
+  it('a cross-chat ORIGIN anchor (origin_turn_id echoed from another chat) is ignored', () => {
+    expect(
+      resolveAnswerThreadId({
+        targetChatId: CHAT_A,
+        originResolved: true,
+        originThreadId: O,
+        originChatId: CHAT_B,
+      }),
+    ).toBeUndefined()
+  })
+
+  it('a dropped cross-chat anchor falls through to the model explicit (its only remaining signal)', () => {
+    expect(
+      resolveAnswerThreadId({
+        targetChatId: CHAT_A,
+        explicitThreadId: T,
+        originResolved: true,
+        originThreadId: O,
+        originChatId: CHAT_B,
+        liveTurnPresent: true,
+        liveThreadId: L,
+        liveChatId: CHAT_B,
+      }),
+    ).toBe(T)
+  })
+
+  it('a dropped cross-chat anchor falls through to the chat-scoped last-ended recovery when there is no explicit', () => {
+    expect(
+      resolveAnswerThreadId({
+        targetChatId: CHAT_A,
+        originResolved: false,
+        liveTurnPresent: true,
+        liveThreadId: L,
+        liveChatId: CHAT_B,
+        lastEndedResolvedForChat: true,
+        lastEndedThreadIdForChat: E,
+      }),
+    ).toBe(E)
+  })
+
+  it('a SAME-chat anchor is untouched — the guard only drops foreign chats', () => {
+    expect(
+      resolveAnswerThreadId({
+        targetChatId: CHAT_B,
+        explicitThreadId: T,
+        originResolved: true,
+        originThreadId: O,
+        originChatId: CHAT_B,
+      }),
+    ).toBe(O)
+  })
+
+  it('an origin in chat A survives while a live turn in chat B is dropped (independent guards)', () => {
+    expect(
+      resolveAnswerThreadId({
+        targetChatId: CHAT_A,
+        originResolved: true,
+        originThreadId: O,
+        originChatId: CHAT_A,
+        liveTurnPresent: true,
+        liveThreadId: L,
+        liveChatId: CHAT_B,
+      }),
+    ).toBe(O)
+  })
+
+  it('the guard also applies under the legacy kill switch — a wrong-chat topic is an API error, not a precedence policy', () => {
+    expect(
+      resolveAnswerThreadId({
+        frameworkTopicAuthority: false,
+        targetChatId: CHAT_A,
+        originResolved: true,
+        originThreadId: O,
+        originChatId: CHAT_B,
+        liveThreadId: L,
+        liveChatId: CHAT_B,
+      }),
+    ).toBeUndefined()
+  })
+
+  it('numeric-vs-string chat ids compare by value, so no anchor is dropped spuriously', () => {
+    expect(
+      resolveAnswerThreadId({
+        targetChatId: CHAT_B,
+        originResolved: true,
+        originThreadId: O,
+        originChatId: String(Number(CHAT_B)),
+      }),
+    ).toBe(O)
+  })
+
+  it('BACK-COMPAT: with no chat ids supplied the guard is inert (identical to pre-guard routing)', () => {
+    expect(
+      resolveAnswerThreadId({
+        originResolved: false,
+        liveTurnPresent: true,
+        liveThreadId: L,
+      }),
+    ).toBe(L)
+  })
+})
+
+describe('isCrossChatAnchor', () => {
+  it('true only when both ids are present and differ', () => {
+    expect(isCrossChatAnchor(CHAT_A, CHAT_B)).toBe(true)
+    expect(isCrossChatAnchor(CHAT_A, CHAT_A)).toBe(false)
+    expect(isCrossChatAnchor(undefined, CHAT_B)).toBe(false)
+    expect(isCrossChatAnchor(CHAT_A, undefined)).toBe(false)
+    expect(isCrossChatAnchor('', CHAT_B)).toBe(false)
+    expect(isCrossChatAnchor(CHAT_A, '')).toBe(false)
+  })
+})
+
 // ── TOTAL-ENUMERATION DETERMINISM PROOF ─────────────────────────────────────
 //
 // The operator standard (memory feedback_prove_finite_fsm_not_sample): a passing
@@ -238,4 +379,37 @@ describe('resolveAnswerThreadId — total-enumeration proof (54 reachable inputs
   it('INV-EXPLICIT-DOMINANCE (legacy): explicit set ⇒ output === explicit, independent of all other fields', () => {
     for (const i of LEGACY) if (i.explicitThreadId != null) expect(resolveAnswerThreadId(i)).toBe(i.explicitThreadId)
   })
+
+  // ── Cross-chat guard, proved over the same enumeration (both modes) ────────
+  it('INV-CROSS-CHAT: anchors in a FOREIGN chat route exactly as if they did not exist, on all 54 inputs × 2 modes', () => {
+    for (const i of [...FA, ...LEGACY]) {
+      const foreign = resolveAnswerThreadId({
+        ...i,
+        targetChatId: CHAT_A,
+        originChatId: CHAT_B,
+        liveChatId: CHAT_B,
+      })
+      const anchorless = resolveAnswerThreadId({
+        ...i,
+        originResolved: false,
+        originThreadId: undefined,
+        liveTurnPresent: false,
+        liveThreadId: undefined,
+      })
+      expect(foreign).toBe(anchorless)
+    }
+  })
+
+  it('INV-SAME-CHAT: annotating anchors with the TARGET chat changes nothing, on all 54 inputs × 2 modes', () => {
+    for (const i of [...FA, ...LEGACY]) {
+      expect(
+        resolveAnswerThreadId({
+          ...i,
+          targetChatId: CHAT_A,
+          originChatId: CHAT_A,
+          liveChatId: CHAT_A,
+        }),
+      ).toBe(resolveAnswerThreadId(i))
+    }
+  })
 })

package/telegram-plugin/gateway/answer-thread-resolve.ts

@@ -44,6 +44,20 @@
  *      orphaned-backstop reply lands in its topic instead of defaulting to the
  *      main chat (General). Not the `chatThreadMap` last-seen heuristic.
  *
+ * **(c) cross-chat thread anchor (2026-08-13).** A reply targeting chat A can be
+ * resolved against a turn anchor that belongs to a DIFFERENT chat B — the
+ * `origin_turn_id` echo lookup is keyed by turn id alone (not chat-scoped), and
+ * the LIVE turn is whatever the session is currently running, which in a
+ * multi-chat agent is frequently another chat. When B is a forum supergroup, its
+ * topic id was attached to the send into A and Telegram rejected the call with
+ * `400 Bad Request: message thread not found`. A retry fallback resent with no
+ * thread and succeeded, so nothing was lost — but every occurrence was a
+ * guaranteed-failed first API call (observed 3× since 2026-08-08). Fixed by
+ * IGNORING any anchor whose chat id does not match the target chat: precedence
+ * falls through to the model's explicit thread / no thread, exactly as if the
+ * anchor did not exist. The chat ids are optional inputs, so a caller that
+ * supplies none keeps the pre-existing behaviour verbatim.
+ *
  * Setting `frameworkTopicAuthority: false` (kill switch
  * SWITCHROOM_REPLY_TOPIC_AUTHORITY=0) restores the legacy explicit-first
  * precedence (the model's thread wins outright).
@@ -95,6 +109,33 @@ export interface AnswerThreadInput {
    * true. Kill switch SWITCHROOM_REPLY_TOPIC_AUTHORITY=0.
    */
   frameworkTopicAuthority?: boolean
+  /**
+   * Chat this reply is being SENT to (bug c). When supplied together with an
+   * anchor's chat id, an anchor from a DIFFERENT chat is ignored. Undefined
+   * disables the guard (behaviour identical to before the guard existed).
+   */
+  targetChatId?: string | undefined
+  /** Chat the ORIGIN anchor turn belongs to (`turn.sessionChatId`). */
+  originChatId?: string | undefined
+  /** Chat the LIVE in-flight turn belongs to (`turn.sessionChatId`). */
+  liveChatId?: string | undefined
+}
+
+/**
+ * True when `anchorChatId` names a DIFFERENT chat than the reply's target — i.e.
+ * the anchor's thread must NOT be attached to this send (bug c). Conservative:
+ * returns false when either id is absent, so an un-instrumented caller is
+ * unaffected. Exported so the gateway's telemetry (`via`,
+ * `CROSS_CHAT_ANCHOR_DROPPED`) derives from the SAME predicate that routes,
+ * rather than a second copy that can drift out of sync.
+ */
+export function isCrossChatAnchor(
+  targetChatId: string | undefined,
+  anchorChatId: string | undefined,
+): boolean {
+  if (targetChatId == null || targetChatId === '') return false
+  if (anchorChatId == null || anchorChatId === '') return false
+  return String(anchorChatId) !== String(targetChatId)
 }
 
 /**
@@ -107,26 +148,37 @@ export interface AnswerThreadInput {
  * exists. The chat last-seen `chatThreadMap` heuristic is NOT in this chain.
  */
 export function resolveAnswerThreadId(input: AnswerThreadInput): number | undefined {
+  // Bug (c): an anchor from another chat is not an anchor. Drop it BEFORE the
+  // precedence runs, in both modes — a wrong-chat topic id is an API error, not
+  // a routing policy, so the kill switch must not reinstate it. `lastEnded*` is
+  // already chat-scoped by its lookup, so it needs no guard here.
+  const originCrossChat = isCrossChatAnchor(input.targetChatId, input.originChatId)
+  const liveCrossChat = isCrossChatAnchor(input.targetChatId, input.liveChatId)
+  const originResolved = input.originResolved && !originCrossChat
+  const originThreadId = originCrossChat ? undefined : input.originThreadId
+  const liveTurnPresent = input.liveTurnPresent === true && !liveCrossChat
+  const liveThreadId = liveCrossChat ? undefined : input.liveThreadId
+
   if (input.frameworkTopicAuthority === false) {
     // ── Legacy precedence (kill switch): the model's explicit thread wins. ──
     if (input.explicitThreadId != null) return input.explicitThreadId
-    if (input.originResolved) return input.originThreadId
-    if (input.liveThreadId != null) return input.liveThreadId
+    if (originResolved) return originThreadId
+    if (liveThreadId != null) return liveThreadId
     if (input.lastEndedResolvedForChat) return input.lastEndedThreadIdForChat
-    return input.liveThreadId
+    return liveThreadId
   }
   // ── Framework-authority precedence (default) ───────────────────────────────
   // (1) origin turn → its thread (authoritative across a currentTurn flip; a
   //     General/DM origin yields undefined → main chat / General).
-  if (input.originResolved) return input.originThreadId
+  if (originResolved) return originThreadId
   // (2) a live in-flight turn → its thread. Key off PRESENCE, not the thread
   //     value: a General live turn has an undefined thread but is still the
   //     anchor, so the model's explicit can't pull the reply out of it.
-  if (input.liveTurnPresent) return input.liveThreadId
+  if (liveTurnPresent) return liveThreadId
   // (3) no framework anchor (genuinely orphaned / proactive) → honour the
   //     model's explicit thread, its only signal here.
   if (input.explicitThreadId != null) return input.explicitThreadId
   // (4) late reply, no anchor, no explicit → recover the chat's last-ended topic.
   if (input.lastEndedResolvedForChat) return input.lastEndedThreadIdForChat
-  return input.liveThreadId
+  return liveThreadId
 }