@open-everywhere/provider-notion 0.1.0

package/agent/channels/notion-scope.ts

@@ -0,0 +1,560 @@
+// The DOMAIN READ FENCE for Notion pages — the Notion analogue of slack-read.ts's
+// assertChannelAllowed / channel-read.ts's assertSurfaceAllowed (OPE-236).
+//
+// WHY IT EXISTS AT ALL. read_notion_page / read_notion_comments used to be bounded ONLY by what the
+// Notion integration itself can see, and said so in a comment: "Notion enforces access itself: the
+// integration can only read pages explicitly shared with it, so an out-of-scope `page` 404s here."
+// That is true and it is not the boundary we need. On the DEFAULT setup there is ONE credential (an
+// internal-integration secret bound to a single workspace) and it is IDENTICAL for every domain —
+// the shipped runbook says it "cannot express anything narrower than the workspace, so it is not the
+// boundary and OE does not present it as one". So Notion's own enforcement fences the WORKSPACE;
+// nothing fenced the DOMAIN, and a session woken in domain A could pass any page id the integration
+// can see — including pages the deployer put in domain B — and Notion would happily serve it.
+// Exactly the shape slack-read.ts calls out: "broad credential underneath, narrow allowlist on top,
+// FAIL CLOSED". This module is that allowlist.
+//
+// 🔴 A DOMAIN MAY NOW BIND ITS OWN INTEGRATION (OPE-467, channels/notion-credentials.ts), and that
+// DOES buy a vendor-enforced fence for the pages nobody shared elsewhere. THIS MODULE IS UNCHANGED
+// BY IT, deliberately: a binding is optional, it does not un-share a page, and an allowlist that
+// weakened whenever a credential looked narrow would be a fence you could switch off by config.
+// Both fences apply, always, and this one never consults the credential.
+//
+// WHY IT IS NOT `assertSurfaceAllowed`. The generic gate admits the caller's own surface plus every
+// `platform`-matching EXACT entry in the caller's domain. That is right for chat, where a domain
+// enumerates its rooms, but it would refuse every page in a workspace a domain reaches by CONTAINER
+// — and a container entry is precisely how a Notion domain is expressed (a two-segment
+// `notion/<workspace>` key, whose whole point is that it reaches pages nobody enumerated). So the
+// fence here resolves BOTH SIDES — caller and target — with the same most-specific-wins rule
+// `resolveDomainForChannel` uses, and admits the read only when the two land in the SAME domain.
+// That inherits the ordering for free: a page named outright in domain B's `reach` stays with B
+// under domain A's workspace container, so a container can never quietly annex a page someone else
+// listed. The event plane's read grant already behaves exactly this way
+// (notion-event-normalizer-test.ts §5b); this brings the TOOL plane into line with it.
+//
+// FAIL CLOSED, in both directions. A page that resolves to NO domain is refused, not admitted — an
+// unassigned page is the case where we cannot say whose it is, and "we can't tell" must never mean
+// "yes". A caller that is itself in no domain keeps only its OWN page. An under-identified session
+// (`notion/unknown/unknown`) therefore reads nothing but itself.
+//
+// AND IT IS AUDITED. The gap this closes was invisible: a cross-domain read produced no refusal, no
+// row, and nothing on the surface to notice. A fence that refuses silently would only fix half of
+// that, so every refusal appends a `read.refused` line (best-effort, never throws — appendAudit's
+// contract) carrying the reason, the caller's domain and the target's, and nothing else: ids and a
+// verdict, never page CONTENT.
+
+import {
+  appendAudit,
+  bindFrom,
+  domainReachVerdict,
+  domainRoster,
+  resolvePartition,
+  ChannelScopeError,
+  type BindableContext,
+  type Domain,
+} from "@open-everywhere/core/agent/adapter-api.js";
+
+/** How a Notion page reached a domain — an EXACT `reach` entry, or a container one. */
+export type NotionVia = "roster" | "container" | "none";
+
+/** A page's domain, how it got there, and the `reach` entry that did it.
+ *
+ *  🔴 `entry` IS THE PARTITION'S SOURCE (OPE-254 §2). It is the config text that matched, so
+ *  {@link notionReachWorkspace} reads the workspace segment off it rather than off the delivery —
+ *  see that function. Absent only when `via` is `"none"`. */
+export interface NotionPageRouting {
+  readonly domain?: Domain;
+  readonly via: NotionVia;
+  readonly entry?: string;
+}
+
+/** Why a read was admitted or refused — the audited `reason`, and the only thing the verdict says. */
+export type NotionScopeReason =
+  /** the page IS the session's own surface — always readable, it is where the agent was engaged */
+  | "own-page"
+  /** caller and target are the same domain, matched through an EXACT `reach` entry */
+  | "roster"
+  /** caller and target are the same domain, matched through a container `reach` entry */
+  | "container"
+  /** the target resolves to a DIFFERENT domain than the caller */
+  | "cross-domain"
+  /** the target resolves to no domain at all — unresolvable ⇒ refused (fail closed) */
+  | "target-unassigned"
+  /** the CALLER is in no domain, so it has no siblings — only its own page is readable */
+  | "caller-unassigned";
+
+export interface NotionScopeVerdict {
+  readonly allowed: boolean;
+  readonly reason: NotionScopeReason;
+  readonly callerDomain?: string;
+  readonly targetDomain?: string;
+}
+
+/**
+ * Compare-form for a Notion id. Notion serves the same page id both hyphenated
+ * (`40000000-0000-4000-8000-000000000101`) and bare (32 hex), and an operator writes whichever form
+ * they pasted into a domain's `reach`, so a raw string compare would refuse a listed page on a
+ * spelling difference. Hyphens and case are the ONLY things normalised away — nothing else is
+ * rewritten, so two genuinely different ids can never collide.
+ */
+export function canonicalNotionId(id: string): string {
+  return id.trim().toLowerCase().replace(/-/g, "");
+}
+
+/** The `<workspace>` and `<page>` segments of a `notion/<workspace>/<page>` surface key. */
+function splitNotionKey(surfaceKey: string): { workspace?: string; page?: string } {
+  const parts = surfaceKey.split("/");
+  if (parts.length !== 3 || parts[0] !== "notion") return {};
+  return { workspace: parts[1] || undefined, page: parts[2] || undefined };
+}
+
+/**
+ * The domain a Notion page belongs to, how it got there, and the `reach` entry responsible — the
+ * SAME rule {@link resolveDomainForChannel} applies, re-expressed here because the exact-key leg has
+ * to compare page ids in {@link canonicalNotionId} form and the core resolver compares whole keys
+ * verbatim.
+ *
+ *   1. EXACT — a `reach` entry `notion/<any workspace>/<page>` whose page id canonicalises equal.
+ *      It WINS, because an exact key is the most specific entry there is: a listed page keeps its
+ *      owner under any container.
+ *   2. CONTAINER — a `reach` entry naming THIS workspace (`notion/<workspace>`). Reaches every page
+ *      in the workspace, including ones nobody enumerated — that is what a container is for. MINUS
+ *      whatever that domain's `exclude` carves out, because exclude always wins (OPE-417). This leg
+ *      asks core's `domainReachVerdict` rather than re-testing the list itself: a second
+ *      implementation of "does this domain reach that page?" is how this fence and the router would
+ *      come to disagree, and the fence is the one people trust. Entries are canonicalised page-id-
+ *      wise first (see `canonicalNotionId`) so an exclusion written with hyphens still matches a
+ *      bare id, exactly like an exact entry.
+ *
+ * WHY THE EXACT LEG IS WORKSPACE-BLIND AND THE CONTAINER LEG IS NOT. A Notion page id is a globally
+ * unique UUID, so an exact `reach` entry identifies THE page whatever workspace segment it was
+ * written under; a container, by contrast, is a statement about a workspace and means nothing
+ * outside it. If the exact leg were workspace-scoped, a page's owner would depend on which workspace
+ * the CALLER's key happens to name — and a domain reaching workspace B would be handed a page domain
+ * A had listed under workspace A, which is exactly the annexation most-specific-wins exists to
+ * prevent. (The first cut of this function got that wrong and the "a container over one workspace
+ * does not reach a page in another workspace" assertion is what caught it.)
+ *
+ * PURE (injected `domains`, no config read), so the fence's whole decision is unit-testable.
+ */
+export function notionPageDomain(workspace: string | undefined, pageId: string, domains: readonly Domain[]): NotionPageRouting {
+  const wanted = canonicalNotionId(pageId);
+  if (wanted.length === 0) return { via: "none" };
+  for (const d of domains) {
+    const exact = domainRoster(d).find((key) => {
+      const parts = key.split("/");
+      return parts.length === 3 && parts[0] === "notion" && canonicalNotionId(parts[2] ?? "") === wanted;
+    });
+    if (exact === undefined) continue;
+    // EXCLUDE ALWAYS WINS, over an exact entry too. Config load refuses that pair as a
+    // contradiction (memory/domain.ts assertDomainsValid), so this is the second line rather than
+    // the first — but the router applies exclude at every entry shape, and a fence that did not
+    // would be the second implementation this module exists to avoid.
+    const entryWorkspace = exact.split("/")[1] ?? "";
+    if (domainReachVerdict(canonicalDomainReach(d), `notion/${entryWorkspace}/${wanted}`)?.kind === "excluded") continue;
+    return { domain: d, via: "roster", entry: exact };
+  }
+  if (!workspace) return { via: "none" };
+  const key = `notion/${workspace}/${wanted}`;
+  for (const d of domains) {
+    const verdict = domainReachVerdict(canonicalDomainReach(d), key);
+    if (verdict?.kind === "admits") return { domain: d, via: "container", entry: verdict.entry };
+  }
+  return { via: "none" };
+}
+
+/**
+ * The WORKSPACE SEGMENT of the `reach` entry that matched this page — the SESSION PARTITION's
+ * workspace, on both legs (OPE-254 §2, closing OPE-537 §1). Undefined when the page reaches no
+ * domain, which is the only case config cannot answer.
+ *
+ * 🔴 THE PARTITION'S TENANT COMES FROM CONFIG, NEVER FROM THE DELIVERY. A delivery's `workspace_id`
+ * is an unauthenticated payload field and Notion returns no workspace id on any REST object, so
+ * there is no verified source for one anywhere. The only place an operator can ever have read one is
+ * a real delivery for that very page — so the segment recorded in the matched `reach` entry IS the
+ * real workspace, and a delivery whose payload disagrees is a stale, mistyped or forged copy, never
+ * a second legitimate one. Composing the surface key with the payload's value instead used to open a
+ * SECOND partition (`notion/<wrong-workspace>/<page>`) beside the honest one, splitting one page's
+ * session and memory history with no domain boundary ever crossed to explain it.
+ *
+ * WHY IT IS DECIDABLE ON THE CONTAINER LEG TOO. A domain may reach at most ONE Notion workspace BY
+ * CONTAINER (memory/domain.ts `partitionTenantProblems`, enforced at config load), so "which
+ * workspace does this domain sweep pages from?" has exactly one config answer — and reading it here
+ * is what makes that assertion load-bearing rather than decorative. Without it, a domain reaching
+ * two workspaces would key the same page under either, chosen by the payload. An EXACT entry needs
+ * no such rule: it carries its own workspace, so a domain may still name pages in several.
+ *
+ * Pure — `domains` is injected, exactly like {@link notionPageDomain}'s.
+ */
+export function notionReachWorkspace(workspace: string | undefined, pageId: string, domains: readonly Domain[]): string | undefined {
+  const routing = notionPageDomain(workspace, pageId, domains);
+  if (routing.entry === undefined) return undefined;
+  return routing.entry.split("/")[1] || undefined;
+}
+
+/**
+ * The domain with its `reach` and `exclude` entries' PAGE-ID segment canonicalised, so the core
+ * predicate compares ids the way this module compares them everywhere else. Only the third segment
+ * is touched (and only when there is one): a `notion/<workspace>` entry is unchanged, and no entry
+ * ever changes shape — a glob stays a glob, its trailing `*` intact.
+ */
+function canonicalDomainReach(d: Domain): Domain {
+  const fix = (entry: string): string => {
+    const parts = entry.split("/");
+    if (parts.length !== 3 || !parts[2]) return entry;
+    const glob = parts[2].endsWith("*");
+    const body = glob ? parts[2].slice(0, -1) : parts[2];
+    return `${parts[0]}/${parts[1]}/${canonicalNotionId(body)}${glob ? "*" : ""}`;
+  };
+  if (!d.reach && !d.exclude) return d;
+  return {
+    ...d,
+    ...(d.reach ? { reach: d.reach.map(fix) } : {}),
+    ...(d.exclude ? { exclude: d.exclude.map(fix) } : {}),
+  };
+}
+
+/**
+ * THE DECISION, pure. Given the calling session's surface key (`notion/<workspace>/<page>`), the
+ * page it wants to read, and the domain registry: may it? See the file header for the doctrine —
+ * own page always, otherwise both sides must land in the same domain, and anything unresolvable is
+ * a refusal.
+ */
+export function notionReadScope(callerSurfaceKey: string, pageId: string, domains: readonly Domain[]): NotionScopeVerdict {
+  const { workspace, page: ownPage } = splitNotionKey(callerSurfaceKey);
+  const wanted = canonicalNotionId(pageId);
+  // The agent can always read the page it was engaged on (slack-read's "its own channel" arm).
+  if (ownPage && wanted.length > 0 && canonicalNotionId(ownPage) === wanted) {
+    const own = notionPageDomain(workspace, pageId, domains);
+    return { allowed: true, reason: "own-page", ...(own.domain ? { callerDomain: own.domain.name, targetDomain: own.domain.name } : {}) };
+  }
+  const caller = ownPage ? notionPageDomain(workspace, ownPage, domains) : { via: "none" as const };
+  const target = notionPageDomain(workspace, pageId, domains);
+  if (!target.domain) {
+    return { allowed: false, reason: "target-unassigned", ...(caller.domain ? { callerDomain: caller.domain.name } : {}) };
+  }
+  if (!caller.domain) {
+    return { allowed: false, reason: "caller-unassigned", targetDomain: target.domain.name };
+  }
+  if (caller.domain.name !== target.domain.name) {
+    return { allowed: false, reason: "cross-domain", callerDomain: caller.domain.name, targetDomain: target.domain.name };
+  }
+  return {
+    allowed: true,
+    reason: target.via === "container" ? "container" : "roster",
+    callerDomain: caller.domain.name,
+    targetDomain: target.domain.name,
+  };
+}
+
+/**
+ * THE WORK-PLANE DECISION, pure (OPE-913). Same doctrine as {@link notionReadScope} — caller and
+ * target must land in the SAME domain, unresolvable is a refusal — with ONE difference, and it is
+ * the whole point of the work grant: the caller's domain is passed IN rather than derived from a
+ * `notion/<workspace>/<page>` surface key.
+ *
+ * That difference is what makes cross-surface grounding work. `notionReadScope` reads the caller's
+ * domain out of its own Notion surface key, so a Slack-woken or GitHub-woken session has no page
+ * segment, resolves no caller domain, and is refused `caller-unassigned` — the exact shape OPE-926
+ * found on Linear from a Slack caller. Capability derives from the DOMAIN (Tommy, 2026-08-21), so
+ * the work plane resolves the caller's domain from whatever surface it was actually woken on and
+ * fences the TARGET against that.
+ *
+ * 🔴 IT IS NOT A LOOSER FENCE. It admits exactly the pages `notionReadScope` would admit for a
+ * Notion-woken caller in the same domain — no page that domain does not own, no cross-domain page,
+ * nothing unassigned. Only the caller side is resolved differently. There is no own-page arm here:
+ * a non-Notion caller has no own page, and a Notion caller reaching this path holds the grant that
+ * covers its own page anyway.
+ *
+ * `workspaceHints` supplies the workspace the CLAIM leg needs (see
+ * notion-work.ts `notionWorkspacesOf`): the roster leg is tried first, workspace-blind, and each
+ * hint is tried only if that found nothing. Hints come from the caller's OWN domain declarations,
+ * so they can never name a workspace the config does not.
+ */
+export function notionWorkScope(
+  callerDomain: Domain | undefined,
+  pageId: string,
+  domains: readonly Domain[],
+  workspaceHints: readonly string[] = [],
+): NotionScopeVerdict {
+  if (!callerDomain) return { allowed: false, reason: "caller-unassigned" };
+  let target = notionPageDomain(undefined, pageId, domains); // roster leg (workspace-blind)
+  for (const ws of workspaceHints) {
+    if (target.domain) break;
+    target = notionPageDomain(ws, pageId, domains);
+  }
+  if (!target.domain) return { allowed: false, reason: "target-unassigned", callerDomain: callerDomain.name };
+  if (target.domain.name !== callerDomain.name) {
+    return { allowed: false, reason: "cross-domain", callerDomain: callerDomain.name, targetDomain: target.domain.name };
+  }
+  return {
+    allowed: true,
+    reason: target.via === "container" ? "container" : "roster",
+    callerDomain: callerDomain.name,
+    targetDomain: target.domain.name,
+  };
+}
+
+/**
+ * Assert this WORK-PLANE session may read `pageId` — else AUDIT the refusal and throw
+ * {@link ChannelScopeError}, exactly like {@link assertNotionPageAllowed} does for the chat plane.
+ * The row lands under the same `read.refused` action with the same detail shape, so an operator
+ * reading the audit log does not have to know which plane refused to find the refusal.
+ */
+export async function assertNotionWorkPageAllowed(
+  ctx: BindableContext,
+  pageId: string,
+  callerDomain: Domain | undefined,
+  domains: readonly Domain[],
+  workspaceHints: readonly string[] = [],
+  deps?: NotionScopeDeps,
+): Promise<void> {
+  const verdict = notionWorkScope(callerDomain, pageId, domains, workspaceHints);
+  if (verdict.allowed) return;
+  await auditNotionReadRefusal(ctx, pageId, verdict.reason, verdict, deps);
+  throw new ChannelScopeError(notionScopeRefusal(pageId, verdict));
+}
+
+/** The refusal copy for a BLOCK drill-in whose owning page could not be established. */
+function notionBlockRefusal(blockId: string, callerDomain: string | undefined): string {
+  const scope = callerDomain ? `domain "${callerDomain}"` : "this session's";
+  return (
+    `Notion block "${blockId}" could not be resolved to a page in ${scope} read scope, so it is refused. ` +
+    "A block is only readable through a page the agent's memory domain owns — pass `page` (and let the " +
+    "sweep find the discussion), or add the owning page to the domain's `reach`."
+  );
+}
+
+/** The refusal copy — one place, so the tool and its test can't drift. */
+function notionScopeRefusal(pageId: string, verdict: NotionScopeVerdict): string {
+  const scope = verdict.callerDomain ? `domain "${verdict.callerDomain}"` : "this page's (no domain owns this session's page)";
+  return (
+    `Notion page "${pageId}" is not in ${scope} read scope. The agent may only read pages in its ` +
+    "memory domain (memory/config/domains/<name>.ts). Add the page to the domain's `reach` as " +
+    "`notion/<workspace>/<page>`, or reach the whole workspace with `notion/<workspace>`, to grant it."
+  );
+}
+
+/**
+ * The refusal copy for {@link assertNotionPageAllowedOrResolveBlock}'s residual arm (OPE-352) — after
+ * BOTH the direct fence and the block-parent resolution attempt have failed to admit `id`. Notion
+ * block ids and page ids share the same UUID shape (there is no way to tell them apart from the
+ * string alone — this is wording only, NEVER a security signal), so the two sub-cases are told apart
+ * by what the resolution attempt actually observed:
+ *
+ *   - `resolvedPage` set: resolution DID find an owning page, and THAT page is also out of scope —
+ *     name it, so the operator grants the id that actually matters (granting `id` itself would do
+ *     nothing; `id` was never the page the fence needs to admit).
+ *   - `resolvedPage` null: resolution could not place `id` at all (not a block Notion will show us,
+ *     a lookup error, or the hop limit) — the worker gets the "this might be a block id" nudge, since
+ *     a manually-supplied parent page id can succeed where automatic resolution could not.
+ */
+function notionPageOrBlockRefusal(id: string, verdict: NotionScopeVerdict, resolvedPage: string | null): string {
+  if (resolvedPage) {
+    const scope = verdict.callerDomain ? `domain "${verdict.callerDomain}"` : "this session's";
+    return (
+      `Notion id "${id}" resolved to its parent page "${resolvedPage}", but that page is not in ${scope} read scope either ` +
+      `(${verdict.reason}). Add "${resolvedPage}" to the domain's \`reach\` as \`notion/<workspace>/<page>\`, or reach the whole ` +
+      "workspace with `notion/<workspace>`, to grant it."
+    );
+  }
+  return (
+    `${notionScopeRefusal(id, verdict)} If "${id}" is a discussion/block id rather than a page id, this looks like a block id ` +
+    "— automatic resolution to its parent page did not succeed (not a block, no API access, or the hop limit), so try passing " +
+    "its parent page id directly."
+  );
+}
+
+/**
+ * Assert this session may read `pageId` — else AUDIT the refusal and throw {@link ChannelScopeError}
+ * (fail closed, the same class every other surface's read fence raises, so a caller that catches
+ * one catches all of them).
+ *
+ * `domains` is passed IN (the tools hand it `getConfig().loadDomains()`, the same way they hand it
+ * to `sourceScopedMount`) rather than read here — it keeps this module config-free and the decision
+ * injectable end-to-end.
+ */
+export async function assertNotionPageAllowed(
+  ctx: BindableContext,
+  pageId: string,
+  domains: readonly Domain[],
+  deps?: NotionScopeDeps,
+): Promise<void> {
+  const partition = resolvePartition(ctx);
+  const verdict = notionReadScope(partition.surfaceKey, pageId, domains);
+  if (verdict.allowed) return;
+  await auditNotionReadRefusal(ctx, pageId, verdict.reason, verdict, deps);
+  throw new ChannelScopeError(notionScopeRefusal(pageId, verdict));
+}
+
+/** Test seam — the audit sink, defaulting to the real append. Same shape delivery-history.ts uses,
+ *  so the refusal ROW is assertable without standing up an operational store. */
+export interface NotionScopeDeps {
+  readonly audit?: (entry: Parameters<typeof appendAudit>[0]) => Promise<void>;
+}
+
+/**
+ * Append the refusal row. Best-effort by contract (appendAudit never throws): the record is EVIDENCE,
+ * not a dependency of the refusal — the throw happens either way. Ids + verdict only; a refused read
+ * has no content to leak because nothing was ever fetched.
+ *
+ * `resolvedPage` (OPE-352): when a block-parent resolution hop was attempted, record what it found —
+ * `null` if it found nothing, the resolved page id if it found one (whether or not THAT page was
+ * itself in scope). Omitted entirely for a refusal that never attempted resolution (the plain
+ * {@link assertNotionPageAllowed} path), so the row shape for that path is byte-identical to before.
+ * This is what makes the audit trail show the HOP, not just the final verdict.
+ *
+ * 🔴 `workspace`/`surface` NAME THE ROW'S SUBJECT, NEVER A FOREIGN CALLER (OPE-935). `platform` is
+ * always `"notion"` here — every `read.refused` row this function writes is about a refused NOTION
+ * read, chat plane or work plane alike. On the chat plane the caller IS the Notion page, so
+ * `resolvePartition(ctx)`'s workspace/surface genuinely describe that subject. On the WORK plane
+ * ({@link assertNotionWorkPageAllowed}) the ctx binds to whatever surface woke the session — a Slack
+ * channel, a GitHub repo, a Linear team — so `resolvePartition(ctx).workspace`/`.surface` name THAT
+ * platform, not Notion. Stamping a Slack team id under a `platform: "notion"` row reads as a bug, not
+ * a cross-plane caller. So when the caller's platform differs from `"notion"`, `workspace`/`surface`
+ * are stamped `"unknown"` instead of a foreign platform's ids. No identity is lost: `detail.callerSurfaceKey`
+ * always carries the caller's real `platform/workspace/surface` string (chat plane: unchanged, still
+ * `notion/<workspace>/<page>`).
+ */
+async function auditNotionReadRefusal(
+  ctx: BindableContext,
+  target: string,
+  reason: string,
+  verdict: { readonly callerDomain?: string; readonly targetDomain?: string },
+  deps?: NotionScopeDeps,
+  resolvedPage?: string | null,
+): Promise<void> {
+  const partition = resolvePartition(ctx);
+  const principalId = bindFrom(ctx).principalId;
+  const foreignCaller = partition.platform !== "notion";
+  await (deps?.audit ?? appendAudit)({
+    org: partition.org,
+    platform: "notion",
+    workspace: foreignCaller ? "unknown" : partition.workspace,
+    surface: foreignCaller ? "unknown" : partition.surface,
+    ...(principalId ? { principalId } : {}),
+    action: "read.refused",
+    detail: {
+      target,
+      reason,
+      callerDomain: verdict.callerDomain ?? null,
+      targetDomain: verdict.targetDomain ?? null,
+      callerSurfaceKey: partition.surfaceKey,
+      ...(resolvedPage !== undefined ? { resolvedPage } : {}),
+    },
+  });
+}
+
+/**
+ * The shared resolve-then-fence walk behind both {@link assertNotionBlockAllowed} and
+ * {@link assertNotionPageAllowedOrResolveBlock} (OPE-352): try `requestedId` directly against the
+ * fence first (cheap, no I/O — own-page / roster / claim), and ONLY on a direct refusal ask Notion
+ * which page owns it and fence THAT page, through the exact same {@link notionReadScope} decision a
+ * directly-passed page id takes.
+ *
+ * 🔴 THE SECURITY PROPERTY: this function is the ONLY place resolution and fencing meet, and the
+ * fence call for the resolved page is the identical pure function used for the direct check — there
+ * is no separate, looser "reached via resolution" grant. Resolution can only ever produce an id that
+ * then has to clear the SAME allowlist a caller-supplied page id would.
+ *
+ * Never audits, never throws — both callers own their own audit target and refusal wording (a block
+ * id and a possibly-block-shaped `page` argument warrant different copy), so this only returns the
+ * outcome: whether it's allowed, the verdict that decided it, and (only when a resolution hop was
+ * attempted) the page id it resolved to, or `null` if resolution found nothing.
+ */
+interface NotionResolveOutcome {
+  readonly allowed: boolean;
+  readonly verdict: NotionScopeVerdict;
+  readonly resolvedPage?: string | null;
+}
+
+async function resolveNotionReadTarget(
+  callerSurfaceKey: string,
+  requestedId: string,
+  domains: readonly Domain[],
+  resolveOwningPage: (id: string) => Promise<string | undefined>,
+): Promise<NotionResolveOutcome> {
+  const direct = notionReadScope(callerSurfaceKey, requestedId, domains);
+  if (direct.allowed) return { allowed: true, verdict: direct };
+  const owning = await resolveOwningPage(requestedId);
+  if (!owning) return { allowed: false, verdict: direct, resolvedPage: null };
+  const viaPage = notionReadScope(callerSurfaceKey, owning, domains);
+  return { allowed: viaPage.allowed, verdict: viaPage, resolvedPage: owning };
+}
+
+/**
+ * Assert this session may read one BLOCK's inline discussion — the `block` drill-in on
+ * read_notion_comments, which addresses a block DIRECTLY and never touches the `page` argument
+ * (notion-api.ts readNotionComments: `if (opts.block) { … return }`). Without this, fencing `page`
+ * alone would leave the fence bypassable in one argument.
+ *
+ * Two tiers, cheapest first:
+ *   1. the block id resolves in the caller's domain by itself — the page-level discussion anchor (a
+ *      page id IS a valid `block` here) and every id under a `notion/<workspace>` reach entry. No I/O.
+ *   2. otherwise ask Notion which PAGE owns the block (`resolveOwningPage`) and fence THAT.
+ * Anything the walk can't answer — a workspace/database parent, hop limit, a lookup that throws —
+ * is a REFUSAL. "We can't tell whose page this is" must never resolve to yes.
+ */
+export async function assertNotionBlockAllowed(
+  ctx: BindableContext,
+  blockId: string,
+  domains: readonly Domain[],
+  resolveOwningPage: (blockId: string) => Promise<string | undefined>,
+  deps?: NotionScopeDeps,
+): Promise<void> {
+  const partition = resolvePartition(ctx);
+  const res = await resolveNotionReadTarget(partition.surfaceKey, blockId, domains, resolveOwningPage);
+  if (res.allowed) return;
+  if (res.resolvedPage) {
+    await auditNotionReadRefusal(ctx, blockId, `block:${res.verdict.reason}`, res.verdict, deps, res.resolvedPage);
+  } else {
+    await auditNotionReadRefusal(ctx, blockId, "block-unresolvable", res.verdict, deps);
+  }
+  throw new ChannelScopeError(notionBlockRefusal(blockId, res.verdict.callerDomain));
+}
+
+/**
+ * Like {@link assertNotionPageAllowed}, but for an id that MIGHT be a discussion/block id rather than
+ * a page id (OPE-352): the Notion worker intermittently hands read_notion_page a block/discussion id
+ * instead of the page it lives on, and the plain page fence has no notion of "resolve it and try
+ * again" — every such call was a silent-looking `target-unassigned` refusal even when the block's
+ * OWNING PAGE was perfectly in scope.
+ *
+ * Same resolve-then-fence walk as {@link assertNotionBlockAllowed} ({@link resolveNotionReadTarget}),
+ * so the SAME security property holds: resolution never grants more than the fence would grant the
+ * resolved page directly, because the resolved page is fenced through the identical
+ * {@link notionReadScope} decision. If the resolved page is itself refused (unassigned/cross-domain),
+ * or resolution fails outright (not a block, no API access, hop limit), the read stays refused.
+ *
+ * Returns the id that is actually authorized to read — `requestedId` unchanged when it passed the
+ * fence directly, or the RESOLVED page id when only the resolution hop admitted it. The caller MUST
+ * use the returned id (not `requestedId`) for the content fetch: reading `requestedId` itself after a
+ * successful resolution would fetch the block's own children, not the parent page's body the caller
+ * actually wants.
+ *
+ * Every refusal is audited with BOTH the originally-requested id (`target`) and the resolved page id
+ * (`resolvedPage`, when a resolution hop was attempted) — the trail shows the hop, not just the final
+ * verdict.
+ */
+export async function assertNotionPageAllowedOrResolveBlock(
+  ctx: BindableContext,
+  requestedId: string,
+  domains: readonly Domain[],
+  resolveOwningPage: (id: string) => Promise<string | undefined>,
+  deps?: NotionScopeDeps,
+): Promise<string> {
+  const partition = resolvePartition(ctx);
+  const res = await resolveNotionReadTarget(partition.surfaceKey, requestedId, domains, resolveOwningPage);
+  if (res.allowed) return res.resolvedPage ?? requestedId;
+  // resolvedPage is ALWAYS explicit here (a string, or `null`) — resolveNotionReadTarget only omits
+  // it on the early ALLOWED return above, so a refusal's audit row always shows whether resolution
+  // was even attempted and, if so, what it found. That is the "trail shows the hop" property.
+  await auditNotionReadRefusal(
+    ctx,
+    requestedId,
+    res.resolvedPage ? `page-via-block:${res.verdict.reason}` : "page-block-unresolvable",
+    res.verdict,
+    deps,
+    res.resolvedPage ?? null,
+  );
+  throw new ChannelScopeError(notionPageOrBlockRefusal(requestedId, res.verdict, res.resolvedPage ?? null));
+}