@open-everywhere/provider-notion 0.1.0

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

@@ -0,0 +1,458 @@
+// 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";
+
+/**
+ * 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 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;
+
+// --- config: the trust roots ---------------------------------------------
+//
+// A trust root is an EXPLICIT operator declaration, exactly like a vouched surface: it exists
+// only to raise a subtree above the fail-closed default, and core never infers one. Preparing the
+// list is FAIL-LOUD (config time) so a grain we do not support is a boot error an operator reads,
+// not a silently-ignored line they assume is covered.
+
+/** 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>>;
+}
+
+/** 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: string) {
+    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: Iterable<string>): NotionTrustRoots {
+  const byWorkspace = new Map<string, Set<string>>();
+  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<string>();
+    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: NotionTrustRoots = { byWorkspace: new Map() };
+
+let registeredRoots: NotionTrustRoots = 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: Iterable<string>): void {
+  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(): NotionTrustRoots {
+  return registeredRoots;
+}
+
+/** Test seam: drop the register (a fresh test must not inherit another's declarations). */
+export function _resetNotionTrustRootsForTest(): void {
+  registeredRoots = NO_TRUST_ROOTS;
+}
+
+// --- the ancestry cache -----------------------------------------------------
+
+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>;
+}
+
+/** The process-wide cache the ingestion path uses when the caller passes none. */
+const notionAncestryCache: 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 = notionAncestryCache): void {
+  cache.entries.clear();
+}
+
+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;
+}
+
+/**
+ * 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: string, deps: NotionAncestryDeps): Promise<NotionParentLink> {
+  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: NotionParentLink;
+  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: string,
+  workspaceId: string,
+  roots: NotionTrustRoots,
+  deps: NotionAncestryDeps,
+): Promise<NotionAncestryVerdict> {
+  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<string>([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<string>();
+
+/** Test seam: forget which roots were probed. */
+export function _resetNotionTrustRootProbesForTest(): void {
+  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: string,
+  roots: NotionTrustRoots,
+  deps: NotionAncestryDeps,
+): Promise<readonly string[]> {
+  const declared = roots.byWorkspace.get(workspaceId);
+  if (!declared || declared.size === 0) return [];
+  const unreachable: string[] = [];
+  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 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 async function resolveNotionDeliveryTrust(
+  pageId: string,
+  workspaceId: string,
+  roots: NotionTrustRoots | undefined,
+  deps: NotionAncestryDeps,
+): Promise<NotionDeliveryTrust> {
+  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;
+}