@vantageos/backend-doctor 0.1.14 → 0.3.0

package/dist/detectors/source/local-identity.js

@@ -0,0 +1,661 @@
+// CR-2 — no application, no MCP server and no starter defines its own identity
+// primitive. Identity lives ONLY in @vantageos/cloud-identity.
+//
+// Operator order, 2026-10-09, verbatim: "No application, no MCP server, and no
+// starter defines its own primitive for: resolving a caller to a tenant,
+// asserting membership of an organisation, filtering rows by a caller's scope,
+// or validating a master credential." The instrument detects it; a reviewer's
+// judgement is not the mechanism.
+//
+// WHY A DOCTOR-OWNED ID (CR-2) AND NOT R-54. The pinned standard
+// (fixtures/backend-standard-2825122.md) numbers R-1..R-53. An R- id the
+// vendored standard does not define makes coverage.ts report an UNKNOWN rule and
+// makes rule-class.ts refuse to classify it ("the pinned standard states no
+// build kind"), which nulls the mechanical count. CR-1 set the precedent for a
+// doctor-owned control: own section, own sidecar entry, drives the exit code.
+// CR-2 is the next free number of that family. Upstreaming it as R-N is a
+// separate change to the standard document in its own repository.
+//
+// WHAT IS A SITE. One site per function that DEFINES a primitive: the innermost
+// named function holding the deciding node (a helper, an MCP tool handler, or a
+// Convex registration whose own handler does it). A file-level statement is
+// owned by `<module>`. Each site names every primitive kind it holds, each with
+// its line.
+//
+// THE FIVE KINDS (any one is a violation):
+//   tenant      resolves a caller to a tenant or agent — R-53's (d) "resolves
+//               identity itself" (an unsanctioned getUserIdentity() read, a
+//               client_org_mapping read keyed on a credential claim), R-53's doors
+//               whose principal is resolved "by the handler itself", plus any
+//               client_org_mapping read outside R-53's org-ID adapter ruling;
+//   membership  asserts membership of an organisation or a role — a gate (an
+//               `if` that throws/returns, a conditional) reading a role/master
+//               field, a read of a membership table, R-53's (c) "continues as
+//               master when unresolved";
+//   scope       filters rows by a caller's scope — a read of an allow-list field
+//               (allowedOrchestrators, fromAllowList, …) or a membership test
+//               over a caller's tenant / name / scope list;
+//   credential  validates a credential — timingSafeEqual, a token hash
+//               (createHash / subtle.digest on a token, secret or key), JWT
+//               verification (jose, jsonwebtoken);
+//   name        identifies an agent by NAME — R-53's (d) "compares names to
+//               admit", R-53 clause 1's recipient-by-name sites, an index or
+//               filter keyed on a name field, a comparison through a name
+//               normaliser.
+// R-53's classifications are REUSED (scanR53Detailed), never re-derived; only
+// the kinds R-53 does not carry are detected here.
+//
+// No package-call exit. A function that calls the package AND compares names
+// locally still defines a local primitive: the order bans the primitive, not
+// the absence of the package. What the package resolves is admitted by R-53's
+// own sanction rules (a getUserIdentity() value that reaches only a package
+// resolver; the org-ID adapter read) — those are not sites here either.
+//
+// EXEMPT, REPORTED: a file of @vantageos/cloud-identity itself, and a site
+// carrying `allow-local-identity: <reason of 8+ characters>` in its leading
+// comment or its body (the CR-1 `allow-no-caller-resolution:` convention). An
+// exempt site is listed by file:line with its reason; it is never counted as a
+// pass silently.
+//
+// COULD-NOT-JUDGE: a file with a syntax error is reported by name and judged
+// nowhere (neither here nor through R-53), never counted as a pass. An empty
+// population is could-not-judge, never a clean bill.
+//
+// CEILING 0. CR-2 is mechanical (fixtures/rule-classes-2825122.json): any
+// violation is a mechanical violation, counted in mechanical_rule_counts with a
+// per-module split, and gives a non-zero exit.
+import * as ts from "typescript";
+import { siteCount, withCount } from "../../violation-count.js";
+import { calleeName, dotted, lineOf, parseFile, propRead, propReadResolved, sourceOf, unwrap, walk, } from "./_ast.js";
+import { isConvexOrMcp, isJudgeable, } from "./_scan.js";
+import { conformantMappingReads, IDENTITY_PACKAGE, scanR53Detailed, } from "./identity-by-id.js";
+export const CR2_ID = "CR-2 no application defines its own identity primitive (tenant resolution, membership, scope filtering, credential validation, identification by name); identity lives only in @vantageos/cloud-identity";
+export const KIND = {
+    tenant: "resolves a caller to a tenant or agent",
+    membership: "asserts membership or role",
+    scope: "filters by the caller's scope",
+    credential: "validates a credential",
+    name: "identifies an agent by name",
+};
+/** The written justification, read FROM THE TARGET SOURCE at the site. */
+export const EXEMPT_MARKER = /allow-local-identity:\s*(\S[^\n]{7,})/;
+/** A file of the identity package itself. */
+const PACKAGE_PATH = /(^|\/)(node_modules\/@vantageos\/cloud-identity|packages\/cloud-identity)\//;
+const SOURCE_EXT = /\.[cm]?[tj]sx?$/;
+const TOOL_CALL = /^(defineTool|tool|registerTool)$/;
+/** The innermost NAMED function holding `n`. A Convex registration's own
+ * `handler` is owned by the registration (`export const NAME = mutation(…)`),
+ * at the same line R-53 reports its doors. */
+function ownerOf(n, rel) {
+    let viaHandler = false;
+    for (let x = n.parent; x; x = x.parent) {
+        if (ts.isFunctionDeclaration(x) && x.name)
+            return { rel, n: lineOf(x), name: x.name.text, node: x };
+        if (ts.isMethodDeclaration(x) && ts.isIdentifier(x.name)) {
+            if (x.name.text === "handler") {
+                viaHandler = true;
+                continue;
+            }
+            return { rel, n: lineOf(x), name: x.name.text, node: x };
+        }
+        if ((ts.isArrowFunction(x) || ts.isFunctionExpression(x)) && x.parent) {
+            const par = x.parent;
+            if (ts.isVariableDeclaration(par) && ts.isIdentifier(par.name))
+                return { rel, n: lineOf(par), name: par.name.text, node: par };
+            if (ts.isPropertyAssignment(par) && ts.isIdentifier(par.name)) {
+                if (par.name.text === "handler") {
+                    viaHandler = true;
+                    continue;
+                }
+                return { rel, n: lineOf(par), name: par.name.text, node: par };
+            }
+            if (ts.isCallExpression(par) &&
+                TOOL_CALL.test((dotted(par.expression) ?? "").split(".").pop() ?? "")) {
+                const label = par.arguments.find((a) => ts.isStringLiteralLike(a) ||
+                    (ts.isIdentifier(a) && /_TOOL_NAME$/.test(a.text)));
+                return {
+                    rel,
+                    n: lineOf(par),
+                    name: `tool ${label ? label.getText() : "<anonymous>"}`,
+                    node: par,
+                };
+            }
+        }
+        // a registration reached by climbing out of its handler
+        if (viaHandler &&
+            ts.isVariableDeclaration(x) &&
+            ts.isIdentifier(x.name) &&
+            x.initializer &&
+            ts.isCallExpression(unwrap(x.initializer)))
+            return { rel, n: lineOf(x), name: x.name.text, node: x };
+    }
+    let top = n;
+    while (top.parent && !ts.isSourceFile(top.parent))
+        top = top.parent;
+    return { rel, n: lineOf(n), name: "<module>", node: top };
+}
+/** The deepest node starting on line `n` of `p` (for a site given by line). */
+function nodeAtLine(p, n) {
+    let hit;
+    walk(p.sf, (x) => {
+        if (x !== p.sf && lineOf(x) === n)
+            hit = x;
+    });
+    return hit;
+}
+/** The marker's reason at an owner: its leading comment, or its own text. */
+function markerOf(o) {
+    let host = o.node;
+    if (ts.isVariableDeclaration(host) && host.parent?.parent)
+        host = host.parent.parent; // the VariableStatement carries the comment
+    return EXEMPT_MARKER.exec(host.getFullText())?.[1].trim();
+}
+// ---- the kinds R-53 does not carry ----------------------------------------
+const snippet = (n) => n.getText().replace(/\s+/g, " ").slice(0, 80);
+/** Credential-validation callees, whatever module they come from. */
+const CREDENTIAL_CALLS = new Set([
+    "timingSafeEqual",
+    "jwtVerify",
+    "jwtDecrypt",
+    "compactVerify",
+    "flattenedVerify",
+    "generalVerify",
+    "createRemoteJWKSet",
+    "createLocalJWKSet",
+    "importJWK",
+    "importSPKI",
+    "importX509",
+]);
+const JWT_MODULES = new Set(["jose", "jsonwebtoken"]);
+const SECRETISH = /token|secret|bearer|password|passphrase|credential|api_?key|apikey|signature/i;
+const ROLE_PROPS = new Set([
+    "role",
+    "roles",
+    "orgRole",
+    "org_role",
+    "isMaster",
+    "masterSource",
+    "isAdmin",
+    "isOwner",
+    "isMember",
+    "membership",
+    "memberships",
+]);
+const MEMBERSHIP_TABLE = /member/i;
+const SCOPE_PROPS = new Set([
+    "allowedOrchestrators",
+    "fromAllowList",
+    "allowList",
+    "allowedNamespaces",
+    "namespacePrefixes",
+    "allowedTenants",
+    "allowedOrgs",
+]);
+const SCOPE_LIST = /^(tenants|tenantIds|names|roster|scopes|orgs|orgIds|orgSlugs|allowed\w*|\w*allowList)$/i;
+const MEMBER_TEST = new Set([
+    "includes",
+    "has",
+    "indexOf",
+    "some",
+    "every",
+]);
+const NAME_FIELDS = new Set([
+    "name",
+    "normalizedName",
+    "recipient",
+    "from",
+    "assignedTo",
+    "createdBy",
+    "lastAssignedTo",
+    "orchestrator",
+    "orchestratorId",
+    "callerOrchestrator",
+    "agentName",
+]);
+const NAME_NORMALISER = /^normali[sz]e\w*(Id|Name)$/;
+const EQ = new Set([
+    ts.SyntaxKind.EqualsEqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsEqualsToken,
+    ts.SyntaxKind.EqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsToken,
+]);
+function isLiteral(e) {
+    const u = unwrap(e);
+    return (ts.isStringLiteralLike(u) ||
+        ts.isNumericLiteral(u) ||
+        u.kind === ts.SyntaxKind.NullKeyword ||
+        u.kind === ts.SyntaxKind.TrueKeyword ||
+        u.kind === ts.SyntaxKind.FalseKeyword ||
+        (ts.isIdentifier(u) && u.text === "undefined"));
+}
+/** Does `n` read a property named in `props` (a value read, not a key)? */
+function readsProp(n, props) {
+    let hit;
+    walk(n, (x) => {
+        const r = ts.isExpression(x) ? propReadResolved(x) : undefined;
+        if (!hit && r && props.has(r.name))
+            hit = x;
+    });
+    return hit;
+}
+function exits(s) {
+    let hit = false;
+    walk(s, (y) => {
+        if (ts.isThrowStatement(y) || ts.isReturnStatement(y))
+            hit = true;
+    }, true);
+    return hit;
+}
+/** Bindings a file imports from jose / jsonwebtoken. */
+function jwtBindings(p) {
+    const out = new Set();
+    for (const st of p.sf.statements) {
+        if (!ts.isImportDeclaration(st))
+            continue;
+        if (!JWT_MODULES.has(st.moduleSpecifier.text))
+            continue;
+        const c = st.importClause;
+        if (c?.name)
+            out.add(c.name.text);
+        const b = c?.namedBindings;
+        if (b && ts.isNamespaceImport(b))
+            out.add(b.name.text);
+        else if (b)
+            for (const e of b.elements)
+                out.add(e.name.text);
+    }
+    return out;
+}
+/** The field a `q.eq(<field>, K)` / `q.eq(q.field("f"), K)` keys on. */
+function eqField(c) {
+    const f = c.arguments[0] && unwrap(c.arguments[0]);
+    if (!f)
+        return undefined;
+    if (ts.isStringLiteralLike(f))
+        return f.text;
+    if (ts.isCallExpression(f) &&
+        calleeName(f) === "field" &&
+        f.arguments[0] &&
+        ts.isStringLiteralLike(f.arguments[0]))
+        return f.arguments[0].text;
+    return undefined;
+}
+/** Inside a `.withIndex(…)` / `.filter(…)` / `.withSearchIndex(…)` callback? */
+function inQueryKey(n) {
+    for (let x = n.parent; x; x = x.parent) {
+        if (ts.isCallExpression(x) &&
+            /^(withIndex|filter|withSearchIndex)$/.test(calleeName(x) ?? "") &&
+            ts.isPropertyAccessExpression(unwrap(x.expression)))
+            return true;
+        if (ts.isBlock(x) || ts.isSourceFile(x))
+            return false;
+    }
+    return false;
+}
+const isNormaliserCall = (e) => {
+    const u = unwrap(e);
+    return ts.isCallExpression(u) && NAME_NORMALISER.test(calleeName(u) ?? "");
+};
+/** The primitives this module adds beside R-53's, one hit per deciding node. */
+function ownHits(p, okReads) {
+    const out = [];
+    const jwt = jwtBindings(p);
+    walk(p.sf, (x) => {
+        // credential
+        if (ts.isCallExpression(x)) {
+            const name = calleeName(x) ?? "";
+            const head = (dotted(x.expression) ?? "").split(".")[0];
+            const chain = (() => {
+                let c = x;
+                while (c.parent &&
+                    (ts.isPropertyAccessExpression(c.parent) ||
+                        ts.isCallExpression(c.parent)))
+                    c = c.parent;
+                return c.getText();
+            })();
+            const ownerName = ownerOf(x, p.rel).name;
+            if (CREDENTIAL_CALLS.has(name))
+                out.push({
+                    node: x,
+                    kind: "credential",
+                    why: `\`${name}()\``,
+                });
+            else if (jwt.has(head) && /verify|decode|jwks|import/i.test(name))
+                out.push({
+                    node: x,
+                    kind: "credential",
+                    why: `JWT verification \`${snippet(x.expression)}()\``,
+                });
+            else if ((name === "createHash" ||
+                name === "createHmac" ||
+                /\bsubtle\.digest$/.test(dotted(x.expression) ?? "")) &&
+                (SECRETISH.test(chain) || SECRETISH.test(ownerName)))
+                out.push({
+                    node: x,
+                    kind: "credential",
+                    why: `token hashing \`${snippet(x)}\``,
+                });
+            // membership table read
+            const a0 = x.arguments[0];
+            if (name === "query" &&
+                /\bdb\.query$/.test(dotted(x.expression) ?? "") &&
+                a0 &&
+                ts.isStringLiteralLike(a0)) {
+                if (MEMBERSHIP_TABLE.test(a0.text))
+                    out.push({
+                        node: x,
+                        kind: "membership",
+                        why: `reads the membership table \`${a0.text}\``,
+                    });
+                if (a0.text === "client_org_mapping" && !okReads.has(x))
+                    out.push({
+                        node: x,
+                        kind: "tenant",
+                        why: "reads `client_org_mapping` itself, outside the org-ID adapter ruling",
+                    });
+            }
+            // scope: membership test over a caller's list
+            const callee = unwrap(x.expression);
+            if (ts.isPropertyAccessExpression(callee) &&
+                MEMBER_TEST.has(callee.name.text) &&
+                x.arguments[0] &&
+                !isLiteral(x.arguments[0])) {
+                const recv = unwrap(callee.expression);
+                const last = propReadResolved(recv)?.name ??
+                    (ts.isIdentifier(recv) ? recv.text : "");
+                if (SCOPE_LIST.test(last) && !SCOPE_PROPS.has(last))
+                    out.push({
+                        node: x,
+                        kind: "scope",
+                        why: `\`${snippet(x)}\``,
+                    });
+            }
+            // name: an index / filter keyed on a name field with a non-literal
+            if (name === "eq" &&
+                x.arguments.length === 2 &&
+                !isLiteral(x.arguments[1]) &&
+                inQueryKey(x)) {
+                const f = eqField(x);
+                if (f !== undefined && NAME_FIELDS.has(f))
+                    out.push({
+                        node: x,
+                        kind: "name",
+                        why: `selects rows by the name field \`${f}\` (\`${snippet(x)}\`)`,
+                    });
+            }
+        }
+        // scope: a read of an allow-list field
+        const rd = propRead(x);
+        if (rd && SCOPE_PROPS.has(rd.name))
+            out.push({ node: x, kind: "scope", why: `reads \`${snippet(x)}\`` });
+        // membership: a gate on a role / master field
+        if (ts.isIfStatement(x) && exits(x.thenStatement)) {
+            const r = readsProp(x.expression, ROLE_PROPS);
+            if (r)
+                out.push({
+                    node: x.expression,
+                    kind: "membership",
+                    why: `gates on \`${snippet(r)}\``,
+                });
+        }
+        if (ts.isConditionalExpression(x)) {
+            const r = readsProp(x.condition, ROLE_PROPS);
+            if (r)
+                out.push({
+                    node: x.condition,
+                    kind: "membership",
+                    why: `branches on \`${snippet(r)}\``,
+                });
+        }
+        // name: a comparison through a name normaliser
+        if (ts.isBinaryExpression(x) &&
+            EQ.has(x.operatorToken.kind) &&
+            !isLiteral(x.left) &&
+            !isLiteral(x.right) &&
+            (isNormaliserCall(x.left) || isNormaliserCall(x.right)))
+            out.push({
+                node: x,
+                kind: "name",
+                why: `compares through a name normaliser (\`${snippet(x)}\`)`,
+            });
+    });
+    return out;
+}
+/** R-53's classifications that ARE local identity primitives, mapped to kinds. */
+function reuseR53(files) {
+    const d = scanR53Detailed(files);
+    const sites = [];
+    for (const s of d.scan.violate) {
+        const layer = /: \(d\) local identity layer — (.*)$/.exec(s.note);
+        if (layer) {
+            for (const why of layer[1].split("; ")) {
+                if (/^compares names to admit/.test(why))
+                    sites.push({
+                        ...at(s),
+                        kind: "name",
+                        why: `R-53 (d): ${why}`,
+                        atOwner: true,
+                    });
+                else if (/^resolves identity itself/.test(why))
+                    sites.push({
+                        ...at(s),
+                        kind: "tenant",
+                        why: `R-53 (d): ${why}`,
+                        atOwner: true,
+                    });
+            }
+            continue;
+        }
+        const door = /\(a\) principal resolved by the handler itself[^|]*/.exec(s.note);
+        if (door) {
+            sites.push({
+                ...at(s),
+                kind: "tenant",
+                why: `R-53 door ${door[0].trim()}`,
+                atOwner: true,
+            });
+            continue;
+        }
+        if (/: \(1\) recipient resolved by name — /.test(s.note)) {
+            sites.push({
+                ...at(s),
+                kind: "name",
+                why: `R-53 clause 1: ${s.note.replace(/^[^:]*: \(1\) /, "").slice(0, 160)}`,
+                atOwner: false,
+            });
+            continue;
+        }
+        if (/: \(c\) continues as master when /.test(s.note))
+            sites.push({
+                ...at(s),
+                kind: "membership",
+                why: `R-53 (c): ${s.note.replace(/^[^:]*: \(c\) /, "")}`,
+                atOwner: false,
+            });
+    }
+    return { sites, cnj: d.scan.cnj };
+}
+const at = (s) => ({ rel: s.rel, n: s.n });
+// ---- the scan -------------------------------------------------------------
+/** Syntactic diagnostics of one file, through the public transpile API. */
+function syntaxErrors(f) {
+    const out = ts.transpileModule(sourceOf(f), {
+        fileName: f.rel,
+        reportDiagnostics: true,
+        compilerOptions: { target: ts.ScriptTarget.Latest },
+    });
+    const errs = (out.diagnostics ?? []).filter((d) => d.category === ts.DiagnosticCategory.Error);
+    if (errs.length === 0)
+        return undefined;
+    const d = errs[0];
+    const line = d.file && d.start !== undefined
+        ? d.file.getLineAndCharacterOfPosition(d.start).line + 1
+        : 0;
+    return `line ${line}: ${ts.flattenDiagnosticMessageText(d.messageText, " ")}`;
+}
+export function scanLocalIdentity(files) {
+    const population = files.filter((f) => (isConvexOrMcp(f) || PACKAGE_PATH.test(f.rel)) &&
+        isJudgeable(f) &&
+        SOURCE_EXT.test(f.rel));
+    const scan = {
+        files: population.length,
+        violate: [],
+        exempt: [],
+        cnj: [],
+    };
+    const judged = [];
+    for (const f of population) {
+        const err = syntaxErrors(f);
+        if (err)
+            scan.cnj.push({
+                rel: f.rel,
+                n: 0,
+                note: `unparsable (${err}) — no site in this file was judged; NOT a pass`,
+            });
+        else
+            judged.push(f);
+    }
+    const parsed = judged.map(parseFile);
+    const byRel = new Map(parsed.map((p) => [p.rel, p]));
+    const okReads = conformantMappingReads(parsed);
+    // owner key -> owner + reasons
+    const sites = new Map();
+    const note = (o, kind, why) => {
+        const key = `${o.rel}:${o.n}`;
+        const e = sites.get(key) ?? { owner: o, why: [] };
+        const line = `${KIND[kind]} — ${why}`;
+        if (!e.why.includes(line))
+            e.why.push(line);
+        sites.set(key, e);
+    };
+    const reused = reuseR53(judged);
+    scan.cnj.push(...reused.cnj);
+    for (const r of reused.sites) {
+        const p = byRel.get(r.rel);
+        const node = p && nodeAtLine(p, r.n);
+        if (!p || !node)
+            continue;
+        // a (d) layer / door site already sits on its owner's line; the node
+        // starting there IS the owner's declaration, so own it directly.
+        const o = r.atOwner ? ownerAtDecl(node, p.rel, r.n) : ownerOf(node, p.rel);
+        note(o, r.kind, r.why);
+    }
+    for (const p of parsed)
+        for (const h of ownHits(p, okReads))
+            note(ownerOf(h.node, p.rel), h.kind, `${h.why}, line ${lineOf(h.node)}`);
+    for (const { owner, why } of [...sites.values()].sort((a, b) => a.owner.rel.localeCompare(b.owner.rel) || a.owner.n - b.owner.n)) {
+        const site = { rel: owner.rel, n: owner.n };
+        const body = `${owner.name}: ${why.join("; ")}`;
+        if (PACKAGE_PATH.test(owner.rel)) {
+            scan.exempt.push({
+                ...site,
+                note: `EXEMPT (package) — inside ${IDENTITY_PACKAGE} itself. ${body}`,
+            });
+            continue;
+        }
+        const reason = markerOf(owner);
+        if (reason !== undefined)
+            scan.exempt.push({
+                ...site,
+                note: `EXEMPT (marker) — "${reason.slice(0, 120)}". ${body}`,
+            });
+        else
+            scan.violate.push({ ...site, note: body });
+    }
+    return scan;
+}
+/** The owner whose declaration starts on line `n` at or above `node`. */
+function ownerAtDecl(node, rel, n) {
+    for (let x = node; x; x = x.parent) {
+        if (lineOf(x) !== n)
+            break;
+        if (ts.isFunctionDeclaration(x) && x.name)
+            return { rel, n, name: x.name.text, node: x };
+        if ((ts.isVariableDeclaration(x) || ts.isPropertyAssignment(x)) &&
+            ts.isIdentifier(x.name))
+            return { rel, n, name: x.name.text, node: x };
+        if (ts.isMethodDeclaration(x) && ts.isIdentifier(x.name))
+            return { rel, n, name: x.name.text, node: x };
+    }
+    // the declaration may start on the line as a descendant's parent chain did
+    // not reach it (a VariableStatement whose first token is `export`)
+    let found;
+    walk(node.getSourceFile(), (x) => {
+        if (found || lineOf(x) !== n)
+            return;
+        if (ts.isFunctionDeclaration(x) && x.name)
+            found = { rel, n, name: x.name.text, node: x };
+        else if (ts.isVariableDeclaration(x) && ts.isIdentifier(x.name))
+            found = { rel, n, name: x.name.text, node: x };
+        else if (ts.isPropertyAssignment(x) && ts.isIdentifier(x.name))
+            found = { rel, n, name: x.name.text, node: x };
+    });
+    return found ?? ownerOf(node, rel);
+}
+// ---- verdict + rendering --------------------------------------------------
+const list = (xs) => xs.map((s) => `${s.rel}:${s.n} (${s.note})`).join("; ");
+export function localIdentityResult(scan) {
+    const nV = scan.violate.length;
+    const nE = scan.exempt.length;
+    const nJ = scan.cnj.length;
+    const counts = `[files=${scan.files} violations=${nV} exempt=${nE} could-not-judge=${nJ}]`;
+    const tail = `${nE ? ` Exempt (reported, not a pass by silence): ${list(scan.exempt)}.` : ""}${nJ ? ` could-not-judge (not decided): ${list(scan.cnj)}.` : ""}`;
+    if (nV > 0)
+        return withCount({
+            id: CR2_ID,
+            anchor: `${scan.violate[0].rel}:${scan.violate[0].n}`,
+            state: "non-conforming",
+            verdict: `CR-2: ${nV} site(s) define a local identity primitive instead of calling ${IDENTITY_PACKAGE}. ${counts} Violations: ${list(scan.violate)}.${tail}`,
+        }, siteCount(scan.violate));
+    if (nJ > 0) {
+        const reason = `CR-2: 0 violations, but ${nJ} file(s) could not be judged. ${counts}${tail} This is NOT a clean bill.`;
+        return {
+            id: CR2_ID,
+            anchor: `${scan.cnj[0].rel}:${scan.cnj[0].n}`,
+            state: "could-not-judge",
+            verdict: reason,
+            reason,
+        };
+    }
+    if (scan.files === 0) {
+        const reason = "CR-2: no applicable file — no convex/ or mcp-server/src source was read. NOT a clean bill.";
+        return {
+            id: CR2_ID,
+            anchor: "local-identity:no-applicable-file",
+            state: "could-not-judge",
+            verdict: reason,
+            reason,
+        };
+    }
+    return {
+        id: CR2_ID,
+        anchor: scan.exempt[0]
+            ? `${scan.exempt[0].rel}:${scan.exempt[0].n}`
+            : "local-identity:none",
+        state: "present",
+        verdict: `CR-2: 0 violations across ${scan.files} file(s); ${nE} exempt. ${counts}${tail}`,
+    };
+}
+/** The rendered section: EVERY violation, exemption and abstention is named. */
+export function localIdentitySection(scan) {
+    const out = [
+        `LOCAL IDENTITY (CR-2) — DOCTOR-OWNED mechanical control, NOT one of the numbered rules in the pinned standard. Identity lives only in ${IDENTITY_PACKAGE}; ceiling 0. It drives the exit code.`,
+        `  files read: ${scan.files}`,
+    ];
+    for (const [label, xs] of [
+        ["VIOLATION", scan.violate],
+        ["EXEMPT", scan.exempt],
+        ["COULD-NOT-JUDGE", scan.cnj],
+    ]) {
+        out.push(`  ${label} (${xs.length}):`);
+        for (const s of xs)
+            out.push(`    ${s.rel}:${s.n} — ${s.note}`);
+    }
+    out.push(`  CR-2 VERDICT: ${scan.violate.length} violation(s) — ${scan.violate.length ? "MECHANICAL, the gate refuses" : "none"}; ${scan.exempt.length} exempt; ${scan.cnj.length} could-not-judge.`);
+    return out.join("\n");
+}
+/** CR-2 as an engine Detector. */
+export const CR2 = {
+    id: CR2_ID,
+    run: (tree) => localIdentityResult(scanLocalIdentity(tree.files)),
+};

package/dist/detectors/source/package-principal.d.ts

@@ -0,0 +1,9 @@
+import { type Parsed } from "./_ast.js";
+/** The checked package principals of one handler. */
+export interface PackagePrincipals {
+    /** `expr` (a source expression) when it IS the checked principal or a member
+     * read of it: a description of why, else undefined. */
+    principalOf(expr: string): string | undefined;
+}
+/** Read handler `handlerName` of `p` before `beforeLine` (the first write). */
+export declare function packagePrincipals(p: Parsed, handlerName: string, beforeLine: number): PackagePrincipals;