@open-everywhere/provider-notion 0.1.0

package/agent/channels/notion-identity.ts

@@ -0,0 +1,271 @@
+// Pure Notion→OpenEverywhere identity capture. The Notion channel (notion.ts) calls
+// these to stow RAW Notion facts (workspace / page / discussion / comment ids + the
+// commenting actor) into the session auth context's `attributes`. The INTERPRETATION of
+// those facts into mode/visibility lives here too — notionMode/notionVisibility — so the
+// test can call them and the security-critical "is this private?" decision sits in one
+// tested place. This file imports no eve types (only a type-only alias, erased at
+// compile), so it's trivially unit-testable.
+//
+// SILO CHOICE (why surface = the PAGE, not the workspace and not the comment thread):
+// the surface-fit criterion is "the persistent multi-instance container, NOT the
+// invocation point". Notion's tiers map onto ours exactly like Linear's do:
+//   Notion workspace  ≈ Linear organization ≈ our `workspace` (the tenant tier)
+//   Notion PAGE       ≈ Linear TEAM         ≈ our `surface`   (the silo — one page
+//                                              hosts many discussion threads over time,
+//                                              just as a team hosts many issues)
+//   Notion discussion ≈ Linear issue        ≈ the conversation ANCHOR (post-back target
+//                                              + continuation key), NOT the partition key
+// So a page's accumulated memory is reused across every comment thread on it, while a
+// bare comment thread (which comes and goes) is only the reply anchor. This mirrors Slack
+// too: surface = channel, the thread is the anchor. (A finer teamspace→page two-level silo
+// is a future refinement; page is the launch grain, matching the Linear team grain.)
+
+import type { SessionMode, Visibility, BindableContext, IdentityMapper, RawIdentity } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** Structural match for eve's SessionAuthContext (attributes + principal). */
+export interface OpenEverywhereNotionAuth {
+  readonly authenticator: string;
+  readonly principalId: string;
+  readonly principalType: string;
+  readonly attributes: Record<string, string>;
+}
+
+export interface NotionIdentityInput {
+  /** Notion workspace id — becomes the OpenEverywhere `workspace` (tenant tier). */
+  readonly workspaceId?: string;
+  /** The page the comment lives on — becomes the OpenEverywhere `surface` (the silo grain). */
+  readonly pageId?: string;
+  /** The discussion thread the comment belongs to — the post-back anchor (create-comment
+   *  targets `discussion_id`), NOT the partition key. */
+  readonly discussionId?: string;
+  /** The specific comment that triggered this turn — for audit/provenance. */
+  readonly commentId?: string;
+  /** The acting Notion user (comment author), if known — becomes the principal. */
+  readonly principalId?: string;
+  /**
+   * The Notion channel credential this DELIVERY was selected to run under (OPE-467) — the
+   * integration whose secret verified it. Stowed so every reply for this turn posts under the SAME
+   * integration that fetched the comment. Without it a reply re-derives the credential from the
+   * page's domain binding alone, and a page shared with an integration its domain does not bind
+   * would fetch under one key and answer under another whose integration was never shared the page
+   * — `createCommentReply` throws and the agent silently never answers.
+   *
+   * HOST-SET (§AUTH-ATTRIBUTE PROVENANCE): built from the HMAC gate's verdict, never from the
+   * comment body, so it cannot be forged into naming another integration's credential.
+   */
+  readonly credentialId?: string;
+  /**
+   * The declared TRUST ROOT this page sits under, canonical form, when the ancestor walk matched one
+   * (OPE-492; channels/notion-ancestry-trust.ts resolveNotionDeliveryTrust). Present ⇒ the operator
+   * declared a page above this one internal, so {@link bindNotion} binds `internal` instead of the
+   * fail-closed `external`. Absent on every untrusted verdict, which is every verdict on a
+   * deployment that declares no roots.
+   *
+   * HOST-SET (§AUTH-ATTRIBUTE PROVENANCE): the webhook core resolves it from Notion's own parent
+   * chain under the VERIFIED credential, never from the comment body, so it cannot be forged into
+   * claiming a root.
+   */
+  readonly trustRoot?: string;
+}
+
+/** Build the auth context OpenEverywhere dispatches with — raw facts as string attributes. */
+export function buildNotionAuth(input: NotionIdentityInput): OpenEverywhereNotionAuth {
+  const attributes: Record<string, string> = {};
+  if (input.workspaceId) attributes.workspace_id = input.workspaceId;
+  if (input.pageId) attributes.page_id = input.pageId;
+  if (input.discussionId) attributes.discussion_id = input.discussionId;
+  if (input.commentId) attributes.comment_id = input.commentId;
+  if (input.credentialId) attributes.credential_id = input.credentialId;
+  if (input.trustRoot) attributes.trust_root = input.trustRoot;
+  return {
+    authenticator: "notion",
+    principalId: input.principalId ?? "",
+    principalType: "notion-user",
+    attributes,
+  };
+}
+
+/**
+ * The workspaceKey a Notion surface resolves to (`notion/<workspace id>`) — the value an
+ * operator lists in agent/identity/surfaces.ts to vouch a whole Notion workspace
+ * as internal (which lets its pages' learnings flow to shared memory despite the
+ * fail-closed default below). Takes the raw workspace id as Notion reports it on the
+ * webhook, so the operator pastes what they see. Notion ids are UUIDs, already within the
+ * binding's `seg` charset (hyphens allowed), so no encoding is needed. notion-test.ts pins
+ * this key against the one bindFrom actually produces.
+ */
+export function notionWorkspaceKey(workspaceId: string): string {
+  return `notion/${workspaceId}`;
+}
+
+/**
+ * The fully-qualified surfaceKey a Notion page resolves to — `notion/<workspace>/<page>` — the
+ * SAME shape resolvePartition(ctx) produces for a bound Notion session (memory/partition.ts:
+ * `platform/workspace/surface`, surface = the page). The ambient-supervisor gate + the
+ * channel_session registry are keyed by this, so the webhook core (which runs BEFORE any eve
+ * binding) must compute the identical key. Falls back through discussion → "unknown" the same way
+ * bindNotion picks its surface, so an under-identified event still keys to a stable string.
+ */
+export function notionSurfaceKey(workspaceId: string | undefined, surface: string | undefined): string {
+  return `notion/${workspaceId ?? "unknown"}/${surface ?? "unknown"}`;
+}
+
+/**
+ * The CONVERSATION key the stop registry keys a Notion turn by (OPE-989) — `<workspace>/<page>`.
+ * ONE derivation, used by BOTH sides of the affordance: {@link bindNotion} writes it onto the
+ * anchor row at turn start (as `anchorChannelId`), and the stop leg (channels/notion-stop.ts)
+ * rebuilds it from the fetched comment. Two spellings of this key would make the arm silently miss
+ * — the same discipline githubConversationKey documents.
+ *
+ * THE PAGE, NOT THE DISCUSSION. The Notion doc-session is page-scoped (notion-supervisor.ts's
+ * `notionSupervisorToken` keys the standing session by page, not by discussion — "a page-scoped
+ * standing session aware of all the doc's discussions"), so the conversation a stop trigger can
+ * name is the page, mirroring how a GitHub stop names the issue/PR and a Teams stop names the
+ * reply chain.
+ *
+ * Returns undefined on any missing part — never "unknown" (unlike {@link notionSurfaceKey}, which
+ * exists for a different purpose: a STABLE partition key even under-identified). A partial anchor
+ * key would let two different under-identified deliveries collide and cancel each other's turns.
+ */
+export function notionConversationKey(workspaceId: string | undefined, pageId: string | undefined): string | undefined {
+  return workspaceId && pageId ? `${workspaceId}/${pageId}` : undefined;
+}
+
+/**
+ * The inverse of {@link notionConversationKey} — split the `<workspace>/<page>` string back into its
+ * two Notion ids. Undefined on anything that is not exactly two non-empty segments: a malformed or
+ * partial address must never resolve to a guessed page. Notion ids are UUIDs (no `/`), so splitting
+ * on the first slash is exact — there is no ambiguity to resolve.
+ *
+ * The one caller today is `notion-message-ops.ts` (OPE-1043): `SurfaceMessageOps.postText`/
+ * `editMessage` are handed only the composed `channelId` (this key), never the two ids apart, so a
+ * transport that needs the page or the workspace on its own has to parse it back out. Kept beside
+ * the composer rather than in that file, for the same reason the composer's own doc states: one
+ * derivation, read by both sides, so the write and the read can never drift into two spellings.
+ */
+export function parseNotionConversationKey(channelId: string): { readonly workspaceId: string; readonly pageId: string } | undefined {
+  const i = channelId.indexOf("/");
+  if (i <= 0 || i === channelId.length - 1) return undefined;
+  const workspaceId = channelId.slice(0, i);
+  const pageId = channelId.slice(i + 1);
+  return workspaceId.length > 0 && pageId.length > 0 ? { workspaceId, pageId } : undefined;
+}
+
+/**
+ * Notion has NO 1:1 DM primitive — every comment is on a shared page/discussion — so a
+ * Notion surface is always `channel` mode. Total function (no input) kept for symmetry
+ * with the other platforms' mode helpers and so the mapper reads the same shape.
+ */
+export function notionMode(): SessionMode {
+  return "channel";
+}
+
+/**
+ * Notion facts → visibility. FAIL CLOSED — Notion is ALWAYS private.
+ * An internal integration only sees pages EXPLICITLY shared with it, and the webhook
+ * carries no cheap, reliable "this page is workspace-public / world-visible" bit — the
+ * `accessible_by` array is a coarse who-can-see list, not a public/private classifier.
+ * With no positive signal that a page is a broadly-shared internal space, a surface's
+ * learnings must never flow up to a shared (workspace) tier: every Notion page stays
+ * surface-tier private. A future maintainer who finds a positive workspace-visible signal
+ * (or enriches page permissions from the API) flips this — until then it fails closed.
+ */
+export function notionVisibility(): Visibility {
+  return "private";
+}
+
+// --- the identity MAPPER (moved out of core identity/binding.ts in OPE-114 stage 3) ---------
+// A Notion comment lives on a PAGE inside a Notion workspace, in a discussion thread. The
+// silo grain is the PAGE (the persistent container that hosts many discussion threads over
+// time — the Linear TEAM / Slack channel analog), NOT the discussion (which is the reply
+// anchor, like a Linear issue / Slack thread ts). So: workspace = workspace_id, surface =
+// page_id (discussion is the post-back target, not the partition key), mode = channel
+// (Notion has no 1:1 DM primitive). Raw facts are stowed by buildNotionAuth above;
+// mode/visibility interpretation lives in this file (the one tested place) — visibility FAILS
+// CLOSED to private (Notion exposes no reliable world-/workspace-public signal).
+//
+// The two attribute helpers are LOCAL COPIES of core binding.ts's module-private probes (attr /
+// authPrincipalId) — deliberately not barrel ports: they are three-line structural reads over
+// the public BindableContext shape, and a mapper author outside core is expected to read its own
+// platform's attributes itself (the barrel exposes the CONTRACT — BindableContext / RawIdentity /
+// registerIdentityMapper — not core's private conveniences).
+
+type AuthAttrs = Readonly<Record<string, string | readonly string[]>> | undefined;
+
+function notionAuthOf(ctx: BindableContext): { attributes?: AuthAttrs; principalId?: string } | null {
+  return ctx.session?.auth?.current ?? ctx.session?.auth?.initiator ?? null;
+}
+
+function notionAttr(a: AuthAttrs, keys: readonly string[]): string | undefined {
+  if (!a) return undefined;
+  for (const k of keys) {
+    const v = a[k];
+    if (typeof v === "string" && v.length > 0) return v;
+    if (Array.isArray(v) && typeof v[0] === "string" && v[0].length > 0) return v[0];
+  }
+  return undefined;
+}
+
+export const bindNotion: IdentityMapper = (ctx): RawIdentity => {
+  const auth = notionAuthOf(ctx);
+  const a = auth?.attributes;
+  const workspaceId = notionAttr(a, ["workspace_id", "workspaceId"]);
+  // Surface = the PAGE (silo grain); fall back to the discussion, then the comment, so a
+  // session always keys to a stable surface even on an under-identified event.
+  const surface =
+    notionAttr(a, ["page_id", "pageId"]) ??
+    notionAttr(a, ["discussion_id", "discussionId"]) ??
+    notionAttr(a, ["comment_id", "commentId"]);
+  const discussionId = notionAttr(a, ["discussion_id", "discussionId"]);
+  const pageId = notionAttr(a, ["page_id", "pageId"]);
+  // The delivery's selected integration (OPE-467), so `reply` posts under the credential that
+  // fetched. Absent on a session that predates the stamp ⇒ the reply arm falls back to the page's
+  // domain binding, which is the pre-OPE-467 behaviour.
+  const credentialId = notionAttr(a, ["credential_id", "credentialId"]);
+  // The ANCESTOR-WALK verdict the webhook core resolved for THIS delivery (OPE-492). Present only
+  // when the page sits under a declared trust root; the stamp names the root that matched.
+  const trustRoot = notionAttr(a, ["trust_root", "trustRoot"]);
+  const principal = auth?.principalId;
+  return {
+    workspace: workspaceId,
+    surface,
+    mode: notionMode(),
+    visibility: notionVisibility(),
+    // Notion refutes no author and reports no room-grain external signal, so trust here is ALWAYS an
+    // operator declaration — never a platform verdict. Two declarations reach it, and this is the
+    // ONE the platform mapper carries: the page sits under a declared TRUST ROOT, walked and matched
+    // at ingestion (channels/notion-ancestry-trust.ts). The other is the flat per-surface vouch
+    // (identity/surfaces.ts), which bindFrom applies one rung lower.
+    //
+    // POSITIVE-ONLY. No root matched ⇒ undefined, NEVER "external": bindFrom must still fall through
+    // to the per-surface vouch and then to the fail-closed default. Returning "external" here would
+    // out-rank the operator's own `defineSurface` line and silently switch off shared memory on every
+    // Notion page of a deployment that declares no roots.
+    trust: trustRoot ? ("internal" as const) : undefined,
+    principalId: (principal && principal.length > 0 ? principal : undefined) ?? notionAttr(a, ["user_id", "userId"]),
+    // Post-back targets the DISCUSSION thread (create-comment's discussion_id), with the page
+    // riding along. Not a thread ts — Notion replies key off discussion_id, carried on the
+    // session state the channel stashes, so this target is for routine/proactive use.
+    target: discussionId ? { discussionId, ...(pageId ? { pageId } : {}), ...(credentialId ? { credentialId } : {}) } : undefined,
+    // THE STOP REGISTRY'S ADDRESS FOR THIS TURN (OPE-989). A Notion doc-session is PAGE-scoped
+    // (notionSupervisorToken keys the standing session by page), so that is what a stop directive
+    // posted on the page can name. It cannot ride `target`: that object composes the REPLY target
+    // (the discussion), a different grain that changes on every comment.
+    //
+    // Notion pushes no reaction webhook (comment.created/updated/deleted is the whole comment event
+    // catalogue — developers.notion.com/reference/webhooks-events-delivery, read 2026-08-23), so the
+    // trigger on this surface is a bare `stop` comment read at the ingress — see
+    // channels/notion-stop.ts. The key it resolves by is this one.
+    ...(notionConversationKey(workspaceId, pageId) ? { anchorChannelId: notionConversationKey(workspaceId, pageId) } : {}),
+    // THE ENGAGEMENT REGISTRY'S ADDRESS FOR THIS TURN (OPE-1501) — the SAME page key, and
+    // deliberately the same derivation rather than a second spelling of it. `stand_down` marks
+    // `binding.engagementKey ?? binding.threadTs`, and Notion carries no `threadTs`, so without this
+    // field the verb found no anchor and refused on every Notion turn.
+    //
+    // THE PAGE, NOT THE DISCUSSION, for the reason {@link notionConversationKey} states: the doc
+    // session is page-scoped and aware of all the page's discussions, so a person asking the agent
+    // to stop is asking it to stop on the page. A per-discussion mark would leave the same standing
+    // session answering the discussion next door.
+    ...(notionConversationKey(workspaceId, pageId) ? { engagementKey: notionConversationKey(workspaceId, pageId) } : {}),
+  };
+};

