@open-everywhere/provider-notion 0.1.0

package/dist/agent/channels/notion-acting-identity.js

@@ -0,0 +1,85 @@
+// THE OWN-ACCOUNT SEAM FOR NOTION (OPE-1525) — the one call every Notion read that runs on the
+// deployment's own integration makes before it resolves that credential.
+//
+// THE DEFECT, measured live 2026-09-07. A member asked the seat to read a Notion page "using my own
+// Notion account". The seat delegated, and the worker read the page under the deployment's Notion
+// integration. No consent card, no personal mint, and nothing in the room saying which account had
+// been spent. The two acting identities do not see the same pages, so the member was handed the
+// org's view of their own workspace and could not tell.
+//
+// 🔴 WHY IT SITS HERE AND NOT IN A PROMPT. This module is called at the exact line where the
+// credential id is chosen, and EVERY such line in this bundle resolves an `install`-family key
+// (`team-key` or `channel-key`; connector-credentials.ts). There is no personal branch, so "act as
+// the requester" has no answer any of these tools can give — which is precisely why the refusal has
+// to be code: a model told to be careful still has only team keys to reach for.
+//
+// 🔴 THE FIVE CALL SITES, AND THE LIST IS THE CLAIM. Gating two tools and leaving the rest is worse
+// than gating none, because the doc then says "covered" while a worker reaches the same pages
+// through a neighbouring verb (OPE-1525 review, finding 1). Every site in this bundle that resolves
+// a Notion credential and returns Notion content calls this:
+//   • `tools/read_notion_page.ts`      — both planes;
+//   • `tools/read_notion_comments.ts`  — the chat plane, the delegated worker's own arm;
+//   • `tools/notion_search.ts`         — the work plane's cross-container read;
+//   • `channels/notion-read.ts` admit()— the generic `read_channel`/`read_thread` pair's Notion arm,
+//                                        which `read_notion_page`'s own header calls its superset;
+//   • `channels/notion-work-search.ts` — the federated `search` tool's Notion arm.
+// TWO READS ARE DELIBERATELY NOT HERE, both INGRESS, and the reason is the same one:
+//   • `memory/memory.ts`          — an org-default subtree pull with no requester turn behind it;
+//   • `channels/notion-catch-up.ts` — the standing seat's since-last-wake catch-up, which fires from
+//     the webhook route with no turn and no `BindableContext` at all.
+// Neither has an ask to honour, and the container each reads is the one the wake itself already
+// admitted, so there is no requester-named page a personal credential could answer differently.
+// Gating either would be decoration: the seam needs a turn context that does not exist at ingress,
+// so the gate could only ever allow. The same ruling covers GitHub's catch-up — see
+// `UNGATED_BY_DECISION` in `packages/core/scripts/github-acting-identity-test.ts`.
+//
+// 🔴 NO NOTION TOOL CAN SPEND THE PERSONAL IDENTITY, AND THE GATE IS TOLD SO. Notion's
+// human-acting credential (`user-oauth`) is spent by BORROWING one of the owner's own MCP tools,
+// which mounts on the seat under a `grant__…` name (core access/credential-grant-broker.ts). So a
+// held grant does not let these tools run; it routes the model to that tool instead.
+import { connectorActingIdentityForTurn, ownAccountVendorFor } from "@open-everywhere/core/agent/adapter-api.js";
+import { NOTION_PROVIDER } from "./notion-credentials.js";
+/** Notion, as the own-account grammar recognises it. The connector id is already the word a person
+ *  writes; the product's other spelling comes from the shared registry.
+ *
+ *  🔴 THE ALIASES ARE THE REGISTRY'S, NOT A LITERAL HERE (OPE-1641). The STAMP PRODUCER reads the
+ *  same registry, so a word this gate recognises on a seat turn is recognised on a delegated one
+ *  too. Two literals agreed the day they were written and had nothing keeping them in step: a call
+ *  site that learned a new spelling on its own would refuse a seat read and answer the same
+ *  sentence as the org inside a worker. */
+const NOTION_OWN_ACCOUNT_VENDOR = ownAccountVendorFor(NOTION_PROVIDER);
+/**
+ * Refuse this Notion read when the requester asked to act with their OWN Notion account.
+ *
+ * Throws the gate's own sentence — which names the consent route when one exists here, says plainly
+ * that there is none when it does not, names the granted tool when the account is already lent, and
+ * asks which account was meant when one sentence named both. Returns normally on every other turn,
+ * which is the ordinary path and is unchanged.
+ *
+ * 🔴 IT ALWAYS WRITES THE `connector.acting_identity` ROW, INCLUDING ON THE ORDINARY PATH. A trail
+ * that records only refusals cannot answer "which account read this page", which is the question
+ * OPE-1525 was filed for.
+ *
+ * 🔴 THE `install` CHECK IS STRUCTURAL, NOT DECORATION. The gate's contract is "refuse on `refusal`,
+ * otherwise run under `identity`" — and every caller of this helper goes on to resolve the
+ * DEPLOYMENT's credential, which is the `install` identity and the only one it can spend. Reading
+ * only the refusal would keep that contract by convention: the day a caller passes
+ * `callerCanSpendPersonal`, the gate would return `identity: "human-acting"`, this helper would
+ * return normally, and the read would run on the install key — the exact OPE-1525 defect, re-entered
+ * through the fix for it. So the precondition is asserted here rather than remembered.
+ */
+export async function assertNotionActingIdentity(ctx, tool) {
+    // own-account-gate: notion — the marker `npm run lint:own-account-gate` reads (OPE-1598). The
+    // connector reaches the gate as a VALUE, through an imported constant, so no checker can read it
+    // from this line; the lint joins CREDENTIAL_GRANT_ROLES to the gated read sites through this
+    // marker, and reds when a connector joins that list with no site declaring it.
+    const verdict = await connectorActingIdentityForTurn(ctx, NOTION_OWN_ACCOUNT_VENDOR, tool);
+    if (verdict.refusal !== undefined)
+        throw new Error(verdict.refusal);
+    if (verdict.identity !== "install") {
+        throw new Error(`Notion read "${tool}": the acting-identity gate allowed ${verdict.identity ?? "no"} identity, ` +
+            `which this call site cannot spend — it resolves the deployment's own Notion credential. ` +
+            `A caller that can act as the member must resolve that credential itself.`);
+    }
+}
+//# sourceMappingURL=notion-acting-identity.js.map

