@open-everywhere/provider-notion 0.1.0

package/agent/channels/notion-bot-user.ts

@@ -0,0 +1,250 @@
+// notion-bot-user — THE deployment's own Notion identity, per integration: the bot user id every
+// road that has to tell "our own words" from someone else's compares against.
+//
+// 🔴 IT LIVES IN ITS OWN MODULE BECAUSE TWO ROADS NEED IT (OPE-1857). The ingress road has always
+// held it — `classifyNotionComment` drops a self-authored comment, and `notionCommentIsStopDirective`
+// refuses one — and it sat as a module-private helper inside `notion.ts`. The SEAT CATCH-UP needs the
+// same answer: it reads the page's own discussion since the seat last woke, and the seat's previous
+// reply is IN that window. Without this the catch-up cannot recognise our own comment, and Notion's
+// comment payload gives it nothing else to go on — `created_by` is a partial user (an id and an
+// object, no `type`), so our own reply is indistinguishable from a person's by shape alone. A second
+// copy of this resolver would be a second spelling of one identity, which is the class OPE-1857 is.
+//
+// 🔴 CACHED PER CREDENTIAL (OPE-467), not per deployment. EVERY Notion integration has its OWN bot
+// user id, so a deployment running a second integration for a bound domain has two of them. One
+// shared cache would compare a reply against the WRONG identity and break the loop guard in both
+// directions: the agent could either loop on its own replies (its id never matches) or drop real
+// human comments. The key is the credential id, which is exactly one integration.
+//
+// FAIL-SOFT, AND THE TWO ROADS READ AN UNRESOLVED ID DIFFERENTLY. A failed resolve answers `{}` and
+// is CACHED as such for the process lifetime.
+//   • THE INGRESS ROAD FAILS CLOSED: `classifyNotionComment` drops on "unresolved bot user id", so
+//     nothing dispatches rather than risk looping on our own replies.
+//   • THE CATCH-UP ROAD DOES NOT. With no id, our own comment reads as a PERSON and enters the
+//     seat's context at the `unauth` floor. That is deliberate and `notion-catch-up.ts` states and
+//     defends it where it reads this resolver: blinding a context read on a transient
+//     `GET /v1/users/me` failure would re-create the OPE-1857 symptom — a seat that keeps nothing.
+//     The ingress road's fail-closed arm covers the PRIMARY id only: a deployment that cannot
+//     resolve THAT dispatches no Notion wake and therefore takes no catch-up. An unresolved SIBLING
+//     still wakes on a person-marked comment (classifyNotionComment step 5), so its own replies can
+//     reach a seat's context as a person's — `notion-catch-up.ts` states that residual.
+
+import { retrieveBotUser, NOTION_INGRESS_RETRY, type ResolvedNotionCredential } from "./notion-api.js";
+// The ORG-DEFAULT credential id, imported rather than spelled: the override scope below is a
+// security decision, and a second spelling of that id would silently widen it.
+import { NOTION_CHANNEL_CREDENTIAL } from "./notion-credentials.js";
+
+/**
+ * EVERY bot user id this deployment posts under, and whether the set is COMPLETE (OPE-1921).
+ *
+ * 🔴 ONE ID IS NOT THE DEPLOYMENT'S IDENTITY WHEN IT RUNS TWO INTEGRATIONS. Each Notion integration
+ * has its own bot user id. The loop guard used to compare a comment against the id of the ONE
+ * integration whose secret verified that delivery, so a reply posted by integration A and delivered
+ * on integration B's subscription carried a real id that matched nothing. It read as a person, woke a
+ * turn, and A's subscription then saw B's answer — a loop the OPE-1906 once-guard cannot bound,
+ * because every reply is a new comment id.
+ *
+ * `all` is what a self-check compares against; `primary` is the VERIFYING integration's own id, kept
+ * separate because the addressed path is still that integration's (a structured @mention names one
+ * bot user, not a deployment).
+ *
+ * 🔴 `complete` IS THE FAIL-CLOSED INPUT, AND IT IS FALSE WHENEVER ONE CONFIGURED INTEGRATION'S ID
+ * DID NOT RESOLVE. Notion serves a comment's `created_by` as a PARTIAL user with no `type`
+ * (OPE-1857), so an unresolved sibling leaves a real authored comment that NOTHING can attribute:
+ * it is either a person or our own second integration, and the payload cannot say which. The guard
+ * therefore drops it — see {@link NotionOwnBotIds.complete} for what that costs.
+ */
+export interface NotionOwnBotIds {
+  /** The bot user id of the integration this delivery VERIFIED under, or undefined when it did not
+   *  resolve. An absent primary is the pre-existing fail-closed arm and still drops on its own. */
+  readonly primary: string | undefined;
+  /** Every bot user id this deployment could resolve, `primary` included. A comment whose author id
+   *  is in here is OUR OWN WORDS, whichever integration posted it. */
+  readonly all: ReadonlySet<string>;
+  /**
+   * True when EVERY configured integration's bot user id resolved. False ⇒ the self-check cannot
+   * answer "is this ours" for an author it does not recognise, and the loop guard fails CLOSED.
+   *
+   * 🔴 THE COST, STATED PLAINLY: an integration that CAN reach Notion but whose `GET /v1/users/me`
+   * fails makes the whole deployment deaf to every Notion comment Notion does not mark
+   * `person`-authored — on every page, including pages the healthy integration serves. That is NOT
+   * only ambient chatter: `classifyNotionComment` step 5 sits ABOVE the addressed arms, so an
+   * addressed name-drop and an `oe link <code>` identity claim drop with it. And
+   * `resolveNotionBotUser` caches a failure for the PROCESS
+   * LIFETIME, so a single rate-limit episode during the first resolve silences that instance until
+   * it restarts. That is the direction this repository takes everywhere else on this guard (an
+   * identity we cannot establish never wakes the agent), and the alternative is worse: a fail-open
+   * sibling is an unbounded reply loop between two integrations of one deployment, on a launch
+   * surface, with no once-guard able to stop it.
+   * The cost is bounded to integrations that could actually have posted — an integration with no
+   * usable key never sets this false. See `collectNotionOwnBotIds`'s `canPost`.
+   */
+  readonly complete: boolean;
+}
+
+/**
+ * Resolve the deployment's own bot user ids: the already-resolved `primary`, plus one per entry of
+ * `siblingCredentialIds` — every CONFIGURED INTEGRATION EXCEPT the one this delivery verified under.
+ * The resolver is the SAME per-credential one and cache the loop guard already reads, so no second
+ * spelling of one identity can exist.
+ *
+ * 🔴 THE ADDED INGRESS COST, EXACTLY: N-1 extra `GET /v1/users/me` calls for N configured
+ * integrations, on the FIRST delivery of a process, and ZERO after it —
+ * {@link resolveNotionBotUser} memoises on the credential id. The verifying integration is excluded
+ * here precisely so the number is N-1 and not N: its id is already in hand, and re-resolving it
+ * would charge a live resolver for an answer the caller just took. A SINGLE-INTEGRATION deployment —
+ * every deployment before OPE-1921 — therefore pays NOTHING at all, and `notion-test.ts`'s
+ * ack-attribution fixture measures that: its `botTriggerPage` bucket is unchanged.
+ *
+ * A resolver that THROWS counts as unresolved rather than failing the delivery: this runs on the
+ * awaited ingress path, and a thrown identity lookup must not turn into a 500 Notion will retry.
+ *
+ * 🔴 AN INTEGRATION THAT CANNOT POST IS NOT A LOOP RISK, AND MARKING THE SET INCOMPLETE FOR ONE IS
+ * PURE AVAILABILITY LOSS. `resolve` answers `undefined` for two different failures: a working key
+ * whose `GET /v1/users/me` failed — that integration CAN post, so we must fail closed — and an
+ * integration THIS DEPLOYMENT holds no usable API key for, so it cannot post FROM HERE. `canPost`
+ * separates them, and it is consulted ONLY when `resolve` came back empty, so the ordinary path
+ * pays nothing for it. Without the split, a domain whose credential is declared but whose secret is
+ * unset or revoked would silence Notion on EVERY page of the deployment, including pages
+ * the healthy org-default integration serves — a blast radius nothing buys. Absent ⇒ every
+ * unresolved sibling is treated as able to post, which is the conservative reading.
+ *
+ * 🔴 THE CLAIM IS "NOT A LOOP RISK FROM HERE", NEVER "CANNOT HAVE AUTHORED ANY COMMENT", and the
+ * difference is real. `canPost` establishes only that THIS deployment cannot resolve a key for that
+ * credential right now. A token an operator deleted here, or one another environment still holds,
+ * can keep authoring comments on the shared page — and this deployment then reads those replies as a
+ * person's, because that id is absent from `all` while `complete` stays true. The residual is
+ * accepted: a loop needs two of OUR OWN integrations answering each other, and an integration we
+ * cannot post under is not one of the two.
+ */
+export async function collectNotionOwnBotIds(
+  primary: string | undefined,
+  siblingCredentialIds: readonly string[],
+  resolve: (credentialId: string) => Promise<string | undefined>,
+  canPost?: (credentialId: string) => Promise<boolean>,
+): Promise<NotionOwnBotIds> {
+  const all = new Set<string>();
+  if (primary) all.add(primary);
+  // An unresolved PRIMARY is already an incomplete set. Step 1 of the classifier drops on it before
+  // step 5 is reached, so this line changes no verdict — it keeps the flag's meaning honest for any
+  // later reader of the structure.
+  let complete = primary !== undefined;
+  for (const credentialId of new Set(siblingCredentialIds)) {
+    let id: string | undefined;
+    try {
+      id = await resolve(credentialId);
+    } catch {
+      id = undefined;
+    }
+    if (id) {
+      all.add(id);
+      continue;
+    }
+    // Unresolved. Only an integration that can REACH Notion could have authored the comment in
+    // hand, so only that one makes the set incomplete.
+    // 🔴 AN UNKNOWN ANSWER COUNTS AS ABLE TO POST. `resolveNotionCredential` signals the real
+    // no-usable-key cases by RETURNING `undefined` — an unregistered credential, one with no
+    // `secretRef`, and a broker `CredentialError` all take that path — so it re-throws only an
+    // UNEXPECTED fault (a store timeout, a decrypt error). A throw therefore says the state is
+    // unknown, never "this integration has no key", and the unknown side of this question has to
+    // fall the way the absent-`canPost` default falls: treat the sibling as able to post and let
+    // the set go incomplete. `reachableOnce` holds that direction.
+    let reachable = true;
+    if (canPost) reachable = await reachableOnce(credentialId, canPost);
+    if (reachable) complete = false;
+  }
+  return { primary, all, complete };
+}
+
+/**
+ * Can this credential reach Notion at all — memoised for the PROCESS LIFETIME, the same lifetime
+ * {@link botUserCache} gives a resolved bot user.
+ *
+ * 🔴 WITHOUT THE MEMO THIS QUESTION IS ASKED ON EVERY DELIVERY, FOR EVER. The answer is consulted
+ * only for a sibling whose bot user id did not resolve — and `botUserCache` holds THAT failure for
+ * the process lifetime, so the arm runs on every subsequent delivery of the process. The webhook
+ * core's own credential memo is per-DELIVERY (`notion.ts` builds a fresh `Map` per delivery), so
+ * each of those deliveries paid a fresh operational-store read on the AWAITED ingress path. Worse,
+ * on the default `db` broker a ref with no stored row writes one `CREDENTIAL_UNRESOLVED` audit row
+ * per attempt by design, so a declared-but-unstored sibling credential — a configuration
+ * `docs/deploy/surfaces/notion.md` calls supported — wrote one row per ingress delivery indefinitely
+ * and drowned the repeated-refusal RATE that row exists to show. `notion-catch-up.ts` refuses that
+ * same cost on the catch-up road; this is the ingress road's answer to it.
+ *
+ * The cached value is the VERDICT, not the credential, so no key is held here. Both answers last
+ * until restart, which matches `botUserCache`: a sibling whose id will not resolve stays unresolved
+ * until then anyway, so a fresher reachability answer could not change any verdict.
+ */
+const reachableCache = new Map<string, Promise<boolean>>();
+
+function reachableOnce(credentialId: string, canPost: (credentialId: string) => Promise<boolean>): Promise<boolean> {
+  const hit = reachableCache.get(credentialId);
+  if (hit) return hit;
+  // `.catch(() => true)` is the fail-CLOSED direction, and it is the whole point: an unknown answer
+  // leaves the sibling counted as able to post, which marks the set incomplete. See the call site.
+  const verdict = canPost(credentialId).catch(() => true);
+  reachableCache.set(credentialId, verdict);
+  return verdict;
+}
+
+const botUserCache = new Map<string, Promise<{ id?: string; name?: string }>>();
+
+/** Where this module's own diagnostics go — the same prefix every Notion channel module logs under. */
+function log(msg: string): void {
+  console.log(`[open-everywhere:notion] ${msg}`);
+}
+
+/**
+ * The bot user (id and display name) for ONE integration, memoised on `credentialId`.
+ * `credential` is a THUNK so an operator override short-circuits the credential resolution entirely.
+ *
+ * 🔴 `NOTION_BOT_USER_ID` PINS THE ORG DEFAULT ONLY, AND SCOPING IT IS LOAD-BEARING (OPE-1921). It
+ * is ONE id, and two Notion integrations NEVER share a bot user — so an override applied to every
+ * credential would answer every integration with the org default's id. That is worse than no
+ * override: the cross-integration loop guard would hold a one-element set AND report it COMPLETE,
+ * so a sibling's reply would match nothing, the fail-closed arm would not fire, and the loop the
+ * set exists to close would reopen silently on a deployment that looks configured. Scoped here, a
+ * sibling still resolves live and an unresolvable one correctly marks the set incomplete.
+ * `NOTION_BOT_NAME` is NOT scoped: it is a display name the judge reads, never an identity anything
+ * is compared against, and a deployment that renames its agent means the new name everywhere.
+ */
+export function resolveNotionBotUser(
+  credentialId: string,
+  credential: () => Promise<ResolvedNotionCredential | undefined>,
+): () => Promise<{ id?: string; name?: string }> {
+  return () => {
+    const cached = botUserCache.get(credentialId);
+    if (cached) return cached;
+    const overrideId = credentialId === NOTION_CHANNEL_CREDENTIAL ? process.env.NOTION_BOT_USER_ID : undefined;
+    const overrideName = process.env.NOTION_BOT_NAME;
+    const named = (u: { id?: string; name?: string }) => ({ id: u.id, name: overrideName && overrideName.length > 0 ? overrideName : u.name });
+    const resolved =
+      overrideId && overrideId.length > 0
+        ? Promise.resolve(named({ id: overrideId }))
+        : credential()
+            // 🔴 THE INGRESS POLICY, BECAUSE THIS RESOLVE IS ON THE AWAITED INGRESS PATH (OPE-1254).
+            // `handleNotionDelivery` awaits `deps.resolveBotUserId` BEFORE `retrieveComment`, and
+            // this is the only thing behind it. On the shared defaults it could spend 60 s of backoff
+            // on its own, ahead of every call the webhook core's own `ingressCallOpts` bounds — so
+            // the delivery's worst case was ~90 s against a 300 s ceiling, not the ~60 s the seam
+            // claims. Worse, a failure here is CACHED for the process lifetime as `{}` below, and an
+            // unresolved bot id makes the classifier fail closed: one rate-limit episode during the
+            // first resolve silences every later delivery on that instance. Bounding the wait shrinks
+            // that window.
+            .then((cred) => (cred ? retrieveBotUser({ ...cred, retry: NOTION_INGRESS_RETRY }).then(named) : {}))
+            .catch((err) => {
+              log(`could not resolve bot user for credential "${credentialId}" (GET /v1/users/me failed): ${String(err)}`);
+              return {};
+            });
+    botUserCache.set(credentialId, resolved);
+    return resolved;
+  };
+}
+
+/** Reset the cached bot users AND the cached reachability verdicts (tests only). Both are keyed by
+ *  credential id and both live for the process lifetime, so a test that resets one and not the other
+ *  would carry a stale answer into the next case. */
+export function _resetNotionBotUserCache(): void {
+  botUserCache.clear();
+  reachableCache.clear();
+}

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