package/agent/channels/notion-ingress-drain.ts

@@ -0,0 +1,289 @@
+// DURABLE NOTION INGRESS DRAIN — the authenticated, fenced consumer of rows admitted by
+// notion-ingress.ts. The public webhook stores a projected provider envelope and returns; both its
+// immediate nudge and the minute recovery schedule send only the row key through this internal
+// HMAC route. The payload never leaves the operational store.
+
+import { createHmac, randomUUID } from "node:crypto";
+
+import {
+  getOrMintSelfSecret,
+  readCappedBody,
+  selfDispatchBaseUrl,
+  selfSecretsArmed,
+  verifyWebhookSignature,
+  type ClaimedIngressDelivery,
+  type IngressDeliveryKey,
+  type OperationalStore,
+} from "@open-everywhere/core/agent/adapter-api.js";
+
+import { decodeNotionIngressPayload, NOTION_INGRESS_SOURCE, type NotionIngressKey } from "./notion-ingress.js";
+
+export const NOTION_INGRESS_DRAIN_PATH = "/eve/v1/notion/drain";
+export const NOTION_INGRESS_DRAIN_SIGNATURE_HEADER = "x-oe-notion-drain-signature";
+const NOTION_INGRESS_DRAIN_SECRET_ENV = "OE_NOTION_INGRESS_DRAIN_SECRET";
+export const NOTION_COMMENT_DISPATCH_SOURCE = "notion-comment-dispatch";
+// Comment ids are globally unique inside Notion. Keep this authority constant so the same comment
+// arriving from two subscriptions shares ONE dispatch lease, matching the legacy OPE-1906 guard.
+export const NOTION_COMMENT_DISPATCH_AUTHORITY = "notion";
+const NOTION_INGRESS_LEASE_MS = 5 * 60_000;
+const NOTION_INGRESS_RETRY_MS = NOTION_INGRESS_LEASE_MS + 1_000;
+const NOTION_INGRESS_TOMBSTONE_MS = 24 * 60 * 60_000;
+const NOTION_COMMENT_DISPATCH_TOMBSTONE_MS = 10 * 60_000;
+const NOTION_INGRESS_DRAIN_MAX_BODY_BYTES = 16 * 1024;
+const NOTION_INGRESS_DRAIN_MAX_SKEW_MS = 5 * 60_000;
+const NOTION_INGRESS_DRAIN_BATCH = 25;
+
+interface DrainEnvelope {
+  readonly authorityId: string;
+  readonly deliveryId: string;
+  readonly issuedAt: number;
+}
+
+export interface NotionIngressDrainKey extends NotionIngressKey {}
+
+export interface AcceptedNotionIngressDrain {
+  readonly key: NotionIngressDrainKey;
+  readonly claim: ClaimedIngressDelivery;
+  readonly rawBody: string;
+  readonly signerCredentialId: string;
+}
+
+export type NotionIngressDisposition = "complete" | "discard" | "retry";
+
+export interface NotionCommentDispatchGuard {
+  readonly claim: (commentId: string) => Promise<boolean>;
+  readonly complete: (commentId: string) => Promise<void>;
+}
+
+export interface AcceptNotionIngressDrainDeps {
+  readonly org: string;
+  readonly store: OperationalStore;
+  readonly secret?: string;
+  readonly now?: () => Date;
+  readonly claimId?: () => string;
+}
+
+function nonEmpty(value: unknown, max = 512): string | undefined {
+  return typeof value === "string" && value.length > 0 && value.length <= max ? value : undefined;
+}
+
+function parseEnvelope(value: unknown): DrainEnvelope | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const row = value as Record<string, unknown>;
+  const authorityId = nonEmpty(row.authorityId);
+  const deliveryId = nonEmpty(row.deliveryId);
+  const issuedAt = row.issuedAt;
+  if (!authorityId || !deliveryId || typeof issuedAt !== "number" || !Number.isFinite(issuedAt)) return undefined;
+  return { authorityId, deliveryId, issuedAt };
+}
+
+export function signNotionIngressDrainBody(secret: string, body: string): string {
+  return `sha256=${createHmac("sha256", secret).update(body, "utf8").digest("hex")}`;
+}
+
+async function drainSecret(injected?: string): Promise<string | undefined> {
+  if (injected !== undefined) return injected;
+  if (!selfSecretsArmed()) return undefined;
+  return getOrMintSelfSecret(NOTION_INGRESS_DRAIN_SECRET_ENV);
+}
+
+/** Cheap public-ACK precondition: recovery can authenticate and reach this deployment. */
+export function notionIngressDrainAvailable(): boolean {
+  return selfSecretsArmed() && selfDispatchBaseUrl() !== undefined;
+}
+
+/** Authenticate an internal row-key request and atomically claim its exact org-scoped row. */
+export async function acceptNotionIngressDrainRequest(
+  req: Request,
+  deps: AcceptNotionIngressDrainDeps,
+): Promise<{ readonly accepted: AcceptedNotionIngressDrain } | { readonly response: Response }> {
+  const read = await readCappedBody(req, NOTION_INGRESS_DRAIN_MAX_BODY_BYTES);
+  if ("tooLarge" in read) return { response: new Response("payload too large", { status: 413 }) };
+  const secret = await drainSecret(deps.secret);
+  if (!secret) return { response: new Response("not found", { status: 404 }) };
+  if (!verifyWebhookSignature(secret, read.body, req.headers.get(NOTION_INGRESS_DRAIN_SIGNATURE_HEADER))) {
+    return { response: new Response("unauthorized", { status: 401 }) };
+  }
+  let envelope: DrainEnvelope | undefined;
+  try {
+    envelope = parseEnvelope(JSON.parse(read.body));
+  } catch {
+    // handled below
+  }
+  if (!envelope) return { response: new Response("bad request", { status: 400 }) };
+  const now = (deps.now ?? (() => new Date()))();
+  if (Math.abs(now.getTime() - envelope.issuedAt) > NOTION_INGRESS_DRAIN_MAX_SKEW_MS) {
+    return { response: new Response("unauthorized", { status: 401 }) };
+  }
+  const key: NotionIngressDrainKey = {
+    source: NOTION_INGRESS_SOURCE,
+    authorityId: envelope.authorityId,
+    deliveryId: envelope.deliveryId,
+  };
+  const staleBefore = new Date(now.getTime() - NOTION_INGRESS_LEASE_MS).toISOString();
+  const claim = await deps.store.claimIngressDelivery(
+    deps.org,
+    key,
+    (deps.claimId ?? randomUUID)(),
+    now.toISOString(),
+    staleBefore,
+  );
+  // A duplicate nudge, active lease or completed tombstone is already safely represented in the
+  // store. Return 200 so the self-client does not amplify it; the minute scan handles stale work.
+  if (!claim) return { response: new Response("ok", { status: 200 }) };
+  const payload = decodeNotionIngressPayload(claim.payloadJson);
+  if (!payload) {
+    await deps.store.releaseIngressDelivery(
+      deps.org,
+      key,
+      claim.claimId,
+      new Date(now.getTime() + NOTION_INGRESS_RETRY_MS).toISOString(),
+    );
+    return { response: new Response("stored payload invalid", { status: 500 }) };
+  }
+  return {
+    accepted: {
+      key,
+      claim,
+      rawBody: JSON.stringify(payload.event),
+      signerCredentialId: key.authorityId,
+    },
+  };
+}
+
+/** Finish one primary claim according to the processor's explicit semantic result. */
+export async function settleNotionIngressDrain(
+  accepted: AcceptedNotionIngressDrain,
+  disposition: NotionIngressDisposition,
+  deps: Pick<AcceptNotionIngressDrainDeps, "org" | "store" | "now">,
+): Promise<void> {
+  const now = (deps.now ?? (() => new Date()))();
+  if (disposition === "discard") {
+    await deps.store.discardIngressDelivery(deps.org, accepted.key, accepted.claim.claimId);
+    return;
+  }
+  if (disposition === "retry") {
+    await deps.store.releaseIngressDelivery(
+      deps.org,
+      accepted.key,
+      accepted.claim.claimId,
+      new Date(now.getTime() + NOTION_INGRESS_RETRY_MS).toISOString(),
+    );
+    return;
+  }
+  await deps.store.completeIngressDelivery(
+    deps.org,
+    accepted.key,
+    accepted.claim.claimId,
+    now.toISOString(),
+    new Date(now.getTime() + NOTION_INGRESS_TOMBSTONE_MS).toISOString(),
+  );
+}
+
+/**
+ * A comment-level guard for the crash seam between "accepted by Eve" and primary-row completion.
+ * Its lease is deliberately the same length as the primary retry delay: a retry never mistakes an
+ * active pre-dispatch lease for a completed duplicate. A stale lease is stolen and may duplicate
+ * after an ambiguous post-dispatch crash, which is the honest at-least-once side of the choice.
+ */
+export function createNotionCommentDispatchGuard(input: {
+  readonly org: string;
+  readonly store: OperationalStore;
+  readonly now?: () => Date;
+  readonly claimId?: () => string;
+}): NotionCommentDispatchGuard {
+  let held: { key: IngressDeliveryKey; claimId: string } | undefined;
+  return {
+    async claim(commentId) {
+      const now = (input.now ?? (() => new Date()))();
+      const key: IngressDeliveryKey = {
+        source: NOTION_COMMENT_DISPATCH_SOURCE,
+        authorityId: NOTION_COMMENT_DISPATCH_AUTHORITY,
+        deliveryId: commentId,
+      };
+      await input.store.enqueueIngressDelivery(input.org, {
+        ...key,
+        payloadJson: JSON.stringify({ schemaVersion: 1 }),
+        receivedAt: now.toISOString(),
+      });
+      const claim = await input.store.claimIngressDelivery(
+        input.org,
+        key,
+        (input.claimId ?? randomUUID)(),
+        now.toISOString(),
+        new Date(now.getTime() - NOTION_INGRESS_LEASE_MS).toISOString(),
+      );
+      if (!claim) return false;
+      held = { key, claimId: claim.claimId };
+      return true;
+    },
+    async complete(commentId) {
+      if (!held || held.key.deliveryId !== commentId) throw new Error("Notion dispatch guard was not claimed");
+      const now = (input.now ?? (() => new Date()))();
+      const completed = await input.store.completeIngressDelivery(
+        input.org,
+        held.key,
+        held.claimId,
+        now.toISOString(),
+        new Date(now.getTime() + NOTION_COMMENT_DISPATCH_TOMBSTONE_MS).toISOString(),
+      );
+      if (!completed) throw new Error("Notion dispatch guard completion lost its lease");
+      held = undefined;
+    },
+  };
+}
+
+export interface PostNotionIngressDrainDeps {
+  readonly secret?: string;
+  readonly baseUrl?: string;
+  readonly fetchImpl?: typeof fetch;
+  readonly now?: () => Date;
+}
+
+/** Post one content-free row key to this deployment's private drain route. */
+export async function postNotionIngressDrain(
+  key: NotionIngressDrainKey,
+  deps: PostNotionIngressDrainDeps = {},
+): Promise<void> {
+  const base = deps.baseUrl ?? selfDispatchBaseUrl();
+  const secret = await drainSecret(deps.secret);
+  if (!base || !secret) throw new Error("Notion ingress drain is unavailable");
+  const body = JSON.stringify({
+    authorityId: key.authorityId,
+    deliveryId: key.deliveryId,
+    issuedAt: (deps.now ?? (() => new Date()))().getTime(),
+  } satisfies DrainEnvelope);
+  const response = await (deps.fetchImpl ?? fetch)(`${base}${NOTION_INGRESS_DRAIN_PATH}`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      [NOTION_INGRESS_DRAIN_SIGNATURE_HEADER]: signNotionIngressDrainBody(secret, body),
+    },
+    body,
+    signal: AbortSignal.timeout(20_000),
+  });
+  if (!response.ok) throw new Error(`Notion ingress drain returned ${response.status}`);
+}
+
+/** One recovery tick. A failed self-hop leaves the row pending for the next minute. */
+export async function recoverNotionIngress(
+  org: string,
+  store: OperationalStore,
+  deps: PostNotionIngressDrainDeps & { readonly now?: () => Date } = {},
+): Promise<{ readonly due: number; readonly posted: number; readonly failed: number }> {
+  const now = (deps.now ?? (() => new Date()))();
+  const due = await store.listDueIngressDeliveries(
+    org,
+    NOTION_INGRESS_SOURCE,
+    now.toISOString(),
+    new Date(now.getTime() - NOTION_INGRESS_LEASE_MS).toISOString(),
+    NOTION_INGRESS_DRAIN_BATCH,
+  );
+  const results = await Promise.allSettled(due.map((key) => postNotionIngressDrain({
+    source: NOTION_INGRESS_SOURCE,
+    authorityId: key.authorityId,
+    deliveryId: key.deliveryId,
+  }, deps)));
+  const posted = results.filter((result) => result.status === "fulfilled").length;
+  return { due: due.length, posted, failed: due.length - posted };
+}