@open-everywhere/provider-notion 0.1.0

package/agent/channels/notion-webhook.ts

@@ -0,0 +1,963 @@
+// The eve-FREE orchestration core behind the Notion comment surface — the full
+// webhook→verify→fetch→classify→dispatch decision, factored out of the channel wiring
+// (notion.ts) so it's unit-testable with a mock fetch + a mock dispatch (no eve boot, no
+// live Notion). Same split the GitHub path uses (routines/events.ts is the tested core;
+// channels/github.ts is the thin route) and the generic webhook path (webhooks/gate.ts +
+// webhooks/dispatch.ts under channels/webhooks.ts).
+//
+// AMBIENT-JUDGED SURFACE (notion-ambient-surface-design.md). The agent is ambiently present on
+// any doc it's connected to: it reads EVERY comment.created and a standing per-doc SUPERVISOR
+// session intelligently decides whether to engage — exactly like OE's Slack ambient supervisor,
+// reusing renderWake's channel-watch judge WHOLESALE. This REPLACES the old mention-gate (Notion
+// doesn't let a user @mention an internal integration, so that gate was structurally dead). The
+// comment.created webhook is still a SIGNAL ONLY (carries the id, not the text) — so this
+// orchestrator does the two-step (retrieve the comment), then classifies (self/bot/@mention/
+// ambient) and dispatches to the supervisor. The whole ambient path is fail-closed OFF behind the
+// per-domain ambientSupervisor flag (opt-in is DOMAIN-level).
+//
+// LOOP GUARD (hardened, design §4.2) — TWO HALVES, AND NEITHER ONE IS THE GUARD ON ITS OWN.
+//   • WHOSE WORDS (step 8e, classifyNotionComment): the agent reads its OWN posted replies, because
+//     each createCommentReply fires a fresh comment.created. OUR OWN reply is recognised by ID and
+//     by nothing else — `created_by.id` against EVERY configured integration's bot user id
+//     (OPE-1921, step 7 builds the set from `signingKeys`) — and the guard fails closed on every
+//     unreadable identity: the verifying integration's own id UNRESOLVED, an author with no
+//     `created_by.id`, and a SIBLING integration whose id did not resolve.
+//     🔴 THE SET IS WHAT MAKES THIS A DEPLOYMENT GUARD. Two integrations can both see one page, so
+//     a reply A posted arrives on B's subscription. Against B's id alone it matched nothing, read
+//     as a person and woke a turn — and A's subscription then saw B's answer. Every reply is a new
+//     comment id, so the once-guard below cannot bound that loop.
+//     🔴 A FOREIGN bot is still the weaker case: the only signal is `created_by.type`, which Notion
+//     omits on a comment (OPE-1857), so a bot belonging to SOMEONE ELSE reads here as a person.
+//     Read the classifier's own step list — it does not claim otherwise.
+//   • HOW MANY TIMES (step 12, firstNotionDispatchOfComment): one comment id wakes ONE turn inside
+//     the dedupe window. A redelivery of a PERSON's comment is invisible to the classifier — same
+//     author, same text — so without this half a vendor retry, or a page two subscriptions both
+//     deliver, buys a second turn and a second reply (ship #216: three dispatches, one comment).
+//
+// THE SURFACE COMES FROM THE FETCH, NOT THE PAYLOAD (OPE-496): the session's page — and therefore
+// its domain, its read credential and the pages the read fence admits — is established from the
+// comment Notion returned under the VERIFIED credential, never from `data.page_id`. A delivery whose
+// page cannot be established that way is acked and dropped. Step 8 carries the reasoning.
+//
+// AND THE WORKSPACE IS FENCED, NOT PROVED (OPE-502): `ev.workspace_id` stays a payload field, because
+// Notion returns no workspace id on any object and no fetch can confirm it. The surface key composes
+// it with the page, so a forged workspace alone could move the session onto a domain that CLAIMS that
+// workspace. Step 8b refuses a delivery whose page reaches such a domain unless the SIGNING
+// integration serves it — the same move OPE-500 made on the trigger plane.
+//
+// AND THE PARTITION USES CONFIG'S WORD (OPE-536, completed by OPE-254): 8b's fence closes the
+// domain boundary but leaves the SESSION PARTITION on the payload's workspace. Step 8c swaps in the
+// workspace segment of the `reach` entry that MATCHED, so a stale or forged workspace beside a page
+// config knows can no longer open a second partition beside the honest one. Read step 8c for what
+// that does and does not cover on each leg — in particular, a workspace no domain reaches at all
+// still composes its own key, which belongs to no domain and therefore opens nothing.
+//
+// AND THE PAGE'S TRUST IS WALKED, NOT ASSUMED (OPE-492): a page under an operator-declared TRUST
+// ROOT binds `internal`. Step 10b resolves that ONCE per delivery, under the same verified
+// credential, and stamps the matched root on the auth. It can only PROMOTE — no root, no stamp, and
+// the binding keeps the fail-closed `external` it had before. A deployment that declares no root
+// spends no API call on it.
+//
+// UNTRUSTED WRAP: the surrounding discussion comments are written by arbitrary workspace members,
+// so they render INSIDE the wake envelope's untrusted wrap (renderWakeEnvelope), oldest-first, as
+// backscroll siblings ending at the triggering comment — the SAME untrusted-wrapping every surface
+// applies. The triggering comment is the trigger message; on a `direct` (@mention) it's the
+// conversation driver, unwrapped, exactly like an addressed turn on every surface.
+
+import {
+  gateNotionDeliveryAcross,
+  parseVerificationHandshake,
+  notionEventType,
+  commentIdFromEvent,
+  pageIdFromEvent,
+  retrieveComment,
+  listBlockComments,
+  resolveBlockOwningPage,
+  richTextToPlainText,
+  notionParentLink,
+  NOTION_INGRESS_RETRY,
+  type FetchLike,
+  type NotionWebhookEvent,
+  type NotionComment,
+  type NotionSigningKey,
+  type NotionCallOpts,
+  type ResolvedNotionCredential,
+} from "./notion-api.js";
+import { buildNotionAuth, notionSurfaceKey } from "./notion-identity.js";
+import { resolveNotionDeliveryTrust, type NotionTrustRoots } from "./notion-ancestry-trust.js";
+import { notionDeliveryScopeVerdict } from "./notion-credentials.js";
+import { collectNotionOwnBotIds, type NotionOwnBotIds } from "./notion-bot-user.js";
+import { notionPageDomain, notionReachWorkspace } from "./notion-scope.js";
+import { classifyNotionComment, type NotionUntieredSupervisorDispatch, type NotionUntieredWakeMessage } from "./notion-supervisor.js";
+import { notionCommentIsStopDirective, routeNotionStopComment } from "./notion-stop.js";
+import { firstNotionDispatchOfComment, resolveNotionEngagement, type NotionEngagementDeps, type NotionSeamFacts } from "./notion-engagement.js";
+import type { NotionWebhookTimingRecorder } from "./notion-webhook-timing.js";
+import type { NotionCommentDispatchGuard } from "./notion-ingress-drain.js";
+import { OE_ADDRESSED_ATTR, OE_BOT_NAME_ATTR, type AttachSessionForCancel, type Domain } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The per-TURN reply target the channel snapshots at `turn.started` (see notion.ts). */
+export interface NotionReplyTarget {
+  readonly discussionId: string;
+  readonly pageId?: string;
+  readonly workspaceId?: string;
+  /** The Notion integration THIS delivery verified under (OPE-467) — snapshotted with the rest of
+   *  the target so the terminal reply posts under the credential that fetched the comment. Absent
+   *  on a turn whose auth predates the stamp ⇒ the post falls back to the page's domain binding. */
+  readonly credentialId?: string;
+}
+
+/** The per-session state the channel stashes so `message.completed` can post the reply into
+ *  the SAME discussion thread (see notion.ts's context factory). */
+export interface NotionSessionState {
+  readonly discussionId: string | null;
+  readonly pageId: string | null;
+  readonly workspaceId: string | null;
+  /**
+   * The PER-TURN reply target, snapshotted at `turn.started` from the delivery's auth
+   * attributes — NOT the seeded fields above. eve applies a `send({ state })` seed only when
+   * it CREATES a session; a resumed (standing supervisor) session keeps its original state, so
+   * the seeded `discussionId` goes stale after the first wake and every later reply would land
+   * in the FIRST discussion. eve rewrites `session.auth.current` from the delivery's auth on
+   * every delivery, so the auth attributes ARE this turn's real trigger — the same snapshot
+   * pattern slack.ts's supervisor turn.started uses (T1.4). Mutable by design (assigned per
+   * turn); `undefined` = no resolvable target, and message.completed FAILS SAFE (posts nothing).
+   */
+  oeReplyTarget?: NotionReplyTarget;
+  /**
+   * True iff this session was CREATED as a UNIFIED (org, domain) supervisor session
+   * (notion-supervisor.ts seeds it; eve applies the seed at creation only, and a session's grain
+   * is fixed for its lifetime — the token shape can't change mid-generation). notion.ts's
+   * message.completed keys the message-tool-only silence gate on it — Notion has a WORKING
+   * `reply` tool on supervisor turns, so a unified turn's terminal prose is DROPPED (never
+   * posted) and a stray leak is audited. Absent/false on every per-doc session ⇒ the gate never
+   * fires ⇒ byte-identical flag-off behaviour.
+   */
+  readonly oeUnified?: boolean;
+}
+
+export interface HandleNotionDeliveryDeps {
+  /**
+   * EVERY configured Notion integration's inbound signing key, org default first
+   * (channels/notion-credentials.ts notionIntegrations). The gate tries each in turn and the one
+   * that verifies IDENTIFIES the sending integration — see gateNotionDeliveryAcross. A single-
+   * integration deployment passes a one-entry list and behaves exactly as it did before OPE-467.
+   */
+  readonly signingKeys: readonly NotionSigningKey[];
+  /** The `webhooks.allowUnverifiedNotion` setting — dev escape hatch only. */
+  readonly allowUnverified: boolean;
+  /** Resolve one Notion channel credential to its integration token AND that credential's endpoint
+   *  rules (resolveNotionCredential). Called with the credential id the VERIFYING integration named
+   *  (else {@link credentialForPage}), so a delivery's REST calls run under the integration that
+   *  actually sent it. Undefined ⇒ unconfigured, and the delivery is acked without a dispatch (never
+   *  a retry storm over a config bug).
+   *
+   *  🔴 The PAIR, never the bare key (OPE-505). Every REST call in this file spreads the result, so
+   *  the credential's endpoint fence rides along; handing on only the token would return an unfenced
+   *  fetch and silently disable the check on the whole webhook two-step. */
+  readonly credentialFor: (credentialId: string) => Promise<ResolvedNotionCredential | undefined>;
+  /** The credential the PAGE'S DOMAIN binds, or undefined when it binds none — see
+   *  channels/notion-credentials.ts. It decides the credential for READS and REPLIES the agent
+   *  initiates. On an INBOUND delivery it is only the fallback: the HMAC has already proven which
+   *  integration sent this body, and a page id read off an unauthenticated payload never overrides
+   *  a proof (step 5). */
+  readonly credentialForPage: (workspaceId: string | undefined, pageId: string | undefined) => string | undefined;
+  /**
+   * The domain registry, passed as DATA rather than as a resolved verdict (OPE-502).
+   *
+   * 🔴 THE FENCE ITSELF STAYS INSIDE THIS CORE ON PURPOSE. Step 8b's decision is a security
+   * boundary, so it must not be a closure a caller supplies — a caller that passed a permissive one,
+   * or forgot the field, would reopen the whole vector with nothing to notice it. `domains` is inert
+   * config, so the only thing a caller can get wrong is passing an EMPTY list, and an empty list
+   * fences nothing because it owns nothing. Required, never optional, for the same reason.
+   *
+   * The route hands it `getConfig().loadDomains()`, fail-soft to `[]` — the same value it already
+   * closes over for {@link credentialForPage} and {@link ambientEnabled}.
+   */
+  readonly domains: readonly Domain[];
+  /**
+   * The operator's declared Notion TRUST ROOTS, prepared (OPE-492) — the route passes
+   * `notionTrustRoots()`, the register core's `subtree: true` trust entries fill at boot (OPE-539).
+   *
+   * OPTIONAL, and that is safe where {@link HandleNotionDeliveryDeps.domains} is not: a missing
+   * roots list can only ever LOSE a promotion. Absent (or empty) ⇒ every page resolves `no-roots`,
+   * with no API call and no probe, and the delivery keeps the fail-closed `external` binding it had
+   * before this seam existed. `domains` is required for the opposite reason — a missing one would
+   * weaken a fence.
+   */
+  readonly trustRoots?: NotionTrustRoots;
+  /** Resolve the bot's own Notion user id FOR ONE INTEGRATION (cached per credential; env override
+   *  or GET /v1/users/me). An unresolved id makes classifyNotionComment fail CLOSED (drop, never
+   *  wake) — the loop guard. 🔴 It is per-integration on purpose: each Notion integration has its
+   *  OWN bot user id, so one cached id shared across integrations would compare a reply against the
+   *  wrong identity and break the loop guard in both directions.
+   *  🔴 THE CORE CALLS IT ONCE PER CONFIGURED INTEGRATION, not once per delivery (OPE-1921): step 7
+   *  walks {@link signingKeys} to build the deployment's whole own-id set. There is deliberately no
+   *  separate "all the ids" dep — the set is DERIVED here from a required one, so no caller can
+   *  omit it and silently reopen the sibling loop, exactly as {@link domains} is required. */
+  readonly resolveBotUserId: (credentialId: string) => Promise<string | undefined>;
+  /** Resolve the bot's own display name for one integration (Step 4) — a judge input (the
+   *  channel-watch preamble's "names you"), never a bypass. Optional so the core works before name
+   *  capture is wired. */
+  readonly resolveBotName?: (credentialId: string) => Promise<string | undefined>;
+  /** Is the ambient supervisor enabled for this doc's surfaceKey? Fail-closed OFF (per-domain
+   *  opt-in, ambientSupervisorEnabled). The WHOLE ambient path is gated behind this. */
+  readonly ambientEnabled: (surfaceKey: string) => boolean;
+  /** Resolve the doc's engagement calibration tier (memory/domain.ts engagementTierFor) for the
+   *  judged preamble. Optional + fail-soft: absent/throwing ⇒ neutral (byte-identical). */
+  readonly engagementTier?: (surfaceKey: string) => "aggressive" | "neutral" | "reserved";
+  /** The §2.5 engagement seam's store seams (OPE-1501) — see channels/notion-engagement.ts.
+   *  Optional: absent ⇒ the live operational store. Injected so a test drives an engaged or a
+   *  stood-down page without one. */
+  readonly engagement?: NotionEngagementDeps;
+  /** Durable comment-level dispatch lease used only by the authenticated inbox processor. The
+   * synchronous development path keeps the legacy event_dedupe guard. */
+  readonly dispatchGuard?: NotionCommentDispatchGuard;
+  /** Injectable fetch (tests pass a mock; prod omits → global fetch). */
+  readonly fetch?: FetchLike;
+  readonly version?: string;
+  /** OVERLAY on the 429 policy every REST call of this delivery takes (OPE-1254). Live code passes
+   *  none and gets {@link NOTION_INGRESS_RETRY} whole — the policy sized against the ingress
+   *  function's 300 s ceiling. A test passes `{ sleep }` alone, which keeps the shipped numbers and
+   *  only makes the waits instant. */
+  readonly retry?: NotionCallOpts["retry"];
+  /** Request-scoped, content-free latency attribution. Absent keeps non-route callers unchanged. */
+  readonly timing?: NotionWebhookTimingRecorder;
+  /** Route the classified comment to the standing doc supervisor (notion-supervisor.ts). The
+   *  dispatch it receives is UNTIERED (OPE-596): this core holds no binding context, so the route
+   *  leg resolves each author's tier before the supervisor core renders anything. */
+  readonly dispatch: (d: NotionUntieredSupervisorDispatch) => Promise<void>;
+  /** Called with the one-time verification token on the handshake POST (channel logs it). */
+  readonly onHandshakeToken?: (token: string) => void;
+  /** eve's cancel door, channel-agnostic (the route's own `args.attachSession`) — what the STOP LEG
+   *  (OPE-989, step 8d below) calls through {@link routeNotionStopComment}. */
+  readonly attachSession: AttachSessionForCancel;
+}
+
+export interface NotionDeliveryOutcome {
+  readonly status: number;
+  readonly body: string;
+  readonly action:
+    | "handshake"
+    | "rejected"
+    | "bad-json"
+    | "ignored"
+    | "ambient-disabled"
+    | "skipped-self"
+    | "skipped-bot"
+    | "dropped"
+    | "dispatched"
+    | "no-api-key"
+    | "unresolved-page"
+    /** A bare `stop` comment from a genuine, distinct human (OPE-989) — the turn on this page was
+     *  handed to `cancelAnchoredTurn`. `detail` carries the cancel outcome, never a refusal reason. */
+    | "stopped"
+    /** A plain comment on a page `stand_down` marked (OPE-1501) — suppressed by the §2.5 engagement
+     *  registry, whatever the ambient opt-in says. `detail` carries the engagement anchor. Naming
+     *  the agent again clears the flag, so this is never the outcome of an addressed comment. */
+    | "stood-down"
+    /** The signer does not serve the domain that owns this delivery's page (OPE-502, step 8b). */
+    | "scope-refused"
+    /** This comment id already woke a turn inside the dedupe window (OPE-1906, step 12) — a vendor
+     *  retry, or a page two subscriptions both deliver. `detail` carries the comment id. Acked 200:
+     *  the delivery was handled the first time, so Notion has nothing to retry. */
+    | "duplicate-delivery"
+    | "error";
+  readonly detail?: string;
+  /**
+   * 🔴 A REAL `x-notion-signature` WAS CHECKED AGAINST A CONFIGURED SECRET (OPE-189).
+   *
+   * NOT the same as "the gate let it through". `gateNotionDelivery` also returns "accepted" when no
+   * secret is set AND `webhooks.allowUnverifiedNotion` is on — a local-dev hatch whose only proof is
+   * possession of the URL. This flag is false in that case, and the route uses it to decide whether
+   * the delivery may enter the ROUTING plane at all.
+   *
+   * Why the two consumers differ, deliberately: the ambient supervisor reads a comment and judges
+   * whether to reply, which is what the hatch exists to let you exercise on a laptop. `admitTrigger`
+   * fires member-authored, human-approved routines — so an unsigned acceptance must not reach it, or
+   * a dev hatch becomes a production capability the moment the env var is set on a real deployment.
+   * Same narrowing S0b applied to runtime hooks, for the same reason.
+   *
+   * False for the handshake (it arrives BEFORE any secret exists and is correctly unverified) and
+   * for every rejection.
+   */
+  readonly verified: boolean;
+  /**
+   * The Notion channel credential this delivery ran under (OPE-467) — the integration whose secret
+   * verified the signature, else (dev hatch only) the page's domain binding. Absent when the
+   * delivery never reached credential selection (handshake, rejection, bad json, ignored event).
+   * Reported so the route can audit WHICH integration served a page without a second resolution.
+   */
+  readonly credentialId?: string;
+  /**
+   * 🔴 THE INTEGRATION WHOSE SECRET VERIFIED THIS BODY (OPE-500) — the ONE authenticated identity a
+   * delivery carries, and a strict subset of {@link NotionDeliveryOutcome.credentialId}.
+   *
+   * NOT the same field. `credentialId` is "which integration SERVED this delivery", which falls back
+   * to the page binding and then to the first configured key on the dev-hatch arm — so it can name an
+   * integration that proved nothing. This one is set at exactly one place, from the HMAC verdict, and
+   * is absent whenever no secret verified (handshake, rejection, the unverified dev hatch).
+   *
+   * Present on EVERY arm past the gate, `ignored` included. The event plane needs it precisely on the
+   * arm the comment path drops: a `page.*` delivery never reaches credential selection, and
+   * `notionTriggerScopeVerdict` cannot fence a scope without knowing who signed for it.
+   */
+  readonly signerCredentialId?: string;
+}
+
+/**
+ * The call options every Notion REST call {@link deliver} issues DIRECTLY takes (OPE-1254).
+ *
+ * ⚠️ Not quite every call of the delivery. `deps.resolveBotUserId` is awaited before any of these
+ * and reaches `retrieveBotUser` through its own path; `notion.ts` passes it the same policy at that
+ * call site. The two together are what make the ingress arithmetic hold.
+ *
+ * 🔴 ONE PLACE, BECAUSE THE POLICY IS THE POINT. These options were built inline at each of the four
+ * call sites below, so the 429 backoff each one carried was whatever the shared defaults are — a 60 s
+ * budget per call across about 15 sequential calls, ~15 minutes worst case, on a function the
+ * platform kills at 300 s. {@link NOTION_INGRESS_RETRY} is the tightened policy that fits under that
+ * ceiling, and routing every site through this helper is what stops the next call site from being
+ * added without it.
+ *
+ * 🔴 `deps.retry` OVERLAYS THE POLICY, IT DOES NOT REPLACE IT. A test injects a stub `sleep` so a
+ * retry sequence waits nothing, and it must keep the SHIPPED numbers while it does — otherwise the
+ * only test that can see this policy is one that passes the policy in, which proves nothing about
+ * the delivery path.
+ */
+function ingressCallOpts(cred: ResolvedNotionCredential, deps: HandleNotionDeliveryDeps): NotionCallOpts {
+  return { ...cred, fetch: deps.fetch, version: deps.version, retry: { ...NOTION_INGRESS_RETRY, ...deps.retry } };
+}
+
+/**
+ * Run the whole inbound loop for one Notion webhook delivery. Returns the HTTP outcome the
+ * route should send AND the semantic action (for the audit row). Pure w.r.t. eve — every
+ * external effect is injected (fetch, resolveBotUserId, resolveBotName, ambientEnabled, dispatch,
+ * onHandshakeToken).
+ */
+export async function handleNotionDelivery(
+  rawBody: string,
+  signatureHeader: string | null,
+  deps: HandleNotionDeliveryDeps,
+): Promise<NotionDeliveryOutcome> {
+  // The HMAC verdict's own answer to "who signed this", collected the same way `signed` is: written
+  // once, at the gate, rather than threaded through the nine returns below. An out-parameter because
+  // `deliver` returns from ten places and only ONE of them knows this fact.
+  const signer: { credentialId?: string } = {};
+  const { signed, ...out } = await deliver(rawBody, signatureHeader, deps, signer);
+  // {@link NotionDeliveryOutcome.verified}, derived ONCE here rather than threaded through the nine
+  // returns below. `signed` is set at exactly one place — the moment an integration's secret
+  // verified the signature — so the three exclusions still hold by construction: the handshake
+  // returns before the gate, a rejection never gets past it, and the
+  // `webhooks.allowUnverifiedNotion` hatch gets past it with NO secret configured and therefore
+  // no signature checked (gateNotionDeliveryAcross reports verified:false for it).
+  const verified = signed === true && out.action !== "handshake" && out.action !== "rejected";
+  // Reported only when the delivery is VERIFIED, so the field cannot name an integration on an arm
+  // where nothing was proved. `signed` and this id are set together at the gate, so the guard is
+  // belt-and-braces rather than a second decision.
+  return { ...out, verified, ...(verified && signer.credentialId ? { signerCredentialId: signer.credentialId } : {}) };
+}
+
+/**
+ * Process a row that crossed {@link handleNotionDelivery}'s HMAC gate before it was committed to
+ * the durable ingress inbox. This is intentionally a separate entrypoint: the public route cannot
+ * pass an optional "already verified" flag, and the internal drain must supply the immutable signer
+ * identity from the row key. A deleted integration is not retargeted to another credential.
+ */
+export async function handleAcceptedNotionDelivery(
+  rawBody: string,
+  signerCredentialId: string,
+  deps: HandleNotionDeliveryDeps,
+): Promise<NotionDeliveryOutcome> {
+  if (!deps.signingKeys.some((key) => key.credentialId === signerCredentialId)) {
+    return {
+      status: 200,
+      body: "ok",
+      action: "no-api-key",
+      detail: "the verified Notion integration is no longer configured",
+      verified: true,
+      signerCredentialId,
+      credentialId: signerCredentialId,
+    };
+  }
+  const signer = { credentialId: signerCredentialId };
+  const { signed: _signed, ...out } = await deliver(rawBody, null, deps, signer, signerCredentialId);
+  return { ...out, verified: true, signerCredentialId };
+}
+
+/** {@link deliver}'s private return: the outcome plus the ONE bit the wrapper turns into
+ *  {@link NotionDeliveryOutcome.verified} — did an integration's secret actually verify this body? */
+type DeliverOutcome = Omit<NotionDeliveryOutcome, "verified"> & { readonly signed?: boolean };
+
+async function deliver(
+  rawBody: string,
+  signatureHeader: string | null,
+  deps: HandleNotionDeliveryDeps,
+  signer: { credentialId?: string },
+  acceptedSignerCredentialId?: string,
+): Promise<DeliverOutcome> {
+  // 1. One-time subscription handshake — log the token for the operator, ack 200. It arrives
+  //    BEFORE any secret is configured, so it is (correctly) not signature-verified.
+  const handshake = acceptedSignerCredentialId === undefined ? parseVerificationHandshake(rawBody) : undefined;
+  if (handshake) {
+    deps.onHandshakeToken?.(handshake);
+    return { status: 200, body: "ok", action: "handshake" };
+  }
+
+  // 2. Fail-closed HMAC gate, across EVERY configured integration (OPE-467). The secret that
+  //    verifies identifies the sender — nothing in the payload steers this.
+  const gate = acceptedSignerCredentialId !== undefined
+    ? { verified: true as const, credentialId: acceptedSignerCredentialId }
+    : deps.timing
+      ? deps.timing.measureSync("credential", () => gateNotionDeliveryAcross(deps.signingKeys, rawBody, signatureHeader, deps.allowUnverified))
+      : gateNotionDeliveryAcross(deps.signingKeys, rawBody, signatureHeader, deps.allowUnverified);
+  if ("rejection" in gate && gate.rejection) {
+    return { status: 401, body: gate.rejection, action: "rejected", detail: gate.rejection };
+  }
+  const signed = gate.verified;
+  // THE ONE WRITE (OPE-500). Everything past this line — including the `ignored` arm the event plane
+  // depends on — carries the signer out to the route.
+  if (gate.credentialId) signer.credentialId = gate.credentialId;
+
+  // 3. Parse.
+  let ev: NotionWebhookEvent;
+  try {
+    ev = JSON.parse(rawBody) as NotionWebhookEvent;
+  } catch {
+    return { status: 400, body: "bad json", action: "bad-json", signed };
+  }
+
+  // 4. Only comment.created is a conversational trigger.
+  if (notionEventType(ev) !== "comment.created") {
+    return { status: 200, body: "ignored", action: "ignored", detail: notionEventType(ev), signed };
+  }
+  const commentId = commentIdFromEvent(ev);
+  if (!commentId) return { status: 200, body: "ignored", action: "ignored", detail: "no comment id", signed };
+
+  // 5. WHICH INTEGRATION SERVES THIS DELIVERY (OPE-467).
+  //
+  //    🔴 THE VERIFYING INTEGRATION WINS. `gate.credentialId` is the one PROVEN fact here: whose
+  //    secret verified THIS body. The page id below is read from the payload, which nothing has
+  //    authenticated — so it must never move a delivery onto a DIFFERENT integration's credential.
+  //    A forger holding integration A's `verification_token` can name a domain-B page; if the page
+  //    binding outranked the HMAC, that forged body would run under B's key. It does not.
+  //
+  //    PREFER, don't refuse, when the two disagree. A page legitimately shared with two
+  //    integrations produces a delivery on EACH subscription, and each one has to run under its own
+  //    verifying integration — refusing on disagreement would break that real case.
+  //
+  //    `credentialForPage` is the fallback for the one arm where the gate names nothing: the
+  //    `webhooks.allowUnverifiedNotion` dev hatch (accepted with NO secret configured, so no
+  //    integration was identified). The org default is the last resort. Every REST call below —
+  //    and the REPLY, which carries this id forward — runs under the one id this line picks.
+  const eventPageId = pageIdFromEvent(ev);
+  const credentialId = gate.credentialId ?? deps.credentialForPage(ev.workspace_id, eventPageId) ?? deps.signingKeys[0]?.credentialId;
+  if (!credentialId) return { status: 200, body: "ok", action: "no-api-key", detail: "no Notion integration is configured", signed };
+
+  // 6. We need the API key to do the two-step fetch. Ack (don't make Notion retry a config bug).
+  const cred = deps.timing
+    ? await deps.timing.measure("credential", () => deps.credentialFor(credentialId))
+    : await deps.credentialFor(credentialId);
+  if (!cred) {
+    return { status: 200, body: "ok", action: "no-api-key", detail: `no value stored for notion credential "${credentialId}"`, signed, credentialId };
+  }
+
+  // 7. Resolve the bot's own identity for THIS integration (loop guard + name-drop input) and fetch
+  //    the actual comment (the event is a signal → the text/mentions/author live on the comment).
+  const botUserId = deps.timing
+    ? await deps.timing.measure("botTriggerPage", () => deps.resolveBotUserId(credentialId))
+    : await deps.resolveBotUserId(credentialId);
+  // 🔴 AND THE SAME ANSWER FOR EVERY OTHER INTEGRATION WE RUN (OPE-1921). The loop guard has to
+  // recognise the deployment's own words, and this deployment posts under one bot user id PER
+  // INTEGRATION. {@link signingKeys} is already every configured integration, org default first, so
+  // the set is derived INSIDE this core from a required dep — a caller cannot forget to pass it and
+  // thereby reopen the loop, which is the reason `domains` is shaped the way it is (step 8b).
+  // COST: one `GET /v1/users/me` per SIBLING integration, memoised per credential for the process
+  // lifetime — so N-1 extra calls on this process's FIRST delivery and none after it. The verifying
+  // integration is filtered out because its id is already `botUserId`, which is what makes a
+  // single-integration deployment pay NOTHING (notion-test.ts's ack-attribution fixture measures it).
+  const siblingCredentialIds = deps.signingKeys.map((k) => k.credentialId).filter((id) => id !== credentialId);
+  // `canPost` is consulted ONLY for a sibling whose bot id did not resolve, so the ordinary path
+  // spends nothing on it. It separates "this integration can reach Notion and we cannot name it"
+  // (a real loop risk — fail closed) from "this integration has no usable key at all" (it cannot
+  // have authored anything, so failing closed on it would silence the deployment for nothing).
+  const collectOwn = () => collectNotionOwnBotIds(
+    botUserId,
+    siblingCredentialIds,
+    deps.resolveBotUserId,
+    async (id) => (await deps.credentialFor(id)) !== undefined,
+  );
+  const ownBotIds = deps.timing ? await deps.timing.measure("botTriggerPage", collectOwn) : await collectOwn();
+  const botName = deps.resolveBotName
+    ? deps.timing
+      ? await deps.timing.measure("botTriggerPage", () => deps.resolveBotName!(credentialId))
+      : await deps.resolveBotName(credentialId)
+    : undefined;
+
+  let comment: NotionComment;
+  try {
+    comment = deps.timing
+      ? await deps.timing.measure("botTriggerPage", () => retrieveComment(commentId, ingressCallOpts(cred, deps)))
+      : await retrieveComment(commentId, ingressCallOpts(cred, deps));
+  } catch (err) {
+    return { status: 200, body: "ok", action: "error", detail: `retrieveComment: ${String(err)}`, signed, credentialId };
+  }
+
+  // 8. WHICH PAGE THIS SESSION IS ON (OPE-496).
+  //
+  //    🔴 THE FETCHED COMMENT DECIDES, NOT THE PAYLOAD. The surface key built here is not a label:
+  //    it selects the session's domain, and through the domain the pages notion-scope.ts admits for
+  //    every READ TOOL (notion-scope.ts's roster/claim fence, never the credential — see OPE-499:
+  //    the credential every read tool runs under is the DELIVERY's own carried one, resolved by
+  //    notion-credentials.ts notionCallerCredential, and it does not depend on this surface key at
+  //    all). `ev.data.page_id` is a payload field that nothing authenticates, so it must never pick
+  //    that page — a holder of ANY ONE subscription's `verification_token` could name a page in a
+  //    domain their integration was never given, and the session would surface on that domain.
+  //
+  //    `comment.parent` came back from Notion under the credential step 5 proved (step 7's
+  //    retrieveComment), so it is the authenticated answer to the same question. A page-level comment
+  //    carries `page_id` directly; an INLINE comment carries `block_id` instead, so the block's
+  //    owning page is resolved under the SAME credential (resolveBlockOwningPage — the walk the read
+  //    fence already uses for the block drill-in).
+  //
+  //    FAIL CLOSED when neither answers. The payload field is NOT a fallback here: falling back to it
+  //    would restore the whole vector on exactly the deliveries whose shape is unusual, which is the
+  //    shape an attacker picks. A delivery that resolves no page is ACKED (200 — Notion must not
+  //    retry a resolution that will fail the same way) and dispatches nothing.
+  const resolvedPage = deps.timing
+    ? await deps.timing.measure("botTriggerPage", () => resolveDeliveryPage(comment, ingressCallOpts(cred, deps)))
+    : await resolveDeliveryPage(comment, ingressCallOpts(cred, deps));
+  if (!resolvedPage.pageId) {
+    return { status: 200, body: "ok", action: "unresolved-page", detail: resolvedPage.reason, signed, credentialId };
+  }
+  const pageId = resolvedPage.pageId;
+  const discussionId = comment.discussion_id ?? "";
+  const payloadWorkspaceId = ev.workspace_id;
+
+  // 8b. WHICH DOMAIN THIS SESSION MAY OPEN ON (OPE-502).
+  //
+  //    🔴 THE WORKSPACE IS STILL THE PAYLOAD'S WORD, HERE. Step 8 established the PAGE from the
+  //    fetch, and it stops there — `ev.workspace_id` above is a payload field, and there is no
+  //    verified source for a workspace id anywhere in Notion's REST surface. The two halves are then
+  //    composed into `notion/<workspace>/<page>`, which picks the domain, and the domain picks the
+  //    ambient flag, the read scope and (for an agent-initiated call) the credential. So a forged
+  //    `workspace_id` beside an honest page moves the session onto whichever domain CLAIMS that
+  //    workspace in a container entry — a claim reaches every page under it, including one nobody
+  //    enumerated.
+  //
+  //    THE SIGNER FENCES IT, exactly as OPE-500 fenced the trigger plane. The one authenticated fact
+  //    a delivery carries is which integration's secret verified it, and `notion-credentials.ts`
+  //    already knows which integration each domain binds. `notionDeliveryScopeVerdict` asks the one
+  //    question that closes the gap: is every domain this page reaches THROUGH A CLAIM a domain THIS
+  //    signer serves? A page reached through an EXACT `reach` entry is exempt and that is
+  //    deliberate — read the function for why, and for what it does not close.
+  //
+  //    `gate.credentialId` is set at exactly one place and only on a VERIFIED gate, so it is the
+  //    signer and never the step-5 fallback (which may name an integration that proved nothing).
+  //
+  //    ACKED, not 4xx: the bytes verified, and making Notion retry a refusal that will repeat is
+  //    wrong. The refusal is its own action so the route can audit it.
+  //
+  //    THE PAYLOAD VALUE, DELIBERATELY, EVEN THOUGH 8c BELOW REPLACES IT FOR THE PARTITION. This
+  //    check is the domain-claim boundary, and the claim leg (`resolveDomainForChannel`'s roster leg
+  //    needs the WHOLE key) is exactly what tells a rostered-but-cross-claimed forgery apart from an
+  //    honest one — see notion-per-domain-credential-test.ts §9(d). Substituting the roster's own
+  //    workspace before THIS call would make that case invisible to the fence.
+  const scope = notionDeliveryScopeVerdict(payloadWorkspaceId, pageId, gate.credentialId, deps.domains);
+  if (!scope.ok) {
+    return { status: 200, body: "ok", action: "scope-refused", detail: scope.reason, signed, credentialId };
+  }
+
+  // 8c. THE PARTITION'S WORKSPACE — CONFIG'S WORD, NOT THE PAYLOAD'S (OPE-536, completed by
+  //     OPE-254 §2). 8b has now cleared the domain boundary; this step fixes a narrower, purely
+  //     app-layer bug that clearing it does not touch.
+  //
+  //     The surface key's workspace segment used to be whatever the payload said, and nothing
+  //     authenticates that. A stale, mistyped or forged workspace beside an honest page composed a
+  //     SECOND surface key (`notion/<wrong-workspace>/<page>`) beside the honest one, splitting one
+  //     page's session + memory history across two partitions with no domain boundary ever crossed
+  //     to explain it.
+  //
+  //     `notionReachWorkspace` answers with the workspace segment of the `reach` entry that MATCHED
+  //     — on both legs, exact and container. Notion returns no workspace id on any object, so the
+  //     only place an operator can ever have read one is a real delivery for that page: the recorded
+  //     segment IS the real workspace. The container leg is decidable because a domain may reach at
+  //     most one Notion workspace BY CONTAINER (memory/domain.ts `partitionTenantProblems`, enforced
+  //     at config load), so the container that swept a page in names exactly one workspace.
+  //
+  //     🔴 WHAT EACH LEG ACTUALLY BUYS, because the two are not the same size. On the EXACT leg the
+  //     match is workspace-BLIND, so config and the payload can genuinely disagree and preferring
+  //     config closes a real split (OPE-536). On the CONTAINER leg admission REQUIRES the payload's
+  //     workspace to equal the container's own text, so the derived value equals the payload's by
+  //     construction: what changes is not the value but where it comes from, plus the config rule
+  //     above that makes "which workspace?" have one answer per domain (OPE-537 §1).
+  //
+  //     Undefined means the page reaches NO domain — the one case config cannot answer, and the
+  //     forged-workspace case on a container-reached page lands here rather than in the domain. The
+  //     payload's value then composes a key that belongs to no domain: no memory, no bundle, and
+  //     the ambient gate refuses it like any unrouted surface. Inventing the domain's workspace
+  //     here instead would HAND a forged delivery that domain's brain — the opposite of the fix.
+  const workspaceId = notionReachWorkspace(payloadWorkspaceId, pageId, deps.domains) ?? payloadWorkspaceId;
+
+  const surfaceKey = notionSurfaceKey(workspaceId, pageId);
+
+  // 8d. THE STOP LEG (OPE-989) — the honest equivalent of the ✋ reaction on this surface.
+  //
+  //    Notion pushes no reaction webhook (comment.created/updated/deleted is the whole comment
+  //    event catalogue — see channels/notion-stop.ts's header for the vendor evidence), so the
+  //    nearest honest equivalent is the GitHub answer: a comment whose ENTIRE body is the bare word
+  //    "stop", read here — before the ambient gate and before any dispatch.
+  //    `notionCommentIsStopDirective` owns the actor guard (fail-closed on an unresolved bot id, an
+  //    UNIDENTIFIABLE author, a comment authored by ANY of our integrations, an unresolved sibling,
+  //    or a declared bot author), so a "stop" from anyone but a resolved, distinct human never
+  //    reaches `cancelAnchoredTurn`. It reads the SAME own-id set the loop guard does (OPE-1921), so
+  //    a sibling integration's own "stop" can no longer cancel this integration's turn. Read that
+  //    function for the case it still cannot separate: a FOREIGN bot, whose comment carries a real
+  //    id and no `created_by.type`, reads there as a person — the same limit the loop guard has,
+  //    stated in this file's header.
+  //
+  //    🔴 IT SUPPRESSES THE REST OF THE PIPELINE FOR ITS OWN DELIVERY, unconditionally on the
+  //    ambient flag — a stop must not depend on the very feature it is asking to stand down.
+  //    Falling through to the ambient gate/classify/dispatch below would wake the supervisor on the
+  //    very comment that asked it to stop.
+  //
+  //    RUNS BEFORE THE AMBIENT GATE ON PURPOSE (unlike steps 9-11), and this is safe: on a domain
+  //    where ambient is disabled no Notion turn is ever started via a comment at all, so the cancel
+  //    resolves `no_turn_found` — the same honest answer it would give after the gate, one step
+  //    later.
+  if (notionCommentIsStopDirective(comment, ownBotIds)) {
+    const stop = () => routeNotionStopComment(
+      { workspaceId, pageId, discussionId: discussionId || undefined, credentialId, requesterId: comment.created_by?.id },
+      { attachSession: deps.attachSession },
+    );
+    const result = deps.timing ? await deps.timing.measure("engagementDedupe", stop) : await stop();
+    return {
+      status: 200,
+      body: "ok",
+      action: "stopped",
+      detail: result.stopped ? result.outcome : result.reason,
+      signed,
+      credentialId,
+    };
+  }
+
+  // 8e. Classify (self / bot / unresolved-fail-closed / @mention / name-drop / ambient). The loop
+  //    guard lives here (hardened): an unresolved botUserId DROPS.
+  //
+  //    🔴 THE COMPUTATION MOVED ABOVE THE AMBIENT GATE; THE DECISION DID NOT (OPE-1501). The gate
+  //    below needs the ADDRESSING to answer, so the classifier — pure, no I/O, no store — runs
+  //    first, and its `drop` verdict is still acted on where it always was, one step lower. A
+  //    delivery whose page is neither addressed nor engaged therefore returns the identical
+  //    `ambient-disabled` it returned before this seam existed.
+  const classification = classifyNotionComment(comment, ownBotIds, botName);
+  const seamFacts: NotionSeamFacts = {
+    workspaceId,
+    pageId,
+    ...(comment.created_by?.id ? { principalId: comment.created_by.id } : {}),
+    ...(credentialId ? { credentialId } : {}),
+  };
+  // The seam's READ half, and ONLY a plain (`channel-watch`) comment asks it. An ADDRESSED comment
+  // enrols the page instead (step 10c) and can never be a stood-down follow-up, because the address
+  // is what lifts a stop; a `drop` verdict — self-authored, bot-authored, or an unresolved bot id —
+  // is going nowhere, so paying a registry read for it would buy an answer no branch uses.
+  // `authorIsBot` is therefore false by construction here, and it is passed rather than assumed so
+  // the loop guard stays readable at the call site.
+  const seam = classification.addressing === "channel-watch"
+    ? deps.timing
+      ? await deps.timing.measure("engagementDedupe", () => resolveNotionEngagement(seamFacts, false, deps.engagement))
+      : await resolveNotionEngagement(seamFacts, false, deps.engagement)
+    : undefined;
+
+  // 9. Ambient gate — the WHOLE ambient path is fail-closed OFF unless this doc's domain opts in
+  //    (DOMAIN-level opt-in, ambientSupervisorEnabled). An unopted doc does nothing (matching the
+  //    old dead mention-gate's net effect, but now it's an explicit, audited decision).
+  //
+  //    🔴 IT NOW HAS TWO MORE DOORS, AND BOTH ARE THE §2.5 SEAM (OPE-1501 / OPE-1510).
+  //      • ADDRESSED, IN A DECLARED DOMAIN. Notion is the only surface whose ADDRESSED leg sat
+  //        behind the ambient opt-in: the gate returned before the classifier ran, so a page that
+  //        had not opted into ambient could not be addressed at all — deaf, not merely
+  //        un-followable, while every other surface answers a mention with no such opt-in. That
+  //        asymmetry is what made the seam unreachable on an addressed-only page.
+  //
+  //        🔴 THE DOMAIN CONDITION IS NOT DECORATION. `notionDeliveryScopeVerdict` (step 8b) admits
+  //        a page NO domain claims — "no claimed domain ⇒ allow" — because it fences claim-reached
+  //        pages rather than deciding presence. Without this second clause a name-drop on ANY page
+  //        the integration can see, in no domain at all, would run a turn: a far wider door than
+  //        this seam asks for. `notionPageDomain` answers the narrow question — does an operator's
+  //        own config, by roster or by claim, hold this page — and it is the same function step 8c
+  //        already routes with. So the widening is exactly "a page the operator declared, which has
+  //        not opted into ambient, can still be addressed".
+  //      • ENGAGED. A page somebody addressed the agent on wakes on plain follow-ups, which is the
+  //        whole §2.5 posture and the reason this ticket exists. It needs no domain clause: the
+  //        engagement row cannot exist unless an addressed comment already passed the door above.
+  //    Every other comment takes the gate exactly as it always did.
+  //
+  //    🔴 THE DOMAIN VERDICT IS RESOLVED ONCE, HERE, and travels to the route on the dispatch
+  //    (`domainVia`). The gate below reads it, and the `notion.dispatched` row reports it — one
+  //    read, so the row can never disagree with the door that admitted the delivery.
+  const pageDomain = notionPageDomain(workspaceId, pageId, deps.domains);
+  const addressedInDeclaredDomain = classification.addressing === "direct" && pageDomain.via !== "none";
+  if (!deps.ambientEnabled(surfaceKey) && !addressedInDeclaredDomain && seam?.kind !== "deliver") {
+    return { status: 200, body: "ok", action: "ambient-disabled", detail: surfaceKey, signed, credentialId };
+  }
+
+  // 10. Act on the classification (self / bot / unresolved-fail-closed).
+  if (classification.addressing === "drop") {
+    const reason = classification.reason;
+    const action = reason.startsWith("self") ? "skipped-self" : reason.startsWith("bot") ? "skipped-bot" : "dropped";
+    return { status: 200, body: "ok", action, detail: reason, signed, credentialId };
+  }
+  // Capture the post-drop narrowing before the later dispatch closure. TypeScript does not retain a
+  // property narrowing inside a closure, even though both the object and property are readonly.
+  const addressing = classification.addressing;
+
+  // 10c. THE §2.5 STOP (OPE-1501). A plain comment on a page `stand_down` marked is SUPPRESSED —
+  //    including where the ambient supervisor is enabled and would otherwise answer it, which is the
+  //    only thing that makes the verb a stop rather than a note. It is a read and a refusal, so it
+  //    runs here, above the sibling fetch and the ancestor walk it makes pointless. An ADDRESSED
+  //    comment never reaches this branch: the address is what lifts a stop.
+  //
+  //    🔴 THE MARK IS NOT HERE. It is a WRITE, and it belongs below the EXTERNAL-AUTHOR decision,
+  //    which on this surface is made inside `handleNotionSupervisorDispatch` rather than at the
+  //    ingress — see that function, and the `markEngaged` note on `NotionSupervisorDeps`. Marking
+  //    here would let an author the operator excluded enrol a page (and clear a stand-down) by
+  //    naming the agent on it.
+  if (classification.addressing !== "direct" && seam?.kind === "hold" && seam.stopped) {
+    return { status: 200, body: "ok", action: "stood-down", detail: seam.anchor, signed, credentialId };
+  }
+
+  // 10b. IS THIS PAGE UNDER A DECLARED TRUST ROOT (OPE-492)?
+  //
+  //    The ancestor walk, run ONCE per ingested event — never per tool call, because the answer is
+  //    about the PAGE and the page is fixed for the whole delivery. It runs HERE, after the
+  //    classifier, so the agent's own reply loop (self/bot comments, already dropped above) never
+  //    pays for it.
+  //
+  //    🔴 IT CAN ONLY PROMOTE. A matched root stamps `trust_root` on the auth and `bindNotion` binds
+  //    `internal`; every other verdict stamps nothing, and the binding falls through to the
+  //    per-surface vouch and then to the fail-closed `external` exactly as before. A deployment that
+  //    declares no roots gets `no-roots` with ZERO API calls, so this step is free until it is used.
+  //
+  //    🔴 THE PAGE IS THE FETCHED ONE, NOT THE PAYLOAD'S. `pageId` came from step 8, and the walk
+  //    runs under the same verified credential — so a forged `data.page_id` cannot name a page inside
+  //    someone's trusted subtree and inherit its trust.
+  //
+  //    THE WORKSPACE IS THE ROSTER'S WORD ON A ROSTERED PAGE, THE PAYLOAD'S OTHERWISE (step 8c) —
+  //    and here it does not need to be more. It only SELECTS which root set to compare against
+  //    (`prepareNotionTrustRoots` matches the workspace segment by exact string, so the spelling
+  //    used HERE decides whether a declared root is even considered), and a root is matched by its
+  //    globally-unique Notion page id. So a wrong workspace can point the walk at another
+  //    workspace's roots — none of which can be an ancestor of this page — or at a workspace with
+  //    no roots. Either way it can only lose a promotion, never manufacture one.
+  //
+  //    The walk is bounded, cached and fail-closed on every miss (channels/notion-ancestry-trust.ts).
+  //    `notionParentLink` never throws, so a Notion outage degrades to "not trusted".
+  const resolveTrust = () => resolveNotionDeliveryTrust(pageId, workspaceId ?? "", deps.trustRoots, {
+    parentOf: (id) => notionParentLink(id, ingressCallOpts(cred, deps)),
+  });
+  const trust = deps.timing ? await deps.timing.measure("ancestorSiblingTrust", resolveTrust) : await resolveTrust();
+
+  // 11. Build the wake parts + auth, then dispatch to the standing doc supervisor.
+  const triggerText = richTextToPlainText(comment.rich_text);
+  const trigger: NotionUntieredWakeMessage = {
+    from: "human", // self/bot already dropped in classify
+    // 🔴 THE API'S OWN SPELLING OF THE ID, NOT THE WEBHOOK'S (OPE-1847). This value rides to the seat
+    // catch-up as `SeatCatchUpRequest.excludeId`, and since the catch-up bound now admits the
+    // trigger's whole MINUTE, that id match is the ONLY thing that keeps the wake's own comment out
+    // of its own context. The other side of the match is `toNotionCommentSummary`, which reads
+    // `comment.id` from `GET /v1/comments`. `commentId` came from the webhook envelope's `entity.id`
+    // instead, so the two sides were resolved from different Notion surfaces and nothing proved they
+    // spell one uuid the same way. `comment` is the object `retrieveComment` returned above, so
+    // taking its id makes both sides the SAME field of the SAME API. The webhook id stays as the
+    // fallback: it is what addressed the retrieve, so it is never wrong, only possibly spelled
+    // differently.
+    id: comment.id ?? commentId,
+    authorId: comment.created_by?.id,
+    sentAt: comment.created_time ?? new Date().toISOString(),
+    text: triggerText.length > 0 ? triggerText : "(the comment had no additional text)",
+    // The comment object was fetched under the credential whose secret authenticated this delivery.
+    // Keep its block parent distinct from the discussion id: Notion lists comments by BLOCK, while
+    // replies and filtering use the DISCUSSION.
+    ...(comment.parent?.block_id ? { anchorId: comment.parent.block_id } : {}),
+  };
+  const loadSiblings = () => loadThreadSiblings(comment, pageId, discussionId, ownBotIds, ingressCallOpts(cred, deps));
+  const threadComments = deps.timing
+    ? await deps.timing.measure("ancestorSiblingTrust", loadSiblings)
+    : await loadSiblings();
+  const auth = buildNotionAuth({
+    workspaceId,
+    pageId,
+    discussionId: discussionId || undefined,
+    commentId,
+    principalId: comment.created_by?.id,
+    // The integration this delivery runs under (step 5) rides the auth so every reply for this turn
+    // posts under it. Host-set from the HMAC verdict — the comment body cannot reach it.
+    credentialId,
+    // The matched trust root (step 10b), when the walk found one. Host-set from Notion's own parent
+    // chain under the verified credential — the comment body cannot reach it either.
+    ...(trust.trusted && trust.matchedRoot ? { trustRoot: trust.matchedRoot } : {}),
+  });
+  // AUTHORITATIVE addressing stamp for the link-claim hook (identity/binding.ts currentTurnAddressed):
+  // a `direct` Notion wake is an ADDRESSED, single-author comment (a name-drop / structured @mention),
+  // so `link <code>` claiming may tolerate the leading name-drop token. Notion's ONLY way to address
+  // the agent is the name-drop, so without this stamp "oe link ABC…" would never be recognised as a
+  // claim (the whole-message anchor rejects the "oe " prefix). Stamped ONLY on `direct` — a judged
+  // `channel-watch` wake carries no stamp and stays strict (fail-closed), so the F1 envelope attack is
+  // unaffected. The resolved integration name rides along so a name-drop matching the deployment's
+  // ACTUAL bot name is stripped even without OE_AGENT_* set. Host-set (§AUTH-ATTRIBUTE PROVENANCE) —
+  // built here from the classifier verdict, never from the comment body — so it cannot be forged.
+  if (classification.addressing === "direct") {
+    auth.attributes[OE_ADDRESSED_ATTR] = "1";
+    if (botName && botName.trim().length >= 2) auth.attributes[OE_BOT_NAME_ATTR] = botName.trim();
+  }
+
+  // Engagement calibration (the ambient-everywhere tier dial) — fail-soft to neutral.
+  let engagementTier: "aggressive" | "neutral" | "reserved" | undefined;
+  try {
+    engagementTier = deps.engagementTier?.(surfaceKey);
+  } catch {
+    engagementTier = undefined;
+  }
+
+  // 12. ONE WAKE PER COMMENT (OPE-1906) — the delivery half of the loop guard.
+  //
+  //    🔴 THE CLASSIFIER CANNOT SEE THIS AND THE AUDIT CANNOT EITHER. Step 8e answers "whose words
+  //    are these"; a SECOND delivery of the same person's comment carries the same author and the
+  //    same text, so it passes every gate above exactly as the first did and wakes a second turn —
+  //    a second model spend, a second `notion.dispatched` row and a second reply in the discussion.
+  //    On ship #216 one Notion discussion carrying ONE driver comment produced THREE dispatch rows.
+  //
+  //    IT SITS HERE, AS LATE AS THIS FUNCTION ALLOWS, so every refusal the INGRESS makes — the drop,
+  //    the ambient gate, the scope fence, the stand-down, the unresolved page — happens before a
+  //    mark is spent, and a redelivery after the operator opens one of those gates still wakes a
+  //    turn. Past this line the mark IS spent: the spend cap runs inside the dispatch closure
+  //    (notion.ts `ingressSpendGate`), so an over-budget delivery marks and then declines — which
+  //    costs nothing real, because that decline posts a VISIBLE refusal rather than going quiet.
+  //    `firstNotionDispatchOfComment`
+  //    states the rest: the mark precedes the wake so two concurrent deliveries cannot both run a
+  //    turn, and it fails OPEN, so a store outage costs a duplicate turn rather than a deaf page.
+  const firstDispatch = () => deps.dispatchGuard
+    ? deps.dispatchGuard.claim(commentId)
+    : firstNotionDispatchOfComment(seamFacts, commentId, deps.engagement);
+  const first = deps.timing ? await deps.timing.measure("engagementDedupe", firstDispatch) : await firstDispatch();
+  if (!first) {
+    return { status: 200, body: "ok", action: "duplicate-delivery", detail: commentId, signed, credentialId };
+  }
+
+  const dispatch = () => deps.dispatch({
+    surfaceKey,
+    credentialId,
+    addressing,
+    pageId,
+    discussionId,
+    workspaceId: workspaceId ?? null,
+    auth,
+    trigger,
+    threadComments,
+    engagementTier,
+    // THE SEAM'S OWN VERDICT, carried so the route's `notion.dispatched` row can say what woke this
+    // delivery (OPE-1510). `deliver` is the ENGAGED door of the gate above, and it is the only door
+    // a plain comment has; an ADDRESSED comment never asks the seam, so it never carries the flag.
+    ...(seam?.kind === "deliver" ? { engagedFollowUp: true } : {}),
+    // HOW THE OPERATOR'S CONFIG HOLDS THIS PAGE (OPE-1510) — the same verdict the addressed door
+    // above gated on. `container` is a CONTAINER entry — the whole workspace, or a same-level
+    // page glob (memory/domain.ts) — so it admits a name-drop on a page nobody enumerated;
+    // `roster` is a page an operator listed by name. The audit row must tell the two apart,
+    // because they are different amounts of declared intent behind the same wake.
+    domainVia: pageDomain.via,
+    // TWO consumers (see NotionSupervisorDispatch.trust): the `notion.dispatched` audit row, and the
+    // single-window privacy floor (`notionSingleWindowPrivacyOk` reads `trust.trusted` as its
+    // admission leg, OPE-540) — trimming this field silently drops trust-root pages from the shared
+    // window. Omitted on the `no-roots` verdict, so a deployment that declares no trust root writes
+    // the same audit row it always did; the floor reads absence as "not internal".
+    ...(trust.reason === "no-roots" ? {} : { trust }),
+  });
+  if (deps.timing) await deps.timing.measure("dispatch", dispatch);
+  else await dispatch();
+  if (deps.dispatchGuard) await deps.dispatchGuard.complete(commentId);
+
+  return { status: 200, body: "ok", action: "dispatched", detail: classification.addressing, signed, credentialId };
+}
+
+/** {@link resolveDeliveryPage}'s answer. Exactly one field is set: `pageId` when the page is
+ *  established, `reason` when it is not. A `reason` is a REFUSAL — never a page id the caller may
+ *  substitute. */
+export interface ResolvedDeliveryPage {
+  readonly pageId?: string;
+  readonly reason?: string;
+}
+
+/**
+ * The page a delivery's comment REALLY lives on, established from the comment Notion returned under
+ * the verified credential (OPE-496). The webhook's step 8 explains why the payload's own `page_id`
+ * may not answer this; this function is the answer that replaces it.
+ *
+ * Two shapes, one credential:
+ *   • a PAGE-level comment carries `parent.page_id` — already the answer, and already authenticated
+ *     (the fetch that returned it ran under the integration whose secret verified the delivery);
+ *   • an INLINE comment carries `parent.block_id` instead, so the block's owning page is walked under
+ *     the SAME credential ({@link resolveBlockOwningPage}, bounded at BLOCK_PARENT_MAX_HOPS).
+ *
+ * Every other outcome is a refusal with a reason: no parent at all, a parent that is neither a page
+ * nor a block, or a block whose walk ends anywhere but a page (a database or workspace parent, an id
+ * the integration cannot see, or too many hops). The caller must treat a reason as "do nothing" —
+ * `resolveBlockOwningPage` already states the same rule for the read fence, and both callers keep it.
+ *
+ * Exported so the delivery test can drive each shape directly, with the mock fetch counting the
+ * block-walk calls.
+ */
+export async function resolveDeliveryPage(
+  comment: NotionComment,
+  opts: NotionCallOpts,
+): Promise<ResolvedDeliveryPage> {
+  const parent = comment.parent;
+  if (parent?.page_id) return { pageId: parent.page_id };
+  if (parent?.block_id) {
+    const owner = await resolveBlockOwningPage(parent.block_id, opts);
+    return owner ? { pageId: owner } : { reason: `comment parent block "${parent.block_id}" resolved no owning page` };
+  }
+  return { reason: "the retrieved comment carries no page or block parent" };
+}
+
+/**
+ * Best-effort surrounding-conversation context: the OTHER comments in the same discussion thread
+ * on this page, as oldest-first {@link NotionUntieredWakeMessage} siblings for the wake envelope's
+ * backscroll (re-sent each wake — cheap at Notion volume — so the judge always has full thread
+ * context). Any failure yields [] (context is enrichment, never a precondition — same posture as
+ * the old renderContext path). The triggering comment is excluded (it's the trigger message).
+ * The bot's own prior comments are marked `self` so the judge tells its voice from a human's.
+ */
+async function loadThreadSiblings(
+  trigger: NotionComment,
+  pageId: string,
+  discussionId: string,
+  own: NotionOwnBotIds,
+  opts: NotionCallOpts,
+): Promise<NotionUntieredWakeMessage[]> {
+  try {
+    const all = await listBlockComments(trigger.parent?.block_id ?? pageId, opts);
+    return all
+      .filter((c) => c.id !== trigger.id && (discussionId ? c.discussion_id === discussionId : true))
+      .map((c) => {
+        // OUR OWN VOICE IS THE DEPLOYMENT'S, NOT ONE INTEGRATION'S (OPE-1921). Compared against the
+        // verifying integration's id alone, a reply a SIBLING integration posted into this very
+        // discussion was rendered to the judge as another person's words.
+        const authorId = c.created_by?.id;
+        const isSelf = Boolean(authorId !== undefined && own.all.has(authorId));
+        // Only an IDENTIFIED PERSON author carries an id downstream (F3): a bot/integration
+        // or an author whose person-ness we can't confirm (created_by.type absent on the REST
+        // payload) is left id-less, so wake-trust resolves the sibling `relay` — never a human
+        // standing (peer/principal) on an unattributed or machine author. Fail-closed: no
+        // positive `type === "person"` ⇒ no id ⇒ relay. The comment still rides as context.
+        const isPerson = c.created_by?.type === "person";
+        return {
+          from: isSelf ? ("self" as const) : ("human" as const),
+          id: c.id ?? "",
+          authorId: isSelf || !isPerson ? undefined : authorId,
+          sentAt: c.created_time ?? "",
+          text: richTextToPlainText(c.rich_text),
+        };
+      })
+      .filter((m) => m.text.length > 0);
+  } catch {
+    return [];
+  }
+}