@open-everywhere/core 0.1.0

package/agent/channels/seat-catch-up.ts

@@ -0,0 +1,482 @@
+// seat-catch-up — the ONE shared since-last-wake catch-up path for a standing seat, and the per-surface FETCH REGISTRY behind it (OPE-1726).
+// 🔴 WHAT THIS CLOSES. OPE-1695 (b) built the catch-up read on SLACK alone: every wake there reads the room since the seat's own `lastWakeAt`, thread-enriched, admission-filtered and capped. The other five surfaces read their bootstrap window and then NOTHING between their own wakes, so a Discord, Teams, GitHub, Linear or Notion seat answered a message and went blind until its next wake. The shape was never surface-specific — only the fetch was — so the bounds, the admission and the cap live here, once, and a surface contributes exactly one thing: a {@link SeatCatchUpFetch} that turns its own container history into {@link NormalizedMessage}s.
+// 🔴 A SURFACE WITH NO HISTORY FETCH REPORTS UNAVAILABLE, NEVER SILENTLY EMPTY. An empty read and an impossible read are different facts, and rendering both as "nothing happened" is how a seat states, with confidence, that a room has been quiet. {@link seatCatchUp} answers with {@link SeatCatchUpResult.unavailable} when the platform registered no fetch, and the wake renderer puts that sentence in the envelope.
+// A REGISTERED FETCH THAT FAILS IS STILL FAIL-SOFT TO EMPTY, and that is deliberate: a transient API error is not a statement about the surface, and a wake must never depend on its catch-up. "Unavailable" names a STRUCTURAL absence — this surface cannot read its own history — which is a fact the model can act on.
+// 🔴 FAIL-SOFT WITHOUT A ROW IS A BLIND SPOT, ON EVERY SURFACE (OPE-1831). Fail-soft is what the SEAT is owed; it is not what an OPERATOR is owed. Every outcome above resolves to an empty message list, so from outside a red ship an empty room, a refused author and an unregistered platform were the SAME evidence. {@link seatCatchUp} now writes exactly ONE {@link SEAT_CATCH_UP_ACTION} row per call, whatever the outcome, naming the outcome as one greppable enum and the raw and kept counts. The row lives HERE and not in six provider modules for the same reason the bounds do: a surface contributes a fetch, and the row it owes comes with the road.
+// 🔴 A BOUND IS ONLY AS FINE AS THE SURFACE'S OWN CLOCK (OPE-1847). A vendor stamps a message in its
+// own UNIT — Slack, Discord, Teams and Linear to the millisecond, GitHub to the SECOND, Notion to the
+// MINUTE — and a bound computed in finer grain than the stamp it is compared against excludes
+// messages that are genuinely inside the window. Ship #211 read the Notion seat's page and kept
+// NOTHING (`outcome=empty raw=2 kept=0 reason=bounds-dropped-all`): the upper bound is the trigger's
+// own minute-floored `created_time` and the filter below was `m.ms < untilMs` STRICT, so every
+// comment sharing the trigger's minute — the comment that woke the seat included — carried the SAME
+// floored instant and was bounded out of its own window. The lower bound has the mirror defect: it
+// comes from the seat's `lastWakeAt`, which is REAL time and is never floored.
+// 🔴 THE FIX IS ONE ROAD, NOT A NOTION ROUNDING PATCH. A surface DECLARES its stamp unit
+// ({@link SeatCatchUpDeclaration.timestampPrecisionMs}) beside its fetch, and {@link seatCatchUp}
+// WIDENS both bounds to that unit once — before the fetch, so the surface asks its vendor the widened
+// question too, and again on the way back. The wake's own message is then removed BY ID
+// ({@link SeatCatchUpRequest.excludeId}) and never by time, because on a coarse surface it shares its
+// instant with the messages the seat must actually read.
+// THE COST IS STATED, AT BOTH ENDS, because the trade is only defensible if it is written down.
+// LOWER: widening can re-show a message the previous wake already read, when both fall in one unit.
+// UPPER: a message posted AFTER the trigger but inside the trigger's own unit now enters that wake's
+// context — and Notion or the vendor then delivers it again as its own wake's trigger, so the seat
+// meets it twice. One second on GitHub, one minute on Notion, one millisecond on the other four.
+// Neither cost is avoidable: inside one unit the vendor's own stamps cannot order two messages, so
+// the choice is to admit the unit or to drop it. Both are the right way round — a seat that sees one
+// message twice is recoverable, a seat that never sees it is not, which is what ship #211 was.
+// 🔴 FAIL-SOFT HAS ONE OWNER (OPE-1842). A provider fetch propagates a transport/read failure to
+// this road; this road catches it, returns an empty window to the seat, and records `failed`. If an
+// adapter turns the failure into `[]` first, the shared row can only call it `empty`, making an
+// unreadable room byte-identical to a quiet one. Provider fetches may still return `[]` for genuine
+// empty/unconfigured/unaddressable answers; only an exception says the attempted read failed.
+
+import { fetchedBackscroll, type BackscrollTrustFor, type NormalizedMessage } from "./backscroll-window.js";
+import { admissionFunction, type SeatAdmissionFn } from "./seat-admission.js";
+import type { WakeMessageInput } from "./wake-envelope.js";
+import { appendAudit, type AuditInput } from "../audit/audit.js";
+import { deploymentOrg } from "../identity/deployment-identity.js";
+import { admitProviderRegistration } from "../access/provider-selection.js";
+import { processRegistryMap } from "../lib/process-registry.js";
+import { admissionNameFor } from "../memory/domain.js";
+import { getConfig } from "../access/config.js";
+import { getSettings } from "../settings/settings.js";
+import { e2eDriverPrincipals, isE2eDriver } from "../testing/driver-allowlist.js";
+
+/**
+ * What a surface is asked to read: the seat's OWN container, between the seat's last wake and the trigger, in the ids that surface's own API calls take.
+ * The container vocabulary is the seat's, not the reader's: a Slack/Discord channel, a Teams channel, a GitHub issue or pull request, a Linear issue, a Notion page.
+ * 🔴 `threadRoot` NAMES the conversation the wake sits in; it does not say what the fetch does with it. A surface may NARROW to it (Slack, Discord) or ADD it to the container read (Teams, whose Graph endpoints serve chain roots and replies separately and neither holds the other). CORE NEVER FILTERS ON IT — a core-side filter would silently drop the half a widening surface adds.
+ */
+export interface SeatCatchUpRequest {
+  /** The container id in the ADAPTER's own vocabulary — never the opaque channel key the model sees. */
+  readonly container: string;
+  /** The conversation inside the container, when the seat is bound to one (a thread root, a discussion id). Absent ⇒ read the container. */
+  readonly threadRoot?: string;
+  /**
+   * A vendor-authenticated resource anchor for the conversation, when the vendor addresses the
+   * read by something other than {@link threadRoot}. Notion inline discussions are the concrete
+   * case: `threadRoot` is a discussion id used for filtering/replies, while `threadAnchor` is the
+   * fetched comment's parent block id used by the comments endpoint. Absent preserves container
+   * level behaviour. Never derive this from message text or guess it from `threadRoot`.
+   */
+  readonly threadAnchor?: string;
+  /**
+   * Epoch ms of the OLDEST message to read — the seat's own last wake, already floored by the adapter's reachback ({@link import("./backscroll-window.js").seatCatchUpSinceMs}).
+   * 🔴 AS THE FETCH RECEIVES IT, this is already WIDENED to the start of the surface's own stamp unit ({@link SeatCatchUpDeclaration.timestampPrecisionMs}), so a fetch that re-states the bound to its vendor states the SAME bound core applies. The caller passes real time; {@link seatCatchUp} widens it.
+   */
+  readonly sinceMs: number;
+  /**
+   * Epoch ms of the trigger — the window's upper bound, to the UNIT. A message in a LATER unit than the trigger is newer than the wake, and rendering it as context would show the seat something it has not been told about.
+   * 🔴 AS THE FETCH RECEIVES IT, this is already WIDENED to the END of the surface's own stamp unit, so a message sharing the trigger's unit stays INSIDE the window. The trigger itself is removed by {@link excludeId}, never by this bound.
+   * 🔴 SO THIS BOUND DOES NOT SEPARATE "BEFORE THE TRIGGER" FROM "AFTER IT" INSIDE ONE UNIT, and it cannot: the vendor's own stamps do not order two messages in one unit. A message posted after the trigger but inside its unit enters that wake's context, and arrives again as its own wake's trigger — see the module header's cost paragraph.
+   */
+  readonly untilMs?: number;
+  /**
+   * The trigger's own platform message id — THE ONE WAY the wake's own message leaves the window (OPE-1847).
+   * 🔴 A SURFACE MUST NORMALIZE ITS MESSAGES TO IDS THIS CAN MATCH. Time cannot do this job: on a coarse-stamped surface the trigger shares its instant with the messages the seat is reading for, so bounding it out by time bounds them out too.
+   */
+  readonly excludeId?: string;
+  /** Domain-grain channel key (`platform/workspace/surface`) — the caller's already-resolved grain, for a fetch that must re-resolve credentials or scope from it. */
+  readonly channelKey?: string;
+  /** The route's own POSITIVE verdict that this container is internal to the workspace — the same fact the trigger's trust tier was resolved from. A fetch that builds a per-author trust resolver needs it, and passing the caller's real verdict is what stops the resolver hardcoding one. Absent ⇒ the fail-closed reading, not internal. */
+  readonly surfaceInternal?: boolean;
+}
+
+/**
+ * ONE surface's wake-time history fetch: the seat's container, normalized and VISIBILITY-GATED.
+ * 🔴 THE VISIBILITY GATE IS THE FETCH'S JOB, never this core's — the same division {@link fetchedBackscroll} already states. A fetch drops the senders it cannot ATTRIBUTE; the DOMAIN's admission policy then decides who enters, here.
+ * A transport/read failure THROWS to {@link seatCatchUp}, which owns the fail-soft boundary and
+ * records `failed`. A genuine empty/unconfigured/unaddressable answer resolves to `[]` and records
+ * `empty`; adapters must not erase that distinction.
+ */
+export type SeatCatchUpFetch = (req: SeatCatchUpRequest) => Promise<readonly NormalizedMessage[]>;
+
+/**
+ * WHAT THE SURFACE DECLARES BESIDE ITS FETCH. One field today, and it is an option rather than a
+ * required argument on purpose: the DEFAULT is the honest reading for a surface that has not thought
+ * about it, and the parity test is what forces every shipped surface to.
+ */
+export interface SeatCatchUpDeclaration {
+  /**
+   * The UNIT this surface stamps its own message times in, in ms — the grain of the timestamps its
+   * {@link SeatCatchUpFetch} puts on `NormalizedMessage.ms`, NOT a tolerance and NOT a skew budget.
+   * 1 for a millisecond-grain surface (Slack, Discord, Teams, Linear), 1_000 for GitHub's
+   * second-grain `created_at`, 60_000 for Notion's minute-floored `created_time`.
+   * 🔴 DECLARE THE VENDOR'S UNIT, NEVER A MARGIN. {@link seatCatchUp} widens the window by exactly
+   * this much at each end, so an inflated value hands the seat messages from outside its own window
+   * and a deflated one is the OPE-1847 defect itself.
+   * Absent, non-finite, below 1 or non-integral ⇒ {@link DEFAULT_TIMESTAMP_PRECISION_MS}.
+   */
+  readonly timestampPrecisionMs?: number;
+}
+
+/**
+ * The stamp unit assumed for a surface that declares none: one millisecond, the finest unit this
+ * declaration can express.
+ * 🔴 IT IS NOT "NO WIDENING", and reading it that way is how the next defect gets written. The road
+ * widens by exactly one unit at each end, so at 1 ms the lower bound is unchanged for an integer
+ * bound and the upper bound moves from `m.ms < untilMs` to `m.ms <= floor(untilMs)`. A message
+ * stamped at the trigger's own instant is therefore INSIDE the window on EVERY surface, and
+ * {@link SeatCatchUpRequest.excludeId} is the only thing that removes the trigger.
+ * It is also not the finest grain every surface HAS: a Slack `ts` carries a microsecond fraction,
+ * which this unit cannot express and the road's floor rounds away.
+ */
+export const DEFAULT_TIMESTAMP_PRECISION_MS = 1;
+
+/** What one platform put on the road: the fetch, and what it declared about itself. */
+interface SeatCatchUpRegistration {
+  readonly fetch: SeatCatchUpFetch;
+  /** Already validated to a finite integer ≥ 1 by {@link registerSeatCatchUp}. */
+  readonly timestampPrecisionMs: number;
+}
+
+// PROCESS-GLOBAL, for the reason lib/process-registry.ts states: the writer is a provider bundle's
+// `register<X>Provider()` and the reader is a wake path, and the two address this seam by module
+// identity. Selection-gated like every other platform-keyed seam, so an unselected bundle registers
+// nothing and its surface reads as having no fetch at all.
+// 🔴 `.v2` BECAUSE THE VALUE SHAPE CHANGED (OPE-1847): the map used to hold a bare fetch and now
+// holds {@link SeatCatchUpRegistration}. The key is what two builds in one process address each other
+// by, so reusing `.v1` would let an older bundle's bare fetch arrive where a record is read.
+const FETCHES = processRegistryMap<SeatCatchUpRegistration>("seat-catch-up.v2");
+
+/**
+ * Register one platform's catch-up fetch and what it declares. Called from the bundle's own
+ * `register<X>Provider()`.
+ * A declared precision that is not a finite integer ≥ 1 is REPLACED by the default rather than
+ * thrown on: this runs at bundle registration, where a throw would cost the deployment its surface,
+ * and the parity test is the place a wrong declaration is meant to be caught.
+ */
+export function registerSeatCatchUp(platform: string, fetch: SeatCatchUpFetch, declaration: SeatCatchUpDeclaration = {}): void {
+  if (!admitProviderRegistration(platform, "seat-catch-up")) return;
+  const declared = declaration.timestampPrecisionMs;
+  const timestampPrecisionMs = typeof declared === "number" && Number.isInteger(declared) && declared >= 1 ? declared : DEFAULT_TIMESTAMP_PRECISION_MS;
+  FETCHES.set(platform, { fetch, timestampPrecisionMs });
+}
+
+/** One platform's registered fetch, or undefined — the STRUCTURAL "this surface cannot read its own history" answer. */
+export function seatCatchUpFetchFor(platform: string): SeatCatchUpFetch | undefined {
+  return FETCHES.get(platform)?.fetch;
+}
+
+/**
+ * The stamp unit one platform DECLARED, or {@link DEFAULT_TIMESTAMP_PRECISION_MS} when it declared
+ * none and for a platform that is not on the road at all.
+ * Exported so the parity test reads each surface's declaration rather than re-deriving it, and so a
+ * removed declaration reds there instead of reaching a ship.
+ */
+export function seatCatchUpPrecisionFor(platform: string): number {
+  return FETCHES.get(platform)?.timestampPrecisionMs ?? DEFAULT_TIMESTAMP_PRECISION_MS;
+}
+
+/** Drop a platform's registration (tests only — the registry is process-global). */
+export function _resetSeatCatchUp(platform: string): void {
+  FETCHES.delete(platform);
+}
+
+/**
+ * THE WINDOW, WIDENED TO ONE SURFACE'S STAMP UNIT (OPE-1847). Pure, and the only place the widening
+ * is computed — {@link seatCatchUp} applies the result both to the request it hands the fetch and to
+ * the messages the fetch hands back, so the vendor and this core can never be asked different
+ * questions.
+ *
+ * `sinceMs` moves DOWN to the start of its unit: the caller's bound is real time (the seat's
+ * `lastWakeAt`) while a fetched message carries a FLOORED stamp, so a message genuinely after the
+ * last wake reads as before it for the rest of that unit.
+ * `untilMs` moves UP to the END of its unit: a message sharing the trigger's unit carries the
+ * trigger's own floored instant, and a strict bound against it drops the very message the seat woke
+ * to read. The trigger itself leaves by {@link SeatCatchUpRequest.excludeId}.
+ *
+ * 🔴 `Math.floor`, NEVER `t - (t % unit)`. JS keeps the sign of the dividend, so the subtraction
+ * rounds a pre-epoch instant UP — toward a NEWER lower bound, which would drop a valid message. The
+ * same arithmetic, for the same reason, as `scripts/e2e/notion-driver.ts` `notionMinuteFloor`.
+ * A non-finite bound passes through UNCHANGED: widening it would invent a number, and the caller's
+ * own `Number.isFinite` guards already report it (the audit row writes `unparsable`).
+ */
+export function seatCatchUpBounds(sinceMs: number, untilMs: number | undefined, precisionMs: number): { readonly sinceMs: number; readonly untilMs: number | undefined } {
+  const unit = Number.isInteger(precisionMs) && precisionMs >= 1 ? precisionMs : DEFAULT_TIMESTAMP_PRECISION_MS;
+  const floorTo = (t: number): number => (Number.isFinite(t) ? Math.floor(t / unit) * unit : t);
+  return {
+    sinceMs: floorTo(sinceMs),
+    untilMs: untilMs === undefined || !Number.isFinite(untilMs) ? untilMs : floorTo(untilMs) + unit,
+  };
+}
+
+/**
+ * The sentence a seat is told when its surface cannot read its own history. TRUSTED, OE-authored and CONSTANT — no interpolation point, so a platform name is the only thing that varies and it is appended by {@link catchUpUnavailableReason} from the caller's own already-validated platform id.
+ * It states the BOUND, not an apology: the seat must not infer silence from an empty context on such a surface.
+ */
+const CATCH_UP_UNAVAILABLE_NOTE =
+  "This surface cannot read its own history between wakes, so nothing below is a catch-up: what the room said since your last wake is NOT shown, and an absence of messages here does not mean the room was quiet.";
+
+/** The unavailable sentence for one platform — the note above, with the platform named. */
+export function catchUpUnavailableReason(platform: string): string {
+  return `${platform}: ${CATCH_UP_UNAVAILABLE_NOTE}`;
+}
+
+/**
+ * THE DOMAIN'S ADMISSION POLICY for one channel key, resolved by NAME (memory/domain.ts `admissionNameFor`) and returned as the deterministic function (channels/seat-admission.ts).
+ * It lives here because six surfaces now need it and the resolution is surface-neutral: a per-bundle copy is six chances for one room's seat to admit a different set depending on which platform woke it.
+ * FAIL-SOFT TO THE DEFAULT: a config that will not load resolves `wide`, which is what an undeclared channel resolves anyway — a throw out of a fail-soft read path would be the worse answer, and config load already refused every unknown name.
+ */
+export function seatAdmissionFor(channelKey: string | undefined): SeatAdmissionFn {
+  try {
+    const domains = getConfig().loadDomains();
+    const base = admissionFunction(channelKey ? admissionNameFor(channelKey, domains) : undefined);
+    if (channelKey === undefined) return base;
+    return withE2eDriverAdmission(base, surfaceOfChannelKey(channelKey), workspaceOfChannelKey(channelKey));
+  } catch {
+    return admissionFunction(undefined);
+  }
+}
+
+/** The platform segment of a surface key (`discord/<guild>/<channel>` → `discord`). Pure. */
+function surfaceOfChannelKey(channelKey: string): string {
+  const slash = channelKey.indexOf("/");
+  return slash === -1 ? channelKey : channelKey.slice(0, slash);
+}
+
+/**
+ * The WORKSPACE segment of a surface key (`slack/<team>/<channel>` → `<team>`), or `undefined` for a
+ * key that carries none. Split-on-slash is safe for index 1: only the trailing surface segment can
+ * itself contain a slash (the same reasoning `identity/wake-trust.ts` states for the pair it builds).
+ * Pure.
+ */
+function workspaceOfChannelKey(channelKey: string): string | undefined {
+  const workspace = channelKey.split("/")[1];
+  return workspace === undefined || workspace === "" ? undefined : workspace;
+}
+
+/**
+ * THE E2E DRIVER CARVE-OUT (OPE-1754, OPE-1969): `base`, plus the deployment's NAMED driver
+ * identities for this surface, in this workspace where the surface's own id vocabulary names one.
+ *
+ * 🔴 THE PRINCIPAL IS WHAT PINS THE REACH, and it differs per surface by design. A Slack entry is a
+ * `teamId:botId` pair, so `workspace` is half the match and a driver named for one workspace has no
+ * standing in another. A Discord or Notion entry names a globally unique vendor id, so it reaches
+ * that identity wherever it speaks on its surface — the same reach the id itself already has.
+ *
+ * 🔴 ONE PREDICATE, AND NO SECOND SCOPE (OPE-1969). The carve-out reaches exactly what the Slack DM
+ * door reaches, because both ask {@link isE2eDriver} the same question about the same
+ * (surface, workspace, author) triple. An earlier cut asked a narrower one here — the channel's
+ * explicit domain had to sit in a tracked `E2E_DRIVER_DOMAINS` roster — and the two planes then
+ * disagreed for a room no domain claims: on board ship #223 leg 56 (`J-ENGAGED-slack`, room
+ * `C0EXCHAN004`, which `agent/memory/config/domains/e2e-engaged.ts` keeps outside every explicit
+ * domain by design) the door admitted the driver's bot-authored messages and the seat's catch-up
+ * dropped them, so the wake envelope carried the seat's own words alone. A door and a read that
+ * answer one question cannot disagree again.
+ *
+ * WHY IT IS A WRAPPER AND NOT A POLICY NAME. A registered admission policy is pure and judges only
+ * `sender`/`trust`/`type`, which is what makes it goldenable from its name alone
+ * (channels/seat-admission.ts). Matching a NAMED identity needs the deployment's configuration and
+ * the message's author, so it is declared here, at the ONE place a domain's policy is resolved,
+ * rather than smuggled into the registry.
+ *
+ * WHY NOT `admission: "wide-with-bots"` ON THE FIXTURE DOMAIN, which was the other way to unblock
+ * the same legs (OPE-1748, refused). That name admits EVERY attributable foreign bot at the `relay`
+ * tier — a posture change to the fixture, and a door any third-party bot in the room walks through.
+ * This admits exactly the identities `wake.e2eDrivers` names, at the same `relay` tier the base
+ * policy already grants every machine author. No tier is invented and no other bot gains anything.
+ *
+ * 🔴 IT ONLY EVER WIDENS FOR A LISTED IDENTITY. Everything `base` admits stays admitted, and a bot
+ * that is not listed gets exactly `base`'s verdict — which is a refusal under `wide`, the fixture's
+ * own policy. Empty configuration, or a surface with no entry, returns `base` ITSELF, so an
+ * unconfigured deployment runs the identical function it ran before. A real deployment ships
+ * `wake.e2eDrivers` empty, so the room this reaches is a room in a test bed.
+ *
+ * 🔴 THE ADDRESSING POSTURE IS UNTOUCHED. This says whose messages ENTER a seat's context; it says
+ * nothing about what WAKES a seat, which is the ambient flag's job and is declared per domain.
+ * `e2e-engaged` stays addressed-only, which is the widening Tommy refused (OPE-1748).
+ */
+export function withE2eDriverAdmission(base: SeatAdmissionFn, surface: string, workspace: string | undefined): SeatAdmissionFn {
+  const drivers = getSettings().wake.e2eDrivers;
+  // The early return is what gives the function its identity property above; the MATCH itself is
+  // the shared `isE2eDriver`, so this read and the Slack DM door can never spell a different one.
+  if (e2eDriverPrincipals(drivers, surface).length === 0) return base;
+  return (c) => base(c) || (c.sender === "bot" && isE2eDriver(drivers, surface, workspace, c.authorId));
+}
+
+/** What {@link seatCatchUp} answers with. `messages` is oldest-first and already admission-filtered and capped; `unavailable` is present ONLY when the platform registered no fetch. */
+export interface SeatCatchUpResult {
+  readonly messages: readonly WakeMessageInput[];
+  /** See {@link catchUpUnavailableReason}. Present ⇒ the seat read nothing because it COULD not, and the wake renderer says so. */
+  readonly unavailable?: string;
+}
+
+/** Knobs the caller already holds: the per-author trust resolver, handed straight to {@link fetchedBackscroll}. `capTokens` defaults to the shared tail cap, so one cap governs the tail ring and every surface's catch-up. */
+export interface SeatCatchUpOpts {
+  readonly trustFor?: BackscrollTrustFor;
+  /**
+   * 🔴 A TEST OVERRIDE, NEVER A WAKE PATH'S KNOB (OPE-1857). {@link seatCatchUp} resolves the
+   * domain's admission policy ITSELF, from the `channelKey` the request already carries, so the
+   * policy is one road's property and not six callers'. A provider that passed its own would be
+   * back to deriving the key its own way, and a provider that passed NONE used to get no admission
+   * at all — a silent widening that looked identical to a policy that admitted.
+   * It stays for the tests that drive one stage in isolation (`admit: () => true` to reach the cap,
+   * a hand-built policy to reach one arm), and `scripts/seat-catch-up-parity-test.ts` proves the
+   * ROAD applies the domain's own policy when nothing is passed.
+   */
+  readonly admit?: SeatAdmissionFn;
+  readonly capTokens?: number;
+  /** The audit writer for the {@link SEAT_CATCH_UP_ACTION} row. Injected so a test reads the row this
+   *  path emits instead of a store; live callers get {@link appendAudit}, which never throws by its
+   *  own contract. */
+  readonly audit?: (entry: AuditInput) => Promise<void>;
+}
+
+/**
+ * The audit action EVERY surface's catch-up read records under. One family, one spelling — the query
+ * for the next red ship is `action = "seat.catch_up"` and nothing else.
+ * 🔴 IT LIVES HERE, NOT IN SIX PROVIDER MODULES (OPE-1831). {@link seatCatchUp} is already the one
+ * place the bounds, the admission and the cap live, so it is the one place the row belongs: a surface
+ * contributes a {@link SeatCatchUpFetch} and gets the row for free, and a new surface cannot ship
+ * without one. Before this, only Teams wrote a row (`teams.catch_up`, OPE-1817) and the other five
+ * surfaces plus the DM seat ran the same blind road — an empty read and a failed read reached a red
+ * ship as the same evidence.
+ */
+export const SEAT_CATCH_UP_ACTION = "seat.catch_up";
+
+/**
+ * What one catch-up call DID, as one greppable enum.
+ * `read` — the seat got messages. `empty` — the read worked and the window holds nothing (`reason`
+ * says which stage emptied it). `unavailable` — this platform registered no fetch, so the read was
+ * IMPOSSIBLE, not quiet. `failed` — a registered fetch's attempted transport/read failed.
+ * 🔴 `failed` IS THE ADAPTER CONTRACT'S ERROR PATH (OPE-1842): providers propagate read failures
+ * here, and this shared boundary keeps them from failing the wake. `empty` therefore means the
+ * fetch returned a real empty/unconfigured/unaddressable answer, not that the adapter swallowed an
+ * exception. It is still not proof the room was quiet: bounds, admission and coverage caps can all
+ * empty a successful read, and its `reason` says which shared stage did so.
+ */
+export type SeatCatchUpOutcome = "read" | "empty" | "unavailable" | "failed";
+
+/**
+ * The `<platform>/<workspace>/<surface>` domain-grain key the caller hands down, split for the audit
+ * row's own WHERE columns. Returns undefined for an absent key, a malformed one, or one belonging to
+ * ANOTHER platform — the row then says `unknown`, which is a fact rather than a borrowed surface.
+ * Pure; exported so the parity test pins the parse rather than re-deriving it.
+ */
+export function seatCatchUpScopeFromChannelKey(platform: string, channelKey: string | undefined): { workspace: string; surface: string } | undefined {
+  if (!channelKey) return undefined;
+  const parts = channelKey.split("/");
+  if (parts.length !== 3 || parts[0] !== platform || !parts[1] || !parts[2]) return undefined;
+  return { workspace: parts[1], surface: parts[2] };
+}
+
+/** The HTTP status inside a thrown fetch's own message (`… (HTTP 404) for <url> — <body>`), or
+ *  undefined when the failure carried none. ONLY the three digits are read: the message also carries
+ *  a slice of the vendor's response body, which never enters a row. */
+function httpStatusOf(err: unknown): number | undefined {
+  const m = /\(HTTP (\d{3})\)/.exec(err instanceof Error ? err.message : String(err));
+  return m ? Number(m[1]) : undefined;
+}
+
+/** The thrown value's ERROR CLASS — `Error`, `TypeError`, a named subclass. Runtime- or OE-controlled
+ *  text, never the vendor's message, which is where a comment body or an author name would ride. */
+function errorNameOf(err: unknown): string {
+  return err instanceof Error && typeof err.name === "string" && err.name.length > 0 ? err.name : "unknown";
+}
+
+/**
+ * THE SHARED CATCH-UP PATH. Resolve the platform's fetch, read the seat's container since its last wake, then apply the ONE neutral core ({@link fetchedBackscroll}: order, admit, cap) every surface shares.
+ * No platform branch — the platform id selects a fetch and is never read again — so a new surface is one registration and no change here.
+ * FAIL-SOFT ABSOLUTELY: a throwing or failing fetch yields an empty read plus a `failed` row, never
+ * a failed wake. A MISSING fetch answers {@link SeatCatchUpResult.unavailable} instead.
+ */
+export async function seatCatchUp(platform: string, req: SeatCatchUpRequest, opts: SeatCatchUpOpts = {}): Promise<SeatCatchUpResult> {
+  const scope = seatCatchUpScopeFromChannelKey(platform, req.channelKey);
+  // ONE widening, computed before the fetch and re-used after it (OPE-1847). Reading the declaration
+  // from the registry rather than from the request is what keeps this a SURFACE property: a wake path
+  // cannot pass a bound in a grain its own vendor does not stamp in.
+  const precisionMs = seatCatchUpPrecisionFor(platform);
+  const bounds = seatCatchUpBounds(req.sinceMs, req.untilMs, precisionMs);
+  // 🔴 EXACTLY ONE ROW PER CALL, ON EVERY RETURN PATH. Each `return` below is preceded by its own
+  // `record`, and no path reaches two — that is what makes a row count a call count, so a census can
+  // read "this seat woke N times and read its room N times" without knowing any surface's internals.
+  // NO MESSAGE BODY AND NO AUTHOR NAME goes in the row: the ids it carries are the ADDRESSING ids the
+  // surface's own dispatch row already records, and the rest is counts.
+  const record = async (outcome: SeatCatchUpOutcome, raw: number, kept: number, extra: Readonly<Record<string, unknown>> = {}): Promise<void> => {
+    try {
+      await (opts.audit ?? appendAudit)({
+        org: deploymentOrg(),
+        platform,
+        workspace: scope?.workspace ?? "unknown",
+        ...(scope ? { surface: scope.surface } : {}),
+        action: SEAT_CATCH_UP_ACTION,
+        detail: {
+          outcome,
+          // `raw` is what the SURFACE returned; `kept` is what survived the bounds, the admission
+          // policy and the cap. The two together are the whole diagnosis: raw 0 is the surface's own
+          // answer, raw>0 with kept 0 is this core's.
+          raw,
+          kept,
+          container: req.container,
+          ...(req.threadRoot === undefined ? {} : { threadRoot: req.threadRoot }),
+          // 🔴 NEVER `new Date(req.sinceMs).toISOString()` BARE. That throws `RangeError` on a
+          // non-finite bound, and the throw would be swallowed by this function's own catch — so a
+          // bad bound would delete the row instead of stamping it, which is the exact silence this
+          // row exists to end, inside the recorder. No live caller can produce one today
+          // (`seatCatchUpSinceMs` always returns a finite number), and that is a reason to be sure
+          // rather than a reason to rely on it.
+          // The bound as APPLIED — widened to this surface's stamp unit, which is the number that
+          // decided what the row's `kept` count is. `precisionMs` sits beside it so the next red ship
+          // can read the unit off the row instead of inferring it from a provider module.
+          since: Number.isFinite(bounds.sinceMs) ? new Date(bounds.sinceMs).toISOString() : "unparsable",
+          precisionMs,
+          ...extra,
+        },
+      });
+    } catch {
+      /* the row is diagnostics; losing it must not cost the seat its catch-up */
+    }
+  };
+
+  const fetch = seatCatchUpFetchFor(platform);
+  if (!fetch) {
+    await record("unavailable", 0, 0, { reason: "no-registered-fetch" });
+    return { messages: [], unavailable: catchUpUnavailableReason(platform) };
+  }
+  // The WIDENED window is what the surface is asked for, so a fetch that re-states the bound to its
+  // vendor (Notion filters in its own sweep, Slack and Discord anchor a paging call on it) states the
+  // same one this core applies below. Handing it the caller's raw bound is how the two drift.
+  const boundedReq: SeatCatchUpRequest = { ...req, sinceMs: bounds.sinceMs, ...(bounds.untilMs === undefined ? {} : { untilMs: bounds.untilMs }) };
+  let window: readonly NormalizedMessage[];
+  try {
+    window = await fetch(boundedReq);
+  } catch (err) {
+    const status = httpStatusOf(err);
+    await record("failed", 0, 0, { reason: "fetch-threw", errorName: errorNameOf(err), ...(status === undefined ? {} : { httpStatus: status }) });
+    return { messages: [] }; // a transient read failure is not a statement about the surface
+  }
+  if (window.length === 0) {
+    await record("empty", 0, 0, { reason: "fetch-returned-none" });
+    return { messages: [] };
+  }
+  // The bounds again, on THIS side of the fetch. A fetch states them to its vendor API in whatever
+  // dialect that API speaks; enforcing them here is what makes the bound true for every surface,
+  // including one whose API can only page and not filter.
+  // 🔴 THE UPPER BOUND IS THE UNIT'S END, AND THE TRIGGER LEAVES BY ID (OPE-1847). `bounds.untilMs`
+  // is already one unit past the trigger's floored instant, so a message sharing that instant STAYS —
+  // and the trigger itself is dropped by `excludeId` alone. Narrowing this back to the trigger's own
+  // stamp is the ship #211 defect, and it takes the seat's whole catch-up with it on a coarse surface.
+  const bounded = window.filter((m) => m.ms >= bounds.sinceMs && (bounds.untilMs === undefined || m.ms < bounds.untilMs) && m.id !== req.excludeId);
+  if (bounded.length === 0) {
+    await record("empty", window.length, 0, { reason: "bounds-dropped-all" });
+    return { messages: [] };
+  }
+  // 🔴 THE ADMISSION POLICY IS THIS ROAD'S, RESOLVED HERE (OPE-1857). It is resolved from the key
+  // the REQUEST carries — the same key the row's own scope, the fetch's credential and the wake's
+  // trust were resolved from — so every surface asks one question of one resolver. Six callers each
+  // passing `seatAdmissionFor(<its own key>)` was the same policy six times until one of them
+  // derived the key differently or stopped passing it, and passing NONE meant no admission at all.
+  // `opts.admit` overrides for a test that drives one stage; no wake path passes it.
+  const messages = fetchedBackscroll(bounded, opts.capTokens, opts.trustFor, opts.admit ?? seatAdmissionFor(req.channelKey));
+  // THE THIRD EMPTY, and the one a surface owner most needs told apart from the other two: the room
+  // spoke, the bounds kept it, and the DOMAIN'S ADMISSION POLICY refused every author.
+  if (messages.length === 0) {
+    await record("empty", window.length, 0, { reason: "admission-dropped-all" });
+    return { messages };
+  }
+  await record("read", window.length, messages.length);
+  return { messages };
+}