@open-everywhere/provider-notion 0.1.0

package/dist/agent/channels/notion-webhook.js

@@ -0,0 +1,675 @@
+// 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, } from "./notion-api.js";
+import { buildNotionAuth, notionSurfaceKey } from "./notion-identity.js";
+import { resolveNotionDeliveryTrust } from "./notion-ancestry-trust.js";
+import { notionDeliveryScopeVerdict } from "./notion-credentials.js";
+import { collectNotionOwnBotIds } from "./notion-bot-user.js";
+import { notionPageDomain, notionReachWorkspace } from "./notion-scope.js";
+import { classifyNotionComment } from "./notion-supervisor.js";
+import { notionCommentIsStopDirective, routeNotionStopComment } from "./notion-stop.js";
+import { firstNotionDispatchOfComment, resolveNotionEngagement } from "./notion-engagement.js";
+import { OE_ADDRESSED_ATTR, OE_BOT_NAME_ATTR } from "@open-everywhere/core/agent/adapter-api.js";
+/**
+ * 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, deps) {
+    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, signatureHeader, deps) {
+    // 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 = {};
+    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, signerCredentialId, deps) {
+    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 };
+}
+async function deliver(rawBody, signatureHeader, deps, signer, acceptedSignerCredentialId) {
+    // 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, 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;
+    try {
+        ev = JSON.parse(rawBody);
+    }
+    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;
+    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 = {
+        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 = {
+        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;
+    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 };
+}
+/**
+ * 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, opts) {
+    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, pageId, discussionId, own, opts) {
+    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" : "human",
+                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 [];
+    }
+}
+//# sourceMappingURL=notion-webhook.js.map