@open-everywhere/provider-notion 0.1.0

package/agent/channels/notion.ts

@@ -0,0 +1,1242 @@
+// The Notion comment surface — an AMBIENT-JUDGED conversational channel. The agent is ambiently
+// present on any doc it's connected to: a standing per-doc SUPERVISOR session reads EVERY comment
+// and intelligently decides whether to engage, reusing OE's Slack channel-watch judge wholesale.
+// Built as a custom `defineChannel` HTTP transport (eve ships no Notion channel) over Notion's
+// public REST API + an integration API key. The eve-free orchestration is the tested core in
+// notion-webhook.ts (classify) + notion-supervisor.ts (session + wake); this file is the thin
+// route that wires the store, the domain opt-in, and the reply post-back.
+//
+// THE LOOP:
+//   POST /eve/v1/notion
+//     → one-time subscription HANDSHAKE ({verification_token}) is CAPTURED for the operator —
+//       stored in the encrypted vault, logged only as a sha256 fingerprint + a one-shot reveal
+//       link, NEVER as a value (OPE-195; it is the permanent HMAC key, not a bootstrap nonce)
+//     → every real delivery is HMAC-verified (X-Notion-Signature = sha256(rawBody) keyed by
+//       the verification token) — fail closed on a bad/missing signature or unset secret
+//     → a comment.created event is a SIGNAL ONLY (no text/mentions), so we RETRIEVE the
+//       comment, gate on the doc's domain having ambientSupervisor ON, then CLASSIFY it
+//       (self / bot / unidentified-author and unresolved-bot-id both fail closed / @mention→direct
+//       / else→judged), take the ONE-WAKE-PER-COMMENT guard, and dispatch to the standing doc
+//       supervisor under its reserved :oe-sup:g token
+//     → the supervisor either replies (POST /v1/comments into the SAME discussion_id) or stays
+//       audibly silent (a notion.no_reply audit row — parity with Slack)
+//     → SEPARATELY, and DISJOINTLY (OPE-189): every VERIFIED delivery is also handed to
+//       admitTrigger. Comments are conversation (the supervisor's, above) and STRUCTURAL changes —
+//       page/database/data_source created, moved, deleted, properties or schema updated — are work
+//       (a routine's). The partition is enforced twice, one-sidedly: the supervisor path ignores
+//       everything that is not comment.created, and the normalizer returns null for the whole
+//       comment.* family. No single delivery ever does both. See channels/notion-event-normalizer.ts
+//   All host-side REST calls use the CHANNEL-PLUMBING integration API key — the notion provider's
+//   `channel-key` credential, resolved via notion-api.ts resolveNotionCredential, stored under
+//   `db:notion:channel-key` (OPE-408 step 2); distinct from the work-surface `team-key` credential
+//   (`db:notion:team-key`) that backs the notion-rest egress connection.
+//   🔴 …UNLESS A DOMAIN BINDS ITS OWN INTEGRATION (OPE-467). Then TWO rules split the calls:
+//   a DELIVERY and everything it triggers — the two-step fetch and the reply — runs under the
+//   integration whose secret VERIFIED the delivery (the HMAC-proven fact; a payload field must
+//   never pick the credential). Agent-initiated READS and proactive posts have no verifying
+//   delivery, so they run under the page's domain binding, else the org default
+//   (channels/notion-credentials.ts holds that decision). Notion's own share list is the fence
+//   either way. Inbound deliveries are verified against EVERY configured integration's secret.
+//
+// ─── GOVERNANCE: the accepted tier ──────────────────────────────────────────────────────
+// The "doc brain" memory UX (a page that remembers every prior discussion) fully lights up only
+// when the operator VOUCHES the workspace: bindNotion pins visibility=private and leaves trust
+// undefined → bindFrom fails closed to `external` (shared/workspace memory gated off) unless the
+// workspace is vouched (identity/trust.ts / OE_TRUST=internal). Ambient does NOT relax this —
+// reading more comments never grants more trust. Unvouched, the agent still judges + replies, but
+// without a shared page silo. Accountability is OE-AUDITED-ONLY: every turn (dispatch, reply, AND
+// judged silence) is in OUR append-only log; Notion's own audit log is Enterprise-admin-only and
+// not integration-queryable, so OE's log is the sole record. This is interim until Notion's
+// waitlisted External Agents API lands (a first-class, Notion-audited agent participant with
+// native HITL) — see design notes notion-surface-and-platform-research.md.
+//
+// Live e2e: scripts/e2e/scenarios.ts J-NOT (capability "notionAmbient" — self-skips without
+// creds). It forge-replays a signed comment.created at a human-authored anchor → judged reply or
+// audited silence (notion.no_reply over GET /control/v1/audit), verifies no self-loop across the
+// reply, and proves reply-targeting across two discussions on one page supervisor session. Still
+// needs a live Notion workspace + human anchor comments + Tommy for provisioning (see
+// notion-ambient-surface-design.md Step 5 / the e2e-issue-surfaces driver investigation).
+// ────────────────────────────────────────────────────────────────────────────────────────
+
+import { defineChannel, POST, type RouteHandlerArgs } from "eve/channels";
+import {
+  receiptEventTime,
+  spreadVendorTs,
+  appendAudit,
+  ingressSpendGate,
+  auditAmbientSkip,
+  deploymentOrg,
+  resolveWakeTrustFromContext,
+  finalMessageActionForTurn,
+  completeSupervisorTurn,
+  getConfig,
+  getSettings,
+  ambientSupervisorEnabled,
+  engagementTierFor,
+  resolveExternalPolicy,
+  externalPolicyOverrideFor,
+  liveMemoryDeltaDep,
+  getOperationalStore,
+  capabilitiesForPlatform,
+  consumeSupervisorReplyMark,
+  declaredTrustForKeys,
+  supervisorGrainFor,
+  mintRotationToken,
+  claimRuntimeRotation,
+  stampMintedRuntime,
+  grainUsesUnifiedWindow,
+  divertInboundToUnifiedWindow,
+  healPrunedDeploymentStrand,
+  captureHandshakeSecret,
+  admitTrigger,
+  NOTION_HANDSHAKE_REF_NAMESPACE,
+  getOperatorSecret,
+  type Domain,
+  type SupervisorGrain,
+  type SurfaceTrust,
+  carryTailForward,
+  type WakeMessageInput,
+  recordWakeTail,
+  postHostNotice,
+  detectBridgeableInputRequest,
+  renderQuestionForSurface,
+  QUESTION_ANSWERED_AUDIT_ACTION,
+  QUESTION_ANSWER_DROPPED_AUDIT_ACTION,
+  seatCatchUp,
+  dispatchNativeWakeWithRetry,
+  readCappedBody,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import {
+  forgetNotionQuestion,
+  rememberNotionQuestion,
+  resolveNotionInboundAnswer,
+  type NotionInboundAnswer,
+} from "./notion-question-return.js";
+import { notionChannelCredentialFor, notionIntegrations, resolveNotionInboundSecret, NOTION_CHANNEL_CREDENTIAL } from "./notion-credentials.js";
+import { resolveNotionBotUser } from "./notion-bot-user.js";
+import { NOTION_EVENT_SOURCE, notionEventDeliveryId, notionTriggerScopeVerdict } from "./notion-event-normalizer.js";
+import { createCommentReply, resolveNotionCredential, type ResolvedNotionCredential } from "./notion-api.js";
+import { notionWorkspaceKey } from "./notion-identity.js";
+import { notionTrustRoots } from "./notion-ancestry-trust.js";
+import { handleAcceptedNotionDelivery, handleNotionDelivery, type NotionDeliveryOutcome, type NotionReplyTarget, type NotionSessionState } from "./notion-webhook.js";
+import { acknowledgeNotionIngress, NOTION_INGRESS_MAX_BODY_BYTES } from "./notion-ingress.js";
+import {
+  acceptNotionIngressDrainRequest,
+  createNotionCommentDispatchGuard,
+  notionIngressDrainAvailable,
+  NOTION_INGRESS_DRAIN_PATH,
+  postNotionIngressDrain,
+  settleNotionIngressDrain,
+  type AcceptedNotionIngressDrain,
+  type NotionIngressDisposition,
+} from "./notion-ingress-drain.js";
+import {
+  createNotionWebhookTiming,
+  NOTION_WEBHOOK_TIMING_ACTION,
+  runNotionWebhookTimed,
+  type NotionWebhookTimingDetail,
+  type NotionWebhookTimingRecorder,
+} from "./notion-webhook-timing.js";
+import {
+  handleNotionSupervisorDispatch,
+  notionSupervisorToken,
+  planNotionSingleWindow,
+  shouldRotate,
+  type NotionSupervisorDeps,
+  type NotionUntieredSupervisorDispatch,
+  type NotionUntieredWakeMessage,
+} from "./notion-supervisor.js";
+import { notionDispatchJoinDetail, notionWakeAuditDetail } from "./notion-engagement.js";
+
+const ROUTE = "/eve/v1/notion";
+
+function log(msg: string): void {
+  console.log(`[open-everywhere:notion] ${msg}`);
+}
+
+// The bot's own Notion user — its id (the loop guard's self-identity) AND its display name (the
+// judge's name-drop input: a person typing the bot's name is a STRONG signal to the channel-watch
+// preamble's "names you", NOT a bypass — the wake stays judged). An integration's bot-user is
+// stable, so resolve once (env overrides NOTION_BOT_USER_ID / NOTION_BOT_NAME win for tests /
+// deploys that know them — but the ID override covers the ORG-DEFAULT `channel-key` credential ONLY,
+// because two Notion integrations never share a bot user and one pinned id standing for a sibling's
+// would reopen the OPE-1921 cross-integration loop; NOTION_BOT_NAME stays unscoped, being a display
+// name and never an identity) and cache both. Best-effort: an unresolved id makes classify fail CLOSED
+// (nothing dispatches — the hardened loop guard) rather than crash; an unresolved name just means
+// the judge relies on the comment text alone (it already contains the name).
+// 🔴 THE RESOLVER AND ITS PER-CREDENTIAL CACHE MOVED TO `notion-bot-user.ts` (OPE-1857), because the
+// SEAT CATCH-UP needs the same identity: the seat's own previous reply sits inside the window it
+// reads, and Notion's comment payload cannot tell our reply from a person's by shape. Two copies of
+// one identity would be the class that ticket closes.
+
+/** Reset the cached bot users (tests only) — re-exported at its historical name. */
+export { _resetNotionBotUserCache } from "./notion-bot-user.js";
+
+// The domain registry, fail-soft. Every OPE-467 credential decision reads it, and a config-load
+// error must degrade to "no domain binds anything" (⇒ the org default everywhere) rather than throw
+// inside a webhook — the same fail-soft posture notionAmbientEnabled / notionGrainFor already take.
+function notionDomains(): readonly Domain[] {
+  try {
+    return getConfig().loadDomains();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The Notion channel credential for an AGENT-INITIATED call on a page — the page's domain binding,
+ * else the org default (channels/notion-credentials.ts holds the decision itself). This is the
+ * fallback rule only: a delivery and its reply carry the VERIFYING integration's credential
+ * instead (notion-webhook.ts selects it once; the reply arms read the carried id).
+ */
+function notionCredentialForPage(workspaceId: string | undefined, pageId: string | undefined): string {
+  return notionChannelCredentialFor(workspaceId, pageId, notionDomains()) ?? NOTION_CHANNEL_CREDENTIAL;
+}
+
+/**
+ * One integration's INBOUND signing key, by operator-secret name. Resolved through
+ * `getOperatorSecret` so a value stored with `oe secret set` wins over an env var of the same name
+ * (the ruled OPE-408 order) — this is the one call that moved `NOTION_WEBHOOK_SECRET` off a bare
+ * `process.env` read. Undefined when nothing is stored under either home: an unconfigured
+ * integration contributes no key, and a delivery it would have signed simply fails the gate.
+ *
+ * The report-or-stay-silent decision lives in channels/notion-credentials.ts
+ * (resolveNotionInboundSecret), where it is testable without a store — see its header for why the
+ * error CLASS, not the message, is the seam.
+ */
+function notionInboundSecret(name: string): Promise<string | undefined> {
+  return resolveNotionInboundSecret(name, getOperatorSecret, log);
+}
+
+// Is the ambient supervisor enabled for a Notion doc's surfaceKey? Domain-level opt-in
+// (ambientSupervisorEnabled, default OFF). Fail-closed: any config-load error → OFF.
+function notionAmbientEnabled(surfaceKey: string): boolean {
+  try {
+    return ambientSupervisorEnabled(surfaceKey, getConfig().loadDomains());
+  } catch {
+    return false;
+  }
+}
+
+// UNIFIED cross-surface grain (channels/unified-supervisor.ts) — the one hop the session deps +
+// wake stamp share (the Slack reference's `grainFor`). FAIL-SOFT to the per-container grain (the
+// byte-identical path) on any config-load error.
+function notionGrainFor(surfaceKey: string): SupervisorGrain {
+  try {
+    return supervisorGrainFor(surfaceKey, getConfig().loadDomains());
+  } catch {
+    return { unified: false, registryKey: surfaceKey };
+  }
+}
+
+/**
+ * The Notion arm of the SINGLE-WINDOW PRIVACY FLOOR — the one decision that admits a page into the
+ * shared cross-surface window. Pure and SYNCHRONOUS: every input is a fact the pipeline already
+ * resolved, so no network call enters this gate. It holds the same role as the Discord and Teams
+ * arms (discordSingleWindowPrivacyOk / teamsSingleWindowPrivacyOk) and is a unit-tested truth table
+ * the same way. It takes a `declared` resolver where those take a boolean `vouched` one, because
+ * this floor must tell a `public` DEMOTION apart from "nothing declared" — see below.
+ *
+ * THREE POSITIVE SIGNALS, and each one is an OPERATOR DECLARATION. None is an inference from a
+ * Notion API field: a page's `public_url` is null for the common guest-shared vector, so a floor
+ * that read it would leak private cross-surface context to an external guest.
+ *   1. `OE_TRUST=internal`, the blanket switch for an internal-only deployment;
+ *   2. the per-surface VOUCH (identity/trust.ts) — an `internal` declaration on the workspaceKey
+ *      `notion/<ws>` or on the full surfaceKey `notion/<ws>/<page>`, most-specific-wins;
+ *   3. the ANCESTOR-TRUST verdict for this delivery (OPE-492): the page sits under a page the
+ *      operator declared a TRUST ROOT.
+ *
+ * 🔴 SIGNAL 3 IS HANDED DOWN, NEVER RE-DERIVED (OPE-540). The webhook core walks the parent chain
+ * ONCE per delivery, under the credential that verified it, and the dispatch carries the verdict
+ * here — the same value the `notion.dispatched` audit row records. The floor only reads it, so the
+ * floor stays a synchronous predicate.
+ *
+ * 🔴 FAIL-CLOSED ON ABSENCE. `trust` is undefined on the `no-roots` verdict, because the webhook
+ * core omits the field there. `trusted` is false on every other refusal. Both read as "not
+ * internal": no throw, no pass.
+ *
+ * 🔴 A `public` DECLARATION DEMOTES ABOVE THE TRUST-ROOT VERDICT, as it does on the binding plane:
+ * identity/binding.ts orders `declaredExternal ?? raw.trust ?? … ?? vouched`, so `bindFrom` puts the
+ * operator's `public` carve-out above the walk's `internal`. A page declared `public` inside a
+ * trusted subtree keeps the shared org brain switched off, and this floor keeps it out of the shared
+ * window for the same reason.
+ *
+ * ⚠️ THE TWO PLANES STILL DIVERGE UNDER `OE_TRUST=internal`. The blanket switch is this floor's FIRST
+ * leg, above the demotion — exactly as on the Discord and Teams floors — while on the binding plane
+ * `local.trust` sits BELOW the demotion. So under the blanket, a `public`-declared page is admitted
+ * to the shared window while its org-brain binding stays external. Pre-existing admission-gate
+ * behaviour, kept deliberately for cross-platform consistency (docs/how-it-works/identity.md).
+ */
+export function notionSingleWindowPrivacyOk(
+  input: {
+    /** `notion/<ws>` — a workspace-level declaration covers every page in the workspace. */
+    readonly workspaceKey: string;
+    /** `notion/<ws>/<page>` — a page-level declaration narrows to one page and beats the workspace. */
+    readonly surfaceKey: string;
+    /** The ancestor-walk verdict this delivery carries. Undefined ⇒ the operator declared no roots. */
+    readonly trust?: { readonly trusted: boolean };
+  },
+  deps: {
+    /** The declaration resolver, injected by tests. Returns the most-specific declared value, or
+     *  undefined when the operator declared nothing for this page. */
+    readonly declared?: (workspaceKey: string, surfaceKey: string) => SurfaceTrust | undefined;
+    readonly trustEnv?: string | undefined;
+  } = {},
+): boolean {
+  const trustEnv = "trustEnv" in deps ? deps.trustEnv : process.env.OE_TRUST;
+  if (trustEnv === "internal") return true; // the blanket internal-only-deploy switch
+  const declared = (deps.declared ?? declaredTrustForKeys)(input.workspaceKey, input.surfaceKey);
+  if (declared === "public") return false; // the DEMOTION — above the trust-root verdict
+  if (declared === "internal") return true; // the per-surface vouch
+  return input.trust?.trusted === true; // the resolved trust-root verdict (OPE-540)
+}
+
+// Per-session state: the discussion thread + page/workspace so message.completed can post the
+// reply back into the SAME thread (Notion's create-comment targets discussion_id).
+type NotionState = NotionSessionState;
+
+/**
+ * Live supervisor deps (mirrors slack-events.ts liveSupervisorDeps): create-or-fetch / rotate /
+ * force-rotate over the (org, surfaceKey) channel_session registry with the reserved :oe-sup:g
+ * token, and a `wake` that continues the session under that token. org is the deployment org (a
+ * deployment fact — never crosses the eve-free core boundary). Rotation reuses shouldRotate AS-IS.
+ * A rotation carries the OUTGOING generation's recorded TAIL forward (OPE-794).
+ */
+// Exported (not just internal to the route) so a test can drive the `wake` leg directly — the SAME
+// reason liveGitHubSupervisorDeps/liveLinearSupervisorDeps are testable without a live webhook.
+// `respond` is the OPE-1305 answer leg, and it is OPTIONAL for one reason: it is the only primitive
+// that reaches a delegated worker, so a caller that cannot supply it has no leg to run. Absent ⇒ the
+// decision is not even attempted — no store read, and no admission call that could write a refusal
+// row against a person whose answer could never have been delivered anyway. The live route supplies
+// it; a test driving the send leg alone need not.
+export function liveNotionSupervisorDeps(
+  send: SendFn,
+  surfaceKey: string,
+  to?: RouteHandlerArgs["to"],
+  respond?: RespondFn,
+  timing?: NotionWebhookTimingRecorder,
+): NotionSupervisorDeps {
+  const org = deploymentOrg();
+  const store = getOperationalStore();
+  // UNIFIED re-key (the Slack reference's exact shape, slack-events.ts liveSupervisorDeps): when
+  // the page's domain has opted in, the registry ROW is the synthetic `oe-domain::<name>` key and
+  // the token is `oe-dom:<name>:oe-sup:g<gen>` — one row + one token per generation for the whole
+  // team. Flag-off, notionGrainFor returns the per-doc grain + token — byte-identical.
+  return {
+    async getOrCreateSession(surfaceKey, pageId, atIso) {
+      const grain = notionGrainFor(surfaceKey);
+      // OPE-599: claim the runtime-change rotation BEFORE the row read, and unconditionally (the
+      // mint arm must consume it too). Why, and why here: channels/runtime-rotation.ts.
+      const runtimeChanged = await claimRuntimeRotation({ org, registryKey: grain.registryKey, surfaceKey, domainName: grain.domainName, atIso });
+      const existing = await store.getChannelSession(org, grain.registryKey);
+      if (!existing) {
+        const row = await store.rotateChannelSession(org, grain.registryKey, mintRotationToken(grain, 1, () => notionSupervisorToken(pageId, 1)), atIso);
+        // OPE-1821: stamp the pair onto the row this build just minted. Without it the seat's next
+        // wake reads NULL, takes the ADOPTED arm and never rotates for the deploy it crossed.
+        await stampMintedRuntime({ org, registryKey: grain.registryKey, surfaceKey, domainName: grain.domainName, atIso });
+        return { token: row.token, generation: row.generation, freshGeneration: true, tail: [] as readonly WakeMessageInput[] };
+      }
+      if (shouldRotate(existing, atIso, { runtimeChanged })) {
+        const gen = existing.generation + 1;
+        // OPE-794: read the OUTGOING generation's recorded tail BEFORE minting its successor.
+        const tail = await carryTailForward(org, grain.registryKey, existing.token);
+        const row = await store.rotateChannelSession(org, grain.registryKey, mintRotationToken(grain, gen, () => notionSupervisorToken(pageId, gen)), atIso);
+        return { token: row.token, generation: row.generation, freshGeneration: true, tail };
+      }
+      // A resume whose first wake never delivered (first_wake_at NULL) is still "fresh" (H7c
+      // self-heal), so the next wake re-carries backscroll. Its tail is empty — carried and cleared
+      // at the rotation that minted this row.
+      const fresh = existing.firstWakeAt == null;
+      // On a NON-fresh generation the row's lastWakeAt IS the previous wake (touchSession advances it
+      // only at dispatch end, AFTER this read) — the memory-delta cursor. Fresh ⇒ no prior wake ⇒ omit.
+      return { token: existing.token, generation: existing.generation, freshGeneration: fresh, tail: [] as readonly WakeMessageInput[], ...(fresh ? {} : { lastWakeAt: existing.lastWakeAt }) };
+    },
+    touchSession: (surfaceKey, atIso) => store.touchChannelSession(org, notionGrainFor(surfaceKey).registryKey, atIso),
+    // THE SINCE-LAST-WAKE CATCH-UP (OPE-1726), through the shared path core holds. Notion's own fetch
+    // is registered at bundle registration; the admission policy is the DOMAIN's, resolved by the
+    // shared road itself from the request's own channel key (OPE-1857). No `trustFor`: this surface
+    // has no synchronous roster probe for a comment author, so the shared core's FAIL-CLOSED
+    // per-sender default applies — a human sibling reads `unauth` and stays fenced, the honest floor
+    // for an author the deployment cannot vouch at wake time.
+    catchUp: (req) => seatCatchUp("notion", req),
+    // OPE-794 — file this wake on the live generation's tail ring. Same key derivation as the
+    // rotation read and the spend counter, so all three target one row.
+    recordWake: (entry, token, surfaceKey) => recordWakeTail(org, notionGrainFor(surfaceKey).registryKey, token, entry),
+    // The "changed since your last wake" memory-delta PUSH — armed ONLY under the unified org gate
+    // (undefined otherwise ⇒ dispatch never computes ⇒ byte-identical). Keyed by the page's surface
+    // so the delta names ONLY silos this session reads.
+    memoryDelta: liveMemoryDeltaDep(org, surfaceKey),
+    now: () => new Date().toISOString(),
+    async wake({ token, auth, message, context, state, window }) {
+      // SINGLE-WINDOW diversion (channels/unified-window.ts, mirroring linear.ts's wake dep): a
+      // window-carrying wake goes through eve's cross-channel `to(...).send(...)` into the synthetic
+      // `unified` channel, so its effective token is `unified:<raw>`, shared with the domain's
+      // Slack/GitHub/Linear wakes: ONE context window. The unified channel's `receive` hook registers
+      // the wakeId→origin map entry (durably, BEFORE the send) and re-checks the gates
+      // fail-closed. A failure propagates to the route's dispatch (fail-closed: never delivered
+      // without a routable reply target). This IS the native-session suppression on Notion —
+      // there is no separate per-doc mention channel to stand down; the one dispatch path either
+      // sends here (native) or diverts (window), off the one seam verdict (planNotionSingleWindow).
+      if (window) {
+        // A window means the wake carries a `direct-mention`/wake-id envelope AND the reply target
+        // must be registered in the map (divertToUnifiedWindow → unified.receive). Without a
+        // cross-channel `to` we CANNOT register it, so a native send would post an
+        // unresolvable wake-id — refuse VISIBLY instead (the route always supplies `to`, so this
+        // is defense-in-depth, never reached in prod).
+        if (!to) throw new Error("notion single-window wake has no cross-channel dispatch — refusing (would post an unregistered wake-id)");
+        // THE OWNED-THREAD INGRESS SEAM (§2.6, OPE-1719) — the INBOUND variant, the one Slack's
+        // front route has always used. A wake landing in a discussion a live task worker or thread
+        // seat OWNS is dispatched to that owner's token instead of the standing seat's. Notion is
+        // thread-first: every wake arrives scoped to one discussion, so every wake on this leg
+        // consults ownership. Flag-off, and on every unowned discussion, this is a byte-identical
+        // passthrough to `divertToUnifiedWindow`.
+        const divert = async () => {
+          // Keep the core divert explicitly awaited at the provider boundary. Besides preserving
+          // rejection timing inside this phase, this is the source-level proof behind Notion's
+          // `owned-thread-ingress` capability declaration.
+          await divertInboundToUnifiedWindow(to, {
+            message,
+            context: [...context],
+            token,
+            window,
+            surfaceKey,
+            auth: auth as unknown as { attributes?: Record<string, unknown> },
+          });
+        };
+        if (timing) await timing.measure("eveSend", divert);
+        else await divert();
+        return;
+      }
+      // ── THE ANSWER LEG (OPE-1305) ────────────────────────────────────────────────────────────
+      // 🔴 `respond` IS THE ONLY PRIMITIVE THAT REACHES A DELEGATED WORKER. eve routes an answer to a
+      // child solely through `payload.inputResponses` entries whose `requestId` is in the parent
+      // session's proxy map; a plain `send` falls to `forSelf` — the parent — every time. So this
+      // branch is the whole return leg on the native route, and everything else here was already
+      // present. channels/notion-question-return.ts owns the decision and fails soft in one
+      // direction: no row, another discussion, a refused answerer ⇒ an ordinary send.
+      //
+      // THE ANSWER TEXT IS THE RENDERED WAKE, deliberately — byte-exactly what eve consumed as the
+      // answer before this branch existed, so the change is WHERE the comment is addressed, not what
+      // the model reads. It keeps the envelope's provenance fence around the human's words.
+      //
+      // NEVER DROP A COMMENT. A `respond` that throws falls through to the ordinary send with the row
+      // LEFT IN PLACE, so the discussion is still heard and the question is still answerable.
+      if (respond !== undefined) {
+        const answer = await resolveNotionInboundAnswer({ org, bareToken: token, auth });
+        if (answer) {
+          const deliverAnswer = () => deliverNotionAnswer({ answerOrg: org, token, auth, message, context, answer, respond, surfaceKey });
+          if (timing ? await timing.measure("eveSend", deliverAnswer) : await deliverAnswer()) return;
+        }
+      }
+      try {
+        const workspace = surfaceKey.split("/")[1] ?? "unknown";
+        const dispatchWake = () => dispatchNativeWakeWithRetry(
+          () => send({ message, context: [...context] }, { auth, continuationToken: token, state }),
+          { platform: "notion", workspace, surfaceKey },
+        );
+        if (timing) await timing.measure("eveSend", dispatchWake);
+        else await dispatchWake();
+      } catch (err) {
+        // OPE-971: the NATIVE (flag-off) send has no window and no divert. `notionGrainFor(surfaceKey)
+        // .registryKey === surfaceKey` flag-off (the exact row `getOrCreateSession` above already
+        // rotates), so it's passed straight through — see the GitHub/Linear/Slack siblings.
+        await healPrunedDeploymentStrand({
+          token,
+          registryKey: surfaceKey,
+          surfaceKey,
+          workspace: surfaceKey.split("/")[1] ?? "unknown",
+          platform: "notion",
+          atIso: new Date().toISOString(),
+          err,
+        });
+        throw err;
+      }
+    },
+  };
+}
+
+/** The channel `send` shape this route uses (structural — avoids importing eve's SendPayload, and
+ *  since eve 0.31 there is no public `SendFn` to import at all: the address moved onto
+ *  `from(address)` and `context` moved from the payload into the send options. {@link notionSendFrom}
+ *  is the one adapter that bridges the two shapes). */
+type SendFn = (
+  payload: { message: string; context?: string[] },
+  opts: { auth: unknown; continuationToken: string; state: NotionState },
+) => Promise<void>;
+
+/** Adapt eve 0.31's `from(address).send(message, options)` to {@link SendFn}. */
+function notionSendFrom(from: RouteHandlerArgs<NotionState>["from"]): SendFn {
+  return async (payload, opts) => {
+    await from(opts.continuationToken).send(payload.message, {
+      auth: opts.auth,
+      state: opts.state,
+      ...(payload.context && payload.context.length > 0 ? { context: payload.context } : {}),
+    } as never);
+  };
+}
+
+/** The ANSWER delivery (OPE-1305) — `from(token).respond([{requestId, text}])`, the one primitive
+ *  that reaches a delegated worker. Structural, for the same reason {@link SendFn} is: eve exports no
+ *  public type for it. */
+type RespondFn = (input: { requestId: string; text: string }, opts: { auth: unknown; continuationToken: string; context?: readonly string[] }) => Promise<void>;
+
+/** Adapt eve's `from(address).respond(responses, options)` to {@link RespondFn}. */
+function notionRespondFrom(from: RouteHandlerArgs<NotionState>["from"]): RespondFn {
+  return async (input, opts) => {
+    await (from(opts.continuationToken) as unknown as { respond: (r: readonly { requestId: string; text: string }[], o: unknown) => Promise<unknown> }).respond(
+      [{ requestId: input.requestId, text: input.text }],
+      {
+        auth: opts.auth,
+        // The side-channel context rides the answer for the same reason it rides the send: a comment
+        // that happens to resolve a question must not lose the context every other wake carries.
+        ...(opts.context && opts.context.length > 0 ? { context: [...opts.context] } : {}),
+      },
+    );
+  };
+}
+
+type NotionWebhookRouteArgs = Pick<RouteHandlerArgs<NotionState>, "from" | "waitUntil" | "to" | "attachSession">;
+
+/** Request-wide timing finalizer: early credential reads, delivery, and late route work share one
+ * emit-once failure boundary, while the wrapped handler keeps the route's original semantics. */
+function timedNotionWebhookRoute(
+  handler: (
+    req: Request,
+    args: NotionWebhookRouteArgs,
+    timing: NotionWebhookTimingRecorder,
+    finishTiming: (outcome: string) => void,
+  ) => Promise<Response>,
+): (req: Request, args: NotionWebhookRouteArgs) => Promise<Response> {
+  return async (req, args) => {
+    const timing = createNotionWebhookTiming();
+    const emit = (detail: NotionWebhookTimingDetail): void => {
+      try {
+        args.waitUntil(
+          appendAudit({
+            org: deploymentOrg(),
+            platform: "notion",
+            workspace: "unknown",
+            surface: "unknown",
+            action: NOTION_WEBHOOK_TIMING_ACTION,
+            detail,
+          }).catch(() => undefined),
+        );
+      } catch {
+        // Telemetry must never replace the delivery's own response or thrown failure.
+      }
+    };
+    return runNotionWebhookTimed(timing, emit, (finish) => handler(req, args, timing, finish));
+  };
+}
+
+/**
+ * Deliver one inbound comment as the ANSWER to the session's outstanding question, and say so in the
+ * audit trail. Returns whether it landed — `false` means the caller must fall through to the
+ * ordinary send, with the outstanding-question row deliberately LEFT IN PLACE.
+ *
+ * 🔴 THE ROW IS CONSUMED ONLY AFTER eve ACCEPTED THE DELIVERY. It is what makes the NEXT comment an
+ * ordinary wake again, so dropping it before the `respond` returns would leave a question answered
+ * and a row saying it is still open — or, worse, consume it for a delivery that never happened.
+ *
+ * 🔴 IDS, ENUMS AND COUNTS ONLY. The answer text is a person's prose in a discussion thread and is
+ * never audited, the same redaction rule the question side states. Both outcomes write a row;
+ * neither is silent.
+ */
+async function deliverNotionAnswer(input: {
+  readonly answerOrg: string;
+  readonly token: string;
+  readonly auth: unknown;
+  readonly message: string;
+  readonly context: readonly string[];
+  readonly answer: NotionInboundAnswer;
+  readonly respond: RespondFn;
+  readonly surfaceKey: string;
+}): Promise<boolean> {
+  const detail = {
+    requestId: input.answer.requestId,
+    floor: input.answer.floor,
+    chars: input.message.length,
+    surfaceKey: input.surfaceKey,
+    route: "native",
+    ...(input.answer.taskId !== undefined ? { taskId: input.answer.taskId } : {}),
+    ...(input.answer.wakeId !== undefined ? { wakeId: input.answer.wakeId } : {}),
+  };
+  // The SAME partition every other Notion row takes (`notion.dispatched` above): the workspace id
+  // and the PAGE, both read off the surface key `notion/<workspace>/<page>`. The full key rides the
+  // detail instead, so an operator can still join these rows to the dispatch that carried them.
+  const [, workspace = "unknown", surface = "unknown"] = input.surfaceKey.split("/");
+  try {
+    await input.respond(
+      { requestId: input.answer.requestId, text: input.message },
+      { auth: input.auth, continuationToken: input.token, context: input.context },
+    );
+  } catch (err) {
+    const error = (err instanceof Error ? err.message : String(err)).slice(0, 300);
+    log(`answer ${input.answer.requestId} could NOT be delivered (${error}) — falling back to an ordinary wake, the question stays open`);
+    await appendAudit({
+      org: input.answerOrg,
+      platform: "notion",
+      workspace,
+      surface,
+      action: QUESTION_ANSWER_DROPPED_AUDIT_ACTION,
+      detail: { ...detail, error },
+    }).catch(() => undefined);
+    return false;
+  }
+  await forgetNotionQuestion(input.answerOrg, input.token);
+  log(`answer ${input.answer.requestId} delivered to ${input.token} (floor ${input.answer.floor})`);
+  await appendAudit({
+    org: input.answerOrg,
+    platform: "notion",
+    workspace,
+    surface,
+    action: QUESTION_ANSWERED_AUDIT_ACTION,
+    detail,
+  }).catch(() => undefined);
+  return true;
+}
+
+function notionIngressDisposition(outcome: NotionDeliveryOutcome, eventPlaneRefused: boolean): NotionIngressDisposition {
+  if (outcome.action === "no-api-key" || outcome.action === "error") return "retry";
+  if (
+    eventPlaneRefused ||
+    outcome.action === "ambient-disabled" ||
+    outcome.action === "skipped-self" ||
+    outcome.action === "skipped-bot" ||
+    outcome.action === "dropped" ||
+    outcome.action === "unresolved-page" ||
+    outcome.action === "stood-down" ||
+    outcome.action === "scope-refused"
+  ) {
+    // These gates all precede the comment-dispatch lease. Deleting the primary row preserves the
+    // prior contract: a later provider redelivery may be reconsidered after config/state changes.
+    return "discard";
+  }
+  return "complete";
+}
+
+const notionWebhookRouteHandler = timedNotionWebhookRoute(
+  async (req, { from, waitUntil, to, attachSession }, timing, finishTiming) => {
+      const send = notionSendFrom(from);
+      // The OPE-1305 answer leg. Built beside `send` from the same `from`, so the two primitives
+      // always address the same session.
+      const respond = notionRespondFrom(from);
+      const internalDrain = new URL(req.url).pathname === NOTION_INGRESS_DRAIN_PATH;
+      let acceptedIngress: AcceptedNotionIngressDrain | undefined;
+      let rawBody: string;
+      let signature: string | null;
+      if (internalDrain) {
+        // Cap and authenticate the ORIGINAL stream before reading provider config or secrets. A
+        // reconstructed Request here would make the 16 KiB cap cosmetic after an unbounded read.
+        const admitted = await acceptNotionIngressDrainRequest(req, {
+          org: deploymentOrg(),
+          store: getOperationalStore(),
+        });
+        if ("response" in admitted) {
+          finishTiming(admitted.response.ok ? "drain-idle" : "drain-refused");
+          return admitted.response;
+        }
+        acceptedIngress = admitted.accepted;
+        rawBody = acceptedIngress.rawBody;
+        signature = null;
+      } else {
+        const read = await timing.measure("credential", () => readCappedBody(req, NOTION_INGRESS_MAX_BODY_BYTES));
+        if ("tooLarge" in read) {
+          finishTiming("accept-refused");
+          return new Response("payload too large", { status: 413 });
+        }
+        rawBody = read.body;
+        signature = req.headers.get("x-notion-signature");
+      }
+      // EVERY configured integration, org default first (OPE-467). One entry on a single-
+      // integration deployment, so the gate below does exactly what it always did.
+      const integrations = notionIntegrations(notionDomains());
+      // Resolve each SECRET NAME at most once per delivery — the same memo shape `apiKeys` below
+      // uses. Two integrations may legitimately share one inbound secret name (a domain that binds
+      // its own credential but omits `inboundSecret` keeps the deployment default), and this runs
+      // on an UNAUTHENTICATED POST, before the HMAC gate: without the memo each such pair costs a
+      // second credential-store read that an anonymous caller can drive. It cannot go below one
+      // read per DISTINCT name — trying every configured secret is what identifies the sender.
+      const secrets = new Map<string, Promise<string | undefined>>();
+      const inboundSecretFor = (name: string): Promise<string | undefined> => {
+        const hit = secrets.get(name);
+        if (hit) return hit;
+        const resolved = notionInboundSecret(name);
+        secrets.set(name, resolved);
+        return resolved;
+      };
+      const signingKeys = await timing.measure("credential", () => Promise.all(
+        integrations.map(async (i) => ({ credentialId: i.credentialId, secret: await inboundSecretFor(i.inboundSecret) })),
+      ));
+
+      if (!internalDrain) {
+        const admission = await acknowledgeNotionIngress(rawBody, signature, {
+          org: deploymentOrg(),
+          signingKeys,
+          allowUnverified: getSettings().webhooks.allowUnverifiedNotion,
+          drainAvailable: notionIngressDrainAvailable(),
+          enqueue: (org, write) => getOperationalStore().enqueueIngressDelivery(org, write),
+          drain: (key) => postNotionIngressDrain(key),
+          waitUntil,
+        });
+        if (admission.headers.get("x-oe-notion-ingress") !== "synchronous") {
+          finishTiming(admission.ok ? "accepted" : "accept-refused");
+          return admission;
+        }
+      }
+      // Resolve each integration's token AT MOST ONCE per delivery. The dispatch closure, the spend
+      // gate's refusal post and the two-step fetch all ask for the same credential id.
+      const credentials = new Map<string, Promise<ResolvedNotionCredential | undefined>>();
+      // OPE-505: the memo holds the key WITH its endpoint rules. Resolving the bare token here would
+      // hand every REST call below an UNFENCED fetch, because guardCredentialFetch returns the base
+      // fetch by identity when it is given no rules.
+      const credentialFor = (credentialId: string): Promise<ResolvedNotionCredential | undefined> => {
+        const hit = credentials.get(credentialId);
+        if (hit) return hit;
+        const resolved = resolveNotionCredential(credentialId);
+        credentials.set(credentialId, resolved);
+        return resolved;
+      };
+      // The bot user for ONE integration — its own id (the loop guard) and its own display name.
+      const botUserFor = (credentialId: string): Promise<{ id?: string; name?: string }> =>
+        resolveNotionBotUser(credentialId, () => credentialFor(credentialId))();
+
+      // Route the classified comment to the standing doc supervisor, then audit the dispatch.
+      // The unified grain is stamped HERE (the webhook core stays grain-free): it drives the
+      // wake's platform address + P5 disclosure and the session's `oeUnified` seed marker; the
+      // registry/token re-key lives in the deps — all off the same fail-soft grain resolution.
+      const dispatch = async (d: NotionUntieredSupervisorDispatch): Promise<void> => {
+        const grain = notionGrainFor(d.surfaceKey);
+        // The integration that serves THIS page (OPE-467). Taken from the DISPATCH, not re-derived:
+        // the webhook core selected it once for this delivery, and the spend gate's visible refusal
+        // post is a real Notion comment that has to go out under that same integration. Re-deriving
+        // it here would be a second rule that agrees by luck.
+        const pageCredential = await credentialFor(d.credentialId);
+        // SINGLE-WINDOW plan (channels/unified-window.ts via planNotionSingleWindow — the shared
+        // seam): on a `singleWindow` grain, resolve the PRIVACY FLOOR through the pure predicate
+        // above ({@link notionSingleWindowPrivacyOk}), which reads the operator-vouch register, the
+        // OE_TRUST blanket switch, and THIS DELIVERY'S ancestor-trust verdict. The verdict arrives
+        // on the dispatch (`d.trust`), already resolved by the webhook core under the credential
+        // that verified the delivery — so the floor stays a synchronous lookup with NO network, and
+        // a page that binds `internal` through a trust root now joins the same cross-surface window
+        // its memory already writes to (OPE-540). Fail-CLOSED: no positive signal → privacyOk=false
+        // → native path. Off the singleWindow grain this is a no-op — byte-identical. (`to` is
+        // always present on this route, so a minted wake-id is always registerable; the wake dep
+        // additionally refuses a window with no `to` — belt-and-braces against a dangling wake-id
+        // on the native send.)
+        const usesWindow = grainUsesUnifiedWindow(grain); // cross-surface OR solo (byte-identical flag-off)
+        const privacyOk =
+          usesWindow &&
+          notionSingleWindowPrivacyOk({
+            workspaceKey: notionWorkspaceKey(d.workspaceId ?? "unknown"),
+            surfaceKey: d.surfaceKey,
+            trust: d.trust,
+          });
+        const window = usesWindow
+          ? planNotionSingleWindow(true, d.addressing === "direct", privacyOk, {
+              discussionId: d.discussionId,
+              pageId: d.pageId || undefined,
+              workspaceId: d.workspaceId,
+              // Freeze the DELIVERY's integration into the origin, so the unified reply posts under
+              // the credential that fetched — the same id the native path carries on the auth.
+              credentialId: d.credentialId,
+              // THE FRONT-DOOR RECEIPT (OPE-1716) — a Notion delivery carries no vendor clock this
+              // seam can read, so the ingress row records our own instant and marks it `receipt`,
+              // which the split reporter renders as a LOWER BOUND and never as a measurement.
+              // 🔴 SAY WHAT IT IS: taken HERE, at the divert decision, not at the route's first byte
+              // — so on Notion the vendor→ingress segment is a floor near zero and carries no
+              // information about the vendor's own hop. It is the truthful floor, not a measure of it.
+              ...spreadVendorTs(receiptEventTime(Date.now())),
+            })
+          : undefined;
+        // PER-MESSAGE TRUST (identity/wake-trust.ts — audit-wedge F3): resolved off the
+        // SAME auth capture the session binds with (Notion's mapper leaves trust
+        // undefined, so the gate fail-closes external — relay — unless the operator
+        // vouches the workspace / OE_TRUST) + the config-as-code admin rosters. Applies
+        // to the trigger AND the discussion-sibling backscroll; the bot's own `self`
+        // comments are relay (machine-authored). Directness stays the `mention` flag —
+        // it no longer implies the principal tier.
+        const wakeCtx = { channel: { kind: "notion" }, session: { auth: { current: d.auth as unknown as { attributes?: Readonly<Record<string, string>> } } } };
+        // A tier above `relay` requires an IDENTIFIED HUMAN author: `from === "human"` AND a
+        // concrete authorId. A sibling with no author id — or a non-person/bot author, which
+        // notion-webhook.ts leaves id-less (F3) — resolves `relay`. isBot:false is safe here
+        // (the trigger passed classify's person gate; a sibling only carries an id when it's a
+        // person). NO principalFallback: a per-message sibling must never borrow the trigger
+        // author's principal id (which would render an unattributed sibling as the trigger's tier).
+        const trustOf = (m: NotionUntieredWakeMessage) =>
+          m.from === "human" && m.authorId ? resolveWakeTrustFromContext(wakeCtx, { id: m.authorId, isBot: false }) : ("relay" as const);
+
+        // SPEND CAP (pre-flight — the ONE shared gate, spend/ingress-gate.ts, the same function every
+        // other surface and the cross-surface divert call): an over-budget scope DECLINES the turn
+        // with a VISIBLE refusal, never a silent drop, before the model turn. CHECK fails OPEN; a
+        // definite OVER fails CLOSED unless the sender is an admin over this scope.
+        //
+        // POSITION: BEFORE handleNotionSupervisorDispatch (and its notion.dispatched audit) so a
+        // decline skips both. Notion has no separate native mention leg — every Notion comment wake
+        // flows through THIS closure — but a single-window wake still passes the divert's own gate
+        // afterwards (channels/unified.ts, door "window"), which is what covers the surfaces whose
+        // window leg bypasses their native one. Here the two simply agree.
+        if ((await ingressSpendGate({
+          bindable: wakeCtx,
+          door: "mention",
+          ...(d.auth.principalId ? { principalId: d.auth.principalId } : {}),
+          post: async (text) => { await createCommentReply({ discussionId: d.discussionId, text, apiKey: pageCredential?.apiKey ?? "", endpoints: pageCredential?.endpoints }); },
+        })) === "declined") {
+          return; // drop — no model turn
+        }
+
+        await handleNotionSupervisorDispatch(
+          {
+            ...d,
+            unified: grain.unified,
+            // SINGLE-WINDOW plumbing: the core renders the wake-id into the envelope and the wake
+            // dep diverts the delivery into the unified channel. `directMention` is the SEAM's
+            // addressed verdict (window.addressing) — the same one decision drives the divert,
+            // the addressed render, and the owed-reply stamp (which since OPE-1982 classifies a
+            // dropped turn rather than selecting a delivery route).
+            window,
+            ...(window?.addressing === "direct-mention" ? { directMention: true } : {}),
+            trigger: { ...d.trigger, trust: trustOf(d.trigger) },
+            threadComments: d.threadComments.map((m) => ({ ...m, trust: trustOf(m) })),
+            // THE EXTERNAL-AUTHOR POLICY (OPE-507), resolved HERE because the supervisor core stays
+            // config-free — the same split `engagementTier` uses. Org default from the settings
+            // block, domain override from `Domain.externalPolicy`, applied field by field.
+            externalPolicy: resolveExternalPolicy(externalPolicyOverrideFor(d.surfaceKey, getConfig().loadDomains())),
+          },
+          liveNotionSupervisorDeps(send, d.surfaceKey, to, respond, timing),
+        );
+        // LOUD, because the alternative is silence (OPE-492). A declared trust root that Notion
+        // serves as neither a page nor a block matches nothing the walk ever sees, so it grants
+        // exactly nothing — and a config line that quietly grants nothing is the failure this warning
+        // exists to end. The usual cause is a TEAMSPACE id, which is a 32-hex uuid and therefore
+        // indistinguishable from a page id at config time.
+        if (d.trust?.unreachableRoots && d.trust.unreachableRoots.length > 0) {
+          console.warn(
+            `[open-everywhere:notion] declared trust root(s) ${d.trust.unreachableRoots.join(", ")} resolve as neither a page nor a block under integration "${d.credentialId}" — such a root can never match, so it grants nothing. If it is a TEAMSPACE id, declare the top PAGE of the teamspace instead.`,
+          );
+        }
+        await timing.measure("finalAudit", () => appendAudit({
+          org: deploymentOrg(),
+          platform: "notion",
+          workspace: d.workspaceId ?? "unknown",
+          surface: d.pageId || d.discussionId || "unknown",
+          principalId: d.auth.principalId || undefined,
+          action: "notion.dispatched",
+          detail: {
+            // WHAT WOKE IT and HOW THE PAGE IS DECLARED (OPE-1510, notion-engagement.ts).
+            // `addressing` is not what the classifier called it — an engaged follow-up reads
+            // `thread-follow` here while the turn stays judged. `via` is the domain origin the
+            // addressed door gated on, so a name-drop admitted by a `container` claim is
+            // distinguishable from one on a `roster` page an operator listed.
+            ...notionWakeAuditDetail(d.addressing, d.engagedFollowUp, d.domainVia),
+            // THE EXACT-JOIN IDS (OPE-1907). Ids only — never a byte of the comment. They are what
+            // lets ONE delivery be joined to the turn it woke: `deliveryId` separates two
+            // deliveries of the same comment, and `wakeId` is the key `wake.ingress` and
+            // `wake.turn_start` already carry, so the row bridges the front door to the session.
+            ...notionDispatchJoinDetail({
+              deliveryId: notionEventDeliveryId(rawBody),
+              commentId: d.trigger.id,
+              ...(window ? { wakeId: window.wakeId } : {}),
+            }),
+            discussionId: d.discussionId,
+            ...(window ? { singleWindow: true } : {}),
+            // The ancestor-trust verdict (OPE-492), when roots are declared. The REASON is the point:
+            // `database-boundary` / `hop-limit` / `cycle` / `unresolvable` / `workspace-root` each say
+            // a different thing about why a page did not inherit trust, and a row that recorded only
+            // "untrusted" would send an operator to look at the wrong thing. `unreachableRoots` names a
+            // declared root Notion serves as neither page nor block — the teamspace-id case.
+            ...(d.trust
+              ? {
+                  trust: {
+                    trusted: d.trust.trusted,
+                    reason: d.trust.reason,
+                    hops: d.trust.hops,
+                    ...(d.trust.matchedRoot ? { matchedRoot: d.trust.matchedRoot } : {}),
+                    ...(d.trust.unreachableRoots ? { unreachableRoots: d.trust.unreachableRoots } : {}),
+                  },
+                }
+              : {}),
+          },
+        }));
+      };
+
+      const deliveryDeps = {
+        signingKeys,
+        allowUnverified: getSettings().webhooks.allowUnverifiedNotion,
+        credentialFor,
+        credentialForPage: (workspaceId, pageId) => notionChannelCredentialFor(workspaceId, pageId, notionDomains()),
+        // The registry the OPE-502 signer fence reads (step 8b). Passed as data, not as a verdict —
+        // the fence itself lives in the tested core so no wiring can weaken it.
+        domains: notionDomains(),
+        // The operator's declared TRUST ROOTS (OPE-492) — the `subtree: true` lines of the shared
+        // trust registry, handed to this bundle at boot (OPE-539). Empty on a deployment that
+        // declares none, which makes step 10b a no-op with no API call.
+        trustRoots: notionTrustRoots(),
+        resolveBotUserId: async (credentialId) => (await botUserFor(credentialId)).id,
+        resolveBotName: async (credentialId) => (await botUserFor(credentialId)).name,
+        ambientEnabled: notionAmbientEnabled,
+        // The ambient-everywhere calibration dial (explicit domain ← org ← platform default);
+        // handleNotionDelivery fail-softs any throw here to neutral.
+        engagementTier: (surfaceKey) => engagementTierFor(surfaceKey, getConfig().loadDomains()),
+        timing,
+        dispatch,
+        ...(acceptedIngress
+          ? {
+              dispatchGuard: createNotionCommentDispatchGuard({
+                org: deploymentOrg(),
+                store: getOperationalStore(),
+              }),
+            }
+          : {}),
+        // THE STOP LEG's cancel door (OPE-989) — eve's channel-agnostic `attachSession`, the same
+        // one github.ts's wrapRoute and teams-stop.ts's route pass to their own stop arms.
+        attachSession,
+      } satisfies Parameters<typeof handleNotionDelivery>[2];
+      let outcome: NotionDeliveryOutcome;
+      try {
+        outcome = acceptedIngress
+          ? await handleAcceptedNotionDelivery(rawBody, acceptedIngress.signerCredentialId, deliveryDeps)
+          : await handleNotionDelivery(rawBody, signature, deliveryDeps);
+      } catch (err) {
+        if (acceptedIngress) {
+          await settleNotionIngressDrain(acceptedIngress, "retry", {
+            org: deploymentOrg(),
+            store: getOperationalStore(),
+          });
+        }
+        throw err;
+      }
+
+      // ─── THE EVENT-PLANE LEG (OPE-189) ──────────────────────────────────────────────────────
+      // The SECOND consumer of this one delivery, and it is DISJOINT from the supervisor above by
+      // event type: `comment.*` is conversation (handled above; the normalizer returns null for it,
+      // so it can never fire a routine) and `page.*`/`database.*`/`data_source.*` is work (ignored
+      // above; only routines see it). The rule lives in ONE place — notion-event-normalizer.ts —
+      // rather than being re-spelled here as a second event-type list that could drift out of step
+      // with it; this route hands over EVERY verified delivery and lets the normalizer decide.
+      //
+      // 🔴 GATED ON `verified`, NOT on the gate having passed: the unverified-hatch acceptance
+      // (`webhooks.allowUnverifiedNotion` with no secret) must never fire a routine. See
+      // NotionDeliveryOutcome.verified.
+      //
+      // `waitUntil` because routing is not part of the response the vendor is waiting on, and
+      // `admitTrigger` NEVER throws for a bad delivery (every "can't route this" case is a report),
+      // so a structural event nobody subscribes to costs one normalize and stops.
+      //
+      // `headers: {}` is honest, not lazy — the Notion normalizer reads NOTHING from headers.
+      // Notion carries its event type, its parents AND its delivery id in the body, which is why
+      // `deliveryIdHeader` is absent on the normalizer and `notionEventDeliveryId` exists instead.
+      // 🔴 AND FENCED ON THE SIGNER (OPE-500). `verified` proves that SOME configured integration's
+      // secret signed these bytes. It does not prove that Notion composed them, so every scope field
+      // the normalizer reads is still the sender's choice. Per-domain subscription tokens are
+      // distributed by design (OPE-467), so the sender who chose them may be one domain's operator
+      // reaching for another domain's routines. notionTriggerScopeVerdict answers the one question
+      // that closes it: is the domain that owns the claimed scope a domain THIS signer serves?
+      //
+      // A refusal drops the delivery out of the trigger plane and says why in the log. It is not a
+      // 4xx — the bytes verified, and making Notion retry a refusal that will repeat is wrong.
+      let eventPlaneRefused = false;
+      if (outcome.verified) {
+        const fence = notionTriggerScopeVerdict(rawBody, outcome.signerCredentialId, notionDomains());
+        if (!fence.ok) {
+          eventPlaneRefused = true;
+          log(`event plane: delivery refused — ${fence.reason}`);
+        } else {
+          const deliveryId = notionEventDeliveryId(rawBody);
+          const eventPlane = admitTrigger(
+            {
+              source: NOTION_EVENT_SOURCE,
+              headers: {},
+              body: rawBody,
+              receivedAt: new Date().toISOString(),
+              ...(deliveryId ? { deliveryId } : {}),
+            },
+            { to },
+          ).then((report) => {
+            if (report.matched > 0) log(`event plane: ${report.matched} matched -> ${report.fired} fired, ${report.skipped} skipped`);
+          });
+          if (acceptedIngress) {
+            try {
+              await eventPlane;
+            } catch (err) {
+              await settleNotionIngressDrain(acceptedIngress, "retry", {
+                org: deploymentOrg(),
+                store: getOperationalStore(),
+              });
+              throw err;
+            }
+          } else {
+            waitUntil(eventPlane.catch((err) => log(`event plane: admitTrigger threw (routing lost for this delivery): ${String(err)}`)));
+          }
+        }
+      }
+
+      if (outcome.action === "handshake") {
+        // 🔴 THE TOKEN IS NEVER LOGGED (OPE-195). It is the PERMANENT HMAC key for every subsequent
+        // delivery on this subscription, so printing it — which this line used to do, and which
+        // .env.example and the Notion runbook used to instruct operators to rely on — put the
+        // signing key of a fail-closed ingress into log retention, forgeable by anyone with log
+        // access for as long as logs are kept. captureHandshakeSecret stores it in the encrypted
+        // vault under a RESERVED ref and logs a redaction + sha256 fingerprint + a single-use,
+        // 15-minute reveal link instead. That link is BEARER-ONLY (there is no clicker at handshake
+        // time) — see the module header. THE ONE CALL SITE: moving this ingress onto the
+        // handshake-capture plane deletes this branch and webhooks/handshake-capture.ts together.
+        try {
+          await captureHandshakeSecret(
+            { refNamespace: NOTION_HANDSHAKE_REF_NAMESPACE, label: "Notion webhook (verification_token)", value: handshakeToken(rawBody) },
+            { log },
+          );
+        } catch (err) {
+          // The old line could not throw; this one reaches the vault, so it can (no AES key, store
+          // down). Never let that 500 the handshake — Notion would mark the endpoint unverified and
+          // the operator would be debugging the wrong thing. Report the FAILURE, never the value:
+          // an uncaptured secret is a rotation (recreate the subscription), a logged one is an
+          // incident. `err` is a store/crypto error and carries no secret material.
+          log(`handshake secret could NOT be captured (${err instanceof Error ? err.message : String(err)}) — the value is NOT logged; delete and recreate the Notion subscription once fixed.`);
+        }
+      } else if (outcome.action === "dispatched") {
+        log(`comment.created → dispatched (${outcome.detail})`);
+      } else if (outcome.action === "stopped") {
+        // OPE-989 — the audit row for the cancel itself (`turn.cancel_requested`) is already
+        // written by `cancelAnchoredTurn`; this is only the operator-facing line.
+        log(`stop comment → ${outcome.detail}`);
+      } else if (outcome.action === "ambient-disabled") {
+        // Was the generic `else` below: ONE log line, no row (OPE-205). `detail` is the surface
+        // key by construction (notion-webhook.ts's gate). The gate itself is unchanged — this
+        // only makes "the supervisor was never asked about this page" as answerable as the
+        // notion.no_reply row we already write when it IS asked and judges silence.
+        const surfaceKey = outcome.detail ?? "";
+        waitUntil(
+          auditAmbientSkip({
+            platform: "notion",
+            workspace: surfaceKey.split("/")[1] ?? "unknown",
+            surfaceKey,
+            log,
+          }),
+        );
+      } else if (outcome.action === "scope-refused") {
+        // OPE-502. A forged `workspace_id` is INVISIBLE on the surface — the agent simply never
+        // wakes — so the refusal writes a row as well as a line, the same reason notion-scope.ts
+        // gives for auditing a refused read. The reason string already names the page, the claimed
+        // workspace, the owning domain and both credentials, each bounded and control-stripped
+        // (notion-credentials.ts). Nothing of the fetched COMMENT is recorded.
+        log(`delivery scope-refused: ${outcome.detail}`);
+        waitUntil(
+          appendAudit({
+            org: deploymentOrg(),
+            platform: "notion",
+            // The claimed workspace is the field under suspicion, so it must not become an audit
+            // dimension. It rides in `detail` inside the reason instead.
+            workspace: "unknown",
+            action: "notion.scope_refused",
+            detail: { reason: outcome.detail ?? null, signer: outcome.signerCredentialId ?? null },
+          }),
+        );
+      } else if (outcome.action === "rejected") {
+        log(`delivery rejected (${outcome.status}): ${outcome.detail}`);
+        waitUntil(
+          appendAudit({
+            org: deploymentOrg(),
+            platform: "notion",
+            workspace: "unknown",
+            action: "notion.rejected",
+            detail: { status: outcome.status, reason: outcome.detail },
+          }),
+        );
+      } else {
+        log(`delivery ${outcome.action}${outcome.detail ? ` (${outcome.detail})` : ""}`);
+      }
+
+      // TELEMETRY ONLY. The delivery, dedupe mark and wake acceptance above remain synchronous;
+      // this content-free row is the sole deferred addition and cannot lengthen the ACK it measures.
+      // `unknown` dimensions are deliberate: the phase buckets need no workspace/page/comment,
+      // credential or message data, and the action + audit timestamp are enough to find a sample.
+      if (acceptedIngress) {
+        await settleNotionIngressDrain(acceptedIngress, notionIngressDisposition(outcome, eventPlaneRefused), {
+          org: deploymentOrg(),
+          store: getOperationalStore(),
+        });
+      }
+      const response = new Response(outcome.body, { status: outcome.status });
+      finishTiming(outcome.action);
+      return response;
+  },
+);
+
+export default defineChannel<NotionState, { state: NotionState }>({
+  kindHint: "notion",
+  // 🔴 QUEUE, NEVER STEER (OPE-412, OPE-1732). eve's default is `steer`, and a steer delivery
+  // carrying a message CANCELS the turn in flight — rolling session history back to the last
+  // completed model call while that call's tool side effects stay real and unrecorded. The policy
+  // resolves per RECEIVING channel, and every Notion comment session lives on THIS channel, so no
+  // other pin covers it. Notion ships no vendor factory, so `lint:turn-policy` cannot see this
+  // line either — `scripts/notion-turn-policy-test.ts` is what holds it. See
+  // packages/providers/slack/agent/channels/slack.ts for the full note.
+  turnPolicy: "queue",
+  state: { discussionId: null, pageId: null, workspaceId: null },
+  context(state) {
+    return { state };
+  },
+  routes: [
+    POST(ROUTE, notionWebhookRouteHandler),
+    POST(NOTION_INGRESS_DRAIN_PATH, notionWebhookRouteHandler),
+  ],
+  events: {
+    // Snapshot the PER-TURN reply target from the delivery's auth attributes. The seeded
+    // `state.discussionId` is applied by eve only when the session is CREATED — a resumed
+    // standing supervisor session keeps its original state, so relying on the seed would post
+    // every later reply into the FIRST discussion. But eve rewrites `session.auth.current`
+    // from the DELIVERY's auth on every delivery, and buildNotionAuth stows discussion_id /
+    // page_id / workspace_id there — so at turn.started they are THIS turn's real trigger
+    // (the exact pattern slack.ts's supervisor turn.started snapshot uses, T1.4). A missing
+    // discussion_id CLEARS the target (never carry a stale one forward) and message.completed
+    // fails safe: no target ⇒ it posts NOTHING, never into a guessed thread.
+    "turn.started"(_data, channel, ctx) {
+      const attrs = ctx?.session?.auth?.current?.attributes as Record<string, unknown> | undefined;
+      const s = (v: unknown): string | undefined => (typeof v === "string" && v.length > 0 ? v : undefined);
+      const discussionId = s(attrs?.discussion_id);
+      channel.state.oeReplyTarget = discussionId
+        ? ({
+            discussionId,
+            pageId: s(attrs?.page_id),
+            workspaceId: s(attrs?.workspace_id),
+            // OPE-467: the integration THIS delivery verified under. Snapshotted per turn like the
+            // rest of the target, so a standing supervisor session answers each doc under the
+            // integration that fetched that doc's comment.
+            credentialId: s(attrs?.credential_id),
+          } satisfies NotionReplyTarget)
+        : undefined;
+      // OPE-811: the OPE-508 REPLIER TIER snapshot is GONE from this handler, and nothing replaced
+      // it. It existed because `message.completed` posted the reply and holds no live auth ctx. The
+      // reply now leaves through the `reply` tool, whose own ctx resolves the grain and task label
+      // directly (tools/reply.ts `replierFor`), and reply-post.ts bakes the bracket at the choke
+      // point for every arm that cannot vary a display name — Notion included. One computation, at
+      // the seam that posts.
+    },
+    // SHOW A PARKED QUESTION OR APPROVAL PROMPT (OPE-1275). Before this, eve's `input.requested` —
+    // an `ask_question` mid-turn, or a `user-approval` turned `tool-approval` — reached this channel
+    // and NOTHING answered it: the generic `defineChannel` this module builds on (unlike the
+    // built-in `slackChannel`/`discordChannel`/`teamsChannel`/`githubChannel` every other native
+    // provider wraps) ships no default handler at all, so a parked Notion turn showed nothing in the
+    // discussion thread. The audit half (a request occurred) is a SEPARATE, surface-agnostic hook
+    // (hooks/native-input-audit.ts) — this handler owns only the post.
+    //
+    // Posts through `postHostNotice` — `postReply` with NO audit parameter to pass, same posture as
+    // the unified window's own bridge (channels/question-bridge.ts): a parked prompt is neither the
+    // model's answer nor an answer to anything yet, so it must not write the `reply.post` row the
+    // eval scorers join on.
+    //
+    // 🔴 AND IT REMEMBERS (OPE-1305), ONLY ON A POSTED QUESTION. The row keyed by this session's
+    // token is what turns the discussion's next comment into `respond([{requestId, text}])` in the
+    // `wake` dep above — the return leg a DELEGATED WORKER's question has no other way to reach. eve
+    // proxies the child's request up through the PARENT's channel adapter, so the prompt reaches this
+    // handler and lands in the thread, but the answer only reaches the child through an
+    // `inputResponses` entry whose `requestId` sits in the parent's proxy map; a plain message falls
+    // to `forSelf` and the parent eats it. Before this, OPE-1275 had traded an INVISIBLE unanswerable
+    // question for a VISIBLE one — better, and a new false promise: the human answered in the thread
+    // and believed they had answered. channels/notion-question-return.ts owns the leg and states the
+    // keying rule; the only thing this handler must get right is that a DROPPED question writes
+    // nothing, because nobody was shown anything that may be answered.
+    //
+    // NO WAKE ID RIDES THE ROW on this route, and none is missing: a wake id is minted on the
+    // SINGLE-WINDOW path only (notion-supervisor.ts), and a windowed wake never reaches this handler
+    // — it diverts to the unified channel, which runs its own leg. The field is an audit join, not a
+    // routing input, so its absence costs a join and nothing else.
+    //
+    // 🔴 AWAITED, NOT FLOATED (cold review, 2026-08-29). Every other `input.requested` handler in
+    // the tree awaits its post (channels/unified.ts, and linear.ts's delegation to eve's own
+    // default) — an un-awaited post here could still be in flight when this invocation's own
+    // response is sent and the host freezes it, turning the exact silence this handler exists to
+    // remove into an intermittent one that is harder to diagnose, because the SEPARATE audit hook
+    // (hooks/native-input-audit.ts) would still report the request as having happened.
+    async "input.requested"(data, channel) {
+      const target = channel.state.oeReplyTarget;
+      if (target === undefined) return; // no resolvable discussion this turn — nothing to post into.
+      const question = detectBridgeableInputRequest((data as { requests?: unknown } | undefined)?.requests);
+      if (!question) return; // eve's session-limit park (or an unrecognisable batch) — not ours.
+      try {
+        await postHostNotice({ platform: "notion", ...target }, renderQuestionForSurface(question));
+      } catch (err) {
+        log(`input-request could not be posted into discussion ${target.discussionId}: ${String(err)}`);
+        return; // NOT posted ⇒ NOT remembered: nothing was shown, so nothing may be consumed as its answer.
+      }
+      // POSTED ⇒ answerable. `rememberNotionQuestion` never throws; a `false` means this discussion
+      // cannot answer after all (no usable token, or an unwritable store), which is the pre-OPE-1305
+      // behaviour and is said out loud rather than left to look like success.
+      const remembered = await rememberNotionQuestion({
+        org: deploymentOrg(),
+        namespacedToken: channel.continuation?.token,
+        requestId: question.requestId,
+        discussionId: target.discussionId,
+      });
+      log(
+        remembered
+          ? `question bridge: posted ${question.toolName} (${question.kind}) into discussion ${target.discussionId} — answerable there (${question.requestId})`
+          : `question bridge: posted ${question.toolName} (${question.kind}) into discussion ${target.discussionId} — NOT answerable (no outstanding-question row); a delegated worker's question will stay parked`,
+      );
+    },
+    // Deliver the supervisor's reply back into the SAME Notion discussion thread — OR audit its
+    // judged SILENCE. finalMessageActionForTurn is the shared decision every surface calls (it
+    // honours BOTH the NO_REPLY sentinel and the audited `no_reply` TOOL). A "silent" turn writes
+    // a notion.no_reply audit row (parity with Slack — every silence is durable and answerable);
+    // a "buffer-tool-status" turn (mid-turn tool call) is not terminal and is left alone.
+    // The reply targets the PER-TURN snapshot (turn.started above), falling back to the seeded
+    // state only for a session's FIRST turn shape where both agree anyway; audit rows fall back
+    // to the seeded page/workspace when the snapshot omits them (context, not a post target).
+    async "message.completed"(data, channel, ctx) {
+      const sessionId = ctx?.session?.id; // stamped into the terminal audit rows → joins to the transcript
+      const action = finalMessageActionForTurn(data.finishReason, data.message);
+      if (action.kind === "buffer-tool-status") return; // not terminal — check BEFORE consuming below
+      const target = channel.state.oeReplyTarget;
+      const discussionId = target?.discussionId;
+      // Read-and-reset the reply-tool signal on every TERMINAL completion (silent or post) — it must
+      // never bleed into the next turn — mirrors slack.ts's consume-at-top. Feeds the shared arm's
+      // stray-prose-leak accounting on the unified path. TURN-ID KEYED (OPE-805): only THIS turn's
+      // own mark answers true — see reply-signal.ts's header.
+      const repliedThisTurn = consumeSupervisorReplyMark(ctx);
+      const org = deploymentOrg();
+      const workspace = target?.workspaceId ?? channel.state.workspaceId ?? "unknown";
+      // The SHARED ticketing completion arm (channels/supervisor-complete.ts). It POSTS NOTHING since
+      // OPE-811: reply-post.ts's notion arm posts into the per-delivery discussion binding on ANY
+      // Notion session, so the `reply` tool is the delivery on a per-doc supervisor turn exactly as
+      // it already was on a windowed one, and the manifest's own midTurnPost is what the gate reads.
+      //
+      // 🔴 THE `oeUnified` CONDITION IS GONE, AND THAT IS THE POINT. It used to pass midTurnPost=false
+      // on a NON-windowed per-doc session, so the gate failed open there and the turn's closing text
+      // posted via createCommentReply. That was the surface's last prose delivery channel, and it made
+      // one seat's delivery contract depend on its domain's topology — the divergence this ticket
+      // removes. (OPE-787's warning still holds for anyone reading `oeUnified`: it is grain.unified,
+      // true for EVERY windowed grain including a solo per-doc window, never "cross-surface".)
+      // The notion.dispatched row above + replied/no_reply/turn.supervisor_prose_dropped = the
+      // "a row closes a row" family — every terminal outcome closes the dispatched row.
+      await completeSupervisorTurn({
+        action,
+        ...(sessionId ? { sessionId } : {}),
+        repliedViaTool: repliedThisTurn,
+        midTurnPost: capabilitiesForPlatform("notion").midTurnPost,
+        noReplyAction: "notion.no_reply",
+        repliedAction: "notion.replied",
+        contextRow: { org, platform: "notion", workspace, surface: target?.pageId ?? channel.state.pageId ?? discussionId ?? "unknown" },
+        repliedRow: { org, platform: "notion", workspace, surface: target?.pageId ?? channel.state.pageId ?? discussionId },
+        silentAnchor: { discussionId: discussionId ?? channel.state.discussionId },
+        droppedAnchor: { discussionId: discussionId ?? null },
+        repliedAnchor: { discussionId },
+        log: (m) => log(m),
+      });
+    },
+  },
+});
+
+// Re-parse the handshake token purely to hand it to captureHandshakeSecret above (handleNotion
+// Delivery already consumed it; this keeps that function's return type clean). Returns "" rather
+// than a placeholder string on a shape it can't read: capture must never store a sentinel as though
+// it were a key. Unreachable in practice — `action === "handshake"` implies parseVerification
+// Handshake already succeeded on this exact body — but a stored lie is worse than a skipped capture.
+function handshakeToken(rawBody: string): string {
+  try {
+    const t = (JSON.parse(rawBody) as { verification_token?: unknown }).verification_token;
+    return typeof t === "string" ? t : "";
+  } catch {
+    return "";
+  }
+}