switchroom 0.19.30 → 0.19.31

package/telegram-plugin/gateway/stale-pin-sweep-store.ts

@@ -0,0 +1,221 @@
+/**
+ * stale-pin-sweep-store.ts — the durable OBLIGATION ledger for the stale-pin
+ * sweep (`stale-pin-sweep.ts`).
+ *
+ * Why an obligation and not a "did we sweep this boot?" flag
+ * ---------------------------------------------------------
+ * Draining a deep pin stack is not one API call. In a DM each pop costs a
+ * re-pin plus an unpin, both rate-gated, so a chat with 21 orphans (klanker,
+ * observed 2026-07-29) takes north of a minute of wall clock. The old
+ * once-per-boot in-memory `Set` (`dm-pin-sweep.ts`) forgot everything the
+ * instant the process died: a gateway restarted mid-drain simply started over
+ * — or, once the per-boot pop budget was in play, never finished at all.
+ *
+ * So the sweep is modelled as a persisted OBLIGATION per `(chatId, threadId)`
+ * target: seeded from the pin stores at boot, advanced as pops land, and
+ * discharged (`done: true`) only once the drain is VERIFIED empty. A restart
+ * mid-sweep reloads the ledger and RESUMES from `popped` rather than forgetting.
+ *
+ * Durability: the write goes through `atomicWriteFileSync` (src/util/atomic.ts)
+ * — tempfile in the same directory, `fsync` on the fd, then `rename(2)`. A
+ * power cut leaves either the previous complete ledger or the new one, and the
+ * bytes of whichever survives are on the platter. A plain
+ * `writeFileSync`+`rename` would give atomicity without durability: the rename
+ * can be ordered before the data reaches disk, which is exactly how a crashed
+ * host comes back with a zero-length ledger and a chat full of orphan pins that
+ * nothing remembers to clean.
+ *
+ * Shape choice mirrors `status-pin-store.ts`: a whole-file SNAPSHOT, because
+ * the obligation set is tiny (one row per chat/topic the agent has ever pinned
+ * in) and rewriting it is trivially cheap. PURE with respect to the injected fs
+ * seam, so the ledger semantics are unit-testable without touching a disk.
+ */
+
+/** Chat classes the sweep treats differently. See `classifyChatForSweep`. */
+export type SweepChatKind = 'dm' | 'forum-topic' | 'supergroup'
+
+/** One persisted sweep obligation for a single `(chatId, threadId)` target. */
+export interface SweepCursor {
+  /** Chat the orphan pins live in. */
+  chatId: string
+  /**
+   * Forum topic the target is scoped to, when known.
+   *
+   * This is the `(chat, thread)` half of the registry key. Telegram's pin stack
+   * is CHAT-WIDE — MTProto `messages.updatePinnedMessage` carries no
+   * `top_msg_id` and the Bot API's `pinChatMessage`/`unpinChatMessage` accept no
+   * `message_thread_id` — so a "topic pin" is really a chat-level pin whose
+   * message happens to live in that thread, and clients render the topic bar by
+   * filtering. A bot therefore cannot enumerate pins or target a topic with
+   * pin/unpin. The ONE topic-scoped verb it does have is
+   * `unpinAllForumTopicMessages(chat_id, message_thread_id)`, and that verb is
+   * the whole reason this field must be persisted: without it, a boot after a
+   * crash knows a forum chat has orphans but not which topic to drain.
+   */
+  threadId?: number
+  /** Chat class, decided when the obligation was seeded. */
+  kind: SweepChatKind
+  /** Pops (or drain attempts) committed so far, ACROSS boots. */
+  popped: number
+  /** True once the drain was verified empty — the obligation is discharged. */
+  done: boolean
+  /**
+   * Boots that have attempted this obligation. Bounded by
+   * {@link SWEEP_MAX_ATTEMPTS} so a permanently-undrainable chat (bot kicked,
+   * rights revoked, a chat that flood-waits forever) cannot re-burn the pop
+   * budget on every boot for the rest of time.
+   */
+  attempts: number
+  /**
+   * Message ids this obligation has already issued a targeted unpin for.
+   *
+   * Load-bearing for the GROUP path, which is not a blind stack drain but a
+   * bounded pass over the ids the gateway is on record as having pinned. When a
+   * boot spends its per-minute budget half way through that list, this is what
+   * lets the next boot resume at the right place instead of re-issuing (and
+   * re-charging the flood ledger for) every unpin from the start.
+   *
+   * Unused by the DM path, which drains by observation and has no id list.
+   */
+  doneIds?: number[]
+  /** Last terminal-ish reason, for operator forensics. Never load-bearing. */
+  lastStatus?: string
+  /** Wall-clock ms of the last write. */
+  updatedAt: number
+}
+
+/**
+ * How many boots may attempt one obligation before it is forfeited. Generous
+ * because a legitimate deep stack is deliberately spread over several boots
+ * (the per-minute pin-op budget, and in a DM the 40-pop-per-chat cap): 8 boots
+ * covers far more than anything observed on the fleet.
+ */
+export const SWEEP_MAX_ATTEMPTS = 8
+
+/** Injected fs seam — same shape as the status-pin store's, so the gateway can
+ *  bind one durable writer for both. `writeFileSync` MUST be durable (fsync +
+ *  atomic rename); the gateway binds `atomicWriteFileSync`. */
+export interface SweepStoreFsSeam {
+  readFileSync: (path: string) => string
+  /** Durable atomic replace of `path` with `data` (fsync then rename). */
+  writeFileSync: (path: string, data: string) => void
+  existsSync: (path: string) => boolean
+}
+
+interface SweepEnvelope {
+  v: 1
+  cursors: SweepCursor[]
+}
+
+const SWEEP_ENVELOPE_VERSIONS = new Set([1])
+
+/** Stable identity of a sweep target: chat plus topic (topic-less = `-`). */
+export function sweepTargetKey(chatId: string, threadId?: number): string {
+  return `${chatId}:${threadId ?? '-'}`
+}
+
+function isCursorRow(x: unknown): x is SweepCursor {
+  if (x == null || typeof x !== 'object') return false
+  const o = x as Record<string, unknown>
+  return (
+    typeof o.chatId === 'string' &&
+    o.chatId.length > 0 &&
+    (o.threadId === undefined || typeof o.threadId === 'number') &&
+    (o.kind === 'dm' || o.kind === 'forum-topic' || o.kind === 'supergroup') &&
+    typeof o.popped === 'number' &&
+    typeof o.done === 'boolean' &&
+    typeof o.attempts === 'number' &&
+    (o.doneIds === undefined ||
+      (Array.isArray(o.doneIds) && o.doneIds.every((n) => typeof n === 'number'))) &&
+    (o.lastStatus === undefined || typeof o.lastStatus === 'string') &&
+    typeof o.updatedAt === 'number'
+  )
+}
+
+/**
+ * Load the obligation ledger. Fails OPEN to `[]` on a missing, unreadable or
+ * malformed file: a corrupt ledger must never crash boot. Worst case the sweep
+ * re-seeds from the pin stores, which is exactly the pre-ledger behaviour.
+ */
+export function loadSweepCursors(path: string, fs: SweepStoreFsSeam): SweepCursor[] {
+  if (!fs.existsSync(path)) return []
+  let raw = ''
+  try {
+    raw = fs.readFileSync(path)
+  } catch {
+    return []
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return []
+  }
+  if (parsed == null || typeof parsed !== 'object') return []
+  const env = parsed as Record<string, unknown>
+  if (
+    typeof env.v !== 'number' ||
+    !SWEEP_ENVELOPE_VERSIONS.has(env.v) ||
+    !Array.isArray(env.cursors)
+  ) {
+    return []
+  }
+  return env.cursors.filter(isCursorRow)
+}
+
+/**
+ * Persist the ledger durably. Best-effort relative to fs availability: a write
+ * failure is logged, never thrown — a failing ledger degrades the sweep to
+ * "forgets across restarts" (the old behaviour), it must not break the gateway.
+ */
+export function persistSweepCursors(
+  path: string,
+  fs: SweepStoreFsSeam,
+  cursors: readonly SweepCursor[],
+  log: (line: string) => void = (l) => process.stderr.write(l),
+): void {
+  const env: SweepEnvelope = { v: 1, cursors: [...cursors] }
+  try {
+    fs.writeFileSync(path, JSON.stringify(env))
+  } catch (err) {
+    log(
+      `stale-pin-sweep-store: persist FAILED path=${path}: ${(err as Error).message} — ` +
+        `durability degraded; a restart mid-sweep will re-seed instead of resume\n`,
+    )
+  }
+}
+
+/**
+ * READ-MODIFY-WRITE one target's row against the file on disk, so a concurrent
+ * writer's rows are never clobbered by a stale in-memory snapshot. Mirrors
+ * `applyStatusPinRow` in status-pin-store.ts.
+ */
+export function upsertSweepCursor(
+  path: string,
+  fs: SweepStoreFsSeam,
+  cursor: SweepCursor,
+  log: (line: string) => void = (l) => process.stderr.write(l),
+): void {
+  const key = sweepTargetKey(cursor.chatId, cursor.threadId)
+  const others = loadSweepCursors(path, fs).filter(
+    (c) => sweepTargetKey(c.chatId, c.threadId) !== key,
+  )
+  persistSweepCursors(path, fs, [...others, cursor], log)
+}
+
+/**
+ * The obligations still owed at boot: not discharged and not forfeited.
+ *
+ * A `done` row is retained in the ledger (rather than deleted) only until the
+ * next seed pass; `pruneSweepCursors` drops it. Keeping it for the duration of
+ * one boot is what makes a mid-sweep restart idempotent — the resumed sweep
+ * sees "already drained" instead of re-draining a chat it just cleared.
+ */
+export function pendingSweepCursors(cursors: readonly SweepCursor[]): SweepCursor[] {
+  return cursors.filter((c) => !c.done && c.attempts < SWEEP_MAX_ATTEMPTS)
+}
+
+/** Drop discharged and forfeited rows — called once the ledger is reseeded. */
+export function pruneSweepCursors(cursors: readonly SweepCursor[]): SweepCursor[] {
+  return cursors.filter((c) => !c.done && c.attempts < SWEEP_MAX_ATTEMPTS)
+}