package/dist/agent/channels/notion-acting-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notion-acting-identity.js","sourceRoot":"","sources":["../../../agent/channels/notion-acting-identity.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,yEAAyE;AACzE,EAAE;AACF,oGAAoG;AACpG,kGAAkG;AAClG,mGAAmG;AACnG,gGAAgG;AAChG,wDAAwD;AACxD,EAAE;AACF,6FAA6F;AAC7F,+FAA+F;AAC/F,mGAAmG;AACnG,oGAAoG;AACpG,gFAAgF;AAChF,EAAE;AACF,oGAAoG;AACpG,8FAA8F;AAC9F,oGAAoG;AACpG,6DAA6D;AAC7D,sDAAsD;AACtD,yFAAyF;AACzF,gFAAgF;AAChF,qGAAqG;AACrG,mGAAmG;AACnG,mFAAmF;AACnF,qFAAqF;AACrF,kGAAkG;AAClG,qGAAqG;AACrG,sEAAsE;AACtE,gGAAgG;AAChG,gGAAgG;AAChG,mGAAmG;AACnG,oFAAoF;AACpF,mFAAmF;AACnF,EAAE;AACF,uFAAuF;AACvF,iGAAiG;AACjG,kGAAkG;AAClG,qFAAqF;AAErF,OAAO,EAAE,8BAA8B,EAAE,mBAAmB,EAA+C,MAAM,4CAA4C,CAAC;AAC9J,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D;;;;;;;2CAO2C;AAC3C,MAAM,yBAAyB,GAAqB,mBAAmB,CAAC,eAAe,CAAC,CAAC;AAEzF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,GAAoB,EAAE,IAAY;IACjF,8FAA8F;IAC9F,iGAAiG;IACjG,6FAA6F;IAC7F,+EAA+E;IAC/E,MAAM,OAAO,GAAG,MAAM,8BAA8B,CAAC,GAAG,EAAE,yBAAyB,EAAE,IAAI,CAAC,CAAC;IAC3F,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,gBAAgB,IAAI,uCAAuC,OAAO,CAAC,QAAQ,IAAI,IAAI,aAAa;YAC9F,0FAA0F;YAC1F,0EAA0E,CAC7E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/agent/channels/notion-ancestry-trust.d.ts

