@open-everywhere/provider-notion 0.1.0

package/agent/channels/notion-ingress.ts

@@ -0,0 +1,182 @@
+// DURABLE NOTION INGRESS — the authenticated acceptance boundary in front of the expensive
+// comment enrichment and Eve dispatch path. A 200 from this module means the verified, projected
+// event is in the operational store. `waitUntil` is only a low-latency nudge; recovery comes from
+// the persisted row and the minute drain schedule, never from the lifetime of this invocation.
+
+import { gateNotionDeliveryAcross, parseVerificationHandshake, type NotionSigningKey } from "./notion-api.js";
+
+export const NOTION_INGRESS_SOURCE = "notion";
+const NOTION_INGRESS_SCHEMA_VERSION = 1 as const;
+export const NOTION_INGRESS_MAX_BODY_BYTES = 256 * 1024;
+
+export interface ProjectedNotionEvent {
+  readonly id: string;
+  readonly timestamp?: string;
+  readonly type?: string;
+  readonly event_type?: string;
+  readonly workspace_id?: string;
+  readonly entity?: { readonly id?: string; readonly type?: string };
+  readonly data?: {
+    readonly page_id?: string;
+    readonly parent?: { readonly id?: string; readonly type?: string };
+    readonly updated_blocks?: readonly { readonly id?: string }[];
+  };
+  readonly authors?: readonly { readonly id?: string; readonly type?: string }[];
+}
+
+export interface NotionIngressPayload {
+  readonly schemaVersion: typeof NOTION_INGRESS_SCHEMA_VERSION;
+  readonly event: ProjectedNotionEvent;
+}
+
+export interface NotionIngressKey {
+  readonly source: typeof NOTION_INGRESS_SOURCE;
+  readonly authorityId: string;
+  readonly deliveryId: string;
+}
+
+export interface NotionIngressWrite extends NotionIngressKey {
+  readonly payloadJson: string;
+  readonly receivedAt: string;
+}
+
+export interface AcknowledgeNotionIngressDeps {
+  readonly org: string;
+  readonly signingKeys: readonly NotionSigningKey[];
+  readonly allowUnverified: boolean;
+  readonly enqueue: (org: string, write: NotionIngressWrite) => Promise<boolean>;
+  /** The internal recovery route has both durable secret custody and a resolvable own URL. */
+  readonly drainAvailable: boolean;
+  readonly drain: (key: NotionIngressKey) => Promise<void>;
+  readonly waitUntil: (promise: Promise<unknown>) => void;
+  readonly now?: () => Date;
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function record(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Readonly<Record<string, unknown>>)
+    : undefined;
+}
+
+/** Project exactly the fields consumed by the conversational and structural processors. */
+function projectNotionIngressEvent(value: unknown): ProjectedNotionEvent | undefined {
+  const input = record(value);
+  const id = text(input?.id);
+  if (!input || !id) return undefined;
+
+  const entityIn = record(input.entity);
+  const entityId = text(entityIn?.id);
+  const entityType = text(entityIn?.type);
+  const entity = entityIn ? { ...(entityId ? { id: entityId } : {}), ...(entityType ? { type: entityType } : {}) } : undefined;
+
+  const dataIn = record(input.data);
+  const parentIn = record(dataIn?.parent);
+  const parentId = text(parentIn?.id);
+  const parentType = text(parentIn?.type);
+  const parent = parentIn ? { ...(parentId ? { id: parentId } : {}), ...(parentType ? { type: parentType } : {}) } : undefined;
+  const updatedBlocks = Array.isArray(dataIn?.updated_blocks)
+    ? dataIn.updated_blocks.map((item) => {
+        const id = text(record(item)?.id);
+        return id ? { id } : {};
+      })
+    : undefined;
+  const pageId = text(dataIn?.page_id);
+  const data = dataIn
+    ? {
+        ...(pageId ? { page_id: pageId } : {}),
+        ...(parent ? { parent } : {}),
+        ...(updatedBlocks ? { updated_blocks: updatedBlocks } : {}),
+      }
+    : undefined;
+
+  const authors = Array.isArray(input.authors)
+    ? input.authors.map((item) => {
+        const author = record(item);
+        const authorId = text(author?.id);
+        const authorType = text(author?.type);
+        return { ...(authorId ? { id: authorId } : {}), ...(authorType ? { type: authorType } : {}) };
+      })
+    : undefined;
+
+  return {
+    id,
+    ...(text(input.timestamp) ? { timestamp: text(input.timestamp) } : {}),
+    ...(text(input.type) ? { type: text(input.type) } : {}),
+    ...(text(input.event_type) ? { event_type: text(input.event_type) } : {}),
+    ...(text(input.workspace_id) ? { workspace_id: text(input.workspace_id) } : {}),
+    ...(entity ? { entity } : {}),
+    ...(data ? { data } : {}),
+    ...(authors ? { authors } : {}),
+  };
+}
+
+export function decodeNotionIngressPayload(payloadJson: string): NotionIngressPayload | undefined {
+  try {
+    const parsed = record(JSON.parse(payloadJson));
+    if (parsed?.schemaVersion !== NOTION_INGRESS_SCHEMA_VERSION) return undefined;
+    const event = projectNotionIngressEvent(parsed.event);
+    return event ? { schemaVersion: NOTION_INGRESS_SCHEMA_VERSION, event } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function synchronousResponse(): Response {
+  return new Response("synchronous", { status: 409, headers: { "x-oe-notion-ingress": "synchronous" } });
+}
+
+/**
+ * Authenticate, project and durably accept one public Notion delivery.
+ *
+ * `409 + x-oe-notion-ingress:synchronous` is an internal hand-off to the existing route for the
+ * subscription handshake and the explicit unsigned development hatch. The live route consumes it;
+ * it is never returned to Notion.
+ */
+export async function acknowledgeNotionIngress(
+  rawBody: string,
+  signatureHeader: string | null,
+  deps: AcknowledgeNotionIngressDeps,
+): Promise<Response> {
+  if (Buffer.byteLength(rawBody, "utf8") > NOTION_INGRESS_MAX_BODY_BYTES) {
+    return new Response("payload too large", { status: 413 });
+  }
+  if (parseVerificationHandshake(rawBody)) return synchronousResponse();
+
+  const gate = gateNotionDeliveryAcross(deps.signingKeys, rawBody, signatureHeader, deps.allowUnverified);
+  if (gate.rejection) return new Response(gate.rejection, { status: 401 });
+  if (!gate.verified || !gate.credentialId) return synchronousResponse();
+  if (!deps.drainAvailable) return new Response("durable ingress drain unavailable", { status: 503 });
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    return new Response("bad json", { status: 400 });
+  }
+  const event = projectNotionIngressEvent(parsed);
+  if (!event) return new Response("missing event id", { status: 400 });
+
+  const key: NotionIngressKey = {
+    source: NOTION_INGRESS_SOURCE,
+    authorityId: gate.credentialId,
+    deliveryId: event.id,
+  };
+  const write: NotionIngressWrite = {
+    ...key,
+    payloadJson: JSON.stringify({ schemaVersion: NOTION_INGRESS_SCHEMA_VERSION, event } satisfies NotionIngressPayload),
+    receivedAt: (deps.now ?? (() => new Date()))().toISOString(),
+  };
+  try {
+    await deps.enqueue(deps.org, write);
+  } catch {
+    return new Response("durable ingress unavailable", { status: 503 });
+  }
+
+  const drain = Promise.resolve().then(() => deps.drain(key));
+  deps.waitUntil(drain);
+  return new Response("ok", { status: 200 });
+}

package/agent/channels/notion-message-ops.ts

@@ -0,0 +1,140 @@
+// notion-message-ops — Notion's SurfaceMessageOps (OPE-1043, the remaining slice of OPE-899's
+// class): the ancillary message ops core features dispatch through channels/surface-message-ops.ts.
+// Before this file, Notion registered none, so the stop acknowledgement (hooks/turn-anchor.ts's
+// `postSurfaceText`) resolved nothing on a Notion turn — OPE-989 shipped the stop CONTROL itself
+// (notion-stop.ts, a bare `stop` comment), it was just invisible: a person who used it saw the agent
+// go quiet and read nothing telling them it had stood down.
+//
+//   - postText    → a FRESH top-level comment on the page (`createPageComment`, notion-api.ts) when
+//                   `opts?.replyToMessageId` is absent — the shape every call on this ticket's own
+//                   path takes (turn-anchor.ts never passes a reply anchor for a stop note). When
+//                   present, this arm resolves the NAMED comment's own `discussion_id` (one extra
+//                   fetch, `retrieveComment`) and replies into that same discussion instead
+//                   (`createCommentReply`) — falling back to a fresh page comment only when that
+//                   comment carries no discussion (never silently drops the anchor request).
+//   - editMessage → `updateComment` (`PATCH /v1/comments/{id}`), confirmed live 2026-08-23
+//                   (developers.notion.com/reference/update-a-comment). `edit_reply`'s own seam
+//                   (`PostArm.editMessage`, a model-facing tool capability with its own ownership/
+//                   locus rules) now wires to the same endpoint too — notion-post-arm.ts's
+//                   `liveNotionEditComment` (OPE-1046) — a separate, reviewable change from this one.
+//   - postFiles   → uploads each file through Notion's two-step flow (`uploadNotionFile`,
+//                   notion-api.ts: create-file-upload, then send the bytes) and attaches the
+//                   resulting `file_upload` ids to a FRESH top-level page comment
+//                   (`createPageComment`'s `attachments`) — OPE-1047. Notion caps a single comment
+//                   at 3 attachments; a larger batch is refused up front, before any byte uploads,
+//                   so a caller never pays for uploads it then has to discard.
+//   - NO `setReaction`: confirmed (2026-08-23, developers.notion.com) — Notion's public API has no
+//     reaction resource for comments at all, the same finding OPE-989 made for the stop trigger
+//     itself. Matches the manifest's existing `reactions: false` (register.ts).
+//
+// `channelId` IS THE STOP REGISTRY'S CONVERSATION KEY — `<workspace>/<page>`, not a
+// notion-message-ops-specific pair invented here. `turn-anchor.ts`'s `turnAnchorAddress` reads it off
+// `binding.anchorChannelId`, which `bindNotion` (notion-identity.ts) mints through
+// `notionConversationKey` — the SAME key `notion-stop.ts`'s `routeNotionStopComment` parses to
+// resolve the cancel. This file reuses `parseNotionConversationKey`, the composer's own documented
+// inverse, rather than writing a second parser: two derivations of the same address is exactly the
+// "silently miss" trap notion-identity.ts's own header warns about.
+//
+// CREDENTIAL RESOLUTION mirrors notion-post-arm.ts's `notionReplyCredential` (a page's domain binding
+// picks its own Notion integration; no binding falls through to the org default) — copied rather than
+// imported, for the same reason notion-identity.ts's `notionAttr`/`notionAuthOf` are local copies: a
+// three-line structural read a caller outside the post-arm's own module is expected to make itself.
+
+import type { SurfaceMessageOps, OutboundFile } from "@open-everywhere/core/agent/adapter-api.js";
+import { getConfig, type Domain } from "@open-everywhere/core/agent/adapter-api.js";
+import {
+  createPageComment,
+  createCommentReply,
+  updateComment,
+  resolveNotionCredential,
+  retrieveComment,
+  uploadNotionFile,
+  NOTION_MAX_ATTACHMENTS,
+  type ResolvedNotionCredential,
+} from "./notion-api.js";
+import { notionChannelCredentialFor } from "./notion-credentials.js";
+import { parseNotionConversationKey } from "./notion-identity.js";
+
+function notionDomains(): readonly Domain[] {
+  try {
+    return getConfig().loadDomains();
+  } catch {
+    return [];
+  }
+}
+
+/** Parse the `<workspace>/<page>` conversation id, or throw the same honest, naming refusal every
+ *  other surface-message-ops call gives on a malformed address — never a guessed target. */
+function requireConversation(channelId: string): { readonly workspaceId: string; readonly pageId: string } {
+  const parsed = parseNotionConversationKey(channelId);
+  if (!parsed) throw new Error(`Notion surface message ops: "${channelId}" is not a conversation id (expected "<workspace>/<page>").`);
+  return parsed;
+}
+
+async function requireCredential(workspaceId: string, pageId: string): Promise<ResolvedNotionCredential> {
+  const credentialId = notionChannelCredentialFor(workspaceId, pageId, notionDomains());
+  const cred = await resolveNotionCredential(credentialId);
+  if (!cred) throw new Error(`Notion surface message ops: no value stored for notion credential "${credentialId ?? "channel-key"}".`);
+  return cred;
+}
+
+export const notionMessageOps: SurfaceMessageOps = {
+  platform: "notion",
+
+  /**
+   * A fresh top-level comment on the page, or — when `opts?.replyToMessageId` names a comment that
+   * carries a `discussion_id` — a reply into that SAME discussion instead. Never guesses a
+   * discussion: a named comment this call cannot resolve (fetch failure, or a comment with no
+   * discussion of its own) falls back to the fresh-comment shape rather than dropping the request.
+   */
+  async postText(channelId, text, opts) {
+    const { workspaceId, pageId } = requireConversation(channelId);
+    const cred = await requireCredential(workspaceId, pageId);
+    if (opts?.replyToMessageId) {
+      let discussionId: string | undefined;
+      try {
+        discussionId = (await retrieveComment(opts.replyToMessageId, cred)).discussion_id;
+      } catch {
+        discussionId = undefined;
+      }
+      if (discussionId) return createCommentReply({ discussionId, text, ...cred });
+    }
+    return createPageComment({ pageId, text, ...cred });
+  },
+
+  /** `PATCH /v1/comments/{id}` — rewrite the comment's body in place (`updateComment`). */
+  async editMessage(channelId, messageId, text) {
+    const { workspaceId, pageId } = requireConversation(channelId);
+    const cred = await requireCredential(workspaceId, pageId);
+    await updateComment({ commentId: messageId, text, ...cred });
+  },
+
+  /**
+   * Upload each file through Notion's two-step flow (`uploadNotionFile`), then land them all on
+   * ONE fresh top-level page comment via `createPageComment`'s `attachments` (OPE-1047). Notion
+   * caps a single comment at {@link NOTION_MAX_ATTACHMENTS} attachments — refused up front, before
+   * any upload runs, so a too-large batch never pays for bytes it then has to discard.
+   *
+   * Always a PAGE comment, never a reply into a named discussion: `SurfaceMessageOps.postFiles`
+   * carries no `replyToMessageId` (unlike `postText`), the same "current channel" shape Discord's
+   * `postFiles` posts into.
+   *
+   * Returns the created comment's id (Notion echoes it, same as `postText`) — undefined only if
+   * the response carries none, never a guessed id.
+   */
+  async postFiles(channelId, files: readonly OutboundFile[], comment) {
+    if (files.length > NOTION_MAX_ATTACHMENTS) {
+      throw new Error(`Notion surface message ops: at most ${NOTION_MAX_ATTACHMENTS} files per post; got ${files.length}.`);
+    }
+    const { workspaceId, pageId } = requireConversation(channelId);
+    const cred = await requireCredential(workspaceId, pageId);
+    const fileUploadIds: string[] = [];
+    for (const file of files) {
+      fileUploadIds.push(
+        await uploadNotionFile({ filename: file.filename, contentType: file.contentType, bytes: file.bytes, ...cred }),
+      );
+    }
+    const id = await createPageComment({ pageId, text: comment ?? "", attachments: fileUploadIds, ...cred });
+    return id.length > 0 ? id : undefined;
+  },
+};

package/agent/channels/notion-origin-codec.ts

@@ -0,0 +1,38 @@
+// The Notion UnifiedWakeOrigin codec — MOVED VERBATIM out of core's
+// channels/wake-origin-codecs.ts (OPE-114 stage 3, the first extracted arm). STORED-DATA
+// COMPATIBILITY IS THE CONTRACT: a Notion origin is JSON-serialised into the durable
+// operational store and fail-closed re-validated on read, so every behaviour here is frozen
+// by core's scripts/wake-origin-fixtures-test.ts (run from the app root with this bundle's
+// boot wiring — scripts/wake-origin-fixtures-boot.ts). Validator tolerances (typeof-only
+// optional checks, extra unknown fields) are LOAD-BEARING for rows already on disk — never
+// tighten them here.
+//
+// The `UnifiedWakeOrigin` TYPE union (including its notion arm) stays in core — it is the
+// wire schema for stored rows; only the codec BEHAVIOUR lives in the bundle, registered by
+// registerNotionProvider() (../register.ts).
+
+import type { UnifiedWakeOrigin, WakeOriginCodec } from "@open-everywhere/core/agent/adapter-api.js";
+
+type NotionOrigin = Extract<UnifiedWakeOrigin, { platform: "notion" }>;
+
+/** COLON-FREE by construction (a task windowId is `[^:]+` — core channels/window-key.ts): any colon
+ *  in a raw surface id is folded to `_`, deterministically, so spawn + ingress agree on identity. */
+const noColon = (s: string): string => s.replace(/:/g, "_");
+
+export const notionWakeOriginCodec: WakeOriginCodec<NotionOrigin> = {
+  validate: (o) =>
+    typeof o.discussionId === "string" &&
+    o.discussionId.length > 0 &&
+    (o.pageId === undefined || typeof o.pageId === "string") &&
+    (o.workspaceId === undefined || typeof o.workspaceId === "string"),
+  threadRef: (origin) => ({ channelKey: noColon(`notion/${origin.pageId ?? origin.discussionId}`), threadKey: noColon(origin.discussionId) }),
+  isThreadScoped: () => true,
+  containerId: (origin) => origin.discussionId,
+  // NO `placementRef` AND NO `carryPlacement`, AND THAT ABSENCE IS THE DECLARATION (OPE-1826). Notion
+  // keeps its placement INSIDE the conversation identity: a reply targets `discussionId`, which is
+  // exactly what `threadRef` keys on, so two origins that pass `sameUnifiedConversation` name the same
+  // discussion and cannot disagree about where the answer lands. `credentialId` is not a
+  // counter-example: it selects the integration the post is made under, never where the post lands.
+  // The position is recorded, and held to account against the live registry, by the
+  // `origin-placement-carry` row in core's identity/surface-parity.ts.
+};

package/agent/channels/notion-post-arm.ts

@@ -0,0 +1,189 @@
+// notion-post-arm — Notion's POST arm for the post-arms registry (OPE-114 stage 1c). Absorbs,
+// VERBATIM, Notion's arms out of the three reply/delivery spines: reply-post.ts (resolveReplyTarget's
+// notion case + dispatchReply's createCommentReply branch), unified-reply.ts (liveNotionPost), and
+// unified-redrive.ts (the notion describe/container cases). Every Notion reply funnels through
+// notion-api.ts createCommentReply — a NEW comment in the triggering discussion thread — under the
+// integration key resolved by resolveNotionCredential, which carries that credential's endpoint
+// rules alongside the key so the guarded fetch can refuse a call outside them.
+//
+// EDIT (OPE-1046). `PATCH /v1/comments/{id}` (`updateComment`, notion-api.ts) exists — confirmed live
+// 2026-08-23, correcting this tree's earlier "no comment-update endpoint" claim. `editMessage` below
+// resolves the credential the SAME way `notion-message-ops.ts`'s `SurfaceMessageOps.editMessage`
+// already does (OPE-1043): parse the `<workspace>/<page>` conversation key back into its two ids
+// (`parseNotionConversationKey`) and look up that page's own credential (`notionReplyCredential`,
+// already defined below for the reply arms). `messageId` is the comment id itself — the one field
+// `edit_reply`'s own-post ledger checked before this arm is ever called (channels/reply-edit.ts).
+
+import { createCommentReply, updateComment, resolveNotionCredential } from "./notion-api.js";
+import { notionChannelCredentialFor, NOTION_CHANNEL_CREDENTIAL, NOTION_PROVIDER } from "./notion-credentials.js";
+import { parseNotionConversationKey } from "./notion-identity.js";
+import { getConfig, resolvePartition, markNotApplied, carryFailureSignals, findConnectorCredential, type Domain } from "@open-everywhere/core/agent/adapter-api.js";
+import type { PostArm, TargetResolveBag, ReplyTarget, UnifiedWakeOrigin, UnifiedReplyDeps, EditLocus } from "@open-everywhere/core/agent/adapter-api.js";
+
+// OPE-467 — THE CREDENTIAL A REPLY POSTS UNDER, in one sentence: the credential the DELIVERY ran
+// under, which the wake stowed on the binding target / wake origin (notion-identity.ts's
+// `credential_id` attribute). The credential that fetched the comment is the credential that
+// answers it — a page shared with an integration its domain does not bind would otherwise fetch
+// under one key and reply under another whose integration was never shared the page, and
+// `createCommentReply` would throw with nobody watching.
+//
+// The page's domain binding is the FALLBACK, for a target minted before the stamp existed and for
+// proactive posts that no delivery woke. Fail-soft on a config-load error: no domains ⇒ no binding
+// ⇒ the org default, which is the pre-OPE-467 behaviour rather than a refusal.
+function notionDomains(): readonly Domain[] {
+  try {
+    return getConfig().loadDomains();
+  } catch {
+    return [];
+  }
+}
+
+function notionReplyCredential(workspaceId: string | undefined, pageId: string | undefined): string | undefined {
+  return notionChannelCredentialFor(workspaceId, pageId, notionDomains());
+}
+
+type NotionTarget = Extract<ReplyTarget, { platform: "notion" }>;
+type NotionOrigin = Extract<UnifiedWakeOrigin, { platform: "notion" }>;
+
+/** MID-TURN: post back into the SAME discussion thread as a new comment (createCommentReply). */
+async function dispatchNotionReply(target: NotionTarget, text: string): Promise<string> {
+  const credentialId = target.credentialId ?? notionReplyCredential(target.workspaceId, target.pageId);
+  // OPE-505: resolve the key WITH its endpoint rules and spread both, so the credential's fence
+  // travels with it into createCommentReply's guarded fetch.
+  const cred = await resolveNotionCredential(credentialId);
+  if (!cred) {
+    // DEFINITIVE (OPE-825): the call never leaves this host — no credential, no request — so
+    // nothing reached Notion and an identical retry is legitimate.
+    throw markNotApplied(new Error(`reply couldn't post to Notion — no value stored for notion credential "${credentialId ?? "channel-key"}".`));
+  }
+  return createCommentReply({ discussionId: target.discussionId, text, ...cred });
+}
+
+/** UNIFIED: POST /v1/comments { discussion_id } — the exact helper (and Notion-Version header) every
+ *  per-doc Notion reply already goes through; a supervisor session on the synthetic unified channel
+ *  has no notion channel state, so the REST call under the integration token (db:notion:channel-key)
+ *  is the reply route. The target discussionId is the frozen wake origin's — host-side, never
+ *  model-authored. */
+async function liveNotionPost(origin: NotionOrigin, text: string): Promise<string> {
+  const credentialId = origin.credentialId ?? notionReplyCredential(origin.workspaceId, origin.pageId);
+  // OPE-505: key + endpoint rules together (see dispatchNotionReply).
+  const cred = await resolveNotionCredential(credentialId);
+  if (!cred) {
+    // DEFINITIVE (OPE-825): no credential ⇒ no request ever left this host.
+    throw markNotApplied(new Error(`unified reply couldn't post to Notion — no value stored for notion credential "${credentialId ?? "channel-key"}" (discussion ${origin.discussionId})`));
+  }
+  let id: string;
+  try {
+    id = await createCommentReply({ discussionId: origin.discussionId, text, ...cred });
+  } catch (err) {
+    // Token-free error: never echo the transport error body (defensive parity with the Linear arm).
+    // carryFailureSignals (OPE-825) carries the numeric status createCommentReply attached, so this
+    // re-wrap doesn't silently downgrade a DEFINITIVE 4xx refusal to AMBIGUOUS.
+    throw carryFailureSignals(err, new Error(`unified reply couldn't post to Notion — createCommentReply failed on discussion ${origin.discussionId}`));
+  }
+  return id || "unknown";
+}
+
+/**
+ * `PATCH /v1/comments/{id}` — rewrite a comment THIS deployment already posted, in place (OPE-1046).
+ * `locus.channelId` is the `<workspace>/<page>` conversation key `replyEditLocus`/`unifiedEditLocus`
+ * (channels/reply-post.ts / unified-reply.ts) compose from the target/origin's `workspaceId`/`pageId`
+ * — parsed back apart here rather than carried as two separate `EditLocus` fields, matching the
+ * SAME composite `notion-message-ops.ts` already parses for its own `editMessage` (OPE-1043).
+ *
+ * Notion 404s a comment the calling connection did not create and 403s a connection lacking
+ * insert-comment capability — both DEFINITIVE (a 4xx `updateComment` already attaches to the thrown
+ * error's `.status`, OPE-825's classifier reads it with no help from this function); a timeout or a
+ * 5xx is AMBIGUOUS. Re-wrapped token-free, matching `liveNotionPost`'s own re-wrap discipline above.
+ */
+async function liveNotionEditComment(locus: EditLocus, messageId: string, text: string): Promise<void> {
+  const parsed = parseNotionConversationKey(locus.channelId);
+  if (!parsed) {
+    // DEFINITIVE (OPE-825): a malformed locus is a host refusal before any byte leaves.
+    throw markNotApplied(new Error(`edit_reply couldn't edit the Notion comment ${messageId} — "${locus.channelId}" is not a conversation id.`));
+  }
+  const credentialId = notionReplyCredential(parsed.workspaceId, parsed.pageId);
+  const cred = await resolveNotionCredential(credentialId);
+  if (!cred) {
+    // DEFINITIVE (OPE-825): no credential ⇒ no request ever left this host.
+    throw markNotApplied(new Error(`edit_reply couldn't edit the Notion comment ${messageId} — no value stored for notion credential "${credentialId ?? "channel-key"}".`));
+  }
+  try {
+    await updateComment({ commentId: messageId, text, ...cred });
+  } catch (err) {
+    // Token-free re-wrap; carryFailureSignals keeps the numeric status (and any `applied:false`)
+    // from downgrading to AMBIGUOUS across the wrap — the same discipline dispatchNotionReply/
+    // liveNotionPost above already apply.
+    throw carryFailureSignals(err, new Error(`edit_reply couldn't edit the Notion comment ${messageId} — updateComment failed`));
+  }
+}
+
+export const notionPostArm: PostArm = {
+  platform: "notion",
+  resolveTarget: (bag: TargetResolveBag): ReplyTarget | null => {
+    // Notion posts into the triggering comment's discussion (bindNotion.target.discussionId).
+    const discussionId = bag.str("discussionId");
+    if (!discussionId) return null;
+    // `pageId` rides the binding target (notion-identity.ts bindNotion); the workspace comes off the
+    // partition. Both are CONTEXT for credential selection only — the post target stays the
+    // discussion. Fail-soft: an unresolvable partition leaves the workspace absent, and the page
+    // alone still resolves a domain through the roster tier.
+    let workspaceId: string | undefined;
+    try {
+      workspaceId = resolvePartition(bag.ctx).workspace;
+    } catch {
+      workspaceId = undefined;
+    }
+    const pageId = bag.str("pageId");
+    // The delivery's own integration (bindNotion carries it off the `credential_id` auth attribute)
+    // — the reply posts under the credential that fetched, never a re-derivation that agrees by luck.
+    const credentialId = bag.str("credentialId");
+    return {
+      platform: "notion",
+      discussionId,
+      ...(pageId ? { pageId } : {}),
+      ...(workspaceId ? { workspaceId } : {}),
+      ...(credentialId ? { credentialId } : {}),
+    };
+  },
+  dispatchReply: (target, text) => dispatchNotionReply(target as NotionTarget, text),
+  dispatchUnified: (origin, text, deps: UnifiedReplyDeps) => (deps.postNotion ?? liveNotionPost)(origin as NotionOrigin, text),
+  // EDIT (OPE-1046): `updateComment` on the address `replyEditLocus`/`unifiedEditLocus` compose from
+  // the target/origin's `workspaceId`/`pageId` — see `liveNotionEditComment` above.
+  editMessage: (locus, messageId, text) => liveNotionEditComment(locus, messageId, text),
+  // 🔴 CAN THAT EDIT ACTUALLY BE ISSUED HERE? (OPE-1753.) `editMessage` above PATCHes
+  // `/v1/comments/{id}`, and this deployment's Notion channel key declares `GET,POST` on purpose —
+  // "a DELETE or PATCH can never be issued under the channel key" is that rule's own stated point.
+  // So the endpoint fence refuses every edit before a byte leaves, and the should-be-edit policy,
+  // which could only see that `editMessage` EXISTS, went on steering the seat at a verb that cannot
+  // work: on soak `soak-2026-09-12-a` that cost a refusal loop and the duplicate post behind it.
+  // This answers the narrower question the policy actually needs — is PATCH within the resolved
+  // credential's declared methods?
+  // 🔴 IT READS THE RULES, IT DOES NOT WIDEN THEM. The endpoint declaration is security posture and
+  // stays exactly as it is; this only stops the host OFFERING an edit the fence will refuse.
+  // FAIL-OPEN in both directions that are not a positive refusal: an unresolvable locus or credential
+  // answers true and leaves the pre-OPE-1753 behaviour, and a credential with NO declared methods is
+  // unnarrowed, so every method is allowed.
+  // 🔴 IT READS THE DECLARATION, NEVER THE SECRET. `resolveNotionCredential` would answer the same
+  // question, but it calls `getSecretVia` — a broker read that fetches the live integration key,
+  // holds it in memory, and on an unstamped broker appends a `credential unresolved` audit row. This
+  // predicate runs on every fold evaluation in a Notion conversation, and the question it asks is
+  // answerable from the static catalogue alone: which methods did the operator declare? The member's
+  // own contract in `channels/post-arms.ts` says READ-ONLY and cheap, and fetching a key to read a
+  // config field is neither.
+  editReachable: async (locus) => {
+    const parsed = parseNotionConversationKey(locus.channelId);
+    if (!parsed) return true;
+    // 🔴 `undefined` MEANS THE DEFAULT KEY, NOT "NO KEY". `notionChannelCredentialFor` answers
+    // undefined whenever the page's domain declares no per-domain override, which is the ORDINARY
+    // case — and `resolveNotionCredential` reads that as `NOTION_CHANNEL_CREDENTIAL`, the very key
+    // whose GET,POST rules this predicate exists to read. Treating undefined as "cannot tell" and
+    // failing open here disabled the whole fix on every default-credential page; `notion-post-arm-
+    // test.ts` §5 caught exactly that.
+    const credentialId = notionReplyCredential(parsed.workspaceId, parsed.pageId) ?? NOTION_CHANNEL_CREDENTIAL;
+    const methods = findConnectorCredential(NOTION_PROVIDER, credentialId)?.endpoints?.methods;
+    return methods === undefined || methods.includes("PATCH");
+  },
+  describeRedriveTarget: (origin) => `notion discussion ${(origin as NotionOrigin).discussionId}`,
+  redriveContainerId: (origin) => (origin as NotionOrigin).discussionId,
+};