@open-everywhere/provider-notion 0.1.0

package/dist/agent/channels/notion-scope.d.ts

@@ -0,0 +1,188 @@
+import { appendAudit, 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 declare function canonicalNotionId(id: string): string;
+/**
+ * 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 declare function notionPageDomain(workspace: string | undefined, pageId: string, domains: readonly Domain[]): NotionPageRouting;
+/**
+ * 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 declare function notionReachWorkspace(workspace: string | undefined, pageId: string, domains: readonly Domain[]): string | undefined;
+/**
+ * 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 declare function notionReadScope(callerSurfaceKey: string, pageId: string, domains: readonly Domain[]): NotionScopeVerdict;
+/**
+ * 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 declare function notionWorkScope(callerDomain: Domain | undefined, pageId: string, domains: readonly Domain[], workspaceHints?: readonly string[]): NotionScopeVerdict;
+/**
+ * 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 declare function assertNotionWorkPageAllowed(ctx: BindableContext, pageId: string, callerDomain: Domain | undefined, domains: readonly Domain[], workspaceHints?: readonly string[], deps?: NotionScopeDeps): Promise<void>;
+/**
+ * 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 declare function assertNotionPageAllowed(ctx: BindableContext, pageId: string, domains: readonly Domain[], deps?: NotionScopeDeps): Promise<void>;
+/** 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>;
+}
+/**
+ * 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 declare function assertNotionBlockAllowed(ctx: BindableContext, blockId: string, domains: readonly Domain[], resolveOwningPage: (blockId: string) => Promise<string | undefined>, deps?: NotionScopeDeps): Promise<void>;
+/**
+ * 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 declare function assertNotionPageAllowedOrResolveBlock(ctx: BindableContext, requestedId: string, domains: readonly Domain[], resolveOwningPage: (id: string) => Promise<string | undefined>, deps?: NotionScopeDeps): Promise<string>;
+//# sourceMappingURL=notion-scope.d.ts.map

package/dist/agent/channels/notion-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notion-scope.d.ts","sourceRoot":"","sources":["../../../agent/channels/notion-scope.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,433 @@
+// 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, } from "@open-everywhere/core/agent/adapter-api.js";
+/**
+ * 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) {
+    return id.trim().toLowerCase().replace(/-/g, "");
+}
+/** The `<workspace>` and `<page>` segments of a `notion/<workspace>/<page>` surface key. */
+function splitNotionKey(surfaceKey) {
+    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, pageId, domains) {
+    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, pageId, domains) {
+    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) {
+    const fix = (entry) => {
+        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, pageId, domains) {
+    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" };
+    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, pageId, domains, workspaceHints = []) {
+    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, pageId, callerDomain, domains, workspaceHints = [], deps) {
+    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, callerDomain) {
+    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, verdict) {
+    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, verdict, resolvedPage) {
+    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, pageId, domains, deps) {
+    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));
+}
+/**
+ * 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, target, reason, verdict, deps, resolvedPage) {
+    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 } : {}),
+        },
+    });
+}
+async function resolveNotionReadTarget(callerSurfaceKey, requestedId, domains, resolveOwningPage) {
+    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, blockId, domains, resolveOwningPage, deps) {
+    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, requestedId, domains, resolveOwningPage, deps) {
+    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));
+}
+//# sourceMappingURL=notion-scope.js.map