@@ -0,0 +1,208 @@
+/**
+ * What Notion says owns an id. A closed union so every branch of the walk is decided explicitly —
+ * `unresolvable` is a real member rather than an `undefined` that a caller might read as "no parent,
+ * so it must be the root".
+ */
+export type NotionParentLink = {
+    readonly kind: "page";
+    readonly pageId: string;
+}
+/** A page nested inside a block (a column, a toggle) — keep walking through the block. */
+ | {
+    readonly kind: "block";
+    readonly blockId: string;
+}
+/** A database row, or a database's own container. The walk STOPS here. */
+ | {
+    readonly kind: "database";
+    readonly databaseId: string;
+}
+/** The workspace itself — the chain ended, and no trust root sat on it. */
+ | {
+    readonly kind: "workspace";
+}
+/** Notion would not say: a 404, a throw, a parent shape we do not recognise. */
+ | {
+    readonly kind: "unresolvable";
+};
+/** Why the verdict came out the way it did — the audited reason, and the whole statement. */
+export type NotionAncestryReason = 
+/** the page IS a declared trust root — no walk, no I/O */
+"self"
+/** a page ABOVE it is a declared trust root */
+ | "ancestor"
+/** the chain reached the workspace root with no root on it */
+ | "workspace-root"
+/** the chain reached a database — rows are never reached by an ancestor declaration */
+ | "database-boundary"
+/** the walk ran out of hops before deciding */
+ | "hop-limit"
+/** the chain revisited an id it had already seen */
+ | "cycle"
+/** Notion would not name a parent (404, throw, unknown shape, an empty id) */
+ | "unresolvable"
+/** no trust root is declared for this workspace at all — nothing to walk towards */
+ | "no-roots";
+export interface NotionAncestryVerdict {
+    readonly trusted: boolean;
+    readonly reason: NotionAncestryReason;
+    /** The trust root that matched, in canonical form. Present only when `trusted`. */
+    readonly matchedRoot?: string;
+    /** How many parent lookups the walk consumed. `0` for the `self` and `no-roots` exits. */
+    readonly hops: number;
+}
+/** How long ONE resolved parent edge stays cached. Short on purpose: a moved page keeps its old
+ *  ancestry for at most this long. */
+export declare const NOTION_ANCESTRY_TTL_MS = 60000;
+/** The prepared, validated roots — canonical page ids grouped by workspace. Opaque by intent: the
+ *  matching rules (canonicalisation, workspace scoping) belong to this module, not to its callers. */
+export interface NotionTrustRoots {
+    readonly byWorkspace: ReadonlyMap<string, ReadonlySet<string>>;
+}
+/** Thrown by {@link prepareNotionTrustRoots}. Its own class so a boot handler can tell a trust-config
+ *  mistake from any other startup error. */
+export declare class NotionTrustConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate and prepare the declared trust roots, FAIL-LOUD.
+ *
+ * An entry is a THREE-SEGMENT Notion surface key, `notion/<workspaceId>/<pageId>` — the same key
+ * shape the trust register and a domain's exact `reach` entries already use. It means "this page and every page
+ * underneath it, except across a database boundary".
+ *
+ * TWO GRAINS ARE REFUSED BY NAME, each with the reason in the message. A named refusal an operator
+ * reads beats a silent gap they assume is covered — the same discipline `memory/domain.ts` applies to
+ * an intermediate container `reach` entry. `defineSurface` refuses both grains first, in vendor-free
+ * words; these messages stay because they name the NOTION reason (a database row, a walk that would
+ * buy nothing), and because this function is also the direct entry point a test drives.
+ *
+ *   1. DATABASE ROWS (`.../<dbId>/rows`, a fourth segment, or a trailing glob). A database row is a
+ *      SEPARATE page whose relation to the database is exactly the ancestry a key does not carry, and
+ *      rows commonly hold customer-submitted content. A declaration on a database page reaches the
+ *      DATABASE PAGE ONLY.
+ *   2. A WORKSPACE key (`notion/<ws>`). A whole workspace needs no walk — vouch it as a workspace
+ *      surface instead. Accepting it here would run an API-call-per-level walk to reach an answer the
+ *      registry already holds for free.
+ *
+ * 🔴 A TEAMSPACE ID CANNOT BE REFUSED HERE, and pretending otherwise was worse than not trying. A
+ * Notion teamspace id is a 32-hex uuid — the SAME shape as a page id — so no test on the string can
+ * tell the two apart. A teamspace never appears as a `parent` on any Notion object either, so a
+ * teamspace root matches nothing the walk ever sees: it is accepted, and then silently grants
+ * nothing. Config time cannot close that; {@link probeUnreachableNotionTrustRoots} closes it at RUN
+ * time by asking Notion what the root is, and {@link resolveNotionDeliveryTrust} runs that probe on
+ * the first walk that fails to match.
+ */
+export declare function prepareNotionTrustRoots(entries: Iterable<string>): NotionTrustRoots;
+/**
+ * THE SUBTREE HANDLER (OPE-539) — core hands this every `subtree: true` surface key an operator
+ * declared for Notion, at boot and again on any later `registerSurfaces`. A call REPLACES the
+ * previous register, the same convention `registerSurfaces` itself uses.
+ *
+ * It is wired ONCE, by `registerSubtreePlatform("notion", registerNotionTrustRoots)` in
+ * agent/register.ts. Nothing else calls it in production; a test may call it directly to stand up a
+ * register without composing core.
+ *
+ * Validation is {@link prepareNotionTrustRoots}, so a key core accepted but Notion cannot use — a
+ * last segment that is not a page id — is a BOOT error the operator reads. Core refuses the grain
+ * (a tenant key, a glob, a group rung, a `public` subtree); this refuses the vendor's own rules.
+ *
+ * Fail-CLOSED before the call and after an empty one: {@link notionTrustRoots} returns an empty
+ * register, and an empty register makes every page's verdict `no-roots` with no I/O at all.
+ */
+export declare function registerNotionTrustRoots(entries: Iterable<string>): void;
+/** The registered roots — the value the Notion route hands the webhook core. Empty until the app
+ *  registers, which is the fail-closed default. */
+export declare function notionTrustRoots(): NotionTrustRoots;
+/** Test seam: drop the register (a fresh test must not inherit another's declarations). */
+export declare function _resetNotionTrustRootsForTest(): void;
+interface CacheEntry {
+    readonly link: NotionParentLink;
+    readonly expiresAt: number;
+}
+/**
+ * The per-page ancestry cache. A separate object (not a module-level singleton only) so a test can
+ * hold its own and so two workspaces never share an entry by accident; {@link notionAncestryCache}
+ * is the shared process-wide one the real ingestion path uses.
+ */
+export interface NotionAncestryCache {
+    readonly entries: Map<string, CacheEntry>;
+}
+/** Test seam, and the operator escape hatch after a big page move: drop every cached edge. */
+export declare function clearNotionAncestryCache(cache?: NotionAncestryCache): void;
+export interface NotionAncestryDeps {
+    /** Ask Notion what owns an id. MUST NOT throw for a "no answer" — but if it does, that is a
+     *  refusal, not an exception the caller has to handle. */
+    readonly parentOf: (id: string) => Promise<NotionParentLink>;
+    readonly cache?: NotionAncestryCache;
+    readonly now?: () => number;
+    readonly maxHops?: number;
+    readonly ttlMs?: number;
+}
+/**
+ * Is `pageId` a declared trust root, or underneath one, in `workspaceId`?
+ *
+ * The cheap decision first: if the page IS a root, the verdict is `self` and NO I/O happens at all —
+ * the same "try the pure fence before paying for the hop" order `resolveNotionReadTarget` uses. Only
+ * a miss walks, one `parentOf` call per level, bounded by `maxHops`.
+ *
+ * Every non-trusted exit is explicit, and each is a REFUSAL rather than a fallthrough: the workspace
+ * root, a database boundary, the hop limit, a cycle, and an unresolvable link. There is no branch
+ * that returns `trusted: true` without a canonical id equal to a declared trust root.
+ *
+ * A BLOCK parent is walked THROUGH, not matched: a root is a page, and a page nested in a column or
+ * a toggle reports the enclosing block as its parent. Walking through it is what makes the subtree
+ * answer correct for a nested page; matching a block id against the roots would be matching a
+ * different kind of id.
+ */
+export declare function resolveNotionAncestorTrust(pageId: string, workspaceId: string, roots: NotionTrustRoots, deps: NotionAncestryDeps): Promise<NotionAncestryVerdict>;
+/** Test seam: forget which roots were probed. */
+export declare function _resetNotionTrustRootProbesForTest(): void;
+/**
+ * Which declared roots for this workspace does Notion NOT serve as a page or a block?
+ *
+ * 🔴 THIS IS THE TEAMSPACE DETECTOR, and it is the only one that can work. A teamspace id is a
+ * 32-hex uuid, so {@link prepareNotionTrustRoots} cannot refuse it on its shape — but Notion answers
+ * neither `GET /v1/pages/<teamspaceId>` nor `GET /v1/blocks/<teamspaceId>`, so `parentOf` returns
+ * `unresolvable` for it while a real page ALWAYS resolves a parent (a top-level page resolves
+ * `workspace`). A root that comes back unresolvable is a root that can never grant anything, and the
+ * operator has to hear about it.
+ *
+ * 🔴 IT REPORTS, IT NEVER WITHDRAWS A ROOT — and that is not timidity. An integration is shared on a
+ * page and inherits DOWNWARD, so a root declared one level ABOVE the shared page is unreadable to
+ * this credential and STILL matches: the walk reads the child's own `parent.page_id` and compares
+ * IDS, with no retrieval of the root. Withdrawing such a root would break a working config over a
+ * permission the walk does not need.
+ *
+ * FAIL-SOFT BY CONSTRUCTION, not by a `catch`: every lookup goes through {@link cachedParentOf},
+ * which turns a throw into `unresolvable`. So a probe can never throw at its caller.
+ *
+ * ⚠️ A TRANSIENT NOTION FAILURE THEREFORE READS AS UNREACHABLE, once. The memo is written whatever
+ * the probe found, so an outage during the first probe costs ONE wrong warning for the life of the
+ * process and never touches a verdict. That is the deliberate trade: re-asking on every delivery
+ * would spend an API call per delivery to sharpen a log line.
+ */
+export declare function probeUnreachableNotionTrustRoots(workspaceId: string, roots: NotionTrustRoots, deps: NotionAncestryDeps): Promise<readonly string[]>;
+/** The per-delivery answer: the ancestry verdict, plus any declared root this credential's probe
+ *  could not resolve. Both fields are AUDIT input — the route writes them onto the dispatch row so
+ *  a refusal says WHICH refusal happened, and a dead root says which root is dead. */
+export interface NotionDeliveryTrust extends NotionAncestryVerdict {
+    /** Declared roots for this workspace that Notion serves as neither a page nor a block. Present
+     *  only when the probe ran and found some — see {@link probeUnreachableNotionTrustRoots}. */
+    readonly unreachableRoots?: readonly string[];
+}
+/**
+ * THE INGESTION SEAM. Resolve one ingested page's trust verdict, and diagnose a root that never
+ * matches.
+ *
+ * 🔴 A DEPLOYMENT THAT DECLARES NO ROOT PAYS NOTHING. No roots for this workspace ⇒ `no-roots`,
+ * zero API calls, zero probes — byte-identical to the behaviour before this seam existed. That is
+ * what makes the feature opt-in rather than a cost every Notion deployment carries.
+ *
+ * The probe runs ONLY on a walk that both ran and failed to match (`no-roots` and `self` never reach
+ * it), so the diagnosis costs nothing on the trusted path and nothing on the un-configured path. It
+ * cannot move the verdict either — it only adds `unreachableRoots`.
+ */
+export declare function resolveNotionDeliveryTrust(pageId: string, workspaceId: string, roots: NotionTrustRoots | undefined, deps: NotionAncestryDeps): Promise<NotionDeliveryTrust>;
+export {};
+//# sourceMappingURL=notion-ancestry-trust.d.ts.map