package/telegram-plugin/gateway/stale-pin-sweep-wiring.ts

@@ -0,0 +1,211 @@
+/**
+ * stale-pin-sweep-wiring.ts — binds the pure stale-pin drain
+ * (`stale-pin-sweep.ts`) to the gateway's world, without putting any of that
+ * glue inside gateway.ts.
+ *
+ * The sweeper itself is deliberately dependency-free so its rate gates, its
+ * circuit-breaker and its "never trust an `ok:true`" invariant are provable in
+ * isolation. Everything it needs from the outside is a function. Assembling
+ * those functions is mechanical, but it is ~70 lines of policy (which pins are
+ * protected, what counts as pin rights, which env var unlocks the supergroup
+ * loop) that belongs next to the drain rather than in the gateway's already
+ * over-long module scope (switchroom#2996 anti-inflation ratchet).
+ *
+ * gateway.ts therefore supplies only the raw Bot API seam + the two live state
+ * readers; the policy lives here and is unit-testable.
+ */
+
+import {
+  createStalePinSweeper,
+  unexpiredStoreRepinIds,
+  type StalePinSweeper,
+  type SweepStoreFsSeam,
+} from './stale-pin-sweep.js'
+import type { PersistedStatusPin } from './status-pin-store.js'
+import type { StatusPinClaim } from './status-pin-retarget.js'
+
+/**
+ * The minimal Telegram surface the drain needs, expressed so the gateway hands
+ * over only its bot handle and its retry wrapper. Building the seam HERE (not
+ * in gateway.ts) keeps the four raw pin/unpin calls next to the comments that
+ * justify them.
+ */
+export interface StalePinSweepBotSeam {
+  /**
+   * Live grammY-shaped handle. A getter, because `lockedBot` is assigned late
+   * (inside `initGatewayBot`) and the sweep may outlive a rebind.
+   *
+   * Named `handle`, not `bot`: gateway.ts is statically scanned for
+   * module-scope identifiers named `bot`/`lockedBot`
+   * (`gateway-bot-construction-deferral.test.ts`, #2996 P0b), and a property
+   * KEY called `bot` at module scope trips that guard even though the value is
+   * a deferred arrow.
+   */
+  handle: () => {
+    api: {
+      getChat: (chatId: string) => Promise<unknown>
+      pinChatMessage: (
+        chatId: string,
+        messageId: number,
+        opts: { disable_notification: boolean },
+      ) => Promise<unknown>
+      unpinChatMessage: (chatId: string, messageId: number) => Promise<unknown>
+      unpinAllForumTopicMessages: (chatId: string, threadId: number) => Promise<unknown>
+      getChatMember: (chatId: string, userId: number) => Promise<unknown>
+    }
+    botInfo?: { id?: number }
+  }
+  /** The gateway's retry/telemetry envelope (`robustApiCall`). */
+  call: <T>(fn: () => Promise<T>, meta: { chat_id: string; verb: string }) => Promise<T>
+}
+
+export interface StalePinSweepWiring {
+  telegram: StalePinSweepBotSeam
+  /** Live in-memory status-pin claims (the single claim registry). */
+  claims: () => Iterable<StatusPinClaim>
+  /** Durable pin rows, read LIVE. Returns [] when persistence is off. Never
+   *  throws — a read failure is logged by the caller and treated as []. */
+  loadPinRows: () => PersistedStatusPin[]
+  /** Mutex-won AND bot-constructed. False ⇒ the drain must not write. */
+  eligible: () => boolean
+  store: { path: string; fs: SweepStoreFsSeam }
+  /** Per-deployment override of `UNPIN_ALL_FORUM_TOPIC_ENABLED`; undefined =
+   *  take the standing policy (the wholesale topic drain stays OFF). */
+  allowUnpinAllForumTopic?: boolean
+  log?: (line: string) => void
+  now?: () => number
+  sleep?: (ms: number) => Promise<void>
+}
+
+/**
+ * Pins that must SURVIVE a drain of `chatId`: the live in-memory claims for
+ * that chat, unioned with the deliberately-retained durable rows (an unexpired
+ * `tool:` pin survives `statusPinBootCleanup` by design and must survive this
+ * too).
+ *
+ * Read from BOTH sources because neither alone is complete at both call sites:
+ * during the boot sweep the in-memory maps are still empty, and during a later
+ * first-inbound sweep the store may lag a claim taken this session.
+ */
+export function protectedPinIds(args: {
+  chatId: string
+  claims: Iterable<StatusPinClaim>
+  loadPinRows: () => PersistedStatusPin[]
+  now: number
+  log: (line: string) => void
+}): number[] {
+  const ids: number[] = []
+  for (const claim of args.claims) {
+    if (claim.chatId === args.chatId) ids.push(claim.messageId)
+  }
+  try {
+    ids.push(...unexpiredStoreRepinIds(args.loadPinRows(), args.chatId, args.now))
+  } catch (err) {
+    args.log(
+      `telegram gateway: stale-pin-sweep: store repin scan failed ` +
+        `(chat=${args.chatId}): ${(err as Error).message}\n`,
+    )
+  }
+  return ids
+}
+
+/**
+ * The message ids the gateway is ON RECORD as having pinned in one
+ * `(chat, thread)` target — the only ids the group drain is allowed to unpin.
+ *
+ * Matched on the FULL target key, not the chat alone: the pin stack is
+ * chat-wide, but the obligation is per topic, and unpinning another topic's
+ * recorded pin while sweeping this one would clear a card that is still live.
+ */
+export function recordedPinIdsFor(
+  rows: readonly PersistedStatusPin[],
+  chatId: string,
+  threadId?: number,
+): number[] {
+  const out: number[] = []
+  for (const r of rows) {
+    if (r.chatId !== chatId) continue
+    if ((r.threadId ?? undefined) !== threadId) continue
+    if (typeof r.messageId === 'number' && !out.includes(r.messageId)) out.push(r.messageId)
+  }
+  return out
+}
+
+/** Assemble the gateway's stale-pin sweeper. */
+export function createGatewayStalePinSweeper(w: StalePinSweepWiring): StalePinSweeper {
+  const log = w.log ?? ((line: string) => process.stderr.write(line))
+  const now = w.now ?? Date.now
+  const { handle: bot, call } = w.telegram
+  return createStalePinSweeper({
+    getTopPinnedMessageId: async (chatId) => {
+      const chat = (await call(() => bot().api.getChat(chatId), {
+        chat_id: chatId,
+        verb: 'stale-pin-sweep.get-chat',
+      })) as { pinned_message?: { message_id?: number } } | undefined
+      return chat?.pinned_message?.message_id ?? null
+    },
+    // The RE-PIN half of the only sequence that actually pops a stack entry (a
+    // bare unpin on a stale entry is a silent no-op). An orphan pin has no
+    // claim to reconcile through, so the unified path cannot express it.
+    pinSilent: (chatId, messageId) =>
+      call(
+        // allow-raw-pin: orphan repin — see above. allow-raw-bot-api: already
+        // inside the gateway's robustApiCall envelope.
+        () => bot().api.pinChatMessage(chatId, messageId, { disable_notification: true }),
+        { chat_id: chatId, verb: 'stale-pin-sweep.repin' },
+      ),
+    // The UNPIN half of the pop. Its result is deliberately ignored — ok:true
+    // proves nothing; progress is read back from getChat.
+    unpin: (chatId, messageId) =>
+      call(
+        // allow-raw-pin: orphan unpin — see above. allow-raw-bot-api: already
+        // inside the gateway's robustApiCall envelope.
+        () => bot().api.unpinChatMessage(chatId, messageId),
+        { chat_id: chatId, verb: 'stale-pin-sweep.unpin' },
+      ),
+    unpinAllForumTopicMessages: (chatId, threadId) =>
+      call(() => bot().api.unpinAllForumTopicMessages(chatId, threadId), {
+        chat_id: chatId,
+        verb: 'stale-pin-sweep.unpin-all-topic',
+      }),
+    // Rights are checked before ANY write in a group. Telegram is HONEST about
+    // missing pin rights (400 "not enough rights to manage pinned messages"),
+    // but the precheck keeps a rights-less bot from emitting doomed traffic.
+    canPinInChat: async (chatId) => {
+      const self = bot().botInfo?.id
+      if (self == null) return false
+      const member = (await call(() => bot().api.getChatMember(chatId, self), {
+        chat_id: chatId,
+        verb: 'stale-pin-sweep.get-chat-member',
+      })) as { status?: string; can_pin_messages?: boolean } | undefined
+      return member?.status === 'administrator' && member.can_pin_messages === true
+    },
+    recordedPinIds: (chatId, threadId) => {
+      try {
+        return recordedPinIdsFor(w.loadPinRows(), chatId, threadId)
+      } catch (err) {
+        log(
+          `telegram gateway: stale-pin-sweep: recorded-pin scan failed ` +
+            `(chat=${chatId}): ${(err as Error).message}\n`,
+        )
+        return []
+      }
+    },
+    protectedMessageIds: (chatId) =>
+      protectedPinIds({
+        chatId,
+        claims: w.claims(),
+        loadPinRows: w.loadPinRows,
+        now: now(),
+        log,
+      }),
+    eligible: w.eligible,
+    sleep: w.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))),
+    now,
+    store: w.store,
+    // Passed through UNCOERCED: undefined means "take the standing policy"
+    // (UNPIN_ALL_FORUM_TOPIC_ENABLED), not the same as an explicit false.
+    allowUnpinAllForumTopic: w.allowUnpinAllForumTopic,
+    log,
+  })
+}