@vantageos/backend-doctor 0.1.14 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 A conformance instrument. It scores a Convex backend against the **VantagePeers backend standard** — a *pinned, frozen fixture*, not a document authored here — and prints, per rule, the sites that fail it or the sites a human verdict is owed on. It **consumes** the `@vantageos/mcp-doctor` engine (`runDoctor` + `renderTable`) — it never re-implements it and touches no engine file; the contract types are derived from the engine's own signatures.
 
-The standard is vendored under `fixtures/backend-standard-<pin>.md`, byte-identical to its upstream git blob; the canonical source lives in ElPi-Corp at `analysis/vantagepeers/backend-standard/backend-standard.md` (pin `51ec7af1`, 48 rules). The doctor never authors the standard — it scores against the frozen copy.
+The standard is vendored under `fixtures/backend-standard-<pin>.md`, byte-identical to its upstream git blob; the canonical source lives in ElPi-Corp at `vantagepeers/backend-standard/backend-standard.md` (pin `2825122`, 52 rules — the merge of ElPi-Corp PR #228 on `origin/main`, on top of #226's merge `9f7d789`; see `PINS.txt`). The doctor never authors the standard — it scores against the frozen copy.
 
 ## What it checks — every rule, one bucket, derived not typed
 
@@ -18,9 +18,10 @@ The detectors read four kinds of material, each a **comparison target, never an
 
 | Kind | Reads | Rules (examples) |
 |---|---|---|
-| oracle-CSV (Axis-2) | the per-tool inventory `fixtures/vp-by-tool-day158.csv` | R-1..R-13, R-7, R-8, R-37 |
-| oracle-CSV (Axis-1) | VP oracle **vs** the VR inventory `fixtures/vr-by-tool-day159.csv` | R-40 |
-| source-tree | the real `convex/` source (live path, or `fixtures/vp-convex/` in CI) | R-6, R-11, R-16..R-36 |
+| oracle-CSV (Axis-2) | the per-tool inventory the target's own `.backend-doctor/vp-by-tool.csv` (or `--oracle <file>`); absent => could-not-judge | R-1..R-13, R-7, R-8, R-37 |
+| writer-tier side-car | `vp-writer-tier.csv` beside the VP oracle (or `--writer-tier <file>`), joined on `outil`; absent => R-10 could-not-judge, file named | R-10 |
+| oracle-CSV (Axis-1) | VP oracle **vs** the VR inventory `.backend-doctor/vr-by-tool.csv` (or `--vr-oracle <file>`) | R-40 |
+| source-tree | the real `convex/` source and `mcp-server/src` (live path, or `fixtures/vp-convex/` in CI) | R-6, R-11, R-16..R-36, R-50..R-53 |
 | standard-document | the vendored standard + the four MCP-family docs | R-14, R-15, R-32, R-38, R-39, R-41, R-42 |
 
 ### The acceptance property — surfacing, not deferring
@@ -33,6 +34,8 @@ backend-doctor is its **own tool** (own package `@vantageos/backend-doctor`, own
 
 ```bash
 npx --yes @vantageos/backend-doctor@<version> <path-to-a-convex-backend>
+# <path> may be the repo root or its convex/ dir: both are normalised to the repo root
+# (nearest package.json/.git) and produce identical results. --version / --help are supported.
 ```
 
 Do not type a stale version as the only pin — read the current one from the registry, never from this README:
@@ -55,6 +58,8 @@ npm test                                          # the detector suite (RED-firs
 npx tsc --noEmit
 ```
 
+`node dist/cli.js` refuses to run (exit 2) when the `dist/` it runs from was compiled from different source than the checkout's `src/`: `npm run build` stamps `dist/build-stamp.json` with a sha256 of `src/**/*.ts`, and the CLI recomputes it before reading anything (`src/build-stamp.ts`). A gate that must not depend on a build step runs from source (`npx tsx src/cli.ts`). An installed package has no `src/` and is identified by its version.
+
 ### The verdict, the tally, and the exit code (D6)
 
 The CLI prints a **machine tally** — the four rule states (`present` / `non-conforming` / `could-not-judge` / `absent`) counted **by code** from the detector results and asserted to sum to the derived rule count (the coverage denominator, never a typed number). No human ever counts rows (the eyeballed-distribution defect is closed). The tally is over **rules** (one worst-state per rule); the printed line also names the raw result count so the two are never confused.
@@ -77,11 +82,67 @@ Verdict mapping, computed from the tally (major = major-high + major):
 
 A `could-not-judge` rule is an **abstention** — a human verdict is owed, never a silent approve; any abstention blocks `approve`, and an abstention on a **critical** rule is reported first. The exit code preserves the engine's honesty (and cross-checks `@vantageos/mcp-doctor`'s `computeExitCode`): **1** = a hard violation (≥1 critical, or any major violation); **2** = a human verdict owed with no hard violation (an abstention — never a clean 0); **0** = approve. `approve` is never printed on an exit that means abstention.
 
+### CR-1 — caller resolution on the exposed surface (doctor-owned, CRITICAL)
+
+Alongside the numbered rules the CLI renders a **CALLER RESOLUTION (CR-1)** section answering one question per registration: **does this public registration resolve its caller before serving or writing data?**
+
+- **Population is the exposed surface itself**, derived from the target tree's own `convex/_generated/api.d.ts` — never a hand-written list and never a pattern over argument names. `internal*`/`httpAction` are excluded and the exclusion is **proven per site** from the builder token on that line. The count classified must **equal** the count exposed; a discrepancy is reported as CR-1's own bug.
+- **Four classes, and every member is named**: `RESOLVES` / `FAIL-OPEN` / `NO-IDENTITY` / `NO-DATA`. `FAIL-OPEN` and unjustified `NO-IDENTITY`/`NO-DATA` are mechanical violations and the gate refuses on them (exit 1).
+- **The only exit is a token in the target source**, `allow-no-caller-resolution: <reason>`, read at the registration. There is no exemption list, no baseline and no tolerated count — `FAIL-OPEN` has no token exit at all.
+- **It asks whether the caller is RESOLVED, never whether a refusal is shaped correctly.** That second question is R-50/R-51's; a handler with no guard has nothing to throw, so it cannot fail a rule about throwing.
+- On a tree that exposes nothing it reports **no applicable site**, never a count.
+
+**CR-1 is NOT one of the numbered rules** in the pinned standard, so it is not in `src/registry.ts` and does not enter the coverage line: registering an id the vendored standard does not define would make `coverage.ts` report a phantom rule. Its upstream number is **pending**: the earlier proposal "R-52" is withdrawn because the standard at `2825122` gives R-52 to the cross-tenant-write rule and R-53 to identity-by-ID (§16); CR-1 takes the next free number when it is upstreamed, in the standard's own repository. Source and rationale: `src/caller-resolution.ts`.
+
+### CR-2 — no local identity primitive (doctor-owned, mechanical, ceiling 0)
+
+Operator order 2026-10-09: *"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."* Identity lives only in `@vantageos/cloud-identity`. The CLI renders a **LOCAL IDENTITY (CR-2)** section; every site is named by `file:line`.
+
+- **One site per function that defines a primitive** (a helper, an MCP tool handler, or a Convex registration whose own handler does it) in `convex/` and `mcp-server/src`. Each site names every kind it holds, with its line: **tenant** (resolves a caller to a tenant or agent), **membership** (a gate on a role / master field, a membership-table read), **scope** (an allow-list field read, a membership test over a caller's tenant / name / scope list), **credential** (`timingSafeEqual`, token hashing, `jose` / `jsonwebtoken` verification), **name** (an agent identified by name: an index keyed on a name field, a comparison through a name normaliser).
+- **R-53 is reused, not re-derived**: its (d) local identity layers, its doors whose principal is resolved by the handler itself, its clause-1 recipient-by-name sites and its (c) master-on-absence branches become CR-2 sites of the matching kind. What R-53 already sanctions (a `getUserIdentity()` value that reaches only a package resolver, the org-ID adapter read) is not a site.
+- **EXEMPT, and reported as exempt**: a file of `@vantageos/cloud-identity` itself, and a site carrying `allow-local-identity: <reason of 8+ characters>` in its leading comment or body. Each exempt site is listed with its reason.
+- **COULD-NOT-JUDGE**: a file with a syntax error is named and judged nowhere (exit 2 when nothing else is red); an empty population is never a clean bill.
+- **Ceiling 0**: CR-2 is mechanical (`fixtures/rule-classes-2825122.json`). Any violation is counted in `mechanical_rule_counts` / `mechanical_rule_module_counts` and exits 1.
+
+**CR-2 is NOT one of the numbered rules** for the same reason as CR-1: the pinned standard numbers R-1..R-53, and an `R-54` it does not define would be reported by `coverage.ts` as an unknown rule and left unclassified by `rule-class.ts` (which would null the mechanical count). Source and rationale: `src/detectors/source/local-identity.ts`.
+
+### R-31 — the read budget of a bulk mutation
+
+- **R-31** (`src/detectors/source/readbudget.ts`): a `.collect()` inside a mutation is non-conforming unless it reads an index-equality range carrying `// read-bound: <reason>`; a bounded read (`.take(n)`/`.paginate`) conforms when the mutation self-reschedules with `ctx.scheduler.runAfter`, or when it is a **caller-driven drain** — the `.paginate` result flows to one return statement of the handler itself (a nested callback's return does not count) carrying both the continuation cursor and the `isDone` flag (any field names), so the caller re-invokes it page by page, and no `ctx.runMutation`/`ctx.runAction` in the same transaction carries that cursor or names the mutation; every other bounded read is could-not-judge.
+
+### R-52 and R-53 — the write reaches the right row, and the actor is who it is by ID
+
+- **R-52** (`src/detectors/source/cross-tenant-write.ts`): a write that reaches a row with no tenant value (no tenant column, or an optional one) through a value the caller chose — an argument, or a stored field a public write set from its arguments, such as `task.project` — must be dominated by a guard reading a server-stamped tenant: the target's own tenant when it has a column, a fleet-only decision when it has none. Tenant columns are the standard's `orgId`/`tenantId`/`workspaceId`/`orgSlug`, or a `namespace` checked against the caller's allowed prefixes (ElPi-Corp #228). The namespace condition is decided per table from its public doors (every query/mutation/action that reads or writes it): every door runs a prefix test (a function taking a namespace parameter and testing it with `.startsWith`, closed over calls — vantage-peers `isNamespaceAllowedForScope` — called on a namespace value: the argument at its namespace parameter derives from `args.namespace`, a row's `.namespace` or a binding of one, never a constant), refuses every non-master, or reads the table only on the true side of an `isMaster` test -> tenant column; no door does -> the table is untenanted; mixed, or no public door -> every R-52 site targeting it is could-not-judge, never green. On vantage-peers `2faa399`, `memories` is mixed (nine doors checked, `oauth.ts:provisionOrganization` reads it through `findSeatNameCollision` unchecked), so its six sites are could-not-judge.
+- **R-53** (`src/detectors/source/identity-by-id.ts`): every public write door resolves its principal through `@vantageos/cloud-identity` (never a `client_org_mapping` lookup in product code, save the one read the ruling of task k1742q0vm05x2f5pqawnz1eah18fp01p admits: keyed by the Clerk org ID — `.withIndex("by_clerk_org_id", (q) => q.eq("clerkOrgId", K))` or `.filter((q) => q.eq(q.field("clerkOrgId"), K))`, then `.unique()`/`.first()` — where `K` is the org ID the package hands the `orgKindOf` adapter (its first parameter, or a helper parameter every call site fills with it), inside an `orgKindOf` or `organisationById` member of a lookups object passed to `resolveActingPrincipal`/`assertTargetBelongsTo` — inline, through a local, or as the return of a named builder that only assembles (no branch, no throw, no expression statement) — deciding nothing but its own return, an `organisationById` answering only `{ id, active }` read from the row or null; a slug or name key, `withOrgScope`/`lookupOrgMapping`, and a read whose result reaches anything else stay red; a `getUserIdentity()` read is admitted only when its value, followed through locals, destructuring and helpers, ends solely as the first argument of `resolveActingPrincipal`/`resolvePersonPrincipal`, since the package verifies nothing about the credential itself), admits by comparing stored IDs (inline, or through the package's own `assertTargetBelongsTo(principal, { orgId: row.orgId[, ownerId: row.ownerId] }, …)` — synchronous at cloud-identity `a6e5780` or awaited with a lookups argument at PR #21 — whose `!ok` branch throws or returns before the write; never a name field against a typed or credential-carried name), and refuses an unresolved principal; any helper or MCP tool handler that compares names to admit, or resolves identity itself, is a local identity layer.
+
+Neither rule has a justification-token exit. Both are mechanical and count in `mechanical_violations`.
+
+### The deploy-gate evidence — `--json-evidence` and `mechanical_violations`
+
+The vantage-peers deploy hook (`enforce-backend-doctor-before-deploy.py`) refuses a Convex deploy unless `qa/backend-doctor-<sha>.json` pins the deployed commit and carries an integer `mechanical_violations == 0`. It refuses on **mechanical** non-conformance only, never on a judgement/process rule. The CLI writes that file:
+
+```bash
+npx tsx src/cli.ts <repo>/convex --json-evidence <repo>/qa/    # a directory -> backend-doctor-<sha>.json
+```
+
+It writes exactly `{"sha","cli_commit","convex_path","exit_code","checked","total","mechanical_violations","mechanical_rule_counts","mechanical_rule_module_counts"}` (the last two are additive; the first seven are unchanged):
+
+- `sha` = `git -C <convex_path>/.. rev-parse HEAD`; no sha, no file (exit 2).
+- `cli_commit` = this checkout's HEAD (`+dirty` when `src/` or `fixtures/` differ from it), or `npm @vantageos/backend-doctor@<version>` for an installed copy.
+- `exit_code` = the code the process actually exits with; `checked`/`total` = the coverage line.
+- `mechanical_violations` = the number of **rules** whose reduced state is `non-conforming` and whose class is **mechanical** (CR-1 and CR-2 each count as one rule). The same count is printed as `MECHANICAL VIOLATIONS: N` right under the VERDICT line, with the per-rule breakdown.
+- `mechanical_rule_counts` = an object mapping each red mechanical rule id to its **non-conforming count**, the number its report line prints: sites for a source rule (`R-53: 113 site(s) VIOLATE` -> `"R-53": 113`), rows for an oracle rule (`R-2: 6 of 106 applicable oracle rows VIOLATE` -> `"R-2": 6`), registrations for CR-1, defining functions for CR-2. Its key count equals `mechanical_violations`; `{}` on a clean run. The count is attached by the reduction that formats the printed line, from the same variable (`src/violation-count.ts`), never parsed back from the text. A rule reduced from two red halves (R-31) sums its red halves; a single structural finding (R-14, R-38) counts 1. Printed as `MECHANICAL RULE COUNTS: R-2 6, …` under the MECHANICAL line. **`null`** when `mechanical_violations` is null, or when a red mechanical rule's producer attached no count (printed as `MECHANICAL RULE COUNTS: COULD-NOT-JUDGE — no count attached for …`): a partial map would read as complete.
+- `mechanical_rule_module_counts` = for each **site-based** red mechanical rule (source scans, R-46, CR-1, CR-2), `{ module: count }` summing to that rule's `mechanical_rule_counts` entry. A `convex/` file's module is its basename without extension (`convex/tasks.ts` -> `tasks`, `convex/lib/auth.ts` -> `auth`); a file outside `convex/` keeps its path without extension (R-53 also reads `mcp-server/src`: `mcp-server/src/tools`). Row- and finding-based rules (R-2, R-8, R-13, R-28 and every other oracle rule, R-14, R-37, R-38, R-40, R-41, the standard-document rules) are absent. `null` with `mechanical_rule_counts`.
+
+**The class is data, not code.** `fixtures/rule-classes-2825122.json` gives every numbered rule plus CR-1 and CR-2 exactly one class with a one-phrase basis (38 mechanical = the standard's 36 + CR-1 + CR-2; 16 judgement = 13 judgement + 3 process). Each R- entry is cross-checked at run time against the pinned standard's own build kind (§15 table, which at `2825122` lists all 52 rules; a Detector spec's `*kind:*` token is the fallback for a rule the table omits), `process` mapping to judgement. Consequence: **R-6, R-11, R-29, R-33, R-34, R-35 now COUNT** (ElPi-Corp #225 settled them mechanical), as do **R-52 and R-53**; R-16..R-20 and the other §15 judgement rules print but are not counted, exactly as the standard classifies them.
+
+**Never a silent 0.** Abstentions (`could-not-judge`) are not violations: they are listed apart on the MECHANICAL line and keep the exit code at 2 when no violation exists. The count becomes `null` (the hook reads it as INCOMPLETE and refuses) when it cannot be certified: a rule with no class, a sidecar class that contradicts the standard, a sidecar pinned to another standard, incomplete coverage, a failed CRUD self-check, or a judged `convex/` tree that differs from the commit `sha` names. Each reason is printed as `CANNOT CERTIFY: …`.
+
 ## Pins
 
 Every input is pinned and, where it is a vendored document, proven byte-identical to its upstream git blob (an un-hashable vendored doc is an authority granted to oneself).
 
-**The single authority for which standard fixture is active is the loader constant** `STANDARD_FILE` in [`src/detectors/standard/_doc.ts`](./src/detectors/standard/_doc.ts) — currently `backend-standard-4bcd605.md` (50 rules — R-50/R-51, org isolation on a subscribed read / a pre-org write is a typed empty/unauthorised result, never an uncaught throw; at this pin a gated `customQuery`/`customMutation` wrapper is JUDGED red/green from its readable `customCtx`, not could-not-judge; canonical source: ElPi-Corp `analysis/vantagepeers/backend-standard/backend-standard.md`). Everything else is provenance, NOT the active pin: `PINS.txt` and any other `fixtures/backend-standard-<sha>.md` still in the tree (e.g. the superseded `backend-standard-a9d7877b.md`, 47 rules — it lacks R-48) are kept only to show what was scored before. If any of them disagrees with `STANDARD_FILE`, `STANDARD_FILE` wins. Read the active pin from `STANDARD_FILE`, never from `PINS.txt` or a number typed elsewhere — following a stale `PINS.txt` would silently score the superseded 47-rule document and never surface R-48. See [`PINS.txt`](./PINS.txt) for the engine, backend snapshot, and MCP-family doc + VR inventory pins.
+**The single authority for which standard fixture is active is the loader constant** `STANDARD_FILE` in [`src/detectors/standard/_doc.ts`](./src/detectors/standard/_doc.ts) — currently `backend-standard-2825122.md` (52 rules — adds R-52, a write reaching a row with no tenant value through a caller-choosable key checks the target's tenant first, and R-53, actor and target identified by ID through `@vantageos/cloud-identity`, a name never selects or authorises; canonical source: ElPi-Corp `vantagepeers/backend-standard/backend-standard.md`). `2825122` is the merge of ElPi-Corp PR #228 on `origin/main` (after #226 at `9f7d789`); it resolves. The previous pins `backend-standard-4dcd3e0.md` (the provisional #226 head) and `backend-standard-4bcd605.md` (50 rules) stay in the tree as provenance. **Declared divergence at this pin:** the R-53 text at `2825122` rules `resolveVerifiedPerson` red under clause 1 because it selects the organisation by `clerkOrgSlug`, a slug, rather than by ID; the R-53 detector reports the slug-keyed lookup itself (vantage-peers `2faa399` `convex/lib/auth.ts:465` `lookupOrgMapping`, clause (d), `query("client_org_mapping").withIndex(<clerk claim>)`) but does not report `resolveVerifiedPerson` (`convex/lib/personPrincipal.ts:73`), which receives that lookup injected, as a site of its own under clause 1 — a gap carried to a follow-up, not a green. Everything else is provenance, NOT the active pin: `PINS.txt` and any other `fixtures/backend-standard-<sha>.md` still in the tree (e.g. the superseded `backend-standard-a9d7877b.md`, 47 rules — it lacks R-48) are kept only to show what was scored before. If any of them disagrees with `STANDARD_FILE`, `STANDARD_FILE` wins. Read the active pin from `STANDARD_FILE`, never from `PINS.txt` or a number typed elsewhere — following a stale `PINS.txt` would silently score the superseded 47-rule document and never surface R-48. See [`PINS.txt`](./PINS.txt) for the engine, backend snapshot, and MCP-family doc + VR inventory pins.
 
 ## Discipline (how a detector is proven)
 

package/dist/args.d.ts

@@ -0,0 +1,16 @@
+export declare const USAGE = "usage: backend-doctor [<target>] [--oracle <csv>] [--vr-oracle <csv>] [--writer-tier <csv>]\n                      [--json-evidence <file-or-dir>]\n       backend-doctor --version | --help\n\n  <target>   the repository root or its convex/ dir (default: the current dir).\n             Both name the same backend: paths are normalised to the repo root\n             (nearest dir holding package.json or .git), so the counts are identical.\n  --oracle, --vr-oracle, --writer-tier\n             explicit oracle CSVs; by default they are read from\n             <repo>/convex/.backend-doctor/ or <repo>/.backend-doctor/ \u2014 never from\n             above the repo root and never from this tool's bundled fixtures.\n  --json-evidence <file-or-dir>\n             also write the deploy-gate evidence JSON, exactly\n             {\"sha\",\"cli_commit\",\"convex_path\",\"exit_code\",\"checked\",\"total\",\n              \"mechanical_violations\",\"mechanical_rule_counts\",\n              \"mechanical_rule_module_counts\"}; a directory receives\n             backend-doctor-<sha>.json. mechanical_violations is null (never 0)\n             when it cannot be certified (an unclassified rule, incomplete\n             coverage, a CRUD self-check failure, or a convex/ tree that differs\n             from HEAD). mechanical_rule_counts maps each red mechanical rule to\n             the count its report line prints; module counts split site-based\n             rules by convex module. Both are null when the count is null or a\n             red rule carries no count.\n  --version  print the tool version and exit 0.\n  --help     print this text and exit 0.\n\nexit: 0 approve, 1 a violation / revise, 2 the run could not judge (bad usage,\nunreadable target, stale build, unreadable standard).";
+export type ParsedArgs = {
+    kind: "run";
+    positional: string[];
+    flags: Record<string, string>;
+} | {
+    kind: "version";
+} | {
+    kind: "help";
+} | {
+    kind: "usage-error";
+    message: string;
+};
+/** Flag reader. `--version`/`--help` win over everything else; an unknown flag or
+ * a value flag with no value is a usage error (exit 2) — never a path. */
+export declare function parseArgs(argv: string[]): ParsedArgs;

package/dist/args.js

@@ -0,0 +1,72 @@
+// CLI argument parsing, kept apart from cli.ts (which runs main() on import) so the
+// flag contract is testable without spawning a process.
+const VALUE_FLAGS = new Set([
+    "oracle",
+    "vr-oracle",
+    "writer-tier",
+    "json-evidence",
+]);
+export const USAGE = `usage: backend-doctor [<target>] [--oracle <csv>] [--vr-oracle <csv>] [--writer-tier <csv>]
+                      [--json-evidence <file-or-dir>]
+       backend-doctor --version | --help
+
+  <target>   the repository root or its convex/ dir (default: the current dir).
+             Both name the same backend: paths are normalised to the repo root
+             (nearest dir holding package.json or .git), so the counts are identical.
+  --oracle, --vr-oracle, --writer-tier
+             explicit oracle CSVs; by default they are read from
+             <repo>/convex/.backend-doctor/ or <repo>/.backend-doctor/ — never from
+             above the repo root and never from this tool's bundled fixtures.
+  --json-evidence <file-or-dir>
+             also write the deploy-gate evidence JSON, exactly
+             {"sha","cli_commit","convex_path","exit_code","checked","total",
+              "mechanical_violations","mechanical_rule_counts",
+              "mechanical_rule_module_counts"}; a directory receives
+             backend-doctor-<sha>.json. mechanical_violations is null (never 0)
+             when it cannot be certified (an unclassified rule, incomplete
+             coverage, a CRUD self-check failure, or a convex/ tree that differs
+             from HEAD). mechanical_rule_counts maps each red mechanical rule to
+             the count its report line prints; module counts split site-based
+             rules by convex module. Both are null when the count is null or a
+             red rule carries no count.
+  --version  print the tool version and exit 0.
+  --help     print this text and exit 0.
+
+exit: 0 approve, 1 a violation / revise, 2 the run could not judge (bad usage,
+unreadable target, stale build, unreadable standard).`;
+/** Flag reader. `--version`/`--help` win over everything else; an unknown flag or
+ * a value flag with no value is a usage error (exit 2) — never a path. */
+export function parseArgs(argv) {
+    if (argv.some((a) => a === "--version" || a === "-V" || a === "-v"))
+        return { kind: "version" };
+    if (argv.some((a) => a === "--help" || a === "-h"))
+        return { kind: "help" };
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("-") && a !== "-") {
+            const body = a.replace(/^--?/, "");
+            const eq = body.indexOf("=");
+            const name = eq === -1 ? body : body.slice(0, eq);
+            if (!a.startsWith("--") || !VALUE_FLAGS.has(name)) {
+                return { kind: "usage-error", message: `unknown flag ${a}` };
+            }
+            if (eq !== -1)
+                flags[name] = body.slice(eq + 1);
+            else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--"))
+                flags[name] = argv[++i];
+            else
+                return { kind: "usage-error", message: `flag ${a} needs a value` };
+        }
+        else
+            positional.push(a);
+    }
+    if (positional.length > 1) {
+        return {
+            kind: "usage-error",
+            message: `expected at most one target, got ${positional.length}: ${positional.join(" ")}`,
+        };
+    }
+    return { kind: "run", positional, flags };
+}

package/dist/build-stamp.d.ts

@@ -0,0 +1,13 @@
+export declare const STAMP_FILE = "build-stamp.json";
+/** sha256 over every `.ts` under `srcDir`: sorted relative path + NUL + bytes. */
+export declare function sourceDigest(srcDir: string): string;
+export type Freshness = {
+    ok: true;
+    mode: "source" | "installed" | "fresh-dist";
+} | {
+    ok: false;
+    reason: string;
+};
+/** Judge the build the CLI is running from. `here` is the directory of the
+ * running module (`dist/` when built, `src/` under tsx). */
+export declare function checkDistFreshness(here: string): Freshness;

package/dist/build-stamp.js

@@ -0,0 +1,76 @@
+// The dist-freshness guard. A gate verdict is a claim about a tree made BY a
+// specific instrument; when `dist/` was compiled from an older `src/` than the
+// checkout it sits in, the verdict silently comes from code nobody is reading
+// (measured: an installed dist built 2026-09-30 judging with detectors that
+// source 60780e6 of 2026-10-01 had already changed).
+//
+// CHOICE — refuse, by CONTENT, not warn by mtime:
+//  - `npm run build` stamps `dist/build-stamp.json` with a sha256 over every
+//    `src/**/*.ts` (path + bytes, sorted). The CLI, when it runs from `dist/` and a
+//    sibling `src/` exists (a checkout), recomputes that digest and REFUSES (exit 2)
+//    on a mismatch or a missing stamp, naming both digests and the two fixes.
+//  - A content digest is immune to what makes mtime useless here: `git checkout`
+//    rewrites mtimes, and a rebuild with no source change must not trip it.
+//  - A warning was rejected: the doctor's verdict line is read by gates, not by a
+//    human watching stderr, so a warning beside a verdict is still a verdict.
+//  - "Document that the gate runs from source" was rejected as the ONLY control:
+//    it is the rule that was already being followed when the stale dist ran.
+//  - An installed package (no sibling `src/`) is not checked: there the published
+//    version IS the instrument's identity, and the tarball carries no source.
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+export const STAMP_FILE = "build-stamp.json";
+/** sha256 over every `.ts` under `srcDir`: sorted relative path + NUL + bytes. */
+export function sourceDigest(srcDir) {
+    const files = [];
+    const walk = (dir) => {
+        for (const name of readdirSync(dir)) {
+            const full = join(dir, name);
+            if (statSync(full).isDirectory())
+                walk(full);
+            else if (name.endsWith(".ts"))
+                files.push(full);
+        }
+    };
+    walk(srcDir);
+    const h = createHash("sha256");
+    for (const f of files.map((x) => relative(srcDir, x)).sort()) {
+        h.update(f);
+        h.update("\0");
+        h.update(readFileSync(join(srcDir, f)));
+        h.update("\0");
+    }
+    return h.digest("hex");
+}
+/** Judge the build the CLI is running from. `here` is the directory of the
+ * running module (`dist/` when built, `src/` under tsx). */
+export function checkDistFreshness(here) {
+    if (basename(here) !== "dist")
+        return { ok: true, mode: "source" };
+    const src = join(here, "..", "src");
+    if (!existsSync(src))
+        return { ok: true, mode: "installed" };
+    const stampPath = join(here, STAMP_FILE);
+    const current = sourceDigest(src);
+    if (!existsSync(stampPath)) {
+        return {
+            ok: false,
+            reason: `dist/ carries no ${STAMP_FILE}, so which source it was compiled from cannot be shown (current src sha256 ${current.slice(0, 12)}). Rebuild with \`npm run build\`, or run from source: \`npx tsx src/cli.ts <target>\`.`,
+        };
+    }
+    let stamped;
+    try {
+        stamped = JSON.parse(readFileSync(stampPath, "utf8")).sourceDigest;
+    }
+    catch {
+        stamped = undefined;
+    }
+    if (stamped !== current) {
+        return {
+            ok: false,
+            reason: `dist/ is STALE: compiled from src sha256 ${String(stamped).slice(0, 12)}, the checkout's src is ${current.slice(0, 12)}. A verdict from this build would come from code that is no longer the source. Rebuild with \`npm run build\`, or run from source: \`npx tsx src/cli.ts <target>\`.`,
+        };
+    }
+    return { ok: true, mode: "fresh-dist" };
+}

package/dist/build-stamp.json

@@ -0,0 +1,4 @@
+{
+  "sourceDigest": "b6bfdbdcea24a6c2a672ed0ebc0b19dcaa680893b280820c23cbaf960130423d",
+  "builtAt": "2026-10-10T15:07:02.464Z"
+}

package/dist/caller-resolution.d.ts

@@ -0,0 +1,222 @@
+import type { Detector, DetectorResult, Tree } from "./engine-types.js";
+export type SrcFile = Tree["files"][number];
+export type SrcLine = SrcFile["lines"][number];
+/** The four classes. Every exposed public registration lands in exactly one. */
+export type CallerClass = "RESOLVES" | "FAIL-OPEN" | "NO-IDENTITY" | "NO-DATA" | "COULD-NOT-JUDGE";
+export interface Registration {
+    /** the api module key the registration is exposed under, e.g. `tasks`. */
+    module: string;
+    /** the exported name, e.g. `listUnlinkedBlocked`. */
+    name: string;
+    /** the api path a caller addresses, e.g. `tasks:listUnlinkedBlocked`. */
+    api: string;
+    rel: string;
+    /** 1-based line of the `export const NAME = <builder>(` opener. */
+    n: number;
+    /** the builder token READ AT THIS SITE — the per-site exclusion proof. */
+    builder: string;
+}
+export interface Finding extends Registration {
+    cls: CallerClass;
+    /** why it landed in that class — the discriminator(s), named. */
+    why: string;
+    /** true when a justification token in the target source cleared the finding. */
+    justified?: boolean;
+}
+export interface CallerResolutionScan {
+    /** api.d.ts module key -> file rel path, derived from the target's own api.d.ts. */
+    exposedModules: Map<string, string>;
+    /** how the population was obtained, for the cross-check line. */
+    populationSource: string;
+    /** every public registration, classified. */
+    findings: Finding[];
+    /** `internal*` / httpAction sites, each with the builder token observed. */
+    excluded: Registration[];
+    /** CR-1's OWN defects: population drift, an unreadable api.d.ts, an
+     *  undelimitable block, an unresolvable builder. Never a silent pass. */
+    selfDefects: string[];
+    /** the cross-check: exposed public registrations vs. classified findings. */
+    exposedCount: number;
+    classifiedCount: number;
+}
+export interface ApiSurface {
+    modules: Map<string, string>;
+    /** set when the surface could NOT be derived — never a silent empty. */
+    unreadable?: string;
+}
+/**
+ * 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 declare function deriveApiSurface(root: string, read?: (p: string) => string): ApiSurface;
+export interface BuilderMap {
+    /** builder name -> the public base it produces. */
+    publicBuilders: Map<string, string>;
+    /** builder name -> the non-public base it produces. */
+    nonPublicBuilders: Map<string, string>;
+    /** a `custom*` wrapper whose base resolves to neither — CR-1 refuses on these. */
+    unresolvable: {
+        rel: string;
+        n: number;
+        name: string;
+        base: string;
+    }[];
+}
+/** a file CR-1 judges — never a test, never generated. */
+export declare function isJudgeable(f: SrcFile): boolean;
+/**
+ * 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 declare function discoverBuilders(files: SrcFile[]): BuilderMap;
+/**
+ * Everything CR-1 knows about the tree's own helpers, DERIVED from the tree.
+ *
+ * KEYS ARE `rel::name`, NEVER a bare name, and a reference resolves ONLY inside the
+ * referencing module's SCOPE (what it declares plus what it imports). A single flat
+ * namespace is not a looseness here, it is a SILENT GREEN: `get`, `list`, `create`
+ * and `accept` are declared in many modules of this tree, so a flat
+ * `\bget\s*\(` test reported `search:searchFixPatterns` — which resolves nothing
+ * and hardcodes its namespace — as "consults the verified principal (get())".
+ * Measured on run 6; this shape is the fix.
+ */
+export interface IdentityModel {
+    /** `rel::name` of every function whose body consults the verified principal,
+     *  directly (`ctx.auth.getUserIdentity()`) or transitively. */
+    helpers: Set<string>;
+    /**
+     * The subset of `helpers` that REFUSE on the absent-identity path — a GATE. A
+     * gate decides by throwing, so calling it as a bare statement (`await
+     * requireOrgAdmin(ctx)`) is the fail-closed idiom and NOT a discarded principal.
+     * Only a RESOLVER — a helper that returns a value the handler must then use —
+     * can have its result computed and discarded. Conflating the two made the rule
+     * accuse 30 correctly master-gated mutations on its second run.
+     */
+    gates: Set<string>;
+    /**
+     * Functions that TOUCH DATA, transitively. A registration whose handler reads
+     * nothing itself but delegates to a module-local helper that does IS serving
+     * data — `tasks:list` (`return await runTasksList(ctx, args, scope)`) and
+     * `search:searchFixPatterns` (`await ragSearch(ctx, {…})`) both do exactly that,
+     * and a non-transitive data test filed all of them under NO-DATA on run 5,
+     * which would have been a silent pass on real read paths.
+     */
+    dataFns: Set<string>;
+    /**
+     * Identity helpers whose absent-identity branch GRANTS — a bare `return;` that
+     * lets the caller proceed. `okfBundleNode.ts::assertCanValidate` is exactly this:
+     * `if (identity === null || identity === undefined) { return; }` with the comment
+     * "CLI / deploy-key — server-trusted path". Calling such a helper is not a gate at
+     * all on the path that matters, so a handler whose only authority is one of these
+     * is FAIL-OPEN, and CR-1 says so in those words rather than under the vaguer
+     * "computed and discarded" reason.
+     */
+    permissiveOnAbsence: Map<string, string>;
+    /** the keys that are REGISTRATIONS: reachable ONLY as `internal.…`/`api.…`. */
+    regNames: Set<string>;
+    /** rel -> the local names that module DECLARES or IMPORTS. */
+    scopes: Map<string, Set<string>>;
+    /** identity helpers whose absent-identity branch can return a PRIVILEGED shape
+     *  when an opt-in flag is passed. flag name -> where it was found. */
+    privilegeOnAbsenceFlags: Map<string, string>;
+    /**
+     * VALUE REFUSERS — plain functions that RECEIVE an already-resolved value as a
+     * parameter and THROW on a test of it: `requireTenantNamespace(scope, ns, door)`
+     * at vantage-peers 58ed649 `convex/lib/auth.ts:1286`, which delegates to
+     * `requireResolvedCaller(scope, …)` (`if (scope.anonymous) throw …`). Keyed
+     * `rel::name` -> the parameter POSITIONS refused on, because only a resolved
+     * value passed AT that position is refused. See `deriveValueRefusers` for what
+     * qualifies and what disqualifies.
+     */
+    refuserParams: Map<string, Set<number>>;
+}
+/** the `name` half of a `rel::name` key. */
+export declare function nameOf(key: string): string;
+/** the `rel` half of a `rel::name` key. */
+export declare function relOf(key: string): string;
+export interface Ref {
+    name: string;
+    /** true when only a qualified `internal.…`/`api.…` reference may match it. */
+    qualified: boolean;
+}
+/**
+ * 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 declare function reachable(model: IdentityModel, set: Set<string>, rel: string): Ref[];
+/** the refs in `refs` that `text` actually references. */
+export declare function referenced(text: string, refs: Ref[]): Ref[];
+export declare function deriveIdentityModel(files: SrcFile[]): IdentityModel;
+/**
+ * `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 declare function references(text: string, name: string, qualified?: boolean): boolean;
+/** Every `if (...)` in `text`, with its brace-balanced condition source. */
+export declare function ifConditions(text: string): {
+    index: number;
+    cond: string;
+    end: number;
+}[];
+/**
+ * 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 declare function absentGuard(text: string, v: string): {
+    index: number;
+    branch: string;
+} | 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 declare function branchAfter(text: string, from: number): string;
+export interface Classified {
+    cls: CallerClass;
+    why: string;
+    justified?: boolean;
+}
+/**
+ * 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 declare function classify(codeText: string, fullText: string, pre: string, model: IdentityModel, rel: string): Classified;
+/** 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 declare function surfaceForTree(tree: Tree): ApiSurface;
+export declare function scanCallerResolution(tree: Tree, surface?: ApiSurface): CallerResolutionScan;
+export declare const CR1_ID = "CR-1 a public registration resolves its caller before serving or writing data";
+export declare function byClass(scan: CallerResolutionScan, cls: CallerClass): Finding[];
+/** the findings that are VIOLATIONS: fail-open, plus unjustified no-identity/no-data. */
+export declare function violations(scan: CallerResolutionScan): Finding[];
+export declare function abstentions(scan: CallerResolutionScan): Finding[];
+export declare function callerResolutionResult(scan: CallerResolutionScan): DetectorResult;
+/** 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 declare function callerResolutionSection(scan: CallerResolutionScan): string;
+/** CR-1 as an engine Detector, for tests and for a future registry slot. */
+export declare const CR1: Detector;