@vantageos/backend-doctor 0.1.14 → 0.2.0

package/dist/caller-resolution.js

@@ -0,0 +1,1195 @@
+// CR-1 — does this public registration RESOLVE ITS CALLER before serving or
+// writing data?
+//
+// WHY THIS CONTROL EXISTS, measured not supposed. At vantage-memory
+// bd8c60e94b4cd9ffd579c9e4f84e670280ddebb4, fourteen public queries returned real
+// rows to an ANONYMOUS POST against the live production deployment — no
+// Authorization header, no bearer, no JWT — including `mandates:list` (spending
+// authority) and `tasks:listUnlinkedBlocked` (159 rows). The instrument scored
+// that exact tree `revise-mandatory` and its rendered verdict table NAMED 0 of the
+// 14 (measured: 0/14 at 14f35d9). R-50 did classify 13 of them as violations, but
+// its renderer prints three examples, so no reader of the report could see them;
+// and the fourteenth — `messages:listByChannel` — R-50 called CONFORM, because
+// R-50 asks whether a REFUSAL IS SHAPED CORRECTLY (a typed value versus a throw),
+// and `listByChannel` does call the fail-closed resolver, then allows any caller
+// through a hardcoded `if (ch === "broadcast") return true`. A fifteenth shape,
+// `convex/search.ts::searchFixPatterns`, is an `action` with a hardcoded namespace
+// and no identity at all — outside R-50's population entirely (R-50 scans queries).
+//
+// SO CR-1 ASKS A DIFFERENT QUESTION, and it is deliberately NOT R-50's:
+//   R-50 / R-51 : when this handler refuses, is the refusal SHAPED so a subscribing
+//                 client can render it?  (a rule about the shape of a refusal)
+//   CR-1        : is there a caller RESOLVED at all, and does the resolution decide
+//                 what is served?        (a rule about the presence of authority)
+// A handler with no guard has nothing to throw, so it can never fail a rule about
+// throwing. That is why CR-1 exists, and it is why a "does it refuse properly"
+// check must never creep in here as the test — that would be R-50's blind spot
+// under a new name.
+//
+// FOUR PROPERTIES THIS MODULE HOLDS ITSELF TO, each a defect it was built against:
+//
+// 1. POPULATION IS THE EXPOSED SURFACE ITSELF. It is derived from the TARGET tree's
+//    own `_generated/api.d.ts` (`declare const fullApi: ApiFromModules<{…}>` plus
+//    the `import type * as <key> from "…"` map that resolves each key to a file) —
+//    never a hand-written list, and never a pattern over ARGUMENT NAMES. Three
+//    side-scripts in the target repository were blind to all fourteen precisely
+//    because each defined its population by argument shape: not one of the fourteen
+//    takes a tenant-shaped argument and most take no arguments at all.
+// 2. THE EXCLUSION OF `internal*` IS PROVEN PER SITE. Every registration is read
+//    with the BUILDER TOKEN observed at its own `export const NAME = <builder>(`,
+//    and an excluded site is REPORTED with that token. Nothing is excluded because
+//    of how it is named.
+// 3. THE COUNT CLASSIFIED EQUALS THE COUNT EXPOSED. A discrepancy is CR-1's OWN
+//    BUG and is reported as could-not-judge naming the drift — never rounded away.
+// 4. NO EXEMPTION LIST, NO BASELINE, NO TOLERATED COUNT. The only exit from a
+//    NO-DATA or NO-IDENTITY finding is a justification token written IN THE TARGET
+//    SOURCE at the registration, which this module reads from there. A list of
+//    names living beside the instrument that can hold a name and still pass IS the
+//    defect, so there is none. FAIL-OPEN has no token exit at all.
+//
+// CR-1 IS CRITICAL AND IT READS THE TREE. FAIL-OPEN and unjustified NO-IDENTITY are
+// MECHANICAL violations, so the deploy gate refuses on them.
+//
+// STANDING GAP, NAMED: CR-1 is DOCTOR-OWNED. The pinned backend standard
+// (fixtures/backend-standard-4bcd605.md) numbers R-1..R-51 and does not yet carry
+// this obligation, so CR-1 is deliberately NOT in `registry.ts` — adding an id the
+// vendored standard does not define would make `coverage.ts` report a phantom rule
+// and would forge a pin. It is rendered in its own section, tallied on its own
+// line, and it drives the exit code. Numbering it upstream (proposed R-52) is a
+// separate change to the standard document in its own repository.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { convexRootOf } from "./target.js";
+// ---------------------------------------------------------------------------
+// population — the exposed surface, from the TARGET tree's own api.d.ts
+// ---------------------------------------------------------------------------
+const API_IMPORT = /^import\s+type\s+\*\s+as\s+([A-Za-z0-9_$]+)\s+from\s+"(\.\.\/[^"]+)"/;
+const FULL_API_OPEN = /declare\s+const\s+fullApi\s*:\s*ApiFromModules\s*<\s*\{/;
+const FULL_API_KEY = /^\s*([A-Za-z0-9_$]+)\s*:\s*typeof\s+([A-Za-z0-9_$]+)\s*;?\s*$/;
+/**
+ * Derive the exposed module surface from `<root>/_generated/api.d.ts`. The engine's
+ * loadTree excludes `_generated/`, so this reads the file from the target root —
+ * the same target the CLI was pointed at, never the tool's own install directory
+ * (the defect that let five oracle-scored rules present a frozen CSV count as a
+ * verdict on a tree they never opened).
+ */
+export function deriveApiSurface(root, read = (p) => readFileSync(p, "utf8")) {
+    const path = join(root, "_generated", "api.d.ts");
+    let blob;
+    try {
+        blob = read(path);
+    }
+    catch (e) {
+        return {
+            modules: new Map(),
+            unreadable: `${path} could not be read (${e.message})`,
+        };
+    }
+    const lines = blob.split("\n");
+    const imports = new Map();
+    for (const raw of lines) {
+        const m = API_IMPORT.exec(raw);
+        if (!m)
+            continue;
+        // "../lib/auth.js" -> "lib/auth.ts" (rel to the convex root the tree uses)
+        imports.set(m[1], m[2].replace(/^\.\.\//, "").replace(/\.js$/, ".ts"));
+    }
+    let inFullApi = false;
+    const modules = new Map();
+    const unmapped = [];
+    for (const raw of lines) {
+        if (!inFullApi) {
+            if (FULL_API_OPEN.test(raw))
+                inFullApi = true;
+            continue;
+        }
+        if (/^\}>/.test(raw))
+            break;
+        const k = FULL_API_KEY.exec(raw);
+        if (!k)
+            continue;
+        const rel = imports.get(k[2]);
+        if (rel === undefined) {
+            unmapped.push(k[1]);
+            continue;
+        }
+        modules.set(k[1], rel);
+    }
+    if (modules.size === 0) {
+        return {
+            modules,
+            unreadable: `${path} carries no resolvable \`declare const fullApi: ApiFromModules<{…}>\` member — the exposed surface cannot be derived from it`,
+        };
+    }
+    if (unmapped.length > 0) {
+        return {
+            modules,
+            unreadable: `${path}: fullApi member(s) ${unmapped.join(", ")} resolve to no \`import type * as\` line — CR-1's api.d.ts parse is incomplete (CR-1's own bug, not a tree finding)`,
+        };
+    }
+    return { modules };
+}
+// ---------------------------------------------------------------------------
+// registrations — read with the builder token observed AT each site
+// ---------------------------------------------------------------------------
+/** `export const NAME = <builder>(` — the only registration shape Convex exposes. */
+const REGISTRATION = /^\s*export\s+const\s+([A-Za-z0-9_$]+)\s*=\s*(?:await\s+)?([A-Za-z0-9_$]+)\s*\(/;
+/** `export const NAME = customQuery(` and friends — a wrapper DEFINITION. */
+const CUSTOM_BUILDER_DEF = /^\s*(?:export\s+)?const\s+([A-Za-z0-9_$]+)\s*=\s*(custom(?:Query|Mutation|Action))\s*\(/;
+const FIRST_IDENT = /([A-Za-z_$][A-Za-z0-9_$]*)/;
+const PUBLIC_BASES = new Set(["query", "mutation", "action"]);
+const NON_PUBLIC_BASES = new Set([
+    "internalQuery",
+    "internalMutation",
+    "internalAction",
+    "httpAction",
+]);
+function base(rel) {
+    return (rel.split("/").pop() ?? rel).toLowerCase();
+}
+/** a file CR-1 judges — never a test, never generated. */
+export function isJudgeable(f) {
+    const b = base(f.rel);
+    return (!b.endsWith(".test.ts") &&
+        !b.endsWith(".d.ts") &&
+        !f.rel.includes("__tests__") &&
+        !f.rel.includes("_generated/"));
+}
+function isCode(l) {
+    return !l.comment;
+}
+/**
+ * Discover every registration BUILDER the tree declares, so a `customQuery(query,…)`
+ * wrapper is recognised as public and a `customQuery(internalQuery,…)` wrapper as
+ * not. A wrapper whose base resolves to neither leaves the exposed surface
+ * unknowable → CR-1 refuses (never a silent green).
+ */
+export function discoverBuilders(files) {
+    const map = {
+        publicBuilders: new Map([...PUBLIC_BASES].map((b) => [b, b])),
+        nonPublicBuilders: new Map([...NON_PUBLIC_BASES].map((b) => [b, b])),
+        unresolvable: [],
+    };
+    for (const f of files) {
+        if (!isJudgeable(f))
+            continue;
+        const code = f.lines.filter(isCode);
+        for (let i = 0; i < code.length; i++) {
+            const m = CUSTOM_BUILDER_DEF.exec(code[i].raw);
+            if (!m)
+                continue;
+            const [, name, ,] = m;
+            const after = code[i].raw.slice((m.index ?? 0) + m[0].length);
+            let b = FIRST_IDENT.exec(after)?.[1];
+            for (let j = i + 1; !b && j < code.length && j <= i + 4; j++) {
+                b = FIRST_IDENT.exec(code[j].raw)?.[1];
+            }
+            if (b !== undefined && PUBLIC_BASES.has(b)) {
+                map.publicBuilders.set(name, b);
+            }
+            else if (b !== undefined && NON_PUBLIC_BASES.has(b)) {
+                map.nonPublicBuilders.set(name, b);
+            }
+            else {
+                map.unresolvable.push({
+                    rel: f.rel,
+                    n: code[i].n,
+                    name,
+                    base: b ?? "<none>",
+                });
+            }
+        }
+    }
+    return map;
+}
+/** delimit a body from its opener at index i by matching braces/parens. */
+function blockAt(lines, i) {
+    let depth = 0;
+    let seenOpen = false;
+    const body = [];
+    for (let j = i; j < lines.length; j++) {
+        body.push(lines[j]);
+        for (const ch of lines[j].raw) {
+            if (ch === "(" || ch === "{") {
+                depth += 1;
+                seenOpen = true;
+            }
+            else if (ch === ")" || ch === "}") {
+                depth -= 1;
+            }
+        }
+        if (seenOpen && depth <= 0)
+            return { lines: body, unterminated: false };
+    }
+    return { lines: body, unterminated: seenOpen };
+}
+// ---------------------------------------------------------------------------
+// identity helpers — DERIVED from the tree, transitively; never a name list
+// ---------------------------------------------------------------------------
+const GET_IDENTITY = /ctx\.auth\.getUserIdentity\s*\(/;
+const FN_DECL = /^\s*(?:export\s+)?(?:async\s+)?function\s+([A-Za-z0-9_$]+)\s*[(<]/;
+const FN_CONST = /^\s*(?:export\s+)?const\s+([A-Za-z0-9_$]+)\s*(?::[^=]*)?=\s*(?:async\s+)?(?:\(|function\b)/;
+/** a privileged shape — what "an absent identity is treated as privileged" LOOKS
+ *  like in a returned object: a master flag, or a wildcard authority sentinel. */
+const PRIVILEGED_MARKER = /isMaster\s*:\s*true|"\*"|'\*'|isAdmin\s*:\s*true/;
+/** `opts?.flag` / `options.flag` / `opts.flag` — an opt-in read inside a helper. */
+const OPT_READ = /\b(?:opts|options|o)\s*\??\.\s*([A-Za-z0-9_$]+)/g;
+/** the `name` half of a `rel::name` key. */
+export function nameOf(key) {
+    return key.slice(key.indexOf("::") + 2);
+}
+/** the `rel` half of a `rel::name` key. */
+export function relOf(key) {
+    return key.slice(0, key.indexOf("::"));
+}
+/**
+ * The members of `set` that a handler in `rel` can actually reach: a plain function
+ * declared in `rel` or imported by `rel`, or a registration (reachable from anywhere,
+ * but only through its qualified `internal.…`/`api.…` name).
+ */
+export function reachable(model, set, rel) {
+    const out = new Map();
+    const scope = model.scopes.get(rel) ?? new Set();
+    for (const key of set) {
+        const name = nameOf(key);
+        const qualified = model.regNames.has(key);
+        if (qualified) {
+            out.set(`q:${name}`, { name, qualified: true });
+            continue;
+        }
+        if (relOf(key) === rel || scope.has(name)) {
+            out.set(name, { name, qualified: false });
+        }
+    }
+    return [...out.values()];
+}
+/** the refs in `refs` that `text` actually references. */
+export function referenced(text, refs) {
+    return refs.filter((r) => references(text, r.name, r.qualified));
+}
+/** `import { a, b as c } from "…"` — the local names a module brings into scope. The
+ *  brace list is very often WRAPPED over several lines by the formatter, so a
+ *  single-line regex misses it entirely: that is not a cosmetic miss, it empties the
+ *  importing module's scope and files every handler that calls an imported resolver
+ *  under NO-IDENTITY (measured on run 8: 83 NO-IDENTITY, `messages:listByChannel`
+ *  among them, because `withOrgScope` is imported across four lines). */
+const IMPORT_OPEN = /^\s*import\s+(?:type\s+)?\{(.*)$/;
+/** collect (`rel::name` -> body) for every function-like declaration in the tree,
+ *  plus, per file, the set of local names it declares or imports. */
+function functionBodies(files) {
+    const bodies = new Map();
+    const scopes = new Map();
+    for (const f of files) {
+        if (!isJudgeable(f))
+            continue;
+        const scope = new Set();
+        scopes.set(f.rel, scope);
+        const lines = f.lines;
+        for (let i = 0; i < lines.length; i++) {
+            if (!isCode(lines[i]))
+                continue;
+            const imp = IMPORT_OPEN.exec(lines[i].raw);
+            if (imp) {
+                // accumulate the brace list, however many lines the formatter wrapped it over.
+                let spec = imp[1];
+                let j = i;
+                while (!spec.includes("}") && j + 1 < lines.length) {
+                    j += 1;
+                    spec += `\n${lines[j].raw}`;
+                }
+                for (const part of spec.slice(0, spec.indexOf("}")).split(",")) {
+                    const local = part
+                        .trim()
+                        .split(/\s+as\s+/)
+                        .pop()
+                        ?.trim();
+                    if (local && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(local))
+                        scope.add(local);
+                }
+                i = j;
+                continue;
+            }
+            // REGISTRATION bodies are indexed too: an ACTION resolves its principal by
+            // `ctx.runQuery(internal.lib.auth.resolveOrgScopeForAction, {})`, so the
+            // internalQuery it names must be modelled as an identity resolver or every
+            // action-side authority gate reads as "never consults the principal".
+            const fn = FN_DECL.exec(lines[i].raw) ?? FN_CONST.exec(lines[i].raw);
+            const reg = fn ? null : REGISTRATION.exec(lines[i].raw);
+            const m = fn ?? reg;
+            if (!m)
+                continue;
+            const blk = blockAt(lines, i);
+            scope.add(m[1]);
+            bodies.set(`${f.rel}::${m[1]}`, {
+                text: blk.lines
+                    .filter(isCode)
+                    .map((l) => l.raw)
+                    .join("\n"),
+                at: `${f.rel}:${lines[i].n}`,
+                isRegistration: reg !== null,
+            });
+        }
+    }
+    return { bodies, scopes };
+}
+export function deriveIdentityModel(files) {
+    const { bodies, scopes } = functionBodies(files);
+    const regNames = new Set([...bodies.entries()].filter(([, b]) => b.isRegistration).map(([k]) => k));
+    const base = {
+        helpers: new Set(),
+        gates: new Set(),
+        dataFns: new Set(),
+        permissiveOnAbsence: new Map(),
+        regNames,
+        scopes,
+        privilegeOnAbsenceFlags: new Map(),
+        refuserParams: new Map(),
+    };
+    /** grow `set` to every body that REACHES a member of `set` from its own scope. */
+    const close = (set, rounds) => {
+        for (let round = 0; round < rounds; round++) {
+            let grew = false;
+            for (const [key, b] of bodies) {
+                if (set.has(key))
+                    continue;
+                if (referenced(b.text, reachable(base, set, relOf(key))).length > 0) {
+                    set.add(key);
+                    grew = true;
+                }
+            }
+            if (!grew)
+                break;
+        }
+    };
+    for (const [key, b] of bodies) {
+        if (GET_IDENTITY.test(b.text))
+            base.helpers.add(key);
+    }
+    close(base.helpers, 4);
+    deriveValueRefusers(bodies, base);
+    // GATES — an identity helper that REFUSES on the absent-identity path, read from
+    // its own body; then transitively, a helper that reaches a gate refuses through it.
+    for (const [key, b] of bodies) {
+        if (!base.helpers.has(key))
+            continue;
+        if (absentIdentityBranchThrows(b.text) ||
+            refusesOnResolvedValue(b.text, base, relOf(key))) {
+            base.gates.add(key);
+        }
+    }
+    for (let round = 0; round < 4; round++) {
+        let grew = false;
+        for (const [key, b] of bodies) {
+            if (!base.helpers.has(key) || base.gates.has(key))
+                continue;
+            if (referenced(b.text, reachable(base, base.gates, relOf(key))).length > 0) {
+                base.gates.add(key);
+                grew = true;
+            }
+        }
+        if (!grew)
+            break;
+    }
+    // DATA-TOUCHING functions, closed the same way.
+    for (const [key, b] of bodies) {
+        if (DATA_ACCESS.test(b.text))
+            base.dataFns.add(key);
+    }
+    close(base.dataFns, 5);
+    // PERMISSIVE-ON-ABSENCE: the absent-identity branch returns with no value, i.e.
+    // "proceed" — the opposite of a refusal, read from the helper's own body.
+    for (const [key, b] of bodies) {
+        if (!GET_IDENTITY.test(b.text))
+            continue;
+        const bind0 = /(?:const|let)\s+([A-Za-z0-9_$]+)\s*(?::[^=\n]*)?=\s*\(?\s*await\s+ctx\.auth\.getUserIdentity/.exec(b.text);
+        if (!bind0)
+            continue;
+        const g0 = absentGuard(b.text, bind0[1]);
+        if (!g0)
+            continue;
+        // ALLOW-ON-ABSENCE, conditional or not. A helper is an assertion that the
+        // caller may proceed; a bare `return;` (or `return true`) ANYWHERE in its
+        // absent-identity branch is a path on which an anonymous caller proceeds.
+        // The pre-fix test required the branch to contain NO throw, so the shape
+        //   if (identity === null) { if (isMasterNamespace) return; throw … }
+        // (vantage-peers 9e1413a okfBundleDurable.ts:124-128, okfBundleNode.ts:280-287)
+        // read as a refusing GATE — the throw was seen and the `return;` before it
+        // was not — and every export registration calling it was classed RESOLVES.
+        // A throw AFTER a conditional allow does not refuse the callers the allow
+        // already let through; the condition is on a caller-supplied value
+        // (`namespace`), never on a resolved principal.
+        const allow = PROCEED_RETURN.exec(g0.branch);
+        if (allow) {
+            const conditional = THROWS.test(g0.branch);
+            base.permissiveOnAbsence.set(nameOf(key), conditional
+                ? `${b.at} (${nameOf(key)}: its absent-identity branch returns \`${allow[0].replace(/\s+/g, " ").trim()}\` on a condition BEFORE it throws — an anonymous caller meeting that condition is waved through; the throw refuses only the others)`
+                : `${b.at} (${nameOf(key)}: its absent-identity branch is a bare \`return;\` — an anonymous caller is waved through)`);
+        }
+    }
+    for (const [key, b] of bodies) {
+        if (!GET_IDENTITY.test(b.text))
+            continue;
+        const bind = /(?:const|let)\s+([A-Za-z0-9_$]+)\s*(?::[^=\n]*)?=\s*\(?\s*await\s+ctx\.auth\.getUserIdentity/.exec(b.text);
+        if (!bind)
+            continue;
+        const guard = absentGuard(b.text, bind[1]);
+        if (!guard)
+            continue;
+        const region = guard.branch;
+        OPT_READ.lastIndex = 0;
+        let m;
+        // biome-ignore lint/suspicious/noAssignInExpressions: standard regex-exec loop
+        while ((m = OPT_READ.exec(region)) !== null) {
+            const after = region.slice(m.index, m.index + 900);
+            if (PRIVILEGED_MARKER.test(after)) {
+                base.privilegeOnAbsenceFlags.set(m[1], `${b.at} (${nameOf(key)}: an absent identity returns a privileged shape when \`${m[1]}\` is opted into)`);
+            }
+        }
+    }
+    return base;
+}
+/**
+ * `name` is REFERENCED in `text` — called (`name(`) or passed as a value
+ * (`internal.lib.auth.resolveOrgScopeForAction,`). The second form is how an action
+ * reaches a resolver, so a call-only test is blind to the whole action surface.
+ */
+export function references(text, name, qualified = false) {
+    if (qualified) {
+        // a registration is reached ONLY through the generated api/internal object —
+        // `internal.lib.auth.resolveOrgScopeForAction`. Nothing else may match it.
+        return new RegExp(`\\b(?:internal|api)(?:\\.[A-Za-z0-9_$]+)*\\.${name}\\b`).test(text);
+    }
+    return new RegExp(`(?:^|[^A-Za-z0-9_$.])${name}\\s*(?:\\(|,|\\)|;|$)`, "m").test(text);
+}
+/** Every `if (...)` in `text`, with its brace-balanced condition source. */
+export function ifConditions(text) {
+    const out = [];
+    const open = /\bif\s*\(/g;
+    let m;
+    // biome-ignore lint/suspicious/noAssignInExpressions: standard regex-exec loop
+    while ((m = open.exec(text)) !== null) {
+        let depth = 1;
+        let j = m.index + m[0].length;
+        for (; j < text.length && depth > 0; j++) {
+            if (text[j] === "(")
+                depth += 1;
+            else if (text[j] === ")")
+                depth -= 1;
+        }
+        out.push({
+            index: m.index,
+            cond: text.slice(m.index + m[0].length, j - 1),
+            end: j,
+        });
+    }
+    return out;
+}
+/**
+ * ABSENT-IDENTITY GUARD — an `if` whose condition tests `v` ITSELF for absence:
+ * `!v`, `v === null`, `v == null`, `v === undefined`, including as one disjunct of a
+ * widened test (`if (identity === null || identity === undefined)`, the real
+ * `assertCanExportNamespace` shape). It must NOT match a test on a PROPERTY of `v`
+ * (`if (!scope.isMaster)` is an authority test on a RESOLVED principal, not a test
+ * for its absence) — reading those as absence accused every correctly-scoped
+ * dashboard query on the first run of this rule.
+ */
+export function absentGuard(text, v) {
+    const bare = new RegExp(`(?:^|[^.\\w$])!\\s*${v}\\s*(?![.\\w$[(])`);
+    const nullish = new RegExp(`\\b${v}\\s*===?\\s*(?:null|undefined)\\b`);
+    for (const c of ifConditions(text)) {
+        if (bare.test(c.cond) || nullish.test(c.cond)) {
+            return { index: c.index, branch: branchAfter(text, c.end) };
+        }
+    }
+    return null;
+}
+/**
+ * The GUARDED BRANCH itself, from just after an `if (…)`'s closing paren: a braced
+ * block to its matching brace, else the single statement up to its `;`. Reading a
+ * fixed-width window instead runs past the branch into the rest of the handler, and
+ * that is not a width error — it INVERTS the verdict: `if (ns === null) return [];`
+ * followed by the normal data path read as "the absent-identity branch serves data",
+ * which accused all three `search:*` actions that in fact refuse first (measured).
+ */
+export function branchAfter(text, from) {
+    let i = from;
+    while (i < text.length && /\s/.test(text[i]))
+        i++;
+    if (text[i] === "{") {
+        let depth = 0;
+        for (let j = i; j < text.length; j++) {
+            if (text[j] === "{")
+                depth += 1;
+            else if (text[j] === "}") {
+                depth -= 1;
+                if (depth === 0)
+                    return text.slice(i, j + 1);
+            }
+        }
+        return text.slice(i);
+    }
+    const semi = text.indexOf(";", i);
+    return text.slice(i, semi === -1 ? text.length : semi + 1);
+}
+/**
+ * A helper that resolves the principal through ANOTHER resolver and then REFUSES on
+ * a test of the resolved value is a GATE too — the real `requireFleetMaster` shape:
+ *   const scope = await withOrgScope(ctx);
+ *   if (!scope.isMaster) throw new ConvexError("RBAC_DENIED: …");
+ * `withOrgScope` itself does not throw on an absent identity (it returns an
+ * anonymous, empty scope), so the refusal lives one level up. Missing this level
+ * made the rule accuse all four `mandates:*` writers, which are master-gated.
+ */
+function refusesOnResolvedValue(text, model, rel) {
+    const refs = referenced(text, reachable(model, model.helpers, rel)).filter((r) => !r.qualified);
+    const alts = refs.map((r) => r.name).join("|");
+    const ALT = alts || "\\0NEVER";
+    // SHAPE 1 — declaration and resolution in ONE statement:
+    //   const scope = await withOrgScope(ctx);
+    const bind = new RegExp(`(?:const|let)\\s+([A-Za-z0-9_$]+)\\s*(?::[^=\\n]*)?=\\s*\\(?\\s*(?:await\\s+)?(?:${ALT})\\s*\\(`, "g");
+    // SHAPE 2 — DECLARE THEN ASSIGN, which shape 1 cannot see:
+    //   let scope: Awaited<ReturnType<typeof withOrgScope>>;
+    //   try { scope = await withOrgScope(ctx); } catch { throw … }
+    //   if (!scope.isMaster) throw …
+    // This is the real `requireServiceAccount` of the audited tree (vantage-peers
+    // convex/oauth.ts @ 40c71cb), which declares the local on its own line
+    // PRECISELY so the resolution can sit inside a try and re-raise naming its
+    // own door. Shape 1 requires the `=` to follow the declarator, so every gate
+    // written this way read as ABSENT and SEVEN correctly service-account-gated
+    // oauth handlers were classed FAIL-OPEN. Measured on that tree: FAIL-OPEN
+    // 11 -> 4, RESOLVES 139 -> 146, classified total unchanged at 179.
+    //
+    // Why this is a detector defect rather than a style complaint: a gate that
+    // can only pass by being rewritten into the matcher's single accepted shape
+    // is a gate-satisfiability failure. The instrument reads the code the
+    // codebase writes; it does not demand the code the matcher finds convenient.
+    //
+    // A bare assignment counts only when the SAME identifier is also DECLARED
+    // with let/var in this body, so an assignment to a parameter, an imported
+    // binding or an object property is not mistaken for a local resolution.
+    const assign = new RegExp(`(?:^|[;{}\\n])\\s*([A-Za-z0-9_$]+)\\s*=\\s*\\(?\\s*(?:await\\s+)?(?:${ALT})\\s*\\(`, "g");
+    // SHAPE 3 — an ACTION resolves through a REGISTRATION it cannot call directly:
+    //   const scope = await ctx.runQuery(internal.lib.auth.resolveOrgScopeForAction, {});
+    // (vantage-peers 58ed649 okfBundleNode.ts:271, `assertCanExportNamespace`). The
+    // registration must be a tree-derived identity helper reached by its QUALIFIED
+    // name — never a name list, and never any `ctx.runQuery` whatever it targets:
+    // a runQuery to a data read is not a resolution. Shapes 1-2 drop qualified refs
+    // (a registration is never called by bare name), so every action-side gate of
+    // this form read as "binds nothing" and three gated OKF doors were FAIL-OPEN.
+    const qualifiedAlts = referenced(text, reachable(model, model.helpers, rel))
+        .filter((r) => r.qualified)
+        .map((r) => r.name)
+        .join("|");
+    const runQueryBind = new RegExp(`(?:const|let)\\s+([A-Za-z0-9_$]+)\\s*(?::[^=\\n]*)?=\\s*\\(?\\s*(?:await\\s+)?ctx\\.runQuery\\s*\\(\\s*(?:internal|api)(?:\\.[A-Za-z0-9_$]+)*\\.(?:${qualifiedAlts || "\\0NEVER"})\\b`, "g");
+    const bound = new Set();
+    for (const re of [bind, assign, runQueryBind]) {
+        re.lastIndex = 0;
+        let m;
+        // biome-ignore lint/suspicious/noAssignInExpressions: standard regex-exec loop
+        while ((m = re.exec(text)) !== null) {
+            const v = m[1];
+            if (re === assign && !new RegExp(`(?:let|var)\\s+${v}\\b`).test(text)) {
+                continue; // assigned but never declared here — not a local resolution.
+            }
+            bound.add(v);
+        }
+    }
+    for (const v of bound) {
+        for (const c of ifConditions(text)) {
+            if (!new RegExp(`\\b${v}\\b`).test(c.cond))
+                continue;
+            if (THROWS.test(branchAfter(text, c.end)))
+                return true;
+        }
+        // The refusal may live in a function the RESOLVED value is handed to:
+        //   requireTenantNamespace(scope, namespace, door);
+        // It counts only when `v` itself is the argument at a refused position of a
+        // reachable value refuser — `requireNonEmpty(namespace)` beside an unread
+        // `scope` refuses nothing about the principal.
+        if (passesToRefuser(text, v, model, rel))
+            return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// value refusers — a refusal expressed as `fn(resolvedValue, …)`
+// ---------------------------------------------------------------------------
+/** split a parenthesised list's inner text on its TOP-LEVEL commas. */
+function splitTopLevel(inner) {
+    const out = [];
+    let depth = 0;
+    let cur = "";
+    for (let i = 0; i < inner.length; i++) {
+        const ch = inner[i];
+        if (ch === "(" || ch === "[" || ch === "{" || ch === "<")
+            depth += 1;
+        else if (ch === ")" || ch === "]" || ch === "}")
+            depth -= 1;
+        // `>` closes a generic, but `=>` is an arrow and closes nothing.
+        else if (ch === ">" && inner[i - 1] !== "=")
+            depth -= 1;
+        if (ch === "," && depth === 0) {
+            out.push(cur);
+            cur = "";
+            continue;
+        }
+        cur += ch;
+    }
+    if (cur.trim() !== "")
+        out.push(cur);
+    return out;
+}
+/** the balanced `(…)` starting at `open` (an index of `(`): inner text and end. */
+function parenAt(text, open) {
+    let depth = 0;
+    for (let j = open; j < text.length; j++) {
+        if (text[j] === "(")
+            depth += 1;
+        else if (text[j] === ")") {
+            depth -= 1;
+            if (depth === 0)
+                return { inner: text.slice(open + 1, j), end: j + 1 };
+        }
+    }
+    return null;
+}
+/**
+ * `v` is passed, as itself, at a refused position of a value refuser REACHABLE from
+ * `rel` — declared in `rel`, or imported by it (the same scope rule `reachable`
+ * applies; a same-named function in a module `rel` does not import is not seen).
+ */
+function passesToRefuser(text, v, model, rel) {
+    const scope = model.scopes.get(rel) ?? new Set();
+    for (const [key, positions] of model.refuserParams) {
+        const name = nameOf(key);
+        if (relOf(key) !== rel && !scope.has(name))
+            continue;
+        const call = new RegExp(`(?:^|[^A-Za-z0-9_$.])${name}\\s*\\(`, "g");
+        let m;
+        // biome-ignore lint/suspicious/noAssignInExpressions: standard regex-exec loop
+        while ((m = call.exec(text)) !== null) {
+            const p = parenAt(text, m.index + m[0].length - 1);
+            if (p === null)
+                continue;
+            const args = splitTopLevel(p.inner).map((a) => a.trim());
+            for (const i of positions) {
+                if (args[i] === v)
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/** parameter names of a function body's FIRST parenthesised list, by position
+ *  (`null` for a destructured or unreadable parameter), and where the list ends. */
+function paramsOf(text) {
+    const open = text.indexOf("(");
+    if (open < 0)
+        return null;
+    const p = parenAt(text, open);
+    if (p === null)
+        return null;
+    const names = splitTopLevel(p.inner).map((raw) => {
+        const m = /^\s*(?:\.\.\.)?([A-Za-z_$][A-Za-z0-9_$]*)\s*[?:=,]?/.exec(raw);
+        return m ? m[1] : null;
+    });
+    return { names, end: p.end };
+}
+/**
+ * Derive the VALUE REFUSERS from the tree, transitively. A plain (non-registration)
+ * function refuses on its parameter `p` when BOTH hold:
+ *
+ *   REFUSES — an `if` whose condition reads `p` has a branch that THROWS
+ *             (`if (scope.anonymous) throw …`), OR it hands `p` itself to another
+ *             value refuser at a refused position (`requireTenantNamespace` ->
+ *             `requireResolvedCaller(scope, …)`).
+ *   NEVER PROCEEDS SILENTLY ON ANYTHING ELSE — every proceed (`return;` /
+ *             `return true`) in the body sits in the branch of an `if` whose
+ *             condition reads `p`. An allow decided on the RESOLVED value
+ *             (`if (isNamespaceAllowedForScope(scope, ns)) return;`) is the
+ *             authority deciding; an allow decided on a caller-supplied argument
+ *             (`if (ns.startsWith("public/")) return;`) lets any principal —
+ *             including none — through, so that function is NOT a refuser.
+ *
+ * What "refuses" means here is the bar CR-1 already applies to an inline gate
+ * (`refusesOnResolvedValue`: an `if` on the resolved value that throws), carried one
+ * call deeper. It is not a proof that every non-authorised input throws — that is
+ * not decidable from source; it is the absent-principal path CR-1 asks about.
+ */
+function deriveValueRefusers(bodies, model) {
+    const parsed = new Map();
+    for (const [key, b] of bodies) {
+        if (b.isRegistration)
+            continue;
+        const ps = paramsOf(b.text);
+        if (ps === null)
+            continue;
+        parsed.set(key, { names: ps.names, body: b.text.slice(ps.end) });
+    }
+    const silentlyProceeds = (body, p) => {
+        const reads = new RegExp(`\\b${p}\\b`);
+        const guarded = [];
+        for (const c of ifConditions(body)) {
+            if (!reads.test(c.cond))
+                continue;
+            let s = c.end;
+            while (s < body.length && /\s/.test(body[s]))
+                s++;
+            guarded.push([s, s + branchAfter(body, c.end).length]);
+        }
+        const proceed = new RegExp(PROCEED_RETURN.source, "g");
+        let m;
+        // biome-ignore lint/suspicious/noAssignInExpressions: standard regex-exec loop
+        while ((m = proceed.exec(body)) !== null) {
+            const at = m.index;
+            if (!guarded.some(([s, e]) => at >= s && at < e))
+                return true;
+        }
+        return false;
+    };
+    for (let round = 0; round < 5; round++) {
+        let grew = false;
+        for (const [key, { names, body }] of parsed) {
+            names.forEach((p, i) => {
+                if (p === null || model.refuserParams.get(key)?.has(i))
+                    return;
+                if (silentlyProceeds(body, p))
+                    return;
+                const reads = new RegExp(`\\b${p}\\b`);
+                const direct = ifConditions(body).some((c) => reads.test(c.cond) && THROWS.test(branchAfter(body, c.end)));
+                if (!direct && !passesToRefuser(body, p, model, relOf(key)))
+                    return;
+                const set = model.refuserParams.get(key) ?? new Set();
+                set.add(i);
+                model.refuserParams.set(key, set);
+                grew = true;
+            });
+        }
+        if (!grew)
+            break;
+    }
+}
+/** true when a helper body resolves the identity and THROWS on its absent path. */
+function absentIdentityBranchThrows(text) {
+    const bind = /(?:const|let)\s+([A-Za-z0-9_$]+)\s*(?::[^=\n]*)?=\s*\(?\s*await\s+ctx\.auth\.getUserIdentity/.exec(text);
+    if (bind) {
+        const g = absentGuard(text, bind[1]);
+        if (g && THROWS.test(g.branch))
+            return true;
+    }
+    // `const identity = await ctx.auth.getUserIdentity(); if (!identity) throw` is the
+    // common form; a helper with no binding that throws on a falsy identity expression
+    // (`if (!(await ctx.auth.getUserIdentity())) throw`) refuses just as decisively.
+    const inline = /if\s*\(\s*!\s*\(?\s*await\s+ctx\.auth\.getUserIdentity/.exec(text);
+    return (inline !== null && THROWS.test(text.slice(inline.index, inline.index + 600)));
+}
+// ---------------------------------------------------------------------------
+// the four classes
+// ---------------------------------------------------------------------------
+/** the handler TOUCHES DATA — reads, writes, schedules, or delegates to a function
+ *  that does. A registration that touches none of these is the NO-DATA class. */
+const DATA_ACCESS = /ctx\.db\b|ctx\.storage\b|ctx\.runQuery\b|ctx\.runMutation\b|ctx\.runAction\b|ctx\.scheduler\b|ctx\.vectorSearch\b|\bcomponents\./;
+/** a refusal — an explicit throw. */
+const THROWS = /\bthrow\b/;
+/** a PROCEED inside an assertion helper: a bare `return;` / `return }` or a
+ *  `return true` — the caller is let through. A `return null` / `return []` /
+ *  `return {…}` is a value (a typed refusal shape in a resolver), not a proceed. */
+const PROCEED_RETURN = /\breturn\s*(?:;|\}|true\b)/;
+/**
+ * A CONSTANT in place of an authority: `if (x === "literal") return true` — an
+ * allow decision taken on a hardcoded string and nothing else. This is the shape
+ * that defeated every predecessor at `messages:listByChannel`
+ * (`if (ch === "broadcast") return true;`) and at `search.ts::searchFixPatterns`
+ * (a hardcoded namespace). A constant is not an authorisation.
+ */
+const CONSTANT_ALLOWANCE = /if\s*\(\s*[^)]*===\s*(['"`])[^'"`\n]*\1\s*\)\s*(?:\{\s*)?return\s+true\b/;
+/** the justification token, read FROM THE TARGET SOURCE at the registration. */
+const JUSTIFICATION = /allow-no-caller-resolution:\s*(\S[^\n]{7,})/;
+/**
+ * Classify ONE registration from its own block text. `pre` is the comment context
+ * immediately above the opener (a justification token may sit there or inside).
+ *
+ * ORDER MATTERS and is the rule's logic:
+ *   no data touched                        -> NO-DATA      (token required)
+ *   data touched, principal never consulted-> NO-IDENTITY  (token required)
+ *   principal consulted but not decisive   -> FAIL-OPEN    (NO token exit)
+ *   otherwise                              -> RESOLVES
+ */
+export function classify(codeText, fullText, pre, model, rel) {
+    const token = JUSTIFICATION.exec(`${pre}\n${fullText}`);
+    const dataFnCalls = referenced(codeText, reachable(model, model.dataFns, rel));
+    const touchesData = DATA_ACCESS.test(codeText) || dataFnCalls.length > 0;
+    if (!touchesData) {
+        return token
+            ? {
+                cls: "NO-DATA",
+                why: `touches no data — neither directly (ctx.db / ctx.storage / ctx.run* / ctx.scheduler / components.*) nor through any tree-derived data-touching helper — and carries a written justification at the registration: "${token[1].trim().slice(0, 120)}"`,
+                justified: true,
+            }
+            : {
+                cls: "NO-DATA",
+                why: "touches no data — neither directly (ctx.db / ctx.storage / ctx.run* / ctx.scheduler / components.*) nor through any tree-derived data-touching helper — and carries NO `allow-no-caller-resolution: <reason>` token at the registration. A public registration that resolves no caller is accepted only against a reason written in this source",
+            };
+    }
+    const helperCalls = referenced(codeText, reachable(model, model.helpers, rel));
+    const gateRefs = reachable(model, model.gates, rel);
+    const consults = GET_IDENTITY.test(codeText) || helperCalls.length > 0;
+    if (!consults) {
+        return token
+            ? {
+                cls: "NO-IDENTITY",
+                why: `serves or writes data and never consults the verified principal, but carries a written justification at the registration: "${token[1].trim().slice(0, 120)}"`,
+                justified: true,
+            }
+            : {
+                cls: "NO-IDENTITY",
+                why: "serves or writes data and NEVER consults the verified principal — no `ctx.auth.getUserIdentity()` and no call to any tree-derived identity helper. An anonymous caller is served whatever this handler reads",
+            };
+    }
+    // --- FAIL-OPEN: the principal is resolved, then does not decide. ---
+    const reasons = [];
+    for (const [flag, where] of model.privilegeOnAbsenceFlags) {
+        if (new RegExp(`\\b${flag}\\s*:\\s*true\\b`).test(codeText)) {
+            reasons.push(`treats an ABSENT identity as privileged: it opts into \`${flag}: true\`, and that flag's own helper — ${where} — returns a privileged shape on a null identity`);
+        }
+    }
+    // A GATE call refuses on the absent-identity path by throwing, so it decides even
+    // as a bare statement — `await requireOrgAdmin(ctx);` IS the fail-closed idiom and
+    // must never be read as a discarded principal. Only a RESOLVER's return value can
+    // be computed and discarded.
+    const isGate = (r) => gateRefs.some((g) => g.name === r.name && g.qualified === r.qualified);
+    const refusesInline = GET_IDENTITY.test(codeText) && absentIdentityBranchThrows(codeText);
+    for (const r of helperCalls) {
+        const where = model.permissiveOnAbsence.get(r.name);
+        if (where === undefined)
+            continue;
+        // The permissive helper only matters if an anonymous caller can REACH it. A
+        // handler that resolves the identity itself and throws on its absence BEFORE
+        // the helper call (`cancelOkfBundleExportDurable` at vantage-peers 9e1413a:
+        // `if (identity === null) throw …` then `assertCanExportNamespaceV8(…)`) has
+        // already refused every anonymous caller; the helper's allow-on-absence path
+        // is unreachable from here. The refusal must PRECEDE the first helper call —
+        // an inline refusal after the helper has run refuses nothing it let through.
+        const helperAt = codeText.search(new RegExp(`(?:^|[^A-Za-z0-9_$.])${r.name}\\s*\\(`));
+        if (refusesInline &&
+            helperAt >= 0 &&
+            absentIdentityBranchThrows(codeText.slice(0, helperAt))) {
+            continue;
+        }
+        reasons.push(`its only authority is \`${r.name}()\`, which GRANTS on an absent identity — ${where}. An anonymous caller passes the gate and reaches the data`);
+    }
+    const gateCalls = helperCalls.filter(isGate).map((r) => r.name);
+    const resolverCalls = helperCalls
+        .filter((r) => !isGate(r))
+        .map((r) => r.name);
+    // the principal is COMPUTED AND DISCARDED: every binding of an identity /
+    // resolver result occurs exactly once (its own declaration), or the call is a
+    // bare statement with no binding at all — and nothing in the handler refuses.
+    const bindPattern = new RegExp(`(?:const|let)\\s+(?:\\{[^}]*\\}|([A-Za-z0-9_$]+))\\s*(?::[^=\\n]*)?=\\s*\\(?\\s*(?:await\\s+)?(?:ctx\\.auth\\.getUserIdentity|${resolverCalls.length ? resolverCalls.join("|") : "\\0NEVER"})\\s*\\(`, "g");
+    const binds = [];
+    let destructured = false;
+    let bm;
+    // biome-ignore lint/suspicious/noAssignInExpressions: standard regex-exec loop
+    while ((bm = bindPattern.exec(codeText)) !== null) {
+        if (bm[1] === undefined)
+            destructured = true;
+        else
+            binds.push(bm[1]);
+    }
+    if (gateCalls.length === 0 && !refusesInline && !destructured) {
+        if (binds.length === 0) {
+            reasons.push("resolves the principal and BINDS NOTHING — the identity/resolver call is a bare statement that does not refuse, so the verified principal is computed and discarded and cannot decide what is served");
+        }
+        else {
+            const unused = binds.filter((b) => (codeText.match(new RegExp(`\\b${b}\\b`, "g")) ?? []).length <= 1);
+            if (unused.length === binds.length) {
+                reasons.push(`resolves the principal into ${unused.map((u) => `\`${u}\``).join(", ")} and never reads ${unused.length > 1 ? "any of them" : "it"} again — the verified principal is computed and discarded`);
+            }
+        }
+    }
+    if (CONSTANT_ALLOWANCE.test(codeText)) {
+        reasons.push('grants access on a HARDCODED CONSTANT — an `if (… === "<literal>") return true` allow decision that no resolved principal takes part in. A constant is not an authorisation');
+    }
+    // an absent-identity branch that SERVES DATA instead of refusing. The guard must
+    // test the binding ITSELF (`if (!scope)`), never a property of it
+    // (`if (!scope.isMaster)` is an authority test on a RESOLVED principal).
+    for (const b of binds) {
+        const g = absentGuard(codeText, b);
+        if (!g)
+            continue;
+        const region = g.branch;
+        const regionServes = DATA_ACCESS.test(region) || referenced(region, dataFnCalls).length > 0;
+        // a `return` in the branch IS a refusal shape (a typed empty / unauthorized
+        // result), exactly as a `throw` is — R-50 governs WHICH of the two a client can
+        // render; CR-1 only asks that the absent-identity path does not reach the data.
+        if (regionServes && !THROWS.test(region) && !/\breturn\b/.test(region)) {
+            reasons.push(`its absent-identity branch (\`if (!${b})\`) SERVES DATA and does not refuse — an unauthenticated caller reaches the data path`);
+        }
+    }
+    if (reasons.length > 0) {
+        return {
+            cls: "FAIL-OPEN",
+            why: `${reasons.join("; ")}. NO justification token clears FAIL-OPEN — a resolved principal that does not decide is the confirmed leak class, not a documented exception`,
+        };
+    }
+    return {
+        cls: "RESOLVES",
+        why: `consults the verified principal (${[
+            GET_IDENTITY.test(codeText) ? "ctx.auth.getUserIdentity()" : "",
+            ...gateCalls.map((h) => `${h}() [refusing gate]`),
+            ...resolverCalls.map((h) => `${h}() [resolver]`),
+        ]
+            .filter(Boolean)
+            .join(", ")}) and ${gateCalls.length > 0 || refusesInline ? "refuses on the absent-identity path" : "the resolved value decides what is served"}`,
+    };
+}
+// ---------------------------------------------------------------------------
+// the scan
+// ---------------------------------------------------------------------------
+/** up to 8 comment lines immediately above `i`, as text. */
+function commentContext(lines, i) {
+    const out = [];
+    for (let j = i - 1; j >= 0 && i - j <= 8; j--) {
+        if (!lines[j].comment && lines[j].raw.trim() !== "")
+            break;
+        out.unshift(lines[j].raw);
+    }
+    return out.join("\n");
+}
+/** The exposed surface for a tree, with module rels in the TREE's rel space: a
+ * tree rooted at the repository (src/target.ts) carries `convex/` on every convex
+ * rel, while api.d.ts names modules relative to the convex dir. */
+export function surfaceForTree(tree) {
+    const cr = convexRootOf(tree);
+    const s = deriveApiSurface(cr.dir);
+    if (cr.prefix === "")
+        return s;
+    return {
+        ...s,
+        modules: new Map([...s.modules].map(([m, rel]) => [m, `${cr.prefix}${rel}`])),
+    };
+}
+export function scanCallerResolution(tree, surface = surfaceForTree(tree)) {
+    // CR-1's population is the CONVEX surface only: a repo-rooted tree also carries
+    // mcp-server/src, whose files api.d.ts never exposes and must not be read as drift.
+    const { dir: convexDir, prefix } = convexRootOf(tree);
+    const inConvex = (f) => f.rel.startsWith(prefix);
+    const files = tree.files.filter((f) => isJudgeable(f) && inConvex(f));
+    const byRel = new Map(files.map((f) => [f.rel, f]));
+    const builders = discoverBuilders(files);
+    const model = deriveIdentityModel(files);
+    const scan = {
+        exposedModules: surface.modules,
+        populationSource: surface.unreadable
+            ? `DEGRADED — ${surface.unreadable}`
+            : `${convexDir}/_generated/api.d.ts (\`declare const fullApi: ApiFromModules<{…}>\`, ${surface.modules.size} exposed module(s))`,
+        findings: [],
+        excluded: [],
+        selfDefects: [],
+        exposedCount: 0,
+        classifiedCount: 0,
+    };
+    // An UNREADABLE api.d.ts is only a defect when there is a surface to miss. On a
+    // tree with ZERO public registrations the absent generated file is CONSISTENT with
+    // "nothing is exposed", and the honest report is NO APPLICABLE SITE — the
+    // empty-tree control (a tree whose only file declares `export const nothing = 1;`)
+    // must yield that, never a count and never a self-defect. On a tree that DOES
+    // register public functions, the same absence means the exposed surface cannot be
+    // derived, which is a refusal — never a silent pass.
+    const publicRegistrationsAnywhere = files.some((f) => f.lines.some((l) => {
+        if (!isCode(l))
+            return false;
+        const m = REGISTRATION.exec(l.raw);
+        return m !== null && builders.publicBuilders.has(m[2]);
+    }));
+    if (surface.unreadable && publicRegistrationsAnywhere) {
+        scan.selfDefects.push(surface.unreadable);
+    }
+    if (surface.unreadable && !publicRegistrationsAnywhere) {
+        scan.populationSource = `${convexDir}/_generated/api.d.ts is absent AND the tree registers no public query/mutation/action — nothing is exposed, so there is no applicable site (consistent, not a defect)`;
+    }
+    for (const u of builders.unresolvable) {
+        scan.selfDefects.push(`${u.rel}:${u.n} — builder \`${u.name}\` = ${u.base === "<none>" ? "custom*(…)" : `custom*(${u.base}, …)`}: its base resolves to neither a public nor an internal Convex base, so whether registrations built from it are EXPOSED cannot be established. CR-1 refuses rather than certify a surface it cannot see`);
+    }
+    // The population is the exposed surface itself: only modules api.d.ts lists.
+    for (const [mod, rel] of surface.modules) {
+        const f = byRel.get(rel);
+        if (f === undefined) {
+            scan.selfDefects.push(`api.d.ts exposes module \`${mod}\` -> ${rel}, which is not in the loaded tree — the exposed surface and the scanned tree DISAGREE (CR-1's own population bug, never a rounding)`);
+            continue;
+        }
+        const lines = f.lines;
+        for (let i = 0; i < lines.length; i++) {
+            if (!isCode(lines[i]))
+                continue;
+            const m = REGISTRATION.exec(lines[i].raw);
+            if (!m)
+                continue;
+            const [, name, builder] = m;
+            const isPublic = builders.publicBuilders.has(builder);
+            const isNonPublic = builders.nonPublicBuilders.has(builder);
+            if (!isPublic && !isNonPublic)
+                continue; // not a registration at all
+            const reg = {
+                module: mod,
+                name,
+                api: `${mod}:${name}`,
+                rel: f.rel,
+                n: lines[i].n,
+                builder,
+            };
+            const blk = blockAt(lines, i);
+            i += blk.lines.length - 1;
+            if (isNonPublic) {
+                // The exclusion is PROVEN PER SITE: the builder token observed at this
+                // very line is what excludes it, never the shape of its name.
+                scan.excluded.push(reg);
+                continue;
+            }
+            scan.exposedCount += 1;
+            if (blk.unterminated) {
+                scan.findings.push({
+                    ...reg,
+                    cls: "COULD-NOT-JUDGE",
+                    why: "its block could not be delimited (unbalanced braces/parens) — whether it resolves its caller is not readable; never a silent green",
+                });
+                continue;
+            }
+            const codeText = blk.lines
+                .filter(isCode)
+                .map((l) => l.raw)
+                .join("\n");
+            const fullText = blk.lines.map((l) => l.raw).join("\n");
+            const c = classify(codeText, fullText, commentContext(lines, blk.lines[0].n - 1), model, f.rel);
+            scan.findings.push({ ...reg, ...c });
+        }
+    }
+    // POPULATION DRIFT, both directions: a public registration in a judgeable file
+    // that api.d.ts does NOT expose is either a stale api.d.ts or a CR-1 parse bug.
+    // Either way it is named, never dropped.
+    const exposedRels = new Set(surface.modules.values());
+    for (const f of files) {
+        if (exposedRels.has(f.rel))
+            continue;
+        for (const l of f.lines) {
+            if (!isCode(l))
+                continue;
+            const m = REGISTRATION.exec(l.raw);
+            if (!m)
+                continue;
+            if (!builders.publicBuilders.has(m[2]))
+                continue;
+            scan.selfDefects.push(`${f.rel}:${l.n} — public registration \`${m[1]}\` (builder \`${m[2]}\`) lives in a file the target's own api.d.ts does not expose. The exposed surface and the tree DISAGREE: either api.d.ts is stale or CR-1's parse is incomplete. Named, never rounded`);
+        }
+    }
+    scan.classifiedCount = scan.findings.length;
+    if (scan.classifiedCount !== scan.exposedCount) {
+        scan.selfDefects.push(`CR-1 OWN BUG: classified ${scan.classifiedCount} != exposed ${scan.exposedCount}. The count classified must EQUAL the count exposed`);
+    }
+    return scan;
+}
+// ---------------------------------------------------------------------------
+// verdict + rendering — EVERY member of EVERY class is named
+// ---------------------------------------------------------------------------
+export const CR1_ID = "CR-1 a public registration resolves its caller before serving or writing data";
+export function byClass(scan, cls) {
+    return scan.findings.filter((f) => f.cls === cls);
+}
+/** the findings that are VIOLATIONS: fail-open, plus unjustified no-identity/no-data. */
+export function violations(scan) {
+    return scan.findings.filter((f) => f.cls === "FAIL-OPEN" ||
+        ((f.cls === "NO-IDENTITY" || f.cls === "NO-DATA") && !f.justified));
+}
+export function abstentions(scan) {
+    return scan.findings.filter((f) => f.cls === "COULD-NOT-JUDGE");
+}
+export function callerResolutionResult(scan) {
+    const v = violations(scan);
+    const a = abstentions(scan);
+    const counts = `[exposed=${scan.exposedCount} classified=${scan.classifiedCount} RESOLVES=${byClass(scan, "RESOLVES").length} FAIL-OPEN=${byClass(scan, "FAIL-OPEN").length} NO-IDENTITY=${byClass(scan, "NO-IDENTITY").length} NO-DATA=${byClass(scan, "NO-DATA").length} could-not-judge=${a.length} internal-excluded=${scan.excluded.length}]`;
+    if (scan.exposedCount === 0 && scan.selfDefects.length === 0) {
+        // The EMPTY-TREE CONTROL. A tree that exposes nothing yields NO APPLICABLE
+        // SITE — never a count. This is the control that exposed the frozen-CSV
+        // defect in the oracle-scored rules, and CR-1 must pass it.
+        const reason = "CR-1: no applicable site — the target exposes no public registration (no `declare const fullApi` member resolving to a file that registers a public query/mutation/action). NOT a clean bill: nothing was certified because there was nothing to certify.";
+        return {
+            id: CR1_ID,
+            anchor: "caller-resolution:no-applicable-site",
+            state: "could-not-judge",
+            verdict: reason,
+            reason,
+        };
+    }
+    if (v.length > 0) {
+        const named = v
+            .map((f) => `${f.api} @ ${f.rel}:${f.n} [${f.cls}] — ${f.why}`)
+            .join("\n    ");
+        return {
+            id: CR1_ID,
+            anchor: `${v[0].rel}:${v[0].n}`,
+            state: "non-conforming",
+            verdict: `CR-1: ${v.length} public registration(s) do NOT resolve their caller before serving or writing data. ${counts}\n    ${named}${scan.selfDefects.length
+                ? `\n    CR-1 SELF-DEFECTS (the instrument's own, never a tree finding): ${scan.selfDefects.join(" | ")}`
+                : ""}`,
+        };
+    }
+    if (a.length > 0 || scan.selfDefects.length > 0) {
+        const reason = `CR-1: 0 violations, but ${a.length} registration(s) could not be judged and ${scan.selfDefects.length} instrument self-defect(s) stand. ${counts} ${[
+            ...a.map((f) => `${f.api} @ ${f.rel}:${f.n} — ${f.why}`),
+            ...scan.selfDefects,
+        ].join(" | ")}. This is NOT a clean bill.`;
+        return {
+            id: CR1_ID,
+            anchor: a.length
+                ? `${a[0].rel}:${a[0].n}`
+                : "caller-resolution:self-defect",
+            state: "could-not-judge",
+            verdict: reason,
+            reason,
+        };
+    }
+    return {
+        id: CR1_ID,
+        anchor: `${scan.findings[0].rel}:${scan.findings[0].n}`,
+        state: "present",
+        verdict: `CR-1: all ${scan.exposedCount} exposed public registration(s) resolve their caller (or carry a written justification at the registration); 0 violations. ${counts}`,
+    };
+}
+/** The rendered section. EVERY member of EVERY class is named — the truncation that
+ *  let R-50 classify thirteen of the fourteen and show a reader none of them is the
+ *  defect this renderer refuses to repeat. */
+export function callerResolutionSection(scan) {
+    const out = [];
+    out.push("CALLER RESOLUTION (CR-1) — DOCTOR-OWNED CRITICAL control, NOT one of the numbered rules in the pinned standard (see src/caller-resolution.ts: numbering it upstream is a separate change to the standard document). It drives the exit code.");
+    out.push(`  population source: ${scan.populationSource}`);
+    out.push(`  population cross-check: exposed=${scan.exposedCount} classified=${scan.classifiedCount} ${scan.exposedCount === scan.classifiedCount
+        ? "EQUAL (ok)"
+        : "DISCREPANT — CR-1's own bug"}; internal/httpAction excluded=${scan.excluded.length}, each proven by the builder token read at its own site`);
+    const order = [
+        "FAIL-OPEN",
+        "NO-IDENTITY",
+        "NO-DATA",
+        "RESOLVES",
+        "COULD-NOT-JUDGE",
+    ];
+    for (const cls of order) {
+        const members = byClass(scan, cls);
+        out.push(`  ${cls} (${members.length}):`);
+        for (const f of members) {
+            out.push(`    ${f.justified ? "JUSTIFIED " : ""}${f.api} @ ${f.rel}:${f.n} (${f.builder}) — ${f.why}`);
+        }
+    }
+    if (scan.selfDefects.length > 0) {
+        out.push(`  CR-1 SELF-DEFECTS (${scan.selfDefects.length}):`);
+        for (const d of scan.selfDefects)
+            out.push(`    ${d}`);
+    }
+    const v = violations(scan);
+    out.push(`  CR-1 VERDICT: ${v.length} violation(s) — ${v.length > 0 ? "CRITICAL, the gate refuses" : "none"}; ${abstentions(scan).length} could-not-judge; ${scan.selfDefects.length} self-defect(s).`);
+    return out.join("\n");
+}
+/** CR-1 as an engine Detector, for tests and for a future registry slot. */
+export const CR1 = {
+    id: CR1_ID,
+    run: (tree) => callerResolutionResult(scanCallerResolution(tree)),
+};