@open-everywhere/provider-notion 0.1.0

package/agent/channels/notion-api.ts

@@ -0,0 +1,1290 @@
+// Pure Notion webhook + REST helpers — the testable core behind the Notion comment
+// surface (notion.ts). Everything here is either a pure function over a payload/string or
+// a thin REST call with an INJECTABLE `fetch` (defaults to global fetch), so the whole
+// inbound→reply loop can be unit-tested against a mock Notion API with no live calls.
+//
+// The loop this backs (see notion.ts for the wiring):
+//   webhook  → verify HMAC (verifyNotionSignature) / handle the one-time handshake
+//   comment.created is a SIGNAL ONLY (no text/mentions on the event) →
+//     retrieveComment(entity.id) → richText → mentionsUser(botUserId)?  → dispatch
+//   model reply → createCommentReply(discussionId) back into the SAME thread
+//
+// Signature scheme (Notion Docs — Webhooks): every delivery carries
+//   X-Notion-Signature: sha256=<hex>
+// which is HMAC-SHA256 of the EXACT RAW request body, keyed by the `verification_token`
+// Notion issued once at subscription time (echoed to the endpoint, then a permanent
+// signing secret). It MUST be computed over the bytes as they arrived — re-serialising the
+// parsed JSON produces different bytes and fails verification — so notion.ts reads
+// `req.text()` and hands that raw string here untouched.
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+import {
+  getSecretVia,
+  CredentialError,
+  findConnectorCredential,
+  guardCredentialFetch,
+  withRetryAfter,
+  type CredentialEndpointRules,
+  type RateLimitRetryOptions,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { NOTION_CHANNEL_CREDENTIAL, NOTION_PROVIDER } from "./notion-credentials.js";
+import type { NotionParentLink } from "./notion-ancestry-trust.js";
+
+/** Notion REST base + the API version header value (override via NOTION_VERSION). The
+ *  default is a stable version that supports the comment retrieve/create endpoints and
+ *  rich-text `mention` objects — everything this surface needs. */
+export const NOTION_API_BASE = "https://api.notion.com";
+function notionVersion(): string {
+  const v = process.env.NOTION_VERSION;
+  return v && v.trim().length > 0 ? v.trim() : "2022-06-28";
+}
+
+/**
+ * File uploads are a NEWER Notion API surface than the rest of this module. Notion's own docs
+ * (developers.notion.com/reference/create-a-file-upload, confirmed live 2026-08-23) name
+ * `2026-03-11` as the only accepted `Notion-Version` for the file-upload endpoints — the
+ * deployment's regular {@link notionVersion} (default `2022-06-28`, override via NOTION_VERSION)
+ * covers the comment/page/block surface this module already calls and does not carry file uploads.
+ * So {@link createFileUpload}, {@link sendFileUploadBytes}, and a create-comment call that attaches
+ * files all pin THIS version, rather than inheriting a caller's `opts.version` — a deployment that
+ * pins an older NOTION_VERSION for its comment traffic must not also break its attachment traffic.
+ */
+const NOTION_FILE_UPLOAD_VERSION = "2026-03-11";
+
+/**
+ * Resolve the Notion CHANNEL-PLUMBING API key through the credential BROKER, so the notion
+ * `channel-key` credential's custody stamp — its `broker` + `secretRef` (agent/access/providers.ts) —
+ * governs every host-side communication-channel REST path (reply posts, the webhook two-step,
+ * page/comment reads), not a hard-coded env pin. Looks the credential up in the registered provider
+ * set (access/providers.ts findConnectorCredential, populated at boot from the app's provider list) and
+ * resolves it via `getSecretVia(broker, secretRef)`. There is no selected default: an api-key
+ * credential always carries its mandatory `broker` stamp, and an absent broker would fail closed
+ * (caught below ⇒ undefined).
+ *
+ * CHANNEL vs WORK-SURFACE SPLIT (decision, Tommy 2026-07-21): the notion provider carries TWO api-key
+ * credentials. `channel-key` (secretRef `db:notion:channel-key`, broker `db` — OPE-408 step 2) is
+ * this communication-channel plumbing — provisioned by the operator via `oe secret set
+ * db:notion:channel-key`. It is a DISTINCT ref from `team-key` (secretRef `db:notion:team-key`), the
+ * WORK-SURFACE credential (the notion-rest egress connection). Even if an operator stores both refs
+ * with the same value, they are separate credentials with separate custody. There is NO fallback
+ * between them: if `db:notion:channel-key` has no stored value, this resolves undefined and channel
+ * Notion fails closed exactly as an unset value does today.
+ *
+ * PER-DOMAIN OVERRIDE (OPE-467). `credentialId` selects WHICH notion channel credential to resolve
+ * and defaults to the org-default `channel-key`, so every existing call site is byte-identical. A
+ * domain that binds its own Notion integration (memory/domain.ts `credentials`) passes that
+ * integration's credential id instead — see channels/notion-credentials.ts for the one rule that
+ * decides it. There is still exactly ONE resolution mechanism: whichever id arrives is looked up in
+ * the registered provider set and resolved through its own custody stamp.
+ *
+ * 🔴 A NAMED-BUT-MISSING CREDENTIAL FAILS CLOSED, and that is the point. When a bound domain's
+ * credential is absent from the provider set this returns undefined and the caller refuses, exactly
+ * as an unset secret does. It NEVER retries under the org default: a domain bound away from the org
+ * key must not be handed the org key by a fallback.
+ *
+ * Fail-closed, two ways, both returning undefined — the exact unset-env semantics every caller
+ * already branches on, NEVER a silent fallback to the work-surface key or an env pin:
+ *   • the provider/credential is UNREGISTERED or carries no `secretRef` (an instance that removed
+ *     the notion provider, or a unit test that never registered one) ⇒ unconfigured ⇒ undefined;
+ *   • the broker resolves no value (the secret is unset) ⇒ the same CredentialError-catch as before.
+ */
+/**
+ * One resolved Notion credential: the key to call with, PAIRED WITH the endpoint rules that key may
+ * be used inside (OPE-505). Spread it straight into a {@link NotionCallOpts} — `{ ...cred, fetch }` —
+ * so the fence and the key can never be threaded separately.
+ *
+ * 🔴 THERE IS DELIBERATELY NO KEY-ONLY RESOLVER. An earlier `resolveNotionApiKey` returned the bare
+ * string, and every call site that used it produced an UNFENCED request: `guardCredentialFetch`
+ * returns the base fetch by identity when it is handed no rules, so a bare key silently disables the
+ * check rather than failing. Deleting that function is what makes the fence total on this module's
+ * paths — a caller cannot obtain a Notion key without also obtaining its rules.
+ */
+export interface ResolvedNotionCredential {
+  readonly apiKey: string;
+  /** The credential's declared endpoint narrowing, or undefined when it declares none. */
+  readonly endpoints?: CredentialEndpointRules;
+}
+
+/**
+ * THE ONLY way to resolve a Notion channel credential — the key together with its endpoint rules.
+ * Fail-closed exactly as before: `undefined` for an unregistered provider, a credential carrying no
+ * `secretRef`, or a broker that resolves no value. A named-but-missing credential NEVER retries
+ * under the org default.
+ *
+ * WHY THE PAIR IS THE UNIT. A credential's endpoint rules are a property OF THAT KEY. Resolving the
+ * key through one function and the rules through another invites exactly the drift the rules exist
+ * to catch: a call site that threads the key from credential A and the rules from credential B has
+ * a fence that permits the leak it was written to block. Returning them together removes that
+ * failure mode by construction rather than by review.
+ */
+export async function resolveNotionCredential(
+  credentialId: string = NOTION_CHANNEL_CREDENTIAL,
+): Promise<ResolvedNotionCredential | undefined> {
+  const cred = findConnectorCredential(NOTION_PROVIDER, credentialId);
+  // Unregistered provider / non-secretRef credential = unconfigured — identical to the env being
+  // unset. Return undefined; do NOT fall back to a process.env / env-broker pin.
+  if (!cred?.secretRef) return undefined;
+  try {
+    const k = await getSecretVia(cred.broker, cred.secretRef);
+    return k.length > 0 ? { apiKey: k, endpoints: cred.endpoints } : undefined;
+  } catch (err) {
+    if (err instanceof CredentialError) return undefined;
+    throw err;
+  }
+}
+
+// --- webhook verification ---------------------------------------------------
+
+/**
+ * The one-time subscription handshake: when a webhook subscription is created, Notion POSTs
+ * `{ "verification_token": "secret_…" }` (and nothing else — no `type`/`event_type`) to the
+ * endpoint. Return that token so the route can LOG it (the operator pastes it back into
+ * Notion's UI to confirm the endpoint, and stores it as NOTION_WEBHOOK_SECRET — the HMAC
+ * key for every subsequent delivery). Returns null for a normal event payload.
+ */
+export function parseVerificationHandshake(rawBody: string): string | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const o = parsed as Record<string, unknown>;
+  const token = o.verification_token;
+  // Only a bare handshake (has the token, carries no event discriminator) qualifies.
+  if (typeof token === "string" && token.length > 0 && o.type === undefined && o.event_type === undefined) {
+    return token;
+  }
+  return null;
+}
+
+/**
+ * Verify a Notion webhook's HMAC-SHA256 signature (`X-Notion-Signature: sha256=<hex>`)
+ * against the verification token, over the RAW body. Constant-time compare. Mirrors
+ * routines/events.ts's verifyGithubSignature (same scheme, different header/secret).
+ */
+export function verifyNotionSignature(secret: string, rawBody: string, signatureHeader: string | null | undefined): boolean {
+  if (!signatureHeader) return false;
+  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
+  const a = Buffer.from(signatureHeader);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+/**
+ * Gate an inbound Notion delivery FAIL-CLOSED. No configured secret means the sender can't
+ * be authenticated, so the delivery is REJECTED — this route dispatches agent sessions, and
+ * accepting unsigned payloads would let anyone on the internet drive the bot. The dev escape
+ * hatch `webhooks.allowUnverifiedNotion` restores unverified acceptance for local smoke
+ * tests. Returns null when the delivery may proceed, else the one-line 401 rejection reason.
+ * (Same shape/posture as gateGithubDelivery.)
+ */
+export function gateNotionDelivery(
+  secret: string | undefined,
+  rawBody: string,
+  signatureHeader: string | null,
+  allowUnverified: boolean,
+): string | null {
+  if (!secret) {
+    return allowUnverified
+      ? null
+      : "NOTION_WEBHOOK_SECRET is not set — rejecting unverified delivery (set the verification token, or turn on webhooks.allowUnverifiedNotion in agent/settings/settings.ts for local dev)";
+  }
+  return verifyNotionSignature(secret, rawBody, signatureHeader) ? null : "invalid signature";
+}
+
+/** One integration's inbound signing key, paired with the credential that integration calls Notion
+ *  with (channels/notion-credentials.ts). `secret` is undefined when nothing is stored under that
+ *  integration's operator-secret name — an unconfigured integration, skipped by the gate. */
+export interface NotionSigningKey {
+  readonly credentialId: string;
+  readonly secret: string | undefined;
+}
+
+/** The gate's answer. `rejection` non-null ⇒ send the 401 and stop. `credentialId` names the
+ *  integration whose secret VERIFIED the delivery — the identity a signature proves. `verified` is
+ *  true only when a real signature was checked against a configured secret (never under the dev
+ *  hatch), and it is what admits a delivery into the routing plane. */
+export interface NotionGateVerdict {
+  readonly rejection: string | null;
+  readonly credentialId?: string;
+  readonly verified: boolean;
+}
+
+/**
+ * Gate an inbound delivery against EVERY configured Notion integration (OPE-467) — the
+ * multi-integration form of {@link gateNotionDelivery}, and the whole of the ingress-routing answer.
+ *
+ * An operator running ten Notion integrations has ten `verification_token`s, and a delivery from
+ * integration #7 cannot verify against integration #1's secret. So the gate tries each in turn and
+ * THE SECRET THAT VERIFIES IDENTIFIES THE SENDER. That is a proof, not an inference: nothing in the
+ * payload is consulted, so no field a caller controls can steer the routing. Trying N keys is the
+ * same shape `webhooks/secrets.ts` already uses for a rotation window, and each comparison stays
+ * constant-time (`verifyNotionSignature` → `timingSafeEqual`).
+ *
+ * Same fail-closed posture as the single-secret gate, with the same wording for the same case:
+ *   • NO integration has a stored secret ⇒ reject, unless the dev hatch is on (and then `verified`
+ *     is false, so the delivery still may not reach the routing plane);
+ *   • at least one secret configured, none verifies ⇒ "invalid signature".
+ */
+export function gateNotionDeliveryAcross(
+  keys: readonly NotionSigningKey[],
+  rawBody: string,
+  signatureHeader: string | null,
+  allowUnverified: boolean,
+): NotionGateVerdict {
+  const configured = keys.filter((k): k is NotionSigningKey & { secret: string } => typeof k.secret === "string" && k.secret.length > 0);
+  if (configured.length === 0) {
+    const rejection = gateNotionDelivery(undefined, rawBody, signatureHeader, allowUnverified);
+    return { rejection, verified: false };
+  }
+  for (const key of configured) {
+    if (verifyNotionSignature(key.secret, rawBody, signatureHeader)) {
+      return { rejection: null, credentialId: key.credentialId, verified: true };
+    }
+  }
+  return { rejection: "invalid signature", verified: false };
+}
+
+// --- webhook payload parsing ------------------------------------------------
+
+export interface NotionWebhookEvent {
+  readonly type?: string;
+  /** Some API versions name the discriminator `event_type` instead of `type`. */
+  readonly event_type?: string;
+  readonly workspace_id?: string;
+  readonly entity?: { readonly id?: string; readonly type?: string };
+  readonly data?: {
+    readonly page_id?: string;
+    readonly parent?: { readonly id?: string; readonly type?: string };
+  };
+  readonly authors?: ReadonlyArray<{ readonly id?: string; readonly type?: string }>;
+}
+
+/** The event discriminator, tolerating both the `type` and `event_type` spellings. */
+export function notionEventType(ev: NotionWebhookEvent): string | undefined {
+  return ev.type ?? ev.event_type;
+}
+
+/** The comment id a `comment.created` event points at — it lives on `entity` (a signal only;
+ *  the comment TEXT is not on the event), not on `data`. Returns undefined if the entity
+ *  isn't a comment (defensive: never dispatch off a mis-shaped event). */
+export function commentIdFromEvent(ev: NotionWebhookEvent): string | undefined {
+  const e = ev.entity;
+  if (e && e.type === "comment" && typeof e.id === "string" && e.id.length > 0) return e.id;
+  return undefined;
+}
+
+/**
+ * The page a `comment.created` event CLAIMS to be anchored on (data.page_id, else data.parent.id).
+ *
+ * 🔴 A CLAIM, NOT A FACT — nothing authenticates a webhook body's fields, and `data.parent.id` is a
+ * block id as often as a page id. It must never select a session's surface, its domain, or a
+ * credential on a VERIFIED delivery: `notion-webhook.ts` step 8 establishes the real page from the
+ * comment Notion returns under the verifying integration's own key instead (OPE-496). The one
+ * remaining caller is the `webhooks.allowUnverifiedNotion` dev hatch, where the gate identifies
+ * no integration and nothing at all has been proven.
+ */
+export function pageIdFromEvent(ev: NotionWebhookEvent): string | undefined {
+  return ev.data?.page_id ?? ev.data?.parent?.id;
+}
+
+// --- rich-text helpers (comment body) ---------------------------------------
+
+/** One rich-text item as returned inside a comment's `rich_text` array. Loosely typed —
+ *  the shapes are probed defensively (a mis-shaped item never throws). */
+export interface NotionRichText {
+  readonly type?: string;
+  readonly plain_text?: string;
+  readonly text?: { readonly content?: string };
+  readonly mention?: { readonly type?: string; readonly user?: { readonly id?: string } };
+}
+
+/** Flatten a comment's rich_text to plain text (concatenated `plain_text`). */
+export function richTextToPlainText(richText: ReadonlyArray<NotionRichText> | undefined): string {
+  if (!Array.isArray(richText)) return "";
+  return richText.map((r) => (typeof r.plain_text === "string" ? r.plain_text : "")).join("").trim();
+}
+
+/**
+ * Detect whether the comment @mentions a specific user id. A Notion @mention is a rich-text
+ * item `{ type:"mention", mention:{ type:"user", user:{ id } } }`; an @mention of an
+ * integration/agent appears as a user mention whose id is the integration's own bot-user id.
+ * So "was the bot mentioned?" = does any mention item's `mention.user.id` equal the bot's
+ * user id (resolveBotUserId). Returns false for an empty id (never dispatch on an
+ * unresolved bot identity — fail closed to "not mentioned").
+ */
+export function mentionsUser(richText: ReadonlyArray<NotionRichText> | undefined, userId: string | undefined): boolean {
+  if (!userId || !Array.isArray(richText)) return false;
+  return richText.some((r) => r.type === "mention" && r.mention?.type === "user" && r.mention.user?.id === userId);
+}
+
+// --- REST calls (injectable fetch) ------------------------------------------
+
+/** The subset of the global `fetch` this module uses — injectable so tests mock it. */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+/** The credential + transport options every Notion REST helper here takes. EXPORTED so a caller that
+ *  threads these options onward (channels/notion-webhook.ts) names this ONE shape rather than
+ *  re-declaring a structural copy that could silently drop `endpoints` and lose the fence. */
+export interface NotionCallOpts {
+  readonly apiKey: string;
+  readonly fetch?: FetchLike;
+  readonly version?: string;
+  /**
+   * The ENDPOINT RULES of the credential `apiKey` came from (OPE-505), carried alongside the key so
+   * the fence travels with it. Every REST call in this module goes out through {@link notionFetch},
+   * which refuses before dispatch when the URL is outside these rules.
+   *
+   * Absent ⇒ unnarrowed, byte-identical to the pre-OPE-505 path. Build the pair with
+   * {@link resolveNotionCredential} rather than assembling it by hand — that is what keeps the rules
+   * and the key from drifting apart, which is the one way this fence could silently stop being one.
+   */
+  readonly endpoints?: CredentialEndpointRules;
+  /**
+   * The 429 backoff policy {@link notionFetch} applies (OPE-1233). A caller that passes none takes
+   * the shared defaults from `channels/rate-limit-retry.ts`. The webhook ingress passes
+   * {@link NOTION_INGRESS_RETRY} because the shared defaults do not fit its ceiling — see there. A
+   * test injects `sleep` and `now` so a retry sequence is driven by a stub clock and waits nothing.
+   */
+  readonly retry?: Pick<RateLimitRetryOptions, "maxAttempts" | "capMs" | "fallbackMs" | "totalBudgetMs" | "sleep" | "now">;
+}
+
+/**
+ * The 429 policy for a call the WEBHOOK INGRESS awaits before it acks Notion (OPE-1254).
+ *
+ * 🔴 THE ARITHMETIC, AGAINST A MEASURED CEILING. `handleNotionDelivery` is awaited before the route
+ * acks, and it fires about 15 calls in sequence: `retrieveBotUser`, `retrieveComment`, up to five
+ * `retrieveBlock` parent hops, `listBlockComments`, and the ancestry walk's `notionParentLink`. On
+ * the shared defaults — 4 attempts, a 30 s per-wait cap, a 60 s budget PER CALL — a rate-limit
+ * episode costs that delivery up to ~15 minutes. The deployed Notion route runs on the INGRESS
+ * function, whose `maxDuration` is 300 s (measured on OPE-1289, `docs/extending/provider-rate-limits.md`
+ * § "Measured: the function maxDuration against the backoff"). So the shared policy does not make
+ * the delivery slow — it makes the function get killed mid-sequence, which is a DROPPED delivery.
+ *
+ * This policy spends at most one 2 s wait per call — `maxAttempts: 2` allows one, and the cap binds
+ * before the 4 s budget can, which is left in place for a later edit that raises the attempts. So
+ * the whole ~15-call sequence spends at most ~30 s of backoff and leaves ~270 s of the ingress
+ * ceiling for the work itself. Every one of those calls is covered: the four `deliver` issues
+ * directly, through `ingressCallOpts`, and `retrieveBotUser` behind `deps.resolveBotUserId`, which
+ * `notion.ts` passes this same policy (it is awaited FIRST, ahead of them all). It is Slack's answer to the
+ * same problem (`slack-web-api.ts`'s `PROBE_OPERATIONS`, 2 attempts / 2 s cap for the calls its
+ * 3-second ack awaits), with the total budget stated too so the arithmetic closes rather than
+ * resting on the shared 60 s.
+ *
+ * ⚠️ IT IS PER CALL, NOT PER DELIVERY. A shared budget consumed ACROSS the sequence is the stronger
+ * shape and it is a change to the shared primitive every provider inherits — still open on OPE-1254.
+ * What this bounds is the worst case, and it bounds it under the ceiling.
+ */
+export const NOTION_INGRESS_RETRY = {
+  maxAttempts: 2,
+  capMs: 2_000,
+  totalBudgetMs: 4_000,
+} as const satisfies NonNullable<NotionCallOpts["retry"]>;
+
+function notionHeaders(opts: NotionCallOpts): Record<string, string> {
+  return {
+    authorization: `Bearer ${opts.apiKey}`,
+    "notion-version": opts.version ?? notionVersion(),
+    "content-type": "application/json",
+  };
+}
+
+/**
+ * The vendor operation name a Notion request carries into {@link RateLimitExhaustedError} — the
+ * request's method plus its endpoint SHAPE, with every id segment replaced by `{id}`.
+ *
+ * 🔴 THE REDACTION IS THE POINT, not tidiness. `RateLimitExhaustedError` states that every field on
+ * it is safe to log, and this string is one of those fields. A raw Notion path carries page, block
+ * and comment ids, which name workspace content — so the shape goes in the failure and the ids stay
+ * out of it. `/v1/comments/abc…` becomes `GET /v1/comments/{id}`.
+ *
+ * The query string is dropped whole for the same reason: `?block_id=…` is an id too.
+ *
+ * Every url this is handed is built from a literal in this file, save one: {@link sendFileUploadBytes}
+ * posts to the `upload_url` Notion itself issued. A value that does not parse as a URL falls back to
+ * the method alone. Naming the method is honest; guessing a path from a string that is not a URL is
+ * not.
+ */
+export function notionOperation(method: string | undefined, url: string): string {
+  const verb = (method ?? "GET").toUpperCase();
+  let path: string;
+  try {
+    path = new URL(url).pathname;
+  } catch {
+    return verb;
+  }
+  const shape = path
+    .split("/")
+    // A Notion id is a UUID, sent with or without its dashes. Anything else — `v1`, `comments`,
+    // `me`, `children` — is a fixed segment and stays readable.
+    .map((seg) => (/^[0-9a-f]{32}$/i.test(seg.replaceAll("-", "")) ? "{id}" : seg))
+    .join("/");
+  return `${verb} ${shape}`;
+}
+
+/**
+ * THE ONE PLACE a Notion REST call leaves this host. Every helper below dispatches through here, so
+ * the credential's endpoint fence ({@link NotionCallOpts.endpoints}) is applied on every path
+ * without each call site remembering to.
+ *
+ * Funnelling matters more than the guard itself: a fence applied at six call sites is a fence a
+ * seventh call site will not have. With one funnel, a new helper is fenced the moment it is written.
+ *
+ * THE 429 BACKOFF RIDES THE SAME FUNNEL (OPE-1233). Notion answers a rate-limited call with HTTP 429
+ * and a `Retry-After` header, and nothing here read it before: the first refusal became whatever
+ * `${caller} failed: 429 …` message the helper throws, so a reply was simply lost. `withRetryAfter`
+ * now honours that delay with bounded attempts and a bounded total wait, and then throws the NAMED
+ * `RateLimitExhaustedError`. Every non-429 answer — a 2xx, a 404, a 5xx — comes back untouched, and
+ * a transport throw still propagates unretried (the request may have applied; repeating it could
+ * double a comment).
+ *
+ * ORDER MATTERS: the fence wraps the transport and the retry wraps the fence, so `guardCredentialFetch`
+ * re-checks the URL on EVERY attempt rather than once before the first.
+ *
+ * 🔴 THE BUDGET IS PER CALL, AND A PATH THAT FIRES A SEQUENCE PAYS IT ONCE EACH. The webhook ingress
+ * fires about 15 calls in sequence and now passes {@link NOTION_INGRESS_RETRY}, which bounds the
+ * whole sequence to ~30 s under that function's 300 s ceiling (OPE-1254). `readNotionComments` does
+ * NOT: it sweeps up to ~82 blocks at the shared 60 s per call, so ~82 minutes worst case, on the turn
+ * function's 800 s ceiling. That one is still open on OPE-1254.
+ * 🔴 AND `maxCommentPages` MULTIPLIES THAT NUMBER (OPE-1831). Each anchor may now cost up to that
+ * many list calls rather than one, so a caller passing 5 — the seat catch-up does — raises the same
+ * worst case about fivefold. It is a CEILING, not a cost: the follow stops the moment Notion reports
+ * no more, so every anchor under 100 comments is still exactly one call and the multiplier is paid
+ * only by an anchor that genuinely overflows. Reaching the ceiling needs all ~82 anchors to overflow
+ * at once, which no real page does.
+ * {@link NotionCallOpts.retry} is the seam a caller uses to tighten its own path.
+ * `docs/extending/provider-rate-limits.md` carries the table.
+ *
+ * A RETRY RE-SENDS `init` UNCHANGED, which is safe for every body this module builds: a JSON string,
+ * and {@link sendFileUploadBytes}'s `FormData` over a `Blob`. Both are values `fetch` re-serialises
+ * per call, not streams a first attempt would consume. A body that WAS a stream could not be replayed
+ * — do not introduce one here without giving `send` a fresh body per attempt.
+ */
+function notionFetch(url: string, init: RequestInit, opts: NotionCallOpts): Promise<Response> {
+  const base = opts.fetch ?? (globalThis.fetch as FetchLike);
+  const send = guardCredentialFetch(opts.endpoints, "notion credential", base);
+  return withRetryAfter(() => send(url, init), {
+    ...opts.retry,
+    surface: "notion",
+    operation: notionOperation(init.method, url),
+  });
+}
+
+export interface NotionComment {
+  readonly id?: string;
+  readonly discussion_id?: string;
+  readonly parent?: { readonly type?: string; readonly page_id?: string; readonly block_id?: string };
+  readonly rich_text?: ReadonlyArray<NotionRichText>;
+  // `type` is a Notion user's kind ("person" | "bot"); present on a full user object, often ABSENT
+  // on a comment's partial `created_by` (id + object only). The ambient loop guard uses it as the
+  // bot-author signal WHEN present, with the self-id + fail-closed-on-unresolved checks as the
+  // backstop when it isn't (notion-supervisor.ts classifyNotionComment; design §4.2, §6.7).
+  readonly created_by?: { readonly id?: string; readonly object?: string; readonly type?: string };
+  /** ISO-8601 creation time, when Notion supplies it — the wake message's `sent-at`. */
+  readonly created_time?: string;
+}
+
+/** GET /v1/comments/{comment_id} — the second step of the two-step (webhook signal → fetch
+ *  the actual comment body + discussion id + author). Throws on a non-2xx response. */
+export async function retrieveComment(commentId: string, opts: NotionCallOpts): Promise<NotionComment> {
+  const res = await notionFetch(`${NOTION_API_BASE}/v1/comments/${encodeURIComponent(commentId)}`, {
+    method: "GET",
+    headers: notionHeaders(opts),
+  }, opts);
+  if (!res.ok) throw new Error(`retrieveComment ${commentId} failed: ${res.status} ${await safeText(res)}`);
+  return (await res.json()) as NotionComment;
+}
+
+/** GET /v1/users/me — the integration's own bot user: its `id` (the loop-guard self-identity)
+ *  AND its `name` (the display name a person types in a name-drop — a judge input, never a
+ *  bypass; design §2.2/Step 4). Resolved once and cached by the channel; env NOTION_BOT_USER_ID /
+ *  NOTION_BOT_NAME short-circuit these — but the ID override applies to the ORG-DEFAULT `channel-key`
+ *  credential ONLY (OPE-1921: two Notion integrations never share a bot user, so one pinned id
+ *  cannot stand for a sibling's, and pinning it for every credential would reopen the
+ *  cross-integration loop). Throws on a non-2xx response. */
+export async function retrieveBotUser(opts: NotionCallOpts): Promise<{ id?: string; type?: string; name?: string }> {
+  const res = await notionFetch(`${NOTION_API_BASE}/v1/users/me`, { method: "GET", headers: notionHeaders(opts) }, opts);
+  if (!res.ok) throw new Error(`retrieveBotUser failed: ${res.status} ${await safeText(res)}`);
+  return (await res.json()) as { id?: string; type?: string; name?: string };
+}
+
+/** GET /v1/comments?block_id=… — list unresolved comments on a page/block, for surrounding
+ *  thread context (best-effort). Returns the raw results array (caller filters by
+ *  discussion + renders untrusted). Throws on a non-2xx response.
+ *
+ *  🔴 NOTION SERVES THIS ENDPOINT OLDEST-FIRST AND PAGINATED, AND ONE PAGE IS THE OLDEST 100
+ *  (OPE-1831). A single unpaginated call therefore reads the anchor's FIRST hundred comments and can
+ *  never reach a comment posted today — which is not a partial read on a long-lived anchor, it is a
+ *  read that structurally cannot answer "what was said since the seat last looked". A PAGE-ANCHORED
+ *  discussion on any long-lived doc is unreachable this way.
+ *  🔴 THIS IS NOT WHAT RED `J-ENGAGED-notion` ON SHIP #208 — do not carry that story forward. That
+ *  journey's comment sits in a BLOCK-anchored discussion, which a page query never returns however
+ *  many pages it follows; the cause there was `readNotionComments`' comment CAP ending the sweep
+ *  before the block walk began (see that function, and `notion-catch-up.ts`). This bound is a real
+ *  and separate one, closed while the file was open.
+ *
+ *  `maxPages` bounds the follow. It DEFAULTS TO 1 — the single call every existing caller already
+ *  made — so a caller that wants the newest comments asks for the pages, and no other read changes
+ *  its cost. The loop stops the moment Notion reports no more, so even at a high `maxPages` an anchor
+ *  with under 100 comments still costs exactly one call.
+ *  🔴 `onPageLimit` FIRES WHEN THE BOUND CUT THE ANCHOR OFF — Notion still had more and this stopped
+ *  asking. Without it a page-limited anchor is indistinguishable from a complete read, so
+ *  {@link readNotionComments} would report `truncated: false` over a read it knows was partial, and
+ *  the coverage disclosure the model sees would be a false claim. A callback rather than a changed
+ *  return type, so the eight existing call sites are untouched. */
+export async function listBlockComments(
+  blockId: string,
+  opts: NotionCallOpts & { readonly maxPages?: number; readonly onPageLimit?: () => void },
+): Promise<NotionComment[]> {
+  const maxPages = Math.max(1, Math.trunc(opts.maxPages ?? 1));
+  const out: NotionComment[] = [];
+  let cursor: string | undefined;
+  for (let page = 0; page < maxPages; page++) {
+    const qs = new URLSearchParams({ block_id: blockId, page_size: "100" });
+    if (cursor) qs.set("start_cursor", cursor);
+    const res = await notionFetch(`${NOTION_API_BASE}/v1/comments?${qs.toString()}`, {
+      method: "GET",
+      headers: notionHeaders(opts),
+    }, opts);
+    if (!res.ok) throw new Error(`listBlockComments ${blockId} failed: ${res.status} ${await safeText(res)}`);
+    const body = (await res.json()) as { results?: NotionComment[]; has_more?: boolean; next_cursor?: string | null };
+    if (Array.isArray(body.results)) out.push(...body.results);
+    cursor = body.has_more && body.next_cursor ? body.next_cursor : undefined;
+    if (!cursor) break;
+    // Notion has more and this was the last page the bound allows ⇒ the read is PARTIAL, and the
+    // caller is told rather than handed a short list that looks complete.
+    if (page === maxPages - 1) opts.onPageLimit?.();
+  }
+  return out;
+}
+
+// --- page comments / inline discussions read (read_notion_comments tool) --------------------
+//
+// The SIBLING of readNotionPage: read_notion_page returns the page BODY; this returns the page's
+// COMMENTS + inline discussions. Notion anchors a discussion PER BLOCK (`parent.block_id` → a
+// distinct inline discussion; page-level comments anchor on the page id itself), and there is no
+// single "all comments on a page" endpoint — comments are listed per block-id. So a full sweep is
+// two moves, both BOUNDED: (1) list the page's own comments (block_id = pageId), then (2) walk the
+// page's top-level blocks (getBlockChildren) and list each one's comments to surface inline
+// discussions. Bounded by BOTH a scanned-block cap (`maxBlockScans`) and a total-comment cap
+// (`maxComments`) so a heavily-annotated page can't fan out into unbounded API calls or blow the
+// context. `truncated` is true when either cap bit (or Notion still had more blocks). Every comment
+// body is EXTERNAL, UNTRUSTED text (commenters include workspace guests / externals) — the caller
+// (the tool's toModelOutput) MUST wrap the rendered listing through ingestUntrusted. Pure over the
+// injectable fetch (no live Notion in tests).
+
+/** One comment, flattened for the read tool. `text` is UNTRUSTED (commenter-authored); the tool
+ *  wraps it. `authorId`/`authorKind` come off the comment's partial `created_by` (id + object,
+ *  and `type` when Notion supplies it) — surfaced as DATA, never a trust signal. */
+/** The subset of a Notion block object the domain fence reads — its `parent`, i.e. which page (or
+ *  which enclosing block) owns it. */
+export interface NotionBlockParent {
+  readonly id?: string;
+  readonly parent?: { readonly type?: string; readonly page_id?: string; readonly block_id?: string };
+}
+
+/** GET /v1/blocks/{block_id} — used ONLY to answer "which page owns this block?" for the domain
+ *  fence (channels/notion-scope.ts). Throws on a non-2xx response. */
+export async function retrieveBlock(blockId: string, opts: NotionCallOpts): Promise<NotionBlockParent> {
+  const res = await notionFetch(`${NOTION_API_BASE}/v1/blocks/${encodeURIComponent(blockId)}`, { method: "GET", headers: notionHeaders(opts) }, opts);
+  if (!res.ok) throw new Error(`retrieveBlock ${blockId} failed: ${res.status} ${await safeText(res)}`);
+  return (await res.json()) as NotionBlockParent;
+}
+
+/**
+ * The PAGE that owns a block — walk `parent` upward until a `page_id`, or give up. The domain fence
+ * needs it because `readNotionComments`' `block` drill-in addresses a block DIRECTLY (it never
+ * touches the `pageId` argument), so without this a block id is an unfenced way into another
+ * domain's page. Bounded at {@link BLOCK_PARENT_MAX_HOPS} hops — the realistic case is ONE (the
+ * sweep only ever surfaces top-level blocks, whose parent IS the page) and an unbounded walk over
+ * attacker-chosen ids is its own problem.
+ *
+ * Returns `undefined` when the chain ends anywhere other than a page (a workspace/database parent),
+ * runs out of hops, or the lookup throws — every one of which the caller must treat as a REFUSAL,
+ * never as permission.
+ */
+export const BLOCK_PARENT_MAX_HOPS = 5;
+export async function resolveBlockOwningPage(blockId: string, opts: NotionCallOpts): Promise<string | undefined> {
+  let id = blockId;
+  for (let hop = 0; hop < BLOCK_PARENT_MAX_HOPS; hop++) {
+    let block: NotionBlockParent;
+    try {
+      block = await retrieveBlock(id, opts);
+    } catch {
+      return undefined; // an id the integration can't see resolves to nothing ⇒ the caller refuses
+    }
+    const parent = block.parent;
+    if (parent?.type === "page_id" && parent.page_id) return parent.page_id;
+    if (parent?.type === "block_id" && parent.block_id && parent.block_id !== id) {
+      id = parent.block_id;
+      continue;
+    }
+    return undefined;
+  }
+  return undefined;
+}
+
+/** The subset of a Notion PAGE object the ancestor walk reads — its `parent`, i.e. what owns it. */
+export interface NotionPageParent {
+  readonly parent?: {
+    readonly type?: string;
+    readonly page_id?: string;
+    readonly block_id?: string;
+    readonly database_id?: string;
+    readonly data_source_id?: string;
+    readonly workspace?: boolean;
+  };
+}
+
+/** GET /v1/pages/{page_id} — used ONLY to answer "what owns this page?" for the ancestor walk
+ *  (channels/notion-ancestry-trust.ts). Throws on a non-2xx response. */
+export async function retrievePage(pageId: string, opts: NotionCallOpts): Promise<NotionPageParent> {
+  const res = await notionFetch(`${NOTION_API_BASE}/v1/pages/${encodeURIComponent(pageId)}`, { method: "GET", headers: notionHeaders(opts) }, opts);
+  if (!res.ok) throw new Error(`retrievePage ${pageId} failed: ${res.status} ${await safeText(res)}`);
+  return (await res.json()) as NotionPageParent;
+}
+
+/**
+ * GET /v1/pages/{page_id}, read for the page's own DISPLAY IDENTITY — its title and its canonical
+ * Notion url (OPE-1714).
+ *
+ * The title is the same `properties`-by-type extraction a search hit takes ({@link notionItemTitle}),
+ * because a page's title property is named by whoever made the page and can only be found by type.
+ * The url is Notion's own `url` field, never assembled here from an id.
+ *
+ * 🔴 FAIL-SOFT, AND SEPARATE FROM THE READ IT DECORATES. A page body read must not fail because this
+ * extra call did, so every error answers an empty identity and the caller renders the page without a
+ * title or a link. Both fields are UNTRUSTED: a workspace member chooses the title.
+ */
+export async function readNotionPageIdentity(pageId: string, opts: NotionCallOpts): Promise<{ readonly title?: string; readonly url?: string }> {
+  try {
+    const res = await notionFetch(`${NOTION_API_BASE}/v1/pages/${encodeURIComponent(pageId)}`, { method: "GET", headers: notionHeaders(opts) }, opts);
+    if (!res.ok) return {};
+    const page = (await res.json()) as { url?: unknown; title?: unknown; properties?: unknown };
+    const title = notionItemTitle(page);
+    return {
+      ...(title.length > 0 ? { title } : {}),
+      ...(typeof page.url === "string" && page.url.length > 0 ? { url: page.url } : {}),
+    };
+  } catch {
+    return {};
+  }
+}
+
+/** Map a raw Notion `parent` object onto the closed union the ancestor walk decides over. An
+ *  unrecognised shape maps to `unresolvable`, never to `workspace` — "we do not know what owns this"
+ *  and "this sits at the workspace root" are different answers and only one of them ends a walk
+ *  cleanly. `data_source_id` is the 2025-09-03 spelling of a row's database parent; both map to
+ *  `database`, which is where the walk stops. */
+export function toNotionParentLink(parent: NotionPageParent["parent"]): NotionParentLink {
+  if (!parent) return { kind: "unresolvable" };
+  if (parent.type === "page_id" && parent.page_id) return { kind: "page", pageId: parent.page_id };
+  if (parent.type === "block_id" && parent.block_id) return { kind: "block", blockId: parent.block_id };
+  if (parent.type === "database_id" && parent.database_id) return { kind: "database", databaseId: parent.database_id };
+  if (parent.type === "data_source_id" && parent.data_source_id) return { kind: "database", databaseId: parent.data_source_id };
+  if (parent.type === "workspace") return { kind: "workspace" };
+  return { kind: "unresolvable" };
+}
+
+/**
+ * What owns `id` — the live `parentOf` the ancestor walk injects (channels/notion-ancestry-trust.ts).
+ *
+ * A PAGE first (`GET /v1/pages/{id}`), because the walk starts on a page id and every level above a
+ * nested page is a page too. A page id that Notion will not serve as a page falls back to the BLOCK
+ * endpoint, which is how a page nested inside a column or a toggle keeps its chain walkable. Both
+ * failing is `unresolvable`, which the walk treats as a refusal — this function NEVER throws, so a
+ * Notion outage degrades to "not trusted" instead of to an exception on the ingestion path.
+ */
+export async function notionParentLink(id: string, opts: NotionCallOpts): Promise<NotionParentLink> {
+  try {
+    return toNotionParentLink((await retrievePage(id, opts)).parent);
+  } catch {
+    // fall through to the block endpoint
+  }
+  try {
+    return toNotionParentLink((await retrieveBlock(id, opts)).parent);
+  } catch {
+    return { kind: "unresolvable" };
+  }
+}
+
+export interface NotionCommentSummary {
+  /**
+   * The comment's OWN Notion id. 🔴 LOAD-BEARING FOR THE SEAT CATCH-UP (OPE-1847): the wake route
+   * passes the trigger's comment id as `SeatCatchUpRequest.excludeId`, and removing the wake's own
+   * message from its catch-up window is done BY ID and never by time — on a surface that floors
+   * `created_time` to the minute, the trigger shares its instant with the comments the seat is
+   * reading for. Absent only when Notion served a comment without one.
+   */
+  readonly id?: string;
+  readonly discussionId?: string;
+  /** The block (or page) the discussion anchors to — distinct inline discussions differ here. */
+  readonly anchorId?: string;
+  /**
+   * The plain text of the ANCHOR BLOCK, when the sweep read the block object that carries it
+   * (OPE-988). It is what a Notion discussion is ABOUT, and the generic `read_channel` / `read_thread`
+   * render it as the discussion's topic — without it a list of discussions is a list of ids.
+   *
+   * ABSENT for a page-level comment (the anchor is the page, which has no block text) and for the
+   * `block` drill-in (which addresses a block by id and never reads the block object). Absence means
+   * "no anchor text was read", never "the block is empty".
+   */
+  readonly anchorText?: string;
+  readonly authorId?: string;
+  readonly authorKind?: string;
+  readonly createdTime?: string;
+  readonly text: string;
+}
+
+/** Flatten ONE raw comment into the read shape. Exported (OPE-988) so the read adapter's cheap
+ *  page-level path maps a `listBlockComments` result the SAME way the sweep does — two spellings of
+ *  one flatten is how an author field goes missing on one path only. */
+export function toNotionCommentSummary(c: NotionComment, fallbackAnchor: string, anchorText?: string): NotionCommentSummary {
+  return {
+    ...(c.id === undefined ? {} : { id: c.id }),
+    discussionId: c.discussion_id,
+    anchorId: c.parent?.block_id ?? c.parent?.page_id ?? fallbackAnchor,
+    ...(anchorText !== undefined && anchorText.length > 0 ? { anchorText } : {}),
+    authorId: c.created_by?.id,
+    authorKind: c.created_by?.type,
+    createdTime: c.created_time,
+    text: richTextToPlainText(c.rich_text),
+  };
+}
+
+/**
+ * Read a Notion page's comments + inline discussions, bounded. When `block` is given, reads ONLY
+ * that block's discussion (one list call — the cheap drill-in). Otherwise sweeps the page's own
+ * comments then walks its top-level blocks (≤ `maxBlockScans`, default 80) listing each block's
+ * comments, stopping once `maxComments` (default 100) is collected. `blockScanOrder` decides WHICH
+ * `maxBlockScans` blocks a page past that cap spends the budget on — the page's first by default,
+ * its last under `"newest-first"` (OPE-1843). Returns the flattened comments
+ * (oldest-first per anchor), the distinct-discussion count, the number of blocks scanned, and
+ * `truncated` (a cap bit, or Notion still had more blocks). Comment bodies are UNTRUSTED — the
+ * caller wraps them. Pure over the injectable fetch.
+ */
+export async function readNotionComments(
+  pageId: string,
+  opts: NotionCallOpts & {
+    readonly block?: string;
+    readonly maxComments?: number;
+    readonly maxBlockScans?: number;
+    /**
+     * Epoch ms of the OLDEST comment worth collecting. A comment older than this — or one Notion gave
+     * no readable `created_time` for — is skipped BEFORE the `maxComments` cap is charged.
+     * 🔴 THE ORDER OF THOSE TWO IS THE WHOLE POINT (OPE-1831). Notion serves comments OLDEST-FIRST,
+     * so a cap that counts every comment it walks past fills with the anchor's most ANCIENT ones and
+     * then reports `truncated` — the exact opposite of what a "since the seat last woke" read needs.
+     * Filtering first makes the cap count comments IN the window. Absent ⇒ no time filter, which is
+     * the whole-history read every existing caller already makes.
+     */
+    readonly sinceMs?: number;
+    /** Pages of comments to follow per anchor ({@link listBlockComments}). Default 1 — one call. */
+    readonly maxCommentPages?: number;
+    /**
+     * Which END of the page's top-level blocks the `maxBlockScans` budget is spent on (OPE-1843).
+     *
+     * `"document"` (the default, and what every caller got before this option existed) scans from
+     * the TOP of the page and stops at the cap. `"newest-first"` lists the children first, then
+     * spends the same budget on the LAST ones, newest block first.
+     *
+     * 🔴 A CATCH-UP READ WANTS THE OTHER END, AND THE DEFAULT ORDER MADE IT BLIND. Notion serves a
+     * page's children in document order and a page GROWS BY APPENDING, so on a page past
+     * `maxBlockScans` top-level blocks the budget is spent entirely on the page's oldest material
+     * and a discussion anchored on a recently appended block is never scanned. The sweep then
+     * returns zero comments with no error — the same answer a genuinely quiet page gives. That is
+     * the `J-ENGAGED-notion` shape: the journey appends a paragraph block per run and opens a
+     * BLOCK-anchored discussion on it (`core/scripts/e2e/scenarios.ts`), and a page-id comment
+     * query never returns a child block's comments, so the block walk is the only code that can
+     * find it.
+     *
+     * 🔴 IT MOVES THE BLIND SPOT, IT DOES NOT REMOVE IT, AND SAYING OTHERWISE WOULD BE A FALSE
+     * CLAIM. A comment posted TODAY on an ANCIENT block of a page past the cap is unread under
+     * `"newest-first"` and was read under `"document"`. Notion offers no "blocks with recent
+     * comments" query and a comment does not touch its block's `last_edited_time`, so no order is
+     * complete and only raising the cap would be — at one list call per block, against the shared
+     * 60 s-per-call 429 budget. `newest-first` is chosen for the CATCH-UP because the growth shape
+     * that crosses the cap at all is append-only, so the newest blocks are where the live
+     * conversation is. `truncated` still reports the read as partial either way.
+     *
+     * A page whose children fit inside `maxBlockScans` scans exactly the same blocks under both
+     * orders, so only an over-cap page pays or gains anything here.
+     */
+    readonly blockScanOrder?: "document" | "newest-first";
+    /**
+     * Pages of block children to list when `blockScanOrder` is `"newest-first"`. Default 10 — a
+     * thousand top-level blocks, because finding the LAST child means paging to the end.
+     * A page longer than this is scanned from the end of what was listed and reports `truncated`.
+     * Cheap next to the scan itself: one `getBlockChildren` call per hundred blocks against one
+     * `listBlockComments` call per SCANNED block.
+     */
+    readonly maxChildPages?: number;
+  },
+): Promise<{ readonly comments: NotionCommentSummary[]; readonly discussionCount: number; readonly blocksScanned: number; readonly truncated: boolean }> {
+  const maxComments = opts.maxComments ?? 100;
+  const maxBlockScans = opts.maxBlockScans ?? 80;
+  const comments: NotionCommentSummary[] = [];
+  const discussions = new Set<string>();
+  let truncated = false;
+  let blocksScanned = 0;
+  const listOpts = {
+    ...opts,
+    ...(opts.maxCommentPages === undefined ? {} : { maxPages: opts.maxCommentPages }),
+    // An anchor the page bound cut off makes the WHOLE read partial — `truncated` is the coverage
+    // disclosure `read_notion_comments` shows the model, and a cut-off anchor reported as complete
+    // would be a false claim about what the sweep saw.
+    onPageLimit: () => {
+      truncated = true;
+    },
+  };
+
+  /** Whether this comment is inside the caller's time window. No window ⇒ every comment is. */
+  const inWindow = (c: NotionComment): boolean => {
+    if (opts.sinceMs === undefined) return true;
+    const ms = Date.parse(c.created_time ?? "");
+    return Number.isFinite(ms) && ms >= opts.sinceMs;
+  };
+
+  const take = (raw: NotionComment[], anchor: string, anchorText?: string): boolean => {
+    // Returns true if the caller should STOP (comment cap hit).
+    for (const c of raw) {
+      if (!inWindow(c)) continue;
+      if (comments.length >= maxComments) {
+        truncated = true;
+        return true;
+      }
+      comments.push(toNotionCommentSummary(c, anchor, anchorText));
+      if (typeof c.discussion_id === "string" && c.discussion_id.length > 0) discussions.add(c.discussion_id);
+    }
+    return false;
+  };
+
+  // Drill-in: a single block's inline discussion.
+  if (opts.block) {
+    take(await listBlockComments(opts.block, listOpts), opts.block);
+    return { comments, discussionCount: discussions.size, blocksScanned: 1, truncated };
+  }
+
+  // Full sweep: page-level comments first, then per-block inline discussions.
+  if (take(await listBlockComments(pageId, listOpts), pageId)) {
+    return { comments, discussionCount: discussions.size, blocksScanned, truncated };
+  }
+
+  // NEWEST-FIRST: list the children to the end (bounded), then spend the block budget on the LAST
+  // ones. Separate from the streaming walk below on purpose — that one cannot know which block is
+  // last until it has paged past it, which is the whole reason the budget used to be spent on the
+  // page's oldest material. See `blockScanOrder`.
+  if (opts.blockScanOrder === "newest-first") {
+    const maxChildPages = opts.maxChildPages ?? 10;
+    const children: NotionBlock[] = [];
+    let childCursor: string | undefined;
+    let pagesRead = 0;
+    do {
+      const { blocks, nextCursor } = await getBlockChildren(pageId, { ...opts, startCursor: childCursor });
+      children.push(...blocks);
+      pagesRead += 1;
+      childCursor = nextCursor && pagesRead < maxChildPages ? nextCursor : undefined;
+      // More children than we listed ⇒ the "last block" we scan is not the page's last, so the read
+      // is partial however the budget is then spent.
+      if (nextCursor && childCursor === undefined) truncated = true;
+    } while (childCursor);
+    if (children.length > maxBlockScans) truncated = true;
+    const tail = children.slice(Math.max(0, children.length - maxBlockScans));
+    for (let i = tail.length - 1; i >= 0; i--) {
+      const b = tail[i]!;
+      blocksScanned += 1;
+      const id = typeof b.id === "string" ? b.id : undefined;
+      if (!id) continue;
+      if (take(await listBlockComments(id, listOpts), id, blockPlainText(b))) break;
+    }
+    return { comments, discussionCount: discussions.size, blocksScanned, truncated };
+  }
+
+  let cursor: string | undefined;
+  outer: do {
+    const { blocks, nextCursor } = await getBlockChildren(pageId, { ...opts, startCursor: cursor });
+    for (const b of blocks) {
+      if (blocksScanned >= maxBlockScans) {
+        truncated = true;
+        break outer;
+      }
+      blocksScanned += 1;
+      const id = typeof b.id === "string" ? b.id : undefined;
+      // Only blocks Notion flags as comment-bearing are worth a list call — `has_children` does NOT
+      // signal comments, so we probe every block, but cheaply: a comment-free block returns [].
+      if (!id) continue;
+      // The block's own text rides with its comments (OPE-988) — the anchor snippet the generic read
+      // verbs render as a discussion's topic. It is free here: the sweep already holds the block.
+      if (take(await listBlockComments(id, listOpts), id, blockPlainText(b))) break outer;
+    }
+    // More blocks we won't scan (cap or simply more) ⇒ partial read.
+    if (nextCursor && blocksScanned < maxBlockScans) {
+      cursor = nextCursor;
+    } else {
+      if (nextCursor) truncated = true;
+      cursor = undefined;
+    }
+  } while (cursor);
+
+  return { comments, discussionCount: discussions.size, blocksScanned, truncated };
+}
+
+// --- page body read (read_notion_page tool, ambient-surface design Step 0) -----------
+//
+// The doc BODY is read BY REFERENCE (chat-vs-ticketing-and-tool-uniformity.md rec #3): it is
+// NEVER inlined into the wake (one big doc would blow the whole backscroll budget — the
+// CEIL_BYTES lesson). The agent PULLS it with read_notion_page only when a reply needs the doc's
+// prose. These helpers are the pure, injectable-fetch core behind that tool: a paginated
+// block-children fetch + a rich-text flatten, bounded by a block count + a total-char cap.
+
+/** One block as returned by GET /v1/blocks/{id}/children. Loosely typed — the per-type
+ *  `rich_text` array is probed defensively (a mis-shaped block never throws). */
+export interface NotionBlock {
+  readonly id?: string;
+  readonly type?: string;
+  readonly has_children?: boolean;
+  // Each block type nests its content under a key equal to its `type` (paragraph, heading_1, …);
+  // most text-bearing types carry a `rich_text` array there. Indexed access, probed by type.
+  readonly [key: string]: unknown;
+}
+
+/** Flatten ONE block to plain text: read the `rich_text` array nested under the block's own type
+ *  key (`block[block.type].rich_text`) — the shape every text-bearing Notion block uses — and
+ *  concatenate its `plain_text`. Returns "" for a block with no readable text (a divider, image,
+ *  etc.), so a page of only such blocks flattens to empty rather than throwing. */
+export function blockPlainText(block: NotionBlock): string {
+  const t = typeof block.type === "string" ? block.type : undefined;
+  if (!t) return "";
+  const inner = block[t];
+  if (!inner || typeof inner !== "object") return "";
+  const rich = (inner as { rich_text?: unknown }).rich_text;
+  return richTextToPlainText(Array.isArray(rich) ? (rich as NotionRichText[]) : undefined);
+}
+
+/** GET /v1/blocks/{block_id}/children — one page of a block's children (top-level only; nested
+ *  children are NOT recursed here — the tool reads the doc's own top-level blocks, which is what
+ *  a comment usually anchors to). Returns the results array + the next cursor (undefined when
+ *  there are no more). Throws on a non-2xx response. */
+export async function getBlockChildren(
+  blockId: string,
+  opts: NotionCallOpts & { readonly startCursor?: string; readonly pageSize?: number },
+): Promise<{ readonly blocks: NotionBlock[]; readonly nextCursor?: string }> {
+  const qs = new URLSearchParams({ page_size: String(opts.pageSize ?? 100) });
+  if (opts.startCursor) qs.set("start_cursor", opts.startCursor);
+  const res = await notionFetch(`${NOTION_API_BASE}/v1/blocks/${encodeURIComponent(blockId)}/children?${qs.toString()}`, {
+    method: "GET",
+    headers: notionHeaders(opts),
+  }, opts);
+  if (!res.ok) throw new Error(`getBlockChildren ${blockId} failed: ${res.status} ${await safeText(res)}`);
+  const body = (await res.json()) as { results?: NotionBlock[]; has_more?: boolean; next_cursor?: string | null };
+  return {
+    blocks: Array.isArray(body.results) ? body.results : [],
+    nextCursor: body.has_more && body.next_cursor ? body.next_cursor : undefined,
+  };
+}
+
+/** Read a Notion page's top-level text, paginating block-children and flattening each block's
+ *  rich-text, bounded by BOTH a block count (`maxBlocks`, default 200) and a total-char cap
+ *  (`maxChars`, default 20,000 — well under the wake backscroll budget so the model can hold it).
+ *  `truncated` is true when either cap was hit or Notion still had more blocks — so the agent
+ *  knows the read is partial. Pure over the injectable fetch (no live Notion in tests). */
+export async function readNotionPage(
+  pageId: string,
+  opts: NotionCallOpts & { readonly maxBlocks?: number; readonly maxChars?: number },
+): Promise<{ readonly text: string; readonly blockCount: number; readonly truncated: boolean }> {
+  const maxBlocks = opts.maxBlocks ?? 200;
+  const maxChars = opts.maxChars ?? 20_000;
+  const lines: string[] = [];
+  let chars = 0;
+  let blockCount = 0;
+  let truncated = false;
+  let cursor: string | undefined;
+  do {
+    const { blocks, nextCursor } = await getBlockChildren(pageId, { ...opts, startCursor: cursor });
+    let stop = false;
+    for (const b of blocks) {
+      if (blockCount >= maxBlocks) {
+        truncated = true;
+        stop = true;
+        break;
+      }
+      blockCount += 1;
+      const text = blockPlainText(b);
+      if (!text) continue;
+      if (chars + text.length > maxChars && lines.length > 0) {
+        truncated = true;
+        stop = true;
+        break;
+      }
+      chars += text.length;
+      lines.push(text);
+    }
+    // A remaining page we won't read (either we stopped on a cap, or there simply is more) means
+    // the read is partial — mark truncated and stop paginating.
+    if (stop) {
+      cursor = undefined;
+    } else if (nextCursor) {
+      cursor = nextCursor;
+    } else {
+      cursor = undefined;
+    }
+  } while (cursor);
+  return { text: lines.join("\n"), blockCount, truncated };
+}
+
+/**
+ * Notion's own per-comment attachment cap (developers.notion.com/reference/create-a-comment,
+ * confirmed live 2026-08-23: "attachments — Array of file objects — Maximum entries: 3"). Exported
+ * so {@link notionMessageOps.postFiles} (notion-message-ops.ts) can refuse a too-large batch BEFORE
+ * uploading a single byte, rather than uploading four files and discarding the fourth's upload.
+ */
+export const NOTION_MAX_ATTACHMENTS = 3;
+
+/** Build the `attachments` field of a create-comment body from completed `file_upload` ids, or `{}`
+ *  when there are none (so a spread `...attachmentsBody(...)` never adds an empty array to a plain
+ *  text comment). Throws over the cap — the same fail-loud posture as `MAX_FILE_BYTES` in
+ *  `post_file.ts`: a caller that hands too many ids gets a clear reason, never a silently truncated
+ *  batch or a 400 from Notion with no context. */
+function attachmentsBody(fileUploadIds: readonly string[] | undefined): { attachments: Array<{ file_upload_id: string; type: "file_upload" }> } | Record<string, never> {
+  if (!fileUploadIds || fileUploadIds.length === 0) return {};
+  if (fileUploadIds.length > NOTION_MAX_ATTACHMENTS) {
+    throw new Error(`Notion comments accept at most ${NOTION_MAX_ATTACHMENTS} attachments; got ${fileUploadIds.length}.`);
+  }
+  return { attachments: fileUploadIds.map((id) => ({ file_upload_id: id, type: "file_upload" as const })) };
+}
+
+/** POST /v1/comments — reply into the SAME discussion thread. Notion caps a single rich-text
+ *  item at 2000 chars, so the reply is chunked across items (≤100). Throws on non-2xx. Returns
+ *  the created comment's id (Notion echoes the comment object) so the mid-turn `reply` tool can
+ *  hand it back — empty string if the response carries none. Notion DOES expose an update verb
+ *  now (`PATCH /v1/comments/{id}`, {@link updateComment}) — the reply tool itself does not wire to
+ *  it (that is `edit_reply`'s seam, `channels/post-arms.ts`'s `editMessage`, a separate decision
+ *  with its own scope). `attachments`, when given, names completed `file_upload` ids
+ *  ({@link uploadNotionFile}) — see {@link attachmentsBody} for the cap. */
+export async function createCommentReply(
+  args: { discussionId: string; text: string; attachments?: readonly string[] } & NotionCallOpts,
+): Promise<string> {
+  const attach = attachmentsBody(args.attachments);
+  const res = await notionFetch(`${NOTION_API_BASE}/v1/comments`, {
+    method: "POST",
+    headers: notionHeaders(Object.keys(attach).length > 0 ? { ...args, version: NOTION_FILE_UPLOAD_VERSION } : args),
+    body: JSON.stringify({ discussion_id: args.discussionId, rich_text: richTextChunks(args.text), ...attach }),
+  }, args);
+  if (!res.ok) {
+    // The numeric HTTP status rides on the error (OPE-825), so the reply/unified post spines can
+    // classify a failed post here the same way they already do for Slack/Discord/Teams
+    // (channels/platform-failure.ts) — a number only, never the response body or a token.
+    throw Object.assign(new Error(`createCommentReply failed: ${res.status} ${await safeText(res)}`), { status: res.status });
+  }
+  const body = (await res.json().catch(() => ({}))) as { id?: unknown };
+  return typeof body.id === "string" ? body.id : "";
+}
+
+/** POST /v1/comments — start a FRESH top-level comment (a new discussion) on a PAGE, rather than
+ *  replying into an existing one. This is what {@link routeNotionStopComment}'s acknowledgement and
+ *  every other host-driven, no-discussion-in-hand notice (`notion-message-ops.ts`'s `postText`/
+ *  `postFiles`) use: they are handed a PAGE address, never a discussion id. Same chunking/error
+ *  shape and `attachments` handling as {@link createCommentReply}. */
+export async function createPageComment(
+  args: { pageId: string; text: string; attachments?: readonly string[] } & NotionCallOpts,
+): Promise<string> {
+  const attach = attachmentsBody(args.attachments);
+  const res = await notionFetch(`${NOTION_API_BASE}/v1/comments`, {
+    method: "POST",
+    headers: notionHeaders(Object.keys(attach).length > 0 ? { ...args, version: NOTION_FILE_UPLOAD_VERSION } : args),
+    body: JSON.stringify({ parent: { page_id: args.pageId }, rich_text: richTextChunks(args.text), ...attach }),
+  }, args);
+  if (!res.ok) {
+    throw Object.assign(new Error(`createPageComment failed: ${res.status} ${await safeText(res)}`), { status: res.status });
+  }
+  const body = (await res.json().catch(() => ({}))) as { id?: unknown };
+  return typeof body.id === "string" ? body.id : "";
+}
+
+/** PATCH /v1/comments/{comment_id} — rewrite a comment THIS integration created, in place
+ *  (developers.notion.com/reference/update-a-comment, confirmed live 2026-08-23: the endpoint takes
+ *  exactly one of `rich_text`/`markdown`, and 404s on a comment the calling connection did not
+ *  create). Chunked the same way `richTextChunks` chunks a create. Throws on non-2xx, carrying the
+ *  numeric status the same way every other write in this module does. */
+export async function updateComment(
+  args: { commentId: string; text: string } & NotionCallOpts,
+): Promise<void> {
+  const res = await notionFetch(`${NOTION_API_BASE}/v1/comments/${encodeURIComponent(args.commentId)}`, {
+    method: "PATCH",
+    headers: notionHeaders(args),
+    body: JSON.stringify({ rich_text: richTextChunks(args.text) }),
+  }, args);
+  if (!res.ok) {
+    throw Object.assign(new Error(`updateComment ${args.commentId} failed: ${res.status} ${await safeText(res)}`), { status: res.status });
+  }
+}
+
+// --- file uploads (OPE-1047 — the transport a comment's `attachments` field needs) ---------
+//
+// Notion's attach-a-file-to-a-comment flow is TWO REST calls, not one (developers.notion.com/
+// reference/create-a-file-upload + .../send-file-upload, both confirmed live 2026-08-23):
+//   1. createFileUpload  — reserve an upload slot, get back an `id` + `upload_url`
+//   2. sendFileUploadBytes — POST the bytes to that `upload_url` as multipart/form-data
+// Only once step 2 succeeds does the object reach `status: "uploaded"`, the state a comment's
+// `attachments[].file_upload_id` may reference (attachmentsBody, above createCommentReply). Both
+// calls are size-bounded to Notion's SINGLE-PART limit (20 MB) — this module never attempts the
+// multi-part flow Notion also documents for larger files, matching post_file.ts's own 10 MB
+// per-file ceiling (well under 20 MB, so no caller of uploadNotionFile can exceed it).
+
+/** One Notion file-upload object, as `POST /v1/file_uploads` (step 1) and `.../send` (step 2)
+ *  return it. Loosely typed — only the fields this module reads. */
+interface NotionFileUploadObject {
+  readonly id?: string;
+  readonly upload_url?: string;
+  readonly status?: string;
+}
+
+/**
+ * POST /v1/file_uploads — step 1: reserve an upload slot for one small (≤20 MB, single-part) file.
+ * Returns the object's `id` (what a comment's `attachments` entry references, once uploaded) and the
+ * `upload_url` step 2 posts bytes to (the SAME host, `api.notion.com`, so it rides the credential
+ * fence like every other call here). Throws on non-2xx, or a response missing either field —
+ * never invents one.
+ */
+export async function createFileUpload(
+  args: { readonly filename: string; readonly contentType: string } & NotionCallOpts,
+): Promise<{ readonly id: string; readonly uploadUrl: string }> {
+  const res = await notionFetch(`${NOTION_API_BASE}/v1/file_uploads`, {
+    method: "POST",
+    headers: notionHeaders({ ...args, version: NOTION_FILE_UPLOAD_VERSION }),
+    body: JSON.stringify({ filename: args.filename, content_type: args.contentType }),
+  }, args);
+  if (!res.ok) throw new Error(`createFileUpload failed: ${res.status} ${await safeText(res)}`);
+  const body = (await res.json().catch(() => ({}))) as NotionFileUploadObject;
+  if (typeof body.id !== "string" || body.id.length === 0 || typeof body.upload_url !== "string" || body.upload_url.length === 0) {
+    throw new Error("createFileUpload: Notion response carried no usable id/upload_url.");
+  }
+  return { id: body.id, uploadUrl: body.upload_url };
+}
+
+/**
+ * POST {uploadUrl} — step 2: send the file's bytes as `multipart/form-data`, field name `file`
+ * (the shape Notion's send-file-upload endpoint requires). No explicit content-type header — like
+ * Discord's `postFiles` (discord-message-ops.ts), `fetch` derives the multipart boundary from the
+ * FormData body itself; setting one by hand would omit the boundary and the upload would 400.
+ * Throws on non-2xx.
+ */
+export async function sendFileUploadBytes(
+  args: { readonly uploadUrl: string; readonly filename: string; readonly contentType: string; readonly bytes: Uint8Array } & NotionCallOpts,
+): Promise<void> {
+  const form = new FormData();
+  // A fresh ArrayBuffer copy so the Blob owns contiguous bytes regardless of the source view
+  // (mirrors discord-message-ops.ts's postFiles — the same reason: a Uint8Array over a larger
+  // backing buffer must not leak neighbouring bytes into the multipart body).
+  const ab = args.bytes.buffer.slice(args.bytes.byteOffset, args.bytes.byteOffset + args.bytes.byteLength) as ArrayBuffer;
+  form.append("file", new Blob([ab], { type: args.contentType }), args.filename);
+  const res = await notionFetch(args.uploadUrl, {
+    method: "POST",
+    headers: { authorization: `Bearer ${args.apiKey}`, "notion-version": NOTION_FILE_UPLOAD_VERSION },
+    body: form,
+  }, args);
+  if (!res.ok) throw new Error(`sendFileUploadBytes failed: ${res.status} ${await safeText(res)}`);
+}
+
+/**
+ * The whole two-step upload (create + send), returning the `file_upload` id — ready to attach to a
+ * comment via {@link createCommentReply}/{@link createPageComment}'s `attachments` argument. ONE
+ * call so a caller (notion-message-ops.ts's `postFiles`) never has to remember the two-step order
+ * or thread the intermediate `upload_url` itself.
+ */
+export async function uploadNotionFile(
+  args: { readonly filename: string; readonly contentType: string; readonly bytes: Uint8Array } & NotionCallOpts,
+): Promise<string> {
+  const { id, uploadUrl } = await createFileUpload(args);
+  await sendFileUploadBytes({ ...args, uploadUrl });
+  return id;
+}
+
+/** Split reply text into Notion rich-text items, each ≤2000 chars (Notion's per-item cap),
+ *  up to 100 items (Notion's per-comment cap). Exported for the test. */
+export function richTextChunks(text: string): Array<{ type: "text"; text: { content: string } }> {
+  const MAX_ITEM = 2000;
+  const MAX_ITEMS = 100;
+  const body = text.length > 0 ? text : "(no content)";
+  const chunks: Array<{ type: "text"; text: { content: string } }> = [];
+  for (let i = 0; i < body.length && chunks.length < MAX_ITEMS; i += MAX_ITEM) {
+    chunks.push({ type: "text", text: { content: body.slice(i, i + MAX_ITEM) } });
+  }
+  return chunks;
+}
+
+
+/** One hit from {@link searchNotion} — ids and a title, never page CONTENT. */
+export interface NotionSearchHit {
+  readonly id: string;
+  /** "page" | "database", as Notion reports it. */
+  readonly object: string;
+  /** The item's title in plain text, or "" when Notion returns none (an untitled page). */
+  readonly title: string;
+  /** Notion's own URL for the item, when it returns one. */
+  readonly url?: string;
+}
+
+/**
+ * Search the workspace the credential is shared into (`POST /v1/search`), the WORK-plane read
+ * (OPE-913).
+ *
+ * 🔴 THE CREDENTIAL IS THE BOUNDARY, AND OE ADDS NO SECOND ONE. Tommy ruled this on 2026-08-21:
+ * "scope can only be controlled at the CREDENTIAL level; the vendor exposes one search tool and we
+ * just use it. OE never filters search results as a boundary (a post-hoc filter is not
+ * enforcement)." Notion enforces it properly — an internal integration sees only the page trees a
+ * human shared with it — so a domain that wants a narrow search shares a narrow integration. Do NOT
+ * add a domain filter over these results: it would read as a boundary while being none.
+ *
+ * Returns ids + titles only. A caller that wants a body reads the page through the fenced page read.
+ */
+export async function searchNotion(
+  query: string,
+  opts: NotionCallOpts & { readonly pageSize?: number; readonly filter?: "page" | "database" },
+): Promise<readonly NotionSearchHit[]> {
+  const body: Record<string, unknown> = { page_size: Math.min(Math.max(opts.pageSize ?? 10, 1), 100) };
+  if (query.length > 0) body.query = query;
+  if (opts.filter) body.filter = { property: "object", value: opts.filter };
+  const res = await notionFetch(`${NOTION_API_BASE}/v1/search`, {
+    method: "POST",
+    headers: notionHeaders(opts),
+    body: JSON.stringify(body),
+  }, opts);
+  if (!res.ok) throw new Error(`notion search failed: ${res.status} ${await safeText(res)}`);
+  const parsed = (await res.json()) as { results?: unknown };
+  const results = Array.isArray(parsed.results) ? parsed.results : [];
+  const hits: NotionSearchHit[] = [];
+  for (const raw of results) {
+    const item = raw as { id?: unknown; object?: unknown; url?: unknown; title?: unknown; properties?: unknown };
+    if (typeof item.id !== "string" || item.id.length === 0) continue;
+    hits.push({
+      id: item.id,
+      object: typeof item.object === "string" ? item.object : "unknown",
+      title: notionItemTitle(item),
+      ...(typeof item.url === "string" ? { url: item.url } : {}),
+    });
+  }
+  return hits;
+}
+
+/** The plain-text title of a search hit. A DATABASE carries `title` directly; a PAGE carries it
+ *  under whichever `properties` entry has `type: "title"` (the name of that property is the user's
+ *  choice, so it must be found by type, never by a guessed key like "Name"). */
+function notionItemTitle(item: { readonly title?: unknown; readonly properties?: unknown }): string {
+  if (Array.isArray(item.title)) return richTextToPlainText(item.title as NotionRichText[]);
+  const props = item.properties as Record<string, { type?: unknown; title?: unknown }> | undefined;
+  for (const value of Object.values(props ?? {})) {
+    if (value?.type === "title" && Array.isArray(value.title)) return richTextToPlainText(value.title as NotionRichText[]);
+  }
+  return "";
+}
+
+async function safeText(res: Response): Promise<string> {
+  try {
+    return (await res.text()).slice(0, 300);
+  } catch {
+    return "";
+  }
+}