@open-everywhere/provider-discord 0.1.0

package/agent/channels/discord-backscroll.ts

@@ -0,0 +1,593 @@
+// Wake-time conversation backscroll for Discord — the parity twin of slack-wake-backscroll.ts.
+//
+// Discord's name-drop WAKE and @mention paths (discord-gateway.ts) used to hand the model ONLY
+// the triggering message: a cold name-drop mid-thread arrived with no idea what's being
+// discussed, and a re-wake after auto-disengage resumed the same session with a GAP for
+// everything said while the bot was away. This module closes both by fetching recent history at
+// wake time and attaching it as the SAME untrusted-wrapped `context` strings the Slack paths use
+// (eve appends each as a user message before the delivery turn — SendPayload.context).
+//
+// SIMPLER THAN SLACK: Discord threads are their OWN channel ids, so ONE endpoint —
+// `GET /channels/{channelId}/messages` — covers both a base channel and a thread (no
+// history/replies split). We always read strictly OLDER than the trigger via `?before=<id>`
+// (Discord returns newest-first; we reverse to oldest-first). For an in-THREAD wake we then slice
+// to "since the agent last spoke" (shared sinceLastAgentReply) — a resumed thread session already
+// holds everything up to its last reply; for a BASE channel we keep the recent tail (last N).
+//
+// AUTH: reuses the Discord bot token exactly as discord-gateway.ts's REST calls do (`Bot <token>`
+// header) — no new auth path. The bot's OWN author id (msg.botId, forwarded by the relay) both
+// labels the agent's prior posts as `sender_type=agent` AND anchors the since-last-agent slice;
+// absent (older relay) it simply degrades (own posts read as a bot, no slice boundary) — never a
+// crash. The requester is injected so the fetcher unit-tests offline with NO network.
+//
+// RENDER REUSE: the ContextLine shape, the render + UNTRUSTED wrap, the caps, and the
+// since-last-agent slice all come from the shared context-render.ts — the SAME renderer Slack
+// uses — so Discord's attribution + untrusted framing are byte-identical to Slack's without
+// cross-importing a slack-named file. The untrusted wrap is a SECURITY invariant (channel content
+// is DATA, never instructions), so it must never diverge between surfaces. NO read-more hint:
+// Discord exposes no read_discord_* tools today, so naming a "fetch more" tool would be a lie —
+// the bounded backscroll (the actual win) is attached regardless.
+//
+// BOOTSTRAP BACKSCROLL is fail-soft: any error yields no context and never blocks the first wake.
+// SEAT CATCH-UP propagates the same read failure to core's shared fail-soft boundary, so the wake
+// still continues but its `seat.catch_up` row says `failed` rather than `empty` (OPE-1842).
+//
+// TWO MECHANISMS LIVE IN THIS FILE (both wake-safe, both Discord-specific fetch adapters):
+//   1. fetchDiscordBackscrollLines — the FLAT name-drop/@mention enrichment above: raw history →
+//      context-render.ts ContextLine. BOTH Discord wake dispatch paths call it directly and grade
+//      the RAW lines with gradeDiscordContextLines (OPE-475) before rendering: the gateway's NATIVE
+//      dispatch hands the graded lines to the shared renderWake as the NormalizedWake's `contextLines`
+//      (W3 — renderWake does the untrusted-wrap); the SINGLE-WINDOW divert path renders them itself
+//      via the shared renderContext (discord-gateway.ts `discordSeatContextForWindow`) — a
+//      pre-rendered `context` string, but sourced from the SAME graded lines the join reads via
+//      contextLineIngestion, so the join can never carry a line the render's own source set did
+//      not. 🔴 THAT IS NOT AN EQUALITY OF COUNTS: renderContext applies its own MAX_CHARS bound and
+//      skips a line whose text trims empty, so the render can keep FEWER lines than the join marks.
+//      The direction over-taints, which is the safe one.
+//      🔴 BOTH PATHS TAKE THE DOMAIN'S ADMISSION POLICY, and the SEAT decides, never the road
+//      (OPE-1800, discord-gateway.ts `admitDiscordSeatLines`). The policy runs wherever
+//      `grainUsesUnifiedWindow` holds for the room — which is the predicate Slack resolves `seated`
+//      from — so a wake that falls through to the native arm because its seat STOOD DOWN (the guild
+//      vouch absent) is policed too. A room with no seat at all keeps every graded line.
+//   2. fetchDiscordBackscrollWindow / fetchDiscordWakeEnvelopeBackscroll (added below) — the DROP-IN
+//      fetch adapter behind the platform-NEUTRAL gap-clustering/bounds core (backscroll-window.ts),
+//      the exact Slack shape (slack-wake-backscroll.ts fetchSlackBackscrollWindow /
+//      fetchWakeEnvelopeBackscroll): raw history → visibility-gated NormalizedMessage[] →
+//      fetchedBackscroll → session-tagged WakeMessageInput[]. This fulfils the neutral core's
+//      "Discord drop-in" seam, and it is LIVE (OPE-1726): `discordSeatCatchUpFetch` below registers it
+//      as this surface's SEAT CATCH-UP fetch, so every wake on an ongoing generation reads the channel
+//      since the seat's own last wake and renders the result as the wake envelope's `<session>`
+//      siblings (discord-gateway.ts `divertDiscordWakeToUnifiedWindow`). The BOOTSTRAP half — a fresh
+//      generation's first wake — still carries the recorded tail rather than a platform fetch.
+//      The flat path (1) continues to serve the mention/name-drop hydration on every Discord wake.
+
+import {
+  sinceLastAgentReply,
+  WAKE_BACKSCROLL_MAX,
+  fetchedBackscroll,
+  resolveWakeTrustFromContext,
+  armedAuthorTrustTenants,
+  catchUpSender,
+  type ContextLine,
+  type NormalizedMessage,
+  type BackscrollTrustFor,
+  type SeatCatchUpFetch,
+  type SeatCatchUpRequest,
+  type WakeMessageInput,
+  type BindableContext,
+  type AuthorTrustQuery,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { discordAuthorRoles } from "../approvals/discord-admin.js";
+
+/** The triggering wake, narrowed to what the backscroll needs. */
+export interface DiscordBackscrollInput {
+  /** The surface to READ — the channel/thread the human's message is IN (msg.channelId), NOT the
+   *  re-keyed reply thread. A Discord thread is its own channel id, so this is one endpoint. */
+  readonly channelId: string;
+  /** The triggering message's id — we read strictly OLDER than this (`?before=`). */
+  readonly triggerMessageId: string;
+  /** True when `channelId` is a thread (types 10/11/12): apply the since-last-agent slice. A base
+   *  channel keeps the recent tail (last N) instead — mirrors Slack's replies/history split. */
+  readonly isThread: boolean;
+  /** The bot's OWN Discord author id (relay `botId`) — labels agent lines + anchors the slice.
+   *  Absent (older relay) → own posts read as a bot and there's no slice boundary (fail-soft). */
+  readonly botId?: string;
+}
+
+/** A Discord REST caller: GETs `/channels/{channelId}/messages?<query>`, returns parsed JSON
+ *  (an array of message objects) or undefined on ANY failure (fail-soft). Injected so the fetcher
+ *  runs without a network in tests but defaults to the live bot-token call. */
+export type DiscordRequester = (channelId: string, query: Record<string, string>) => Promise<unknown>;
+
+export interface DiscordBackscrollDeps {
+  readonly request: DiscordRequester;
+}
+
+// Direct bot-token GET to the Discord REST API. Mirrors discord-gateway.ts's own fetch calls
+// (`Bot <token>` header; the token is a SECRET — never logged). Fail-soft: no token / non-ok /
+// any throw → undefined. Kept local rather than imported from discord-gateway.ts so the module
+// graph stays a DAG (discord-gateway → here; importing back up would cycle).
+const liveRequest: DiscordRequester = async (channelId, query) => {
+  const token = process.env.DISCORD_BOT_TOKEN;
+  if (!token || !channelId) return undefined;
+  try {
+    const qs = new URLSearchParams(query).toString();
+    const res = await fetch(`https://discord.com/api/v10/channels/${channelId}/messages?${qs}`, {
+      headers: { authorization: `Bot ${token}` },
+    });
+    if (!res.ok) return undefined;
+    return await res.json();
+  } catch {
+    return undefined;
+  }
+};
+
+const liveDeps: DiscordBackscrollDeps = { request: liveRequest };
+
+// Discord message `type`s we keep as ordinary conversation: 0 = DEFAULT, 19 = REPLY. Everything
+// else (7 member-join, 6 pin, channel-name-change, thread-created, …) is system noise, dropped
+// like Slack's `subtype` filter. A message with no/other type is treated conservatively as noise.
+function isConversationType(type: unknown): boolean {
+  return type === 0 || type === 19;
+}
+
+/**
+ * Map raw Discord message objects (`GET /channels/{id}/messages` — raw REST JSON, probe
+ * defensively) into {@link ContextLine}s, dropping system-type + empty-content messages. `botId`
+ * is the agent's own author id: a message by it is labelled `agent` (Discord uses one `author.id`
+ * for everyone — bots included — so we compare ids, same idea as Slack comparing bot_id/user_id).
+ * Order is PRESERVED — the caller reverses to oldest-first before rendering. Pure. Exported for
+ * the test oracle. Kept HERE (not shared): Discord's message JSON is shaped differently from
+ * Slack's, so the mapping is genuinely platform-specific; only the ContextLine target + renderer
+ * are shared (context-render.ts).
+ */
+export function linesFromDiscordMessages(raw: ReadonlyArray<Record<string, unknown>>, botId?: string): ContextLine[] {
+  const lines: ContextLine[] = [];
+  for (const m of raw) {
+    if (!isConversationType(m.type)) continue; // system noise (joins, pins, thread-created, …)
+    const text = typeof m.content === "string" ? m.content : "";
+    if (!text) continue; // empty content (Message Content Intent off, or an embed-only post)
+    const author = typeof m.author === "object" && m.author !== null ? (m.author as Record<string, unknown>) : undefined;
+    const authorId = author && typeof author.id === "string" ? author.id : undefined;
+    const isBot = author?.bot === true;
+    const id = typeof m.id === "string" ? m.id : "";
+    if (botId !== undefined && authorId === botId) lines.push({ senderType: "agent", ts: id, text });
+    else if (isBot && authorId) lines.push({ senderType: "bot", senderId: authorId, ts: id, text });
+    else if (authorId) lines.push({ senderType: "user", senderId: authorId, ts: id, text });
+    else lines.push({ senderType: "unknown", ts: id, text });
+  }
+  return lines;
+}
+
+/** Resolves a sibling author's real guild roles for the register query below — injected so the
+ *  grading step is unit-testable offline. Live wiring: {@link discordAuthorRoles}. `undefined` =
+ *  cannot check (never a guess); a real (possibly empty) array = verified role evidence. */
+export type DiscordRoleProbe = (guildId: string, userId: string) => Promise<readonly string[] | undefined>;
+
+/**
+ * PER-LINE trust for a mention/name-drop backscroll's {@link ContextLine}s (OPE-475) — the Discord
+ * analogue of Slack's regrade step, converging both backscroll shapes on ONE trust story rather than
+ * a second mechanism. Two additive facts, mirroring exactly what the TRIGGER already carries
+ * (discord-gateway.ts `resolveWakeTrustFromContext` + `authorFacts`), resolved per SIBLING:
+ *
+ *   `trust`       — {@link resolveWakeTrustFromContext} off the SAME binding the trigger reads, with
+ *                    `principalFallback` OFF (a sibling has its own author — see that function's own
+ *                    per-message-resolution note). Read by the RENDER. Resolved for every `user` line,
+ *                    unconditionally — no I/O, no gate.
+ *   `authorTrust` — the OPERATOR's author-trust register query (identity/author-trust.ts, OPE-516):
+ *                    Discord's ONLY per-author refutation reachable here. `member.pending` (the
+ *                    trigger's own signal) is NOT available: it rides the gateway relay's MESSAGE_CREATE
+ *                    member object, and Discord's documented Message object (the shape
+ *                    `GET /channels/{id}/messages` — what this backscroll fetch reads — returns) has
+ *                    no `member` field at all. Read ONLY by the taint join.
+ *
+ * 🔴 THE REGISTER QUERY IS BUILT FROM VERIFIED ROLE EVIDENCE, NEVER FROM AN UNCHECKED GUESS (fixed
+ * after a caught bug: an earlier revision hardcoded `memberships: []` on EVERY sibling — on a guild
+ * armed the documented-usual way, `{ membership: "discord/<g>/role:*" }`, that made EVERY sibling
+ * look role-less and therefore `external`, so a mention wake that hydrated ordinary colleagues'
+ * messages marked the taint bit on a role-armed guild — the always-on-bit failure this whole plane
+ * exists to avoid). So the role fetch is COST-GATED and FAIL-OPEN, in that order:
+ *
+ *   1. UNARMED tenant (the common case — `armedAuthorTrustTenants()` doesn't list `discord/<guild>`):
+ *      no register query is even worth building, so NO role fetch runs at all. Zero new I/O on the
+ *      default posture.
+ *   2. ARMED tenant: each DISTINCT candidate author (a `user` line with a `senderId`) gets ONE
+ *      {@link DiscordRoleProbe} call (TTL-cached — {@link discordAuthorRoles}), mirroring exactly how
+ *      {@link regradeSlackContextLineTrust}'s probe is one call per distinct author, not per message.
+ *   3. The probe's THREE outcomes are kept apart, never collapsed to a boolean: a real (possibly
+ *      empty, on a verified 404) roles array builds the SAME group-rung `{tenantKey}/role:<id>` keys
+ *      the trigger's own `authorFacts` builds from `msg.memberRoles`; `undefined` (no token, a
+ *      network error, an unreadable body) means "cannot check", and that line gets NO `authorTrust`
+ *      at all — SKIPPED, never an unverified `[]`. "Cannot check" is not "checked and empty".
+ *
+ * 🔴 THE REGISTER LEG NEVER DEMOTES `trust` — it matches the trigger, and access/taint-signal.ts's own
+ * design: the register is a JOIN-ONLY refutation, decoupled from the render (see `nonMemberChatTrust`).
+ * So a register-refuted Discord backscroll sibling marks the turn but does not render the reference-only
+ * note — an honest limit of what this endpoint can tell the model, not a shortfall against Slack's
+ * parity (Slack's refutation is a SURFACE fact and demotes the render; Discord has none here).
+ *
+ * `agent`/`bot`/`unknown` lines are left untouched — machine or unattributable authors are not this
+ * leg's question.
+ */
+export async function gradeDiscordContextLines(
+  lines: readonly ContextLine[],
+  ctx: BindableContext,
+  guildId: string | undefined,
+  roleProbe: DiscordRoleProbe = discordAuthorRoles,
+): Promise<ContextLine[]> {
+  const withTrust = lines.map((l): ContextLine =>
+    l.senderType !== "user" ? l : { ...l, trust: resolveWakeTrustFromContext(ctx, { id: l.senderId, isBot: false }) },
+  );
+  const tenantKey = guildId !== undefined ? `discord/${guildId}` : undefined;
+  // COST GATE: an unarmed tenant's register leg contributes nothing (identity/author-trust.ts —
+  // silence is not a declaration), so there is nothing worth a role fetch for. Zero new I/O here is
+  // the default posture, not an edge case.
+  if (tenantKey === undefined || !armedAuthorTrustTenants().includes(tenantKey)) return withTrust;
+
+  const candidates = new Set<string>();
+  for (const l of withTrust) {
+    if (l.senderType === "user" && l.senderId !== undefined) candidates.add(l.senderId);
+  }
+  if (candidates.size === 0) return withTrust;
+  const ids = [...candidates];
+  const roleResults = await Promise.all(ids.map((id) => roleProbe(guildId!, id)));
+  const rolesById = new Map(ids.map((id, i) => [id, roleResults[i]] as const));
+
+  return withTrust.map((l) => {
+    if (l.senderType !== "user" || l.senderId === undefined) return l;
+    const roles = rolesById.get(l.senderId);
+    if (roles === undefined) return l; // cannot check — SKIP the register query for this line entirely
+    const authorTrust: AuthorTrustQuery = {
+      tenantKey,
+      authorId: l.senderId,
+      memberships: roles.map((r) => `${tenantKey}/role:${r}`),
+    };
+    return { ...l, authorTrust };
+  });
+}
+
+// Pull the message array out of a REST response, or undefined (fail-soft on junk / non-array).
+function extractDiscordMessages(res: unknown): Array<Record<string, unknown>> | undefined {
+  if (!Array.isArray(res)) return undefined;
+  return res as Array<Record<string, unknown>>;
+}
+
+/**
+ * Fetch recent conversation history for a Discord wake/mention as RAW, oldest-first
+ * {@link ContextLine}s, capped at {@link WAKE_BACKSCROLL_MAX}. `undefined` = nothing to add OR any
+ * failure — always non-fatal. Both Discord wake dispatch paths (discord-gateway.ts, native and
+ * single-window divert) call this directly, grade the lines with gradeDiscordContextLines
+ * (OPE-475), and render them via the shared renderContext THEMSELVES — no pre-rendered string is
+ * built inside this module.
+ *
+ * One endpoint (`GET /channels/{channelId}/messages?limit&before`) for both cases:
+ *   - IN-THREAD (`isThread`): strictly-older messages, then sliced to "since the agent's last
+ *     reply" (a resumed thread session already holds everything up to its last reply).
+ *   - BASE CHANNEL: strictly-older messages, most recent N.
+ */
+export async function fetchDiscordBackscrollLines(
+  input: DiscordBackscrollInput,
+  deps: DiscordBackscrollDeps = liveDeps,
+): Promise<{ readonly lines: ContextLine[]; readonly source: string } | undefined> {
+  try {
+    const res = await deps.request(input.channelId, {
+      limit: String(WAKE_BACKSCROLL_MAX),
+      // Strictly OLDER than the trigger — the trigger's text already rides on the wake message.
+      before: input.triggerMessageId,
+    });
+    const raw = extractDiscordMessages(res);
+    if (!raw) return undefined;
+    // Discord returns newest-first → reverse to oldest-first for the slice + render.
+    const ordered = [...raw].reverse();
+    let lines = linesFromDiscordMessages(ordered, input.botId);
+    // In a thread, keep only what followed the agent's last reply (the disengage/re-wake gap, or
+    // "someone answered while I was away"); a base channel keeps the recent tail via the N-cap.
+    if (input.isThread) lines = sinceLastAgentReply(lines);
+    const capped = lines.slice(-WAKE_BACKSCROLL_MAX);
+    if (capped.length === 0) return undefined;
+    return { lines: capped, source: `discord ${input.isThread ? "thread" : "channel"} ${input.channelId}` };
+  } catch {
+    return undefined; // fail-soft: a wake never depends on its backscroll
+  }
+}
+
+
+// --- neutral-core first-wake backscroll (supervisor context hydration) — DISCORD ADAPTER -----
+//
+// THIS IS THE DISCORD FETCH ADAPTER behind the platform-NEUTRAL clustering/bounds core
+// (backscroll-window.ts), the mirror of slack-wake-backscroll.ts's fetchSlackBackscrollWindow.
+// Its job: turn `GET /channels/{id}/messages` into a visibility-GATED {@link NormalizedMessage}[]
+// window, then hand it to {@link fetchedBackscroll}, which caps it most-recent-first and
+// spine/bolt + count/time/token bounds and emits session-tagged {@link WakeMessageInput}[] the wake
+// envelope renders as `<session>` groups.
+//
+// SIMPLER THAN SLACK (again): a Discord thread is its own channel id, so the SAME single endpoint
+// covers a base channel AND a thread — there is no conversations.history/replies split and thus no
+// bounded thread-reply fan-out to mirror (a base-channel window here does NOT reach into the
+// replies of threads hanging off it; that's the deliberate one-endpoint scope, matching the flat
+// path). FAIL-SOFT ABSOLUTELY throughout, exactly like {@link fetchDiscordBackscrollLines}.
+
+/** Reachback (hours) for the raw Discord window: how far back from the trigger we paginate. Shares
+ *  the SAME env + 7d default as the Slack adapter (slack-wake-backscroll.ts RAW_FETCH_REACHBACK_HOURS)
+ *  — it is one supervisor-backscroll concept, kept in sync by reading the same knob. Generous enough
+ *  that the spine (the most-recent cluster, exempt from the 36h enrichment cap) still spans a
+ *  weekend/overnight gap, yet a hard floor bounding the fetch. */
+export const DISCORD_RAW_FETCH_REACHBACK_HOURS = Number(process.env.OE_SUPERVISOR_BACKSCROLL_REACHBACK_HOURS) || 168;
+
+/** `GET /channels/{id}/messages` page size (Discord's max is 100). */
+const DISCORD_RAW_FETCH_PAGE_LIMIT = 100;
+
+/** Max history pages to paginate — bounds a busy channel's fetch at ≤300 messages so a burst can't
+ *  fan out into an unbounded loop. Combined with the reachback floor (whichever binds first). */
+const DISCORD_RAW_FETCH_MAX_PAGES = 3;
+
+/** Discord's epoch (2015-01-01T00:00:00Z, ms) — the offset baked into every snowflake id. */
+const DISCORD_EPOCH_MS = 1_420_070_400_000;
+
+/**
+ * The creation time (epoch ms) encoded in a Discord snowflake id: the top 42 bits are
+ * `(unix_ms - DISCORD_EPOCH_MS)`. Robust — every message id carries it, so we can derive a time even
+ * when the raw `timestamp` field is absent/garbled. Returns undefined for a non-numeric / non-positive
+ * id (fail-soft; the caller drops that message from the window rather than guessing a time).
+ */
+export function snowflakeToMs(id: string): number | undefined {
+  try {
+    const n = BigInt(id);
+    if (n <= 0n) return undefined;
+    return Number(n >> 22n) + DISCORD_EPOCH_MS;
+  } catch {
+    return undefined; // not an integer id → no derivable time
+  }
+}
+
+/**
+ * The INVERSE of {@link snowflakeToMs}: the smallest snowflake whose encoded time is `ms`, for a
+ * `before=` anchor when the caller states a TIME and holds no message id (the catch-up fetch with no
+ * trigger). The low 22 bits (worker, process, sequence) are zero, which is exactly what "the
+ * beginning of this millisecond" means to Discord's own ordering. A time at or before Discord's epoch
+ * clamps to `1` — the smallest usable anchor — rather than producing a negative id.
+ */
+function msToSnowflake(ms: number): string {
+  const delta = Math.max(0, Math.floor(ms) - DISCORD_EPOCH_MS);
+  const id = BigInt(delta) << 22n;
+  return (id > 0n ? id : 1n).toString();
+}
+
+/** The message's epoch ms: prefer the canonical ISO `timestamp` field, else decode the snowflake
+ *  `id` (both present on a REST message object). undefined ⇒ neither yielded a finite time. */
+function messageMs(m: Record<string, unknown>, id: string): number | undefined {
+  const iso = typeof m.timestamp === "string" ? Date.parse(m.timestamp) : Number.NaN;
+  if (Number.isFinite(iso)) return iso;
+  return snowflakeToMs(id);
+}
+
+/**
+ * The VISIBILITY / TRUST GATE (the load-bearing SECURITY filter) — the Discord parity of
+ * slack-wake-backscroll.ts isBackscrollVisible, kept LOCAL (not imported from a slack-named file, the
+ * same DAG discipline as linesFromDiscordMessages). Backscroll must never surface a message it can't
+ * ATTRIBUTE. KEEPS: the bot's OWN prior posts (`agent` → `self`); identifiable humans (`user` →
+ * `human`); ATTRIBUTABLE foreign bots (`bot` WITH a bot id → `bot`) as MARKED AWARENESS (clearly
+ * bot-flagged, CONTEXT-ONLY, never a wake trigger — dropping them would break conversational
+ * coherence when a human replies to a bot post). DROPS ONLY unattributable senders (`unknown`, or a
+ * `bot` with no id) — no auth'd author ⇒ fail closed. (System-subtype / empty-content noise is already
+ * dropped upstream by linesFromDiscordMessages.) The neutral core never sets `trigger` on backscroll,
+ * and the gateway's live wake gate still drops bot authors as triggers, so a bot post here is
+ * awareness, never a response obligation. */
+export function isDiscordBackscrollVisible(line: ContextLine): boolean {
+  return (
+    line.senderType === "agent" ||
+    line.senderType === "user" ||
+    (line.senderType === "bot" && line.senderId !== undefined) // attributable foreign bot: marked awareness
+  );
+}
+
+/**
+ * Normalize ONE raw Discord message → {@link NormalizedMessage}, reusing {@link linesFromDiscordMessages}
+ * for the exact sender classification + system/empty drop, then applying the VISIBILITY GATE and
+ * resolving the epoch ms. Returns undefined for a dropped (invisible / system / empty / timeless)
+ * message. `type`/`threadId` describe the surface the window was read from (a Discord thread is its
+ * own channel id, so a thread window tags every message `thread` with the thread's id as the root).
+ */
+function normalizeDiscordMessage(
+  m: Record<string, unknown>,
+  botId: string | undefined,
+  type: "channel" | "thread",
+  threadId: string | undefined,
+): NormalizedMessage | undefined {
+  const [line] = linesFromDiscordMessages([m], botId);
+  if (!line) return undefined; // system type / empty content (dropped upstream)
+  if (!isDiscordBackscrollVisible(line)) return undefined; // VISIBILITY GATE (unattributable sender only)
+  const ms = messageMs(m, line.ts);
+  if (ms === undefined) return undefined; // no derivable time → can't cluster it, drop
+  return {
+    id: line.ts,
+    ms,
+    // undefined for the bot's OWN posts (agent); the foreign bot's id for a `bot`; the user id for a
+    // human — kept raw for @-tagging / attribution.
+    authorId: line.senderId,
+    // THE SHARED SENDER RULE (OPE-1857): agent → self (our own post); bot → bot (attributable
+    // foreign bot, marked awareness); every other visible line is a `user` → human. `unknown` was
+    // already dropped by the gate above.
+    sender: catchUpSender({ self: line.senderType === "agent", bot: line.senderType === "bot" }),
+    type,
+    threadId,
+    text: line.text,
+  };
+}
+
+/** Paginate `GET /channels/{id}/messages` backward from `before` (exclusive), bounded by
+ *  {@link DISCORD_RAW_FETCH_MAX_PAGES} AND the reachback floor (`oldestMs`, whichever binds first).
+ *  Discord returns each page newest-first; the next page anchors on the page's OLDEST id. Returns the
+ *  raw messages (newest-first across pages — the neutral core sorts by ms anyway). Fail-soft: a
+ *  junk/empty page ends pagination with whatever's in hand. */
+async function fetchDiscordWindow(
+  request: DiscordRequester,
+  channelId: string,
+  triggerMessageId: string,
+  oldestMs: number,
+): Promise<Array<Record<string, unknown>>> {
+  const all: Array<Record<string, unknown>> = [];
+  let before = triggerMessageId;
+  for (let page = 0; page < DISCORD_RAW_FETCH_MAX_PAGES; page++) {
+    const res = await request(channelId, { limit: String(DISCORD_RAW_FETCH_PAGE_LIMIT), before });
+    const msgs = extractDiscordMessages(res);
+    if (!msgs || msgs.length === 0) break;
+    all.push(...msgs);
+    const oldest = msgs[msgs.length - 1]; // Discord newest-first → last is the oldest in this page
+    const oldestId = typeof oldest.id === "string" ? oldest.id : undefined;
+    if (!oldestId) break;
+    const oldestMsThisPage = messageMs(oldest, oldestId);
+    if (oldestMsThisPage !== undefined && oldestMsThisPage < oldestMs) break; // paged past the floor
+    if (msgs.length < DISCORD_RAW_FETCH_PAGE_LIMIT) break; // short page ⇒ no more history
+    before = oldestId; // next page: strictly older than this page's oldest
+  }
+  return all;
+}
+
+/** The triggering first wake, narrowed to what the neutral-core window needs (mirrors Slack's
+ *  {@link import("./slack-wake-backscroll.js").WakeEnvelopeBackscrollInput}). */
+export interface DiscordBackscrollWindowInput {
+  /** The surface to READ — the channel/thread the trigger is IN (a Discord thread is its own id). */
+  readonly channelId: string;
+  /** The triggering message's id — the window's upper (exclusive) bound (`before=`) and, decoded to
+   *  ms, the reachback origin the core clusters against. */
+  readonly triggerMessageId: string;
+  /** True when `channelId` is a thread (types 10/11/12) — every message is then tagged `thread`. */
+  readonly isThread: boolean;
+  /** The bot's OWN Discord author id (relay `botId`) — labels its own posts `self`. Absent (older
+   *  relay) → own posts read as an attributable bot (still visible), never a crash. */
+  readonly botId?: string;
+  /** Hours to look back from the trigger for the raw fetch. Defaults to
+   *  {@link DISCORD_RAW_FETCH_REACHBACK_HOURS}. */
+  readonly reachbackHours?: number;
+  /**
+   * THE CATCH-UP BOUND (OPE-1726, the Slack seam's exact field): epoch milliseconds of the seat's own
+   * LAST WAKE, so this read returns what the channel said since the seat last looked. It only ever
+   * NARROWS the window — the reachback floor above still applies — so a seat quiet for a month reads
+   * the recent tail, and a seat with no recorded wake reads the bootstrap window unchanged.
+   */
+  readonly sinceMs?: number;
+}
+
+/**
+ * DISCORD FETCH SEAM: fetch a bounded, visibility-GATED, NORMALIZED backscroll window for a first
+ * wake. This is the platform boundary — the neutral core ({@link fetchedBackscroll}) consumes its
+ * output. FAIL-SOFT: any error/failure yields `[]`. Deduped by message id.
+ */
+export async function fetchDiscordBackscrollWindow(
+  input: DiscordBackscrollWindowInput,
+  deps: DiscordBackscrollDeps = liveDeps,
+  failureMode: "soft" | "throw" = "soft",
+): Promise<NormalizedMessage[]> {
+  try {
+    const triggerMs = snowflakeToMs(input.triggerMessageId);
+    const reachbackHours = input.reachbackHours ?? DISCORD_RAW_FETCH_REACHBACK_HOURS;
+    // Reachback origin = the trigger's own time when derivable, else now (fail-soft — a bad trigger
+    // id still yields a sane recent window rather than nothing).
+    const originMs = triggerMs ?? Date.now();
+    // The reachback floor, then the seat's own last wake where it is LATER — never earlier, so the
+    // catch-up can only narrow the fetch (see {@link DiscordBackscrollWindowInput.sinceMs}).
+    const floorMs = originMs - reachbackHours * 3_600_000;
+    const oldestMs = typeof input.sinceMs === "number" && Number.isFinite(input.sinceMs) ? Math.max(floorMs, input.sinceMs) : floorMs;
+
+    const raw = await fetchDiscordWindow(deps.request, input.channelId, input.triggerMessageId, oldestMs);
+    if (raw.length === 0) return [];
+
+    const type: "channel" | "thread" = input.isThread ? "thread" : "channel";
+    const threadId = input.isThread ? input.channelId : undefined;
+    const seen = new Set<string>();
+    const out: NormalizedMessage[] = [];
+    for (const m of raw) {
+      const n = normalizeDiscordMessage(m, input.botId, type, threadId);
+      if (!n) continue;
+      if (n.ms < oldestMs) continue; // outside the reachback window
+      if (seen.has(n.id)) continue; // dedupe (paging overlap / repeats)
+      seen.add(n.id);
+      out.push(n);
+    }
+    return out;
+  } catch (err) {
+    if (failureMode === "throw") throw err;
+    return []; // fail-soft: a first wake never depends on its backscroll
+  }
+}
+
+/**
+ * Fetch + cluster a Discord first-wake backscroll into session-tagged {@link WakeMessageInput}
+ * entries (oldest-first, no `trigger`). Thin orchestration over the Discord fetch seam
+ * ({@link fetchDiscordBackscrollWindow}) + the neutral clustering/bounds core
+ * ({@link fetchedBackscroll}) — the exact parity of slack-wake-backscroll.ts
+ * fetchWakeEnvelopeBackscroll. FAIL-SOFT ABSOLUTELY.
+ *
+ * Per-message trust mirrors the Slack seam: pass a `trustFor` resolver (build it with
+ * identity/wake-trust.ts `backscrollTrustResolver`, off the confirmInternal verdict + domain-grain
+ * channelKey) so each backscroll author gets its real roster/gate-derived tier (F3). When omitted,
+ * fetchedBackscroll's fail-closed per-sender default applies (a human → `unauth`, self/bot →
+ * `relay`), never a blanket `peer`.
+ *
+ * NOTE: this is a proven DROP-IN with no live caller yet — Discord has no wake-envelope render
+ * surface to render the `<session>` output on a live wake (see the file header + the
+ * TODO(discord-supervisor-backscroll) at discord-gateway.ts's dispatch seam). The `trustFor` seam
+ * is wired here ahead of that surface so, when the Discord supervisor lands, it passes the resolver
+ * exactly as slack-events.ts's live supervisor deps do for fetchWakeEnvelopeBackscroll.
+ */
+export async function fetchDiscordWakeEnvelopeBackscroll(
+  input: DiscordBackscrollWindowInput,
+  deps: DiscordBackscrollDeps = liveDeps,
+  trustFor?: BackscrollTrustFor,
+): Promise<WakeMessageInput[]> {
+  try {
+    const window = await fetchDiscordBackscrollWindow(input, deps);
+    if (window.length === 0) return [];
+    return fetchedBackscroll(window, undefined, trustFor);
+  } catch {
+    return []; // fail-soft: a first wake never depends on its backscroll
+  }
+}
+
+/**
+ * DISCORD'S REGISTERED CATCH-UP FETCH (OPE-1726) — the one thing this surface contributes to the
+ * shared since-last-wake path (core channels/seat-catch-up.ts). It reuses the window fetch above,
+ * addressed by the neutral request shape: the seat's container, bounded below by its last wake.
+ * 🔴 THE UPPER BOUND IS A MESSAGE ID, not a time, because `GET /channels/:id/messages` pages with
+ * `before=<snowflake>` and takes no timestamp. `excludeId` IS that snowflake (the trigger's own id),
+ * and with none the read anchors on a snowflake synthesised from `untilMs` — Discord ids embed their
+ * own millisecond, so the synthesised anchor orders correctly even though it names no real message.
+ * The shared path re-applies both bounds on its own side, so a page that overshoots is trimmed there.
+ * `threadRoot` present ⇒ the seat is bound to a thread, and a Discord thread IS its own channel id,
+ * so the read addresses that id and tags every message `thread`.
+ * A transport/read failure propagates to core's shared boundary, which keeps the wake alive and
+ * records `failed` instead of reporting a quiet channel (OPE-1842). Bootstrap callers keep the
+ * window fetch's default fail-soft mode.
+ */
+export async function fetchDiscordSeatCatchUp(req: SeatCatchUpRequest, deps: DiscordBackscrollDeps = liveDeps): Promise<readonly NormalizedMessage[]> {
+  const isThread = req.threadRoot !== undefined;
+  const anchor = req.threadRoot ?? req.container;
+  const triggerMessageId = req.excludeId ?? msToSnowflake(req.untilMs ?? Date.now());
+  const strictDeps: DiscordBackscrollDeps = {
+    request: async (channelId, query) => {
+      const res = await deps.request(channelId, query);
+      if (!Array.isArray(res)) throw new Error("Discord catch-up request failed");
+      return res;
+    },
+  };
+  return fetchDiscordBackscrollWindow({ channelId: anchor, triggerMessageId, isThread, sinceMs: req.sinceMs }, strictDeps, "throw");
+}
+
+/**
+ * A Discord snowflake encodes MILLISECONDS and the ISO `timestamp` field carries them too (OPE-1847,
+ * `core/agent/channels/seat-catch-up.ts` {@link SeatCatchUpDeclaration.timestampPrecisionMs}).
+ * 🔴 ONE MILLISECOND IS NOT ZERO WIDENING. The road widens the LOWER bound by nothing here and the
+ * UPPER bound by exactly one millisecond, so a message stamped at the trigger's own instant is
+ * INSIDE the window and `excludeId` is the only thing that removes the trigger. The paging call
+ * already anchors on `before=<the trigger snowflake>`, which is exclusive, and a message that did
+ * arrive would carry that snowflake as its id.
+ * 🔴 IT IS STILL DECLARED, and the parity test requires it. The declaration is what makes "this
+ * surface needs the finest unit" a CHECKED claim rather than an omission, and an omission is
+ * indistinguishable from the GitHub and Notion defect this whole mechanism exists to close.
+ */
+export const DISCORD_TIMESTAMP_PRECISION_MS = 1;
+
+/** The registered form — the transport seam is fixed to the live one. Tests drive
+ *  {@link fetchDiscordSeatCatchUp} with a canned requester instead. */
+export const discordSeatCatchUpFetch: SeatCatchUpFetch = (req) => fetchDiscordSeatCatchUp(req);