@@ -0,0 +1,339 @@
+// notion-catch-up — Notion's registered SEAT CATCH-UP FETCH (OPE-1726): the seat's own page
+// discussion since its last wake, normalized for core's shared catch-up path
+// (channels/seat-catch-up.ts).
+//
+// WHAT "THE SEAT'S CONTAINER" IS HERE. A Notion seat is bound to a PAGE and every wake arrives scoped
+// to one DISCUSSION on it. The read is the PAGE's comment sweep, narrowed to that discussion here.
+// 🔴 THERE IS NO PER-DISCUSSION ENDPOINT. Notion lists comments by their PAGE/BLOCK anchor, while a
+// discussion id is only the reply/filter identity. For an INLINE trigger, ingress carries the
+// fetched comment's authenticated parent block as `threadAnchor`; this fetch drills into that exact
+// block, then filters by `threadRoot`. A PAGE-level trigger has no block anchor and preserves the
+// full page sweep. Guessing the discussion id as a block id would 404 on every wake.
+//
+// WHY A STANDALONE CALLER, not `notionReadAdapter.readChannel`: that method takes a live
+// {@link BindableContext} and runs the turn-time domain-scope fence over it. A catch-up fires from a
+// webhook route with no turn, and its container is the one the wake itself already admitted. The
+// CREDENTIAL is resolved the SAME way the read adapter resolves it — from the DOMAIN that binds this
+// surface (`notionChannelCredentialForSurface`), never the org default alone — so a deployment whose
+// Notion domain binds its own integration reads the page over that integration, and this opens no
+// second transport: the same endpoint fence and the same 429 backoff.
+//
+// 🔴 THE VENDOR CANNOT FILTER BY TIME: Notion's comments endpoint takes no `since`, so the bound is
+// applied on this side and again by the shared path.
+//
+// 🔴 …AND IT SERVES OLDEST-FIRST, WHICH IS WHAT RED `J-ENGAGED-notion` ON SHIP #208 (OPE-1831).
+// THE CAUSE IS THE COMMENT CAP, CHARGED FROM THE OLD END. `readNotionComments` sweeps the PAGE's own
+// comments first and only THEN walks the page's blocks. `maxComments` was charged over the whole
+// history, so on the pinned journey page — which had collected every prior ship's page-level comments
+// — the oldest hundred filled the cap and `take` returned STOP. The sweep ended with `blocksScanned`
+// at ZERO: the block sweep never ran at all. The journey's own comment lives in a BLOCK-anchored
+// discussion on a block the run appends itself (`scripts/e2e/scenarios.ts`: `appendParagraphBlock`
+// then `createBlockDiscussion`), and a page-id comment query never returns a child block's comments
+// (`scripts/e2e/notion-driver.ts` records that, live-confirmed). So the read returned `[]` with no
+// error at all, on a discussion that HAD carried the message.
+// THE FIX IS `sinceMs`, handed to the sweep so the cap counts comments IN the seat's window. The
+// ancient page-level comments are then skipped without charging it, `take` does not stop, and the
+// block sweep runs — which is where the seat's discussion actually is.
+// 🔴 `maxCommentPages` IS A SECOND, SEPARATE BOUND, and it is NOT what fixed ship #208. One call
+// returns an anchor's oldest hundred comments and nothing follows `next_cursor`, so a PAGE-ANCHORED
+// discussion on a busy page is unreachable for the same oldest-first reason. Real, and worth closing
+// while the file is open — but a page follow could never have reached a BLOCK-anchored comment, so do
+// not read it as the ship #208 cause.
+// 🔴 THE 80-BLOCK PAGE-SWEEP BOUND STILL EXISTS FOR PAGE-LEVEL CATCH-UP, AND IT IS NOW SPENT ON THE
+// PAGE'S NEWEST BLOCKS (OPE-1843). It never hid the triggering INLINE discussion, because that path
+// uses the authenticated block drill-in. A PAGE-level seat has no narrower anchor, so it keeps the
+// bounded sweep — but in document order the whole budget went to the oldest material of a page that
+// had outgrown the cap, and Notion pages grow by APPENDING. A discussion on a recently appended
+// block was therefore never scanned, and the read returned zero comments with no error: byte for
+// byte the answer a quiet page gives. `blockScanOrder: "newest-first"` spends the same 80 scans on
+// the last blocks instead, which is where a live conversation on an append-only page is.
+// 🔴 IT MOVES THE BLIND SPOT RATHER THAN CLOSING IT: a comment posted today on an ANCIENT block of
+// an over-cap page is now the unread case. Notion can neither query "blocks with recent comments"
+// nor stamp a block when one is commented on, so no scan order is complete at any cap below the
+// page's own length. `notion-api.ts` `blockScanOrder` carries the full reasoning.
+//
+// An unresolvable credential yields `[]` because no transport was attempted. An attempted read
+// failure propagates to core's shared fail-soft boundary and records `outcome=failed` (OPE-1842).
+// 🔴 THE ROW CANNOT CARRY THE RESIDUAL COVERAGE MISS, AND THAT IS A CONTRACT LIMIT, NOT A CHOICE.
+// `readNotionComments` returns a `truncated` bit, but {@link SeatCatchUpFetch} answers with
+// `NormalizedMessage[]` and nothing else, so a surface has no slot to report partial coverage in
+// and `seat.catch_up` writes `outcome=empty raw=0 kept=0 reason=fetch-returned-none` for an
+// over-cap miss exactly as for a quiet page. Closing that needs the shared fetch contract to carry
+// a coverage bit — core's decision, not this surface's.
+
+import { readNotionComments, resolveNotionCredential, type NotionCommentSummary, type ResolvedNotionCredential } from "./notion-api.js";
+import { notionChannelCredentialForSurface, notionIntegrations, NOTION_CHANNEL_CREDENTIAL } from "./notion-credentials.js";
+import { resolveNotionBotUser } from "./notion-bot-user.js";
+import { catchUpSender, getConfig, type Domain, type NormalizedMessage, type SeatCatchUpFetch } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The loaded domain roster, or none. FAIL-SOFT: a config that will not load must not throw out of a
+ *  read contracted never to throw — it degrades to the org-default credential, which is what a
+ *  surface bound to no domain resolves anyway. */
+function safeDomains(): readonly Domain[] {
+  try {
+    return getConfig().loadDomains();
+  } catch {
+    return [];
+  }
+}
+
+/** One sweep. The catch-up window is "since the seat last woke", and a page that collected more than
+ *  this in that window is one core's token cap would trim regardless. */
+const CATCH_UP_MAX_COMMENTS = 100;
+
+/** Blocks the page sweep scans. Matches the read adapter's own bound, so a catch-up never costs more
+ *  API calls than a `read_channel` on the same page. */
+const CATCH_UP_MAX_BLOCK_SCANS = 80;
+
+/**
+ * Pages of comments the sweep follows PER ANCHOR (`notion-api.ts listBlockComments`).
+ * 🔴 ONE PAGE IS THE OLDEST HUNDRED, WHICH IS WHY THIS IS NOT 1 (OPE-1831). Notion serves comments
+ * oldest-first, so an anchor that has collected more than a page puts today's comment on the LAST
+ * page and the default single call can never reach it. A PAGE-ANCHORED discussion on any long-lived
+ * doc then reads as permanently quiet to its seat, with no error to show for it.
+ * IT COSTS NOTHING ON A NORMAL ANCHOR: the follow stops the moment Notion reports no more, so an
+ * anchor under a hundred comments is still exactly one call. Only an overflowing anchor pays, and
+ * five pages is five hundred comments — far past any window a seat's last wake can span.
+ *
+ * 🔴 THE PER-WAKE CALL BUDGET, STATED BECAUSE THIS CHANGE GREW IT (OPE-1831). One catch-up now costs
+ * up to `1 + CATCH_UP_MAX_BLOCK_SCANS` list calls (the page anchor, then one per block), each up to
+ * `CATCH_UP_MAX_COMMENT_PAGES` pages — so 81 calls typically and 405 at the theoretical ceiling,
+ * against the shared 60 s-per-call 429 budget (`channels/rate-limit-retry.ts`, OPE-1254).
+ * 🔴 AND THE OLD CHEAP PATH WAS THE BUG. Before `sinceMs`, a page whose own comments filled
+ * `maxComments` returned after ONE call — cheap, and WRONG: that early return is exactly what stopped
+ * the block sweep and shipped #208. Paying the sweep is the correction, not a regression to undo.
+ * The 405 ceiling needs every one of 81 anchors to hold over 100 comments, which no real page does;
+ * the realistic cost is one extra call or two on the page anchor alone.
+ */
+const CATCH_UP_MAX_COMMENT_PAGES = 5;
+
+/**
+ * Normalize ONE Notion comment, applying the VISIBILITY GATE every fetch adapter owes core: a comment
+ * with no author, no text or no readable time is dropped, because an unattributable body must never
+ * reach a seat. The deployment's OWN integration id resolves `self`.
+ *
+ * 🔴 `authorKind` IS ABSENT ON ALMOST EVERY COMMENT, AND READING THAT AS "NOT A PERSON" IS OPE-1857.
+ * It is Notion's own actor type, and Notion serves a comment's `created_by` as a PARTIAL user —
+ * `id` and `object`, no `type` (notion-api.ts, whose interface says so). This line used to read
+ * `authorKind === "person" ? "human" : "bot"`, so EVERY comment this surface read arrived tagged
+ * `bot` — and the default `wide` admission policy refuses every bot, on every wake, for ever. Ship
+ * #212 measured it: `seat.catch_up outcome=empty raw=4 kept=0 reason=admission-dropped-all` on a
+ * read the bounds had kept in full. A real page member's comment was refused by that arithmetic
+ * exactly as the e2e driver's was, so the seat read a page it was being spoken on as silent.
+ * 🔴 THE RULE IS CORE'S NOW ({@link catchUpSender}), and this surface contributes only the SIGNAL:
+ * a kind Notion actually stated, or `undefined` when it stated none. The repository's own trigger
+ * road already read it this way — `classifyNotionComment` (notion-supervisor.ts) drops on
+ * `author?.type && author.type !== "person"`, so an absent type is a person there too. The two roads
+ * disagreeing about one comment is the whole defect.
+ */
+function normalizeComment(c: NotionCommentSummary, selfActorIds: ReadonlySet<string>): NormalizedMessage | undefined {
+  const text = c.text.trim();
+  if (text.length === 0 || !c.authorId || !c.discussionId) return undefined;
+  const ms = Date.parse(c.createdTime ?? "");
+  if (!Number.isFinite(ms)) return undefined;
+  // OUR OWN VOICE IS THE DEPLOYMENT'S, NOT ONE INTEGRATION'S (OPE-1921) — see collectCatchUpSelfIds.
+  const isSelf = selfActorIds.has(c.authorId);
+  return {
+    // 🔴 THE COMMENT'S OWN NOTION ID, AND IT HAS TO BE (OPE-1847). The wake route passes the trigger's
+    // comment id as `excludeId`, and core removes the wake's own message BY ID alone — time cannot do
+    // it here, because `created_time` floors to the MINUTE and the trigger therefore shares its
+    // instant with every comment the seat is reading for. This slot used to hold a render label
+    // (`<discussion>:<created_time>`) that could never equal that id, so the trigger had to be bounded
+    // out by `untilMs` — which took the seat's whole catch-up with it and shipped #211 red.
+    // The label survives only as the fallback for a comment Notion served with no id, where nothing
+    // better exists; it is NOT unique (a coarse stamp lets two comments in one discussion collide).
+    id: c.id ?? `${c.discussionId}:${c.createdTime ?? ms}`,
+    ms,
+    // The bot's OWN posts carry no author id, matching every other surface's normalized shape.
+    ...(isSelf ? {} : { authorId: c.authorId }),
+    sender: catchUpSender({ self: isSelf, ...(c.authorKind === undefined ? {} : { bot: c.authorKind !== "person" }) }),
+    // A Notion wake is thread-first: every comment belongs to a discussion, which IS the thread.
+    type: "thread",
+    threadId: c.discussionId,
+    text,
+  };
+}
+
+/** Injected seam so the fetch drives offline in tests; defaults to the live brokered credential. */
+export interface NotionCatchUpDeps {
+  readonly readComments: typeof readNotionComments;
+  readonly resolveCredential: typeof resolveNotionCredential;
+  /** The domain roster the per-surface credential is resolved against. Injected so the fetch drives
+   *  with no config registered; the live default is the loaded roster. */
+  readonly domains?: readonly Domain[];
+  /** ONE own Notion bot id, pinning the whole self set — a TEST override, so a fetch drives with a
+   *  fixed identity and resolves nothing. Present ⇒ {@link selfActorIdFor} is never called and no
+   *  sibling integration is resolved. The live read builds the set through `collectCatchUpSelfIds`. */
+  readonly selfActorId?: string;
+  /**
+   * Resolve the deployment's own bot user id for ONE integration. The live default is the SAME
+   * per-credential resolver and cache the ingress road reads (`notion-bot-user.ts`), so the catch-up
+   * and the loop guard can never hold two answers for one integration. `collectCatchUpSelfIds` calls
+   * it once per CONFIGURED integration, so the seat recognises its own words whichever one posted
+   * them (OPE-1921).
+   *
+   * 🔴 IT IS LOAD-BEARING SINCE OPE-1857, NOT A LABEL. Notion's comment payload carries a partial
+   * `created_by` — an id and an object, no `type` — so this read cannot tell our own reply from a
+   * person's by SHAPE. Before OPE-1857 an absent `type` made every author a `bot`, which refused our
+   * own comment as a side effect of refusing everyone. Now that an unsignalled author is a person,
+   * the id comparison is the ONLY thing keeping the seat's own previous reply — which lands in the
+   * very discussion this read sweeps — out of its next wake as another person's words.
+   * 🔴 THE READING CREDENTIAL AND THE POSTING ONE CAN DIFFER, AND THAT NO LONGER LOSES THE REPLY.
+   * This read's credential comes from the page's DOMAIN BINDING, while the reply sitting in the
+   * discussion was posted under the DELIVERY's carried credential, which wins where the two differ
+   * (OPE-499, `notion-credentials.ts`). On a page served by two integrations they disagree, and the
+   * seat's own reply used to read as a person's. `collectCatchUpSelfIds` resolves BOTH, so the
+   * comparison no longer depends on which credential posted — and the delivery's credential id,
+   * which this seam once needed on `SeatCatchUpRequest` to close this, is not required after all.
+   * 🔴 AN UNRESOLVED ID DOES NOT BLIND THIS READ, and it does not have to: the INGRESS road fails
+   * CLOSED on the same id from the same cache (`classifyNotionComment` drops on "unresolved bot user
+   * id"), so a deployment that cannot resolve it dispatches no Notion wake at all and takes no
+   * catch-up. Blinding the read here as well would re-create the OPE-1857 symptom — a seat that
+   * keeps nothing — out of a transient `GET /v1/users/me` failure.
+   */
+  readonly selfActorIdFor?: (credentialId: string, credential: () => Promise<ResolvedNotionCredential | undefined>) => Promise<string | undefined>;
+}
+
+const liveDeps: NotionCatchUpDeps = {
+  readComments: readNotionComments,
+  resolveCredential: resolveNotionCredential,
+  selfActorIdFor: async (credentialId, credential) => (await resolveNotionBotUser(credentialId, credential)()).id,
+};
+
+/**
+ * EVERY configured integration's bot user id, for the same reason the ingress road takes a SET
+ * (OPE-1921): this deployment posts under one bot user id PER INTEGRATION, and a reply a SIBLING
+ * integration posted lands in the very discussion this read sweeps. Against the reading
+ * integration's id alone it matched nothing, so the seat was handed its own words as another
+ * person's — at the `unauth` floor, in the context it then answers from.
+ *
+ * 🔴 THE BLOCKER THIS FILE USED TO NAME IS GONE. It said closing this needed the DELIVERY's
+ * credential id on the shared `SeatCatchUpRequest`, which carries none. That was true only while the
+ * answer had to be ONE id: the set does not care which integration posted, so no new request field
+ * is needed. What remains is the ordinary residual — an integration whose id will not resolve.
+ *
+ * FAIL-SOFT PER INTEGRATION, and DELIBERATELY NOT fail-closed like the ingress road. An id this
+ * cannot resolve just leaves that integration's comments reading as a person's, which is where this
+ * read already stood; blinding the catch-up on a transient `GET /v1/users/me` failure would
+ * re-create the OPE-1857 symptom — a seat that keeps nothing.
+ * 🔴 AND THE INGRESS ARM DOES NOT COVER THIS ONE, SO DO NOT READ IT AS A BACKSTOP. An unresolved
+ * PRIMARY id blocks every wake, so that case really does take no catch-up. An unresolved SIBLING
+ * does not: `classifyNotionComment` step 5 drops only authors Notion does not mark `person`, so a
+ * person-marked comment still wakes a turn, still takes a catch-up, and that integration's own
+ * prior replies then enter the seat's context as a person's words at the `unauth` floor. That
+ * residual is the price of the fail-soft posture here, and it is stated rather than covered.
+ *
+ * Cost: one `GET /v1/users/me` per SIBLING integration, memoised for the process lifetime by
+ * `resolveNotionBotUser`'s per-credential cache — against the up-to-81 list calls the sweep itself
+ * makes. The sibling's CREDENTIAL is passed as a thunk, so on a cache hit it is never resolved at
+ * all; `resolveNotionCredential` has no memo of its own, and an eager resolve here would charge
+ * every wake a store read and a decrypt. A single-integration deployment resolves exactly what it
+ * did before.
+ */
+async function collectCatchUpSelfIds(
+  readingCredentialId: string,
+  readingCredential: ResolvedNotionCredential,
+  domains: readonly Domain[],
+  deps: NotionCatchUpDeps,
+): Promise<ReadonlySet<string>> {
+  const ids = new Set<string>();
+  const add = async (credentialId: string, credential: () => Promise<ResolvedNotionCredential | undefined>): Promise<void> => {
+    try {
+      const id = await deps.selfActorIdFor?.(credentialId, credential);
+      if (id) ids.add(id);
+    } catch {
+      /* an id we cannot resolve leaves that integration's comments reading as a person's */
+    }
+  };
+  await add(readingCredentialId, async () => readingCredential);
+  for (const integration of notionIntegrations(domains)) {
+    if (integration.credentialId === readingCredentialId) continue;
+    // 🔴 A THUNK, NOT A RESOLVED CREDENTIAL. `resolveNotionBotUser` memoises the bot user per
+    // credential and NEVER CALLS the thunk on a cache hit, while `resolveNotionCredential` has no
+    // memo of its own — so resolving eagerly here would charge every wake an operational-store read
+    // and a decrypt for an answer the cache already holds, and would write one
+    // credential-unresolved audit row per wake, for ever, on a sibling with no stored secret.
+    await add(integration.credentialId, () => deps.resolveCredential(integration.credentialId));
+  }
+  return ids;
+}
+
+/** The fetch, with its seams exposed so the contract test drives it with no network. */
+export async function fetchNotionCatchUpWindow(
+  req: { container: string; threadRoot?: string; threadAnchor?: string; sinceMs: number; channelKey?: string },
+  deps: NotionCatchUpDeps = liveDeps,
+): Promise<readonly NormalizedMessage[]> {
+  // The DOMAIN's own integration where this surface binds one, else the org default — the same
+  // resolution `notionReadAdapter` makes, so the catch-up reads the page over the credential the
+  // operator selected for it rather than a broader one.
+  const domains = deps.domains ?? safeDomains();
+  const credentialId = req.channelKey ? notionChannelCredentialForSurface(req.channelKey, domains) : undefined;
+  const cred = await deps.resolveCredential(credentialId);
+  if (!cred) return []; // unconfigured ⇒ nothing to read, never a guessed key
+  // OUR OWN IDENTITY, under the SAME key the ingress road caches it by: an absent `credentialId`
+  // means the ORG DEFAULT, which is stored as `NOTION_CHANNEL_CREDENTIAL` — so both roads memoise
+  // one integration under one key rather than resolving it twice. EVERY configured integration's id,
+  // for the reason the ingress road takes the set (OPE-1921) — see `selfActorIds` below.
+  const readingCredentialId = credentialId ?? NOTION_CHANNEL_CREDENTIAL;
+  const selfActorIds = deps.selfActorId !== undefined
+    ? new Set([deps.selfActorId])
+    : await collectCatchUpSelfIds(readingCredentialId, cred, domains, deps);
+  const res = await deps.readComments(req.container, {
+    // 🔴 THE ENDPOINT FENCE TRAVELS WITH THE KEY, unconditionally and ON ONE LINE: a bare `apiKey`
+    // silently disables it, and `notion-credential-fence-test.ts` §2 reads the pair line by line —
+    // so splitting them reads as a bare key to the rule that exists to stop one. An absent
+    // `endpoints` is already the unnarrowed reading, so the pair is always passed together.
+    apiKey: cred.apiKey, endpoints: cred.endpoints,
+    maxComments: CATCH_UP_MAX_COMMENTS,
+    maxBlockScans: CATCH_UP_MAX_BLOCK_SCANS,
+    // 🔴 THE WINDOW GOES TO THE SWEEP, not only to the loop below (OPE-1831). `maxComments` is
+    // charged in the order Notion serves — OLDEST FIRST — so a cap applied over the whole history
+    // fills with a page's most ancient comments and truncates before it reaches the seat's own
+    // window. Handing the bound down makes the cap count comments IN the window instead.
+    sinceMs: req.sinceMs,
+    maxCommentPages: CATCH_UP_MAX_COMMENT_PAGES,
+    // 🔴 THE BLOCK BUDGET IS SPENT ON THE PAGE'S NEWEST BLOCKS (OPE-1843). Document order spends
+    // all 80 scans on the oldest material of a page that has outgrown the cap, so a discussion on a
+    // recently appended block is never scanned and the seat reads a quiet room. A catch-up asks
+    // "what happened since I last woke", and the growth shape that crosses the cap is append-only.
+    // No effect on a page under the cap, and none on the `block` drill-in above, which scans one
+    // named block. The residual — a new comment on an ANCIENT block of an over-cap page — is
+    // `readNotionComments`'s own to state, and it does: see `blockScanOrder`.
+    blockScanOrder: "newest-first",
+    // An inline comment's authenticated parent block addresses the exact discussion anchor. The
+    // discussion id is not a block id and remains only the filter below.
+    ...(req.threadAnchor ? { block: req.threadAnchor } : {}),
+  });
+  const out: NormalizedMessage[] = [];
+  for (const c of res.comments) {
+    // The seat's own discussion, filtered HERE — see the header for why there is no endpoint that
+    // could do it. A seat bound to no discussion reads the whole page.
+    if (req.threadRoot !== undefined && c.discussionId !== req.threadRoot) continue;
+    const n = normalizeComment(c, selfActorIds);
+    if (n && n.ms >= req.sinceMs) out.push(n);
+  }
+  return out;
+}
+
+/**
+ * 🔴 NOTION FLOORS `created_time` TO THE MINUTE, and this is the number the shared catch-up road
+ * widens both of its bounds by (OPE-1847, `core/agent/channels/seat-catch-up.ts`
+ * {@link SeatCatchUpDeclaration.timestampPrecisionMs}).
+ * It is the VENDOR'S UNIT, not a margin: every comment posted inside one wall-clock minute comes back
+ * carrying that minute's opening instant. Declare it too small and a comment in the trigger's own
+ * minute is bounded out of the window it belongs to — the ship #211 red, where the seat read two
+ * comments and kept none. Declare it too large and the seat is handed comments from before its window.
+ * Measured on the live workspace (OPE-1711) and the repository's own e2e driver floors to the same
+ * unit (`core/scripts/e2e/notion-driver.ts` `notionMinuteFloor`).
+ */
+export const NOTION_TIMESTAMP_PRECISION_MS = 60_000;
+
+/** Notion's registered {@link SeatCatchUpFetch} — the one thing this surface contributes to the shared path. */
+export const notionSeatCatchUpFetch: SeatCatchUpFetch = (req) =>
+  fetchNotionCatchUpWindow({
+    container: req.container,
+    ...(req.threadRoot ? { threadRoot: req.threadRoot } : {}),
+    ...(req.threadAnchor ? { threadAnchor: req.threadAnchor } : {}),
+    sinceMs: req.sinceMs,
+    ...(req.channelKey ? { channelKey: req.channelKey } : {}),
+  });