package/dist/agent/channels/notion-ancestry-trust.d.ts.map

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

package/dist/agent/channels/notion-ancestry-trust.js

@@ -0,0 +1,331 @@
+// The NOTION ANCESTOR WALK for trust (OPE-491) — "is this page underneath a TRUST ROOT the operator
+// declared?", answered in the VENDOR ADAPTER.
+//
+// WHERE IT IS CALLED (OPE-492). ONE call site: `handleNotionDelivery` (channels/notion-webhook.ts)
+// resolves {@link resolveNotionDeliveryTrust} once per INGESTED EVENT, after the classifier drops a
+// self/bot comment and before it builds the auth. The verdict rides the auth as the `trust_root`
+// attribute, and `bindNotion` (channels/notion-identity.ts) turns that attribute into the mapper's
+// `internal` verdict. So the walk runs once per page per delivery, never per tool call — the layer
+// above only ever sees an already-resolved answer, which is the whole reason the walk is allowed to
+// live here (see below).
+//
+// 🔴 WHERE A ROOT IS DECLARED (OPE-539). A root is ONE LINE of the shared trust registry that carries
+// the word `subtree`:
+//
+//     defineSurface({ key: "notion/<workspaceId>/<pageId>", trust: "internal", subtree: true })
+//
+// An entry WITHOUT `subtree` vouches THAT ONE PAGE and nothing under it — the widening is opt-in on
+// the line, so no Notion entry an operator already wrote changed meaning when the walk shipped. This
+// bundle declares that Notion honours the word (`registerSubtreePlatform` in agent/register.ts) and
+// receives the declared keys through {@link registerNotionTrustRoots}. There is no second list and no
+// app file that imports this package: core carries the claim, this module resolves it.
+//
+// Format: `notion/<workspaceId>/<pageId>` — the same key shape the trust register and the `reach`
+// rosters use. Hyphenated or bare ids both work; they are canonicalised.
+//
+// WHY IT LIVES HERE AND NOT IN CORE. A Notion surface key is `notion/<workspace>/<page>` and it
+// carries NO hierarchy: a page's parent is on the page OBJECT, so a subtree question costs an API
+// call per level. Core's `resolveDomainForChannel` is PURE and SYNCHRONOUS on purpose — a domain is
+// an authorization input, and "making it depend on a fetch would make EffectiveAccess time-varying —
+// that is a change of authorization semantics, not a refactor". The same doctrine names the way out:
+// "any hierarchy that needs a lookup belongs in the vendor adapter, which hands this layer keys it
+// has already resolved" (memory/domain.ts). This module is that adapter-side lookup. It hands back a
+// verdict about ONE page, so the layer above still only ever sees an already-resolved answer.
+//
+// THE SHIPPED PRECEDENT for the async resolve-then-fence hop is `assertNotionPageAllowedOrResolveBlock`
+// in notion-scope.ts: try the cheap pure decision first, and only on a miss pay for the walk. The
+// same shape is used here — a page that IS a root needs no I/O at all.
+//
+// 🔴 FAIL CLOSED, EVERY EXIT. Unresolvable ancestry is NOT trusted. A lookup that throws, a chain
+// that runs out of hops, a chain that loops, a parent Notion will not name — all of them return
+// `trusted: false`. "We could not walk it" must never read as "we walked it and it was internal".
+//
+// 🔴 THE WALK STOPS AT A DATABASE. A database ROW is a separate page whose parent is the database,
+// and a row commonly holds customer-submitted content. So a root declared above a database does NOT
+// reach that database's rows: the walk returns `database-boundary` and the row is untrusted. The
+// matching CONFIG-TIME refusal is in {@link prepareNotionTrustRoots}, by name, so an operator who
+// tries to declare row-grain trust reads why instead of assuming it worked.
+//
+// 🔴 THE CACHE IS THE STALENESS. Ancestry is cached per page id for {@link NOTION_ANCESTRY_TTL_MS},
+// so a page MOVED between trees keeps its old ancestry until the entry expires — in whichever
+// direction the move went. That is a known and accepted cost of this route, and it is why the TTL is
+// short. Only a RESOLVED edge is ever cached; an unresolvable one is never written, so a transient
+// API failure can never stick as a lasting answer.
+import { canonicalNotionId } from "./notion-scope.js";
+/** How far up the walk will climb before giving up. A real page tree is a handful of levels deep;
+ *  an unbounded walk over attacker-chosen ids is its own problem. Exhausting it is a REFUSAL. */
+const NOTION_ANCESTRY_MAX_HOPS = 8;
+/** How long ONE resolved parent edge stays cached. Short on purpose: a moved page keeps its old
+ *  ancestry for at most this long. */
+export const NOTION_ANCESTRY_TTL_MS = 60_000;
+/** A Notion id: 32 hex digits, hyphenated or bare. The `<page>` segment must look like one — this
+ *  is what stops a human-readable label from being accepted as a page and silently never matching. */
+const NOTION_ID = /^[0-9a-f]{32}$/;
+/** Thrown by {@link prepareNotionTrustRoots}. Its own class so a boot handler can tell a trust-config
+ *  mistake from any other startup error. */
+export class NotionTrustConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NotionTrustConfigError";
+    }
+}
+/**
+ * Validate and prepare the declared trust roots, FAIL-LOUD.
+ *
+ * An entry is a THREE-SEGMENT Notion surface key, `notion/<workspaceId>/<pageId>` — the same key
+ * shape the trust register and a domain's exact `reach` entries already use. It means "this page and every page
+ * underneath it, except across a database boundary".
+ *
+ * TWO GRAINS ARE REFUSED BY NAME, each with the reason in the message. A named refusal an operator
+ * reads beats a silent gap they assume is covered — the same discipline `memory/domain.ts` applies to
+ * an intermediate container `reach` entry. `defineSurface` refuses both grains first, in vendor-free
+ * words; these messages stay because they name the NOTION reason (a database row, a walk that would
+ * buy nothing), and because this function is also the direct entry point a test drives.
+ *
+ *   1. DATABASE ROWS (`.../<dbId>/rows`, a fourth segment, or a trailing glob). A database row is a
+ *      SEPARATE page whose relation to the database is exactly the ancestry a key does not carry, and
+ *      rows commonly hold customer-submitted content. A declaration on a database page reaches the
+ *      DATABASE PAGE ONLY.
+ *   2. A WORKSPACE key (`notion/<ws>`). A whole workspace needs no walk — vouch it as a workspace
+ *      surface instead. Accepting it here would run an API-call-per-level walk to reach an answer the
+ *      registry already holds for free.
+ *
+ * 🔴 A TEAMSPACE ID CANNOT BE REFUSED HERE, and pretending otherwise was worse than not trying. A
+ * Notion teamspace id is a 32-hex uuid — the SAME shape as a page id — so no test on the string can
+ * tell the two apart. A teamspace never appears as a `parent` on any Notion object either, so a
+ * teamspace root matches nothing the walk ever sees: it is accepted, and then silently grants
+ * nothing. Config time cannot close that; {@link probeUnreachableNotionTrustRoots} closes it at RUN
+ * time by asking Notion what the root is, and {@link resolveNotionDeliveryTrust} runs that probe on
+ * the first walk that fails to match.
+ */
+export function prepareNotionTrustRoots(entries) {
+    const byWorkspace = new Map();
+    for (const raw of entries) {
+        const entry = typeof raw === "string" ? raw.trim() : "";
+        const segs = entry.split("/");
+        if (segs[0] !== "notion") {
+            throw new NotionTrustConfigError(`notion trust root ${JSON.stringify(entry)} is not a Notion surface key — expected "notion/<workspaceId>/<pageId>".`);
+        }
+        if (segs.length === 2) {
+            throw new NotionTrustConfigError(`notion trust root ${JSON.stringify(entry)} names a WHOLE WORKSPACE, which is not a trust root — a workspace needs no ancestor walk, so vouch the workspace key directly in the surface register instead of paying an API call per level to reach the same answer.`);
+        }
+        if (segs.length < 3) {
+            throw new NotionTrustConfigError(`notion trust root ${JSON.stringify(entry)} is not a Notion surface key — expected "notion/<workspaceId>/<pageId>".`);
+        }
+        if (segs.length > 3) {
+            throw new NotionTrustConfigError(`notion trust root ${JSON.stringify(entry)} is DEEPER than a page, which is refused BY NAME: the only thing under a Notion page that a deeper path could name is a DATABASE ROW, and a row is a separate page holding commonly customer-submitted content. A declaration on a database page reaches the DATABASE PAGE ITSELF and never its rows. Declare "notion/<workspaceId>/<pageId>" for the page, and list any row you genuinely trust as its own entry.`);
+        }
+        const page = segs[2] ?? "";
+        if (page.includes("*")) {
+            throw new NotionTrustConfigError(`notion trust root ${JSON.stringify(entry)} uses a GLOB, which cannot match anything: a Notion page id is an opaque 32-hex uuid, so a prefix carries no meaning. Name the top page; the ancestor walk is what reaches the pages under it.`);
+        }
+        const workspace = segs[1] ?? "";
+        if (!workspace) {
+            throw new NotionTrustConfigError(`notion trust root ${JSON.stringify(entry)} has an EMPTY workspace segment — expected "notion/<workspaceId>/<pageId>".`);
+        }
+        const canonical = canonicalNotionId(page);
+        if (!NOTION_ID.test(canonical)) {
+            throw new NotionTrustConfigError(`notion trust root ${JSON.stringify(entry)} does not name a page — the last segment must be a Notion page id (32 hex digits, hyphenated or bare), not a title or a label.`);
+        }
+        const set = byWorkspace.get(workspace) ?? new Set();
+        set.add(canonical);
+        byWorkspace.set(workspace, set);
+    }
+    return { byWorkspace };
+}
+/** No workspace, no root — the value every read gets before the app registers, and the value a
+ *  deployment that declares nothing keeps for ever. Fail-closed: nothing is a trust root. */
+const NO_TRUST_ROOTS = { byWorkspace: new Map() };
+let registeredRoots = NO_TRUST_ROOTS;
+/**
+ * THE SUBTREE HANDLER (OPE-539) — core hands this every `subtree: true` surface key an operator
+ * declared for Notion, at boot and again on any later `registerSurfaces`. A call REPLACES the
+ * previous register, the same convention `registerSurfaces` itself uses.
+ *
+ * It is wired ONCE, by `registerSubtreePlatform("notion", registerNotionTrustRoots)` in
+ * agent/register.ts. Nothing else calls it in production; a test may call it directly to stand up a
+ * register without composing core.
+ *
+ * Validation is {@link prepareNotionTrustRoots}, so a key core accepted but Notion cannot use — a
+ * last segment that is not a page id — is a BOOT error the operator reads. Core refuses the grain
+ * (a tenant key, a glob, a group rung, a `public` subtree); this refuses the vendor's own rules.
+ *
+ * Fail-CLOSED before the call and after an empty one: {@link notionTrustRoots} returns an empty
+ * register, and an empty register makes every page's verdict `no-roots` with no I/O at all.
+ */
+export function registerNotionTrustRoots(entries) {
+    registeredRoots = prepareNotionTrustRoots(entries);
+}
+/** The registered roots — the value the Notion route hands the webhook core. Empty until the app
+ *  registers, which is the fail-closed default. */
+export function notionTrustRoots() {
+    return registeredRoots;
+}
+/** Test seam: drop the register (a fresh test must not inherit another's declarations). */
+export function _resetNotionTrustRootsForTest() {
+    registeredRoots = NO_TRUST_ROOTS;
+}
+/** The process-wide cache the ingestion path uses when the caller passes none. */
+const notionAncestryCache = { entries: new Map() };
+/** Test seam, and the operator escape hatch after a big page move: drop every cached edge. */
+export function clearNotionAncestryCache(cache = notionAncestryCache) {
+    cache.entries.clear();
+}
+/**
+ * One cached parent lookup.
+ *
+ * 🔴 ONLY A RESOLVED EDGE IS CACHED. An `unresolvable` answer — including a thrown lookup — is
+ * returned but never written, for two reasons that both matter: a transient Notion failure must not
+ * pin a page as untrusted for the whole TTL, and an entry that says "unknown" is exactly the entry a
+ * later reader could mistake for a decided one. The verdict for an unresolvable edge is untrusted
+ * either way, so nothing is gained by remembering it.
+ */
+async function cachedParentOf(id, deps) {
+    const cache = deps.cache ?? notionAncestryCache;
+    const now = deps.now ?? Date.now;
+    const ttl = deps.ttlMs ?? NOTION_ANCESTRY_TTL_MS;
+    const key = canonicalNotionId(id);
+    const hit = cache.entries.get(key);
+    if (hit) {
+        if (hit.expiresAt > now())
+            return hit.link;
+        cache.entries.delete(key);
+    }
+    let link;
+    try {
+        link = await deps.parentOf(id);
+    }
+    catch {
+        return { kind: "unresolvable" };
+    }
+    if (!link || link.kind === "unresolvable")
+        return { kind: "unresolvable" };
+    cache.entries.set(key, { link, expiresAt: now() + ttl });
+    return link;
+}
+/**
+ * Is `pageId` a declared trust root, or underneath one, in `workspaceId`?
+ *
+ * The cheap decision first: if the page IS a root, the verdict is `self` and NO I/O happens at all —
+ * the same "try the pure fence before paying for the hop" order `resolveNotionReadTarget` uses. Only
+ * a miss walks, one `parentOf` call per level, bounded by `maxHops`.
+ *
+ * Every non-trusted exit is explicit, and each is a REFUSAL rather than a fallthrough: the workspace
+ * root, a database boundary, the hop limit, a cycle, and an unresolvable link. There is no branch
+ * that returns `trusted: true` without a canonical id equal to a declared trust root.
+ *
+ * A BLOCK parent is walked THROUGH, not matched: a root is a page, and a page nested in a column or
+ * a toggle reports the enclosing block as its parent. Walking through it is what makes the subtree
+ * answer correct for a nested page; matching a block id against the roots would be matching a
+ * different kind of id.
+ */
+export async function resolveNotionAncestorTrust(pageId, workspaceId, roots, deps) {
+    const declared = roots.byWorkspace.get(workspaceId);
+    if (!declared || declared.size === 0)
+        return { trusted: false, reason: "no-roots", hops: 0 };
+    const start = canonicalNotionId(pageId);
+    if (declared.has(start))
+        return { trusted: true, reason: "self", matchedRoot: start, hops: 0 };
+    const maxHops = deps.maxHops ?? NOTION_ANCESTRY_MAX_HOPS;
+    const seen = new Set([start]);
+    let current = pageId;
+    for (let hop = 1; hop <= maxHops; hop++) {
+        const link = await cachedParentOf(current, deps);
+        if (link.kind === "unresolvable")
+            return { trusted: false, reason: "unresolvable", hops: hop };
+        if (link.kind === "workspace")
+            return { trusted: false, reason: "workspace-root", hops: hop };
+        if (link.kind === "database")
+            return { trusted: false, reason: "database-boundary", hops: hop };
+        const next = link.kind === "page" ? link.pageId : link.blockId;
+        const canonical = canonicalNotionId(next);
+        // An EMPTY parent id is not a loop, it is Notion declining to say — keep the two reasons apart
+        // so the audited reason stays true. Both are refusals; only the wording differs.
+        if (!canonical)
+            return { trusted: false, reason: "unresolvable", hops: hop };
+        if (seen.has(canonical))
+            return { trusted: false, reason: "cycle", hops: hop };
+        seen.add(canonical);
+        if (link.kind === "page" && declared.has(canonical)) {
+            return { trusted: true, reason: "ancestor", matchedRoot: canonical, hops: hop };
+        }
+        current = next;
+    }
+    return { trusted: false, reason: "hop-limit", hops: maxHops };
+}
+// --- the ingestion seam (OPE-492) -------------------------------------------
+//
+// One function the webhook core calls per ingested event: resolve the page's verdict, and — only
+// when a declared root failed to match — spend one probe telling the operator that a root of theirs
+// is not a page Notion will serve.
+/** Ids already probed in this process, keyed `<workspaceId>/<canonical root>`. A root is probed AT
+ *  MOST ONCE per process, whatever the probe found: the finding is a WARNING, so re-asking on every
+ *  delivery would buy nothing and cost an API call each time. A process restart re-probes. */
+const probedRoots = new Set();
+/** Test seam: forget which roots were probed. */
+export function _resetNotionTrustRootProbesForTest() {
+    probedRoots.clear();
+}
+/**
+ * Which declared roots for this workspace does Notion NOT serve as a page or a block?
+ *
+ * 🔴 THIS IS THE TEAMSPACE DETECTOR, and it is the only one that can work. A teamspace id is a
+ * 32-hex uuid, so {@link prepareNotionTrustRoots} cannot refuse it on its shape — but Notion answers
+ * neither `GET /v1/pages/<teamspaceId>` nor `GET /v1/blocks/<teamspaceId>`, so `parentOf` returns
+ * `unresolvable` for it while a real page ALWAYS resolves a parent (a top-level page resolves
+ * `workspace`). A root that comes back unresolvable is a root that can never grant anything, and the
+ * operator has to hear about it.
+ *
+ * 🔴 IT REPORTS, IT NEVER WITHDRAWS A ROOT — and that is not timidity. An integration is shared on a
+ * page and inherits DOWNWARD, so a root declared one level ABOVE the shared page is unreadable to
+ * this credential and STILL matches: the walk reads the child's own `parent.page_id` and compares
+ * IDS, with no retrieval of the root. Withdrawing such a root would break a working config over a
+ * permission the walk does not need.
+ *
+ * FAIL-SOFT BY CONSTRUCTION, not by a `catch`: every lookup goes through {@link cachedParentOf},
+ * which turns a throw into `unresolvable`. So a probe can never throw at its caller.
+ *
+ * ⚠️ A TRANSIENT NOTION FAILURE THEREFORE READS AS UNREACHABLE, once. The memo is written whatever
+ * the probe found, so an outage during the first probe costs ONE wrong warning for the life of the
+ * process and never touches a verdict. That is the deliberate trade: re-asking on every delivery
+ * would spend an API call per delivery to sharpen a log line.
+ */
+export async function probeUnreachableNotionTrustRoots(workspaceId, roots, deps) {
+    const declared = roots.byWorkspace.get(workspaceId);
+    if (!declared || declared.size === 0)
+        return [];
+    const unreachable = [];
+    for (const root of declared) {
+        const memo = `${workspaceId}/${root}`;
+        if (probedRoots.has(memo))
+            continue;
+        probedRoots.add(memo);
+        const link = await cachedParentOf(root, deps);
+        if (link.kind === "unresolvable")
+            unreachable.push(root);
+    }
+    return unreachable;
+}
+/**
+ * THE INGESTION SEAM. Resolve one ingested page's trust verdict, and diagnose a root that never
+ * matches.
+ *
+ * 🔴 A DEPLOYMENT THAT DECLARES NO ROOT PAYS NOTHING. No roots for this workspace ⇒ `no-roots`,
+ * zero API calls, zero probes — byte-identical to the behaviour before this seam existed. That is
+ * what makes the feature opt-in rather than a cost every Notion deployment carries.
+ *
+ * The probe runs ONLY on a walk that both ran and failed to match (`no-roots` and `self` never reach
+ * it), so the diagnosis costs nothing on the trusted path and nothing on the un-configured path. It
+ * cannot move the verdict either — it only adds `unreachableRoots`.
+ */
+export async function resolveNotionDeliveryTrust(pageId, workspaceId, roots, deps) {
+    const declared = roots ?? NO_TRUST_ROOTS;
+    const verdict = await resolveNotionAncestorTrust(pageId, workspaceId, declared, deps);
+    if (verdict.trusted || verdict.reason === "no-roots")
+        return verdict;
+    // No `try` here on purpose: probeUnreachableNotionTrustRoots cannot throw (see its contract), and a
+    // catch that can never run is a guard nobody can test.
+    const unreachable = await probeUnreachableNotionTrustRoots(workspaceId, declared, deps);
+    return unreachable.length > 0 ? { ...verdict, unreachableRoots: unreachable } : verdict;
+}
+//# sourceMappingURL=notion-ancestry-trust.js.map