@vantageos/backend-doctor 0.2.0 → 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
 
@@ -21,7 +21,7 @@ The detectors read four kinds of material, each a **comparison target, never an
 | 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 (live path, or `fixtures/vp-convex/` in CI) | R-6, R-11, R-16..R-36 |
+| 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
@@ -92,13 +92,57 @@ Alongside the numbered rules the CLI renders a **CALLER RESOLUTION (CR-1)** sect
 - **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 the 50-of-50 coverage line is unchanged: registering an id the vendored standard does not define would make `coverage.ts` report a phantom rule. Numbering it upstream (proposed **R-52**) is a separate change to the standard document in its own repository. Source and rationale: `src/caller-resolution.ts`.
+**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

@@ -1,4 +1,4 @@
-export declare const USAGE = "usage: backend-doctor [<target>] [--oracle <csv>] [--vr-oracle <csv>] [--writer-tier <csv>]\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  --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 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[];

package/dist/args.js

@@ -1,7 +1,13 @@
 // 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"]);
+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).
@@ -11,6 +17,18 @@ export const USAGE = `usage: backend-doctor [<target>] [--oracle <csv>] [--vr-or
              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.
 

package/dist/build-stamp.json

@@ -1,4 +1,4 @@
 {
-  "sourceDigest": "f9c7040c0ed49bdf7a77370eeed51651d4556c1ec8a8f674c2ca8ffd55000592",
-  "builtAt": "2026-10-03T20:51:43.107Z"
+  "sourceDigest": "b6bfdbdcea24a6c2a672ed0ebc0b19dcaa680893b280820c23cbaf960130423d",
+  "builtAt": "2026-10-10T15:07:02.464Z"
 }

package/dist/caller-resolution.js

@@ -51,15 +51,18 @@
 // 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.
+// (fixtures/backend-standard-2825122.md) numbers R-1..R-53 (R-49 held, not
+// defined) and does not 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 (CR-1, numbering pending — R-52 is now the cross-tenant-write rule and
+// R-53 identity-by-ID, standard §16; CR-1 takes the next free number when it is
+// upstreamed) 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";
+import { siteCount, withCount } from "./violation-count.js";
 // ---------------------------------------------------------------------------
 // population — the exposed surface, from the TARGET tree's own api.d.ts
 // ---------------------------------------------------------------------------
@@ -1124,14 +1127,14 @@ export function callerResolutionResult(scan) {
         const named = v
             .map((f) => `${f.api} @ ${f.rel}:${f.n} [${f.cls}] — ${f.why}`)
             .join("\n    ");
-        return {
+        return withCount({
             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(" | ")}`
                 : ""}`,
-        };
+        }, siteCount(v));
     }
     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} ${[

package/dist/cli.js

@@ -5,22 +5,25 @@
 // DISTINCTLY. The target is a real directory so the engine's loadTree succeeds;
 // the first-wave detectors ignore the tree and consult the oracle.
 import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { renderTable, runDoctor } from "@vantageos/mcp-doctor";
 import { parseArgs, USAGE } from "./args.js";
 import { checkDistFreshness } from "./build-stamp.js";
 import { CR1_ID, callerResolutionResult, callerResolutionSection, violations as crViolations, scanCallerResolution, } from "./caller-resolution.js";
-import { coverage, coverageSummary } from "./coverage.js";
+import { coverage, coverageSummary, deriveRuleIds } from "./coverage.js";
 import { crudCoverageSection, extractReactRouterPaths, scanCrudCoverage, } from "./crud-coverage.js";
+import { CR2_ID, localIdentityResult, localIdentitySection, scanLocalIdentity, } from "./detectors/source/local-identity.js";
 import { checkStandardReadable } from "./detectors/standard/_doc.js";
 import { NOT_MECHANICALLY_CHECKABLE, notCheckableResults, } from "./not-checkable.js";
 import { activateOracle, describeOracle, resolveOracle } from "./oracle.js";
 import { REGISTRY } from "./registry.js";
 import { writeReport } from "./report.js";
+import { buildEvidence, classifyRules, countMechanical, mechanicalLine, } from "./rule-class.js";
 import { handlerSurfaceLine, handlerSurfaceStats, tally, tallyLine, verdict, } from "./tally.js";
 import { describeScope, loadScopedTree, onScopedTree, resolveTarget, } from "./target.js";
+import { mechanicalRuleCounts, mechanicalRuleCountsLine, } from "./violation-count.js";
 const here = dirname(fileURLToPath(import.meta.url));
 /** `git -C <target> rev-parse HEAD`, or "not a git repo" when it is not one. */
 function targetCommit(target) {
@@ -44,6 +47,41 @@ function treeStatus(target) {
         return "not a git repo";
     }
 }
+/** The instrument's own identity for the evidence file: the backend-doctor
+ * checkout's HEAD when this module runs from its own git checkout (`+dirty` when
+ * src/ or fixtures/ differ from it), else the published package version. Never the
+ * HEAD of a repository that merely CONTAINS an installed copy. */
+function cliCommit() {
+    const root = resolve(here, "..");
+    try {
+        const top = execFileSync("git", ["-C", root, "rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (resolve(top) !== root)
+            throw new Error("not this checkout");
+        const head = execFileSync("git", ["-C", root, "rev-parse", "HEAD"], {
+            encoding: "utf8",
+        }).trim();
+        const dirty = execFileSync("git", ["-C", root, "status", "--porcelain", "--", "src", "fixtures"], { encoding: "utf8" }).trim();
+        return dirty ? `${head}+dirty` : head;
+    }
+    catch {
+        return `npm @vantageos/backend-doctor@${toolVersion()}`;
+    }
+}
+/** `git -C <dir> <args>` trimmed, or undefined when git refuses. */
+function gitOut(dir, args) {
+    try {
+        return execFileSync("git", ["-C", dir, ...args], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
 function toolVersion() {
     const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
     return pkg.version;
@@ -247,6 +285,27 @@ function main() {
     console.log(callerResolutionSection(crScan));
     const crResult = callerResolutionResult(crScan);
     const crDefect = crViolations(crScan).length > 0;
+    // LOCAL IDENTITY (CR-2) — DOCTOR-OWNED mechanical control, same footing as
+    // CR-1: no application defines its own identity primitive; identity lives
+    // only in @vantageos/cloud-identity. Ceiling 0 — any violation exits non-zero.
+    console.log("");
+    let liScan;
+    runDoctor(scope.repoRoot, onScopedTree(tree, [
+        {
+            id: CR2_ID,
+            run: (t) => {
+                liScan = scanLocalIdentity(t.files);
+                return localIdentityResult(liScan);
+            },
+        },
+    ]));
+    if (liScan === undefined) {
+        console.error("CR-2: the engine did not run the local-identity detector — refusing to report a surface that was never scanned.");
+        process.exit(2);
+    }
+    console.log(localIdentitySection(liScan));
+    const liResult = localIdentityResult(liScan);
+    const liDefect = liScan.violate.length > 0;
     console.log("");
     const cov = coverage();
     console.log(coverageSummary(cov));
@@ -272,12 +331,68 @@ function main() {
     // driven to 0 (Laurent: an instrument that cannot go red protects nothing).
     console.log(handlerSurfaceLine(handlerSurfaceStats(results)));
     console.log(`CALLER-RESOLUTION TALLY (CR-1, doctor-owned, outside the pinned rule set): state=${crResult.state} violations=${crViolations(crScan).length} | ${crResult.verdict.split("\n")[0]}`);
+    console.log(`LOCAL-IDENTITY TALLY (CR-2, doctor-owned, outside the pinned rule set): state=${liResult.state} violations=${liScan.violate.length} exempt=${liScan.exempt.length} could-not-judge=${liScan.cnj.length}`);
     console.log(v.summary);
     if (v.criticalViolations > 0) {
         console.log(`  critical violations: ${v.violations.critical.join(", ")}`);
     }
     if (v.criticalAbstentions > 0) {
-        console.log(`  critical abstentions (human verdict owed): ${v.abstentions.critical.join(", ")}`);
+        console.log(`  critical abstentions (not decided; each rule names why): ${v.abstentions.critical.join(", ")}`);
+    }
+    // The process exit code, decided ONCE so the evidence file records the code the
+    // process actually exits with. Order matches the NOTE lines printed below.
+    let exitCode = v.exitCode;
+    if (!cov.ok || crudDefect || crDefect || liDefect)
+        exitCode = 1;
+    // CR-2 abstaining (an unparsable file) is never a pass.
+    if (exitCode === 0 && liResult.state === "could-not-judge")
+        exitCode = 2;
+    // MECHANICAL VIOLATIONS — the deploy gate's only refusal driver. The class of
+    // each rule is DATA (fixtures/rule-classes-<pin>.json, cross-checked against the
+    // pinned standard in src/rule-class.ts). Instrument self-defects and an
+    // unclassified rule make the count null (could-not-judge), never 0.
+    const convexPath = scope.convexDir ?? target;
+    const repoOfConvex = scope.convexDir
+        ? dirname(scope.convexDir)
+        : scope.repoRoot;
+    const instrumentDefects = [];
+    if (!cov.ok)
+        instrumentDefects.push(coverageSummary(cov));
+    if (crudDefect)
+        instrumentDefects.push("CRUD coverage self-check failed (rows do not cover every schema table, or the schema is unreadable)");
+    // CR1_ID is the detector's full label; its rule id is the leading `CR-N` token.
+    const cr1Rule = /^CR-\d+/.exec(CR1_ID)?.[0] ?? CR1_ID;
+    const cr2Rule = /^CR-\d+/.exec(CR2_ID)?.[0] ?? CR2_ID;
+    const classification = classifyRules([...deriveRuleIds(), cr1Rule, cr2Rule]);
+    const ruleStates = new Map(t.ruleState);
+    ruleStates.set(cr1Rule, crResult.state);
+    ruleStates.set(cr2Rule, liResult.state);
+    const evidencePath = args.flags["json-evidence"];
+    let evidenceSha;
+    if (evidencePath !== undefined) {
+        evidenceSha = gitOut(repoOfConvex, ["rev-parse", "HEAD"]);
+        const dirty = gitOut(convexPath, [
+            "status",
+            "--porcelain",
+            "--untracked-files=all",
+            "--",
+            ".",
+        ]);
+        if (evidenceSha !== undefined && dirty === undefined)
+            instrumentDefects.push(`git status of ${convexPath} failed — whether the judged tree equals HEAD cannot be shown`);
+        else if (dirty)
+            instrumentDefects.push(`the judged convex tree differs from HEAD ${evidenceSha?.slice(0, 12)} (${dirty.split("\n").length} path(s) modified or untracked) — the count would describe bytes the sha does not name`);
+    }
+    const mech = countMechanical(ruleStates, classification, instrumentDefects);
+    if (mech.count === null && exitCode === 0)
+        exitCode = 2;
+    console.log(mechanicalLine(mech));
+    // Per red mechanical rule, the count its report line printed — read from the
+    // result the detector returned (src/violation-count.ts), never from the text.
+    const ruleCounts = mechanicalRuleCounts([...results, crResult, liResult], mech);
+    console.log(mechanicalRuleCountsLine(ruleCounts));
+    if (classification.stale.length > 0) {
+        console.log(`  STALE SIDECAR ENTRIES (name no rule of this run): ${classification.stale.join(", ")}`);
     }
     // The run WRITES its report to a FILE, ALWAYS — not behind a flag. The clock and
     // the git facts are gathered HERE (a real process) and handed to the pure writer.
@@ -292,26 +407,60 @@ function main() {
     const reportDir = join(here, "..", "reports");
     const path = writeReport(ctx, results, t, v, reportDir, undefined, [
         callerResolutionSection(crScan),
+        localIdentitySection(liScan),
+        mechanicalLine(mech),
+        mechanicalRuleCountsLine(ruleCounts),
     ]);
     console.log(`\nreport written: ${path}`);
+    // The deploy-gate evidence, keyed to the sha of the repository holding the
+    // judged convex dir. No sha, no file: evidence that names no commit certifies
+    // nothing, so the run refuses (exit 2) rather than write one.
+    if (evidencePath !== undefined) {
+        if (evidenceSha === undefined) {
+            console.error(`backend-doctor: --json-evidence REFUSED — \`git -C ${repoOfConvex} rev-parse HEAD\` failed, so the evidence would name no commit. No evidence file written.`);
+            process.exit(2);
+        }
+        const evidence = buildEvidence({
+            sha: evidenceSha,
+            cli_commit: cliCommit(),
+            convex_path: convexPath,
+            exit_code: exitCode,
+            checked: cov.checked.length,
+            total: cov.ruleIds.length,
+            mechanical_violations: mech.count,
+            mechanical_rule_counts: ruleCounts.counts,
+            mechanical_rule_module_counts: ruleCounts.moduleCounts,
+        });
+        let out = resolve(evidencePath);
+        // A trailing slash names a directory even before it exists.
+        if (/[/\\]$/.test(evidencePath))
+            mkdirSync(out, { recursive: true });
+        if (existsSync(out) && statSync(out).isDirectory())
+            out = join(out, `backend-doctor-${evidenceSha}.json`);
+        else
+            mkdirSync(dirname(out), { recursive: true });
+        writeFileSync(out, `${JSON.stringify(evidence, null, 2)}\n`);
+        console.log(`evidence written: ${out}`);
+    }
     if (!cov.ok) {
         console.log("\nNOTE: coverage is INCOMPLETE — a rule is in neither bucket. See the summary above.");
-        process.exit(1);
     }
-    // The CRUD coverage self-check is fail-closed: an unreadable schema or a rows
-    // union that does not cover the schema tables is a DOCTOR DEFECT → RED, never a
-    // silent pass. (ABSENT cells are honest reported gaps, NOT a defect.)
-    if (crudDefect) {
+    else if (crudDefect) {
+        // The CRUD coverage self-check is fail-closed: an unreadable schema or a rows
+        // union that does not cover the schema tables is a DOCTOR DEFECT → RED, never a
+        // silent pass. (ABSENT cells are honest reported gaps, NOT a defect.)
         console.log("\nNOTE: CRUD coverage self-check FAILED — the rows do not cover every schema table (or the schema is unreadable). See the CRUD COVERAGE section above.");
-        process.exit(1);
     }
-    // CR-1 is CRITICAL: a FAIL-OPEN or unjustified NO-IDENTITY public registration is
-    // a mechanical violation, so the gate refuses on it even when every numbered rule
-    // is satisfied. Reported BEFORE the numbered-rule exit so the reason is legible.
-    if (crDefect) {
+    else if (crDefect) {
+        // CR-1 is CRITICAL: a FAIL-OPEN or unjustified NO-IDENTITY public registration
+        // is a mechanical violation, so the gate refuses on it even when every numbered
+        // rule is satisfied.
         console.log(`\nNOTE: CR-1 (caller resolution) FAILED — ${crViolations(crScan).length} public registration(s) serve or write data without resolving their caller. CRITICAL, no bypass. See the CALLER RESOLUTION section above; every member is named there.`);
-        process.exit(1);
     }
-    process.exit(v.exitCode);
+    if (liDefect) {
+        // Reported independently of the NOTE chain above: CR-2 is its own gate.
+        console.log(`\nNOTE: CR-2 (local identity) FAILED — ${liScan.violate.length} site(s) define a local identity primitive instead of calling @vantageos/cloud-identity. Ceiling 0. See the LOCAL IDENTITY section above; every site is named there.`);
+    }
+    process.exit(exitCode);
 }
 main();

package/dist/contract.d.ts

@@ -1,4 +1,4 @@
-import type { OracleColumn } from "./oracle.js";
+import { type OracleColumn, type WriterTierTable } from "./oracle.js";
 export interface ContractField {
     /** the §2 contract field name. */
     field: string;
@@ -9,10 +9,28 @@ export interface ContractField {
 }
 /** The thirteen §2 contract fields (R-38 completeness gate operates on this). */
 export declare const CONTRACT_FIELDS: ContractField[];
-/** The two §2 fields that MUST be two distinct columns — reader and writer
- * authority. The oracle merges both onto `rbac_qui`: the structural defect. */
+/** Reader authority (R-5) lives in the oracle's own `rbac_qui` column. */
 export declare const READER_AUTHORITY_COLUMN: OracleColumn;
-export declare const WRITER_AUTHORITY_COLUMN: OracleColumn;
-/** True when reader and writer authority resolve to the SAME column — the
- * merged-authority non-conformance R-14 names by construction. */
-export declare function authorityIsMerged(): boolean;
+/** Without a side-car, writer authority (R-10) can only fall back to the SAME
+ * column — the merge §12 calls non-conforming by construction. */
+export declare const MERGED_WRITER_AUTHORITY_COLUMN: OracleColumn;
+/** The side-car column that carries writer authority apart from `rbac_qui`. */
+export declare const SPLIT_WRITER_AUTHORITY_COLUMN: "writer_tier";
+export type AuthoritySplit = {
+    kind: "split";
+    sideCar: string;
+    writeTools: number;
+} | {
+    kind: "merged";
+    reason: string;
+    uncovered: string[];
+} | {
+    kind: "unjudgeable";
+    reason: string;
+};
+/**
+ * Resolve where writer authority lives for this oracle.
+ * @param writeTools the `outil` of every inventory row whose verb writes.
+ * @param sideCar the bound writer-tier side-car.
+ */
+export declare function resolveAuthoritySplit(writeTools: readonly string[], sideCar: WriterTierTable): AuthoritySplit;

package/dist/contract.js

@@ -1,8 +1,20 @@
+// The §2 per-table contract, transcribed from the pinned standard
+// (backend-standard.md @ a9d7877b, read by command — never from memory).
+//
+// §2 splits authority into TWO distinct contract fields — reader authority (R-5)
+// and writer authority (R-10). The oracle's eighteen columns carry ONE authority
+// column, `rbac_qui`. An oracle alone is therefore merged, and R-14 calls a merged
+// authority column "non-conforming by construction". An oracle declares the split
+// through its writer-tier side-car (see resolveAuthoritySplit below).
+import { basename } from "node:path";
+import { WRITER_TIER_NAME } from "./oracle.js";
 /** The thirteen §2 contract fields (R-38 completeness gate operates on this). */
 export const CONTRACT_FIELDS = [
     { field: "exposure", columns: ["surface"], rule: "R-1" },
     { field: "operation verb", columns: ["crud"], rule: "R-2" },
     { field: "reader authority", columns: ["rbac_qui"], rule: "R-5" },
+    // §2's table maps writer authority onto `rbac_qui` too; that mapping IS the
+    // merge. The split column is the side-car's `writer_tier` (resolveAuthoritySplit).
     { field: "writer authority", columns: ["rbac_qui"], rule: "R-10" },
     { field: "retrieval mechanism", columns: ["search_mecanisme"], rule: "R-4" },
     { field: "pagination", columns: ["search_mecanisme"], rule: "R-3" },
@@ -18,12 +30,45 @@ export const CONTRACT_FIELDS = [
         rule: "R-13/R-27",
     },
 ];
-/** The two §2 fields that MUST be two distinct columns — reader and writer
- * authority. The oracle merges both onto `rbac_qui`: the structural defect. */
+/** Reader authority (R-5) lives in the oracle's own `rbac_qui` column. */
 export const READER_AUTHORITY_COLUMN = "rbac_qui";
-export const WRITER_AUTHORITY_COLUMN = "rbac_qui";
-/** True when reader and writer authority resolve to the SAME column — the
- * merged-authority non-conformance R-14 names by construction. */
-export function authorityIsMerged() {
-    return READER_AUTHORITY_COLUMN === WRITER_AUTHORITY_COLUMN;
+/** Without a side-car, writer authority (R-10) can only fall back to the SAME
+ * column — the merge §12 calls non-conforming by construction. */
+export const MERGED_WRITER_AUTHORITY_COLUMN = "rbac_qui";
+/** The side-car column that carries writer authority apart from `rbac_qui`. */
+export const SPLIT_WRITER_AUTHORITY_COLUMN = "writer_tier";
+const UNKNOWN_WRITER_TIER = new Set(["", "?", "unknown", "n/a", "tbd"]);
+/**
+ * Resolve where writer authority lives for this oracle.
+ * @param writeTools the `outil` of every inventory row whose verb writes.
+ * @param sideCar the bound writer-tier side-car.
+ */
+export function resolveAuthoritySplit(writeTools, sideCar) {
+    if (sideCar.status === "absent") {
+        return {
+            kind: "merged",
+            reason: `writer-tier side-car ${WRITER_TIER_NAME} ABSENT (${sideCar.origin}; searched: ${sideCar.searched.join(", ") || "<none>"}), so writer authority has no column of its own`,
+            uncovered: [],
+        };
+    }
+    if (sideCar.status === "unreadable") {
+        return {
+            kind: "unjudgeable",
+            reason: `writer-tier side-car ${sideCar.path} unreadable — ${sideCar.reason}; whether \`${SPLIT_WRITER_AUTHORITY_COLUMN}\` declares writer authority cannot be read`,
+        };
+    }
+    const tools = [...new Set(writeTools)];
+    const uncovered = tools.filter((t) => {
+        const entries = sideCar.byTool.get(t) ?? [];
+        return !entries.some((e) => !UNKNOWN_WRITER_TIER.has(e.writer_tier.trim().toLowerCase()));
+    });
+    const file = basename(sideCar.path);
+    if (uncovered.length > 0) {
+        return {
+            kind: "merged",
+            reason: `${file} records no \`${SPLIT_WRITER_AUTHORITY_COLUMN}\` for ${uncovered.length} write tool(s) of ${tools.length} (${uncovered.join(", ")}), so for those tools writer authority is omitted`,
+            uncovered,
+        };
+    }
+    return { kind: "split", sideCar: file, writeTools: tools.length };
 }

package/dist/coverage.d.ts

@@ -4,7 +4,7 @@
  * canonical 48-rule standard (51ec7af1) to 2bb402f7, which closes R-7/R-8/R-37/R-40
  * as a written-justification-token control (§23) — the paired standard PR the four
  * decisive detectors below track. Still 48 rules; the pin moves forward with them. */
-export declare const STANDARD_SHA = "4bcd605656ceff52d4f1593a9176cd6b988471be";
+export declare const STANDARD_SHA = "2825122a3ab1e4ddb4b955cfb136b7e8ab04f8f3";
 export declare const VENDORED_STANDARD_PATH: string;
 /**
  * Derive the full rule list R-1..R-42 from the VENDORED standard fixture —

package/dist/coverage.js

@@ -18,8 +18,8 @@ const here = dirname(fileURLToPath(import.meta.url));
  * canonical 48-rule standard (51ec7af1) to 2bb402f7, which closes R-7/R-8/R-37/R-40
  * as a written-justification-token control (§23) — the paired standard PR the four
  * decisive detectors below track. Still 48 rules; the pin moves forward with them. */
-export const STANDARD_SHA = "4bcd605656ceff52d4f1593a9176cd6b988471be";
-export const VENDORED_STANDARD_PATH = join(here, "..", "fixtures", "backend-standard-4bcd605.md");
+export const STANDARD_SHA = "2825122a3ab1e4ddb4b955cfb136b7e8ab04f8f3";
+export const VENDORED_STANDARD_PATH = join(here, "..", "fixtures", "backend-standard-2825122.md");
 /**
  * Derive the full rule list R-1..R-42 from the VENDORED standard fixture —
  * never typed, never a git show against a local repo. Reads the `**R-NN`

package/dist/detectors/oracle-axis1.js

@@ -20,7 +20,8 @@
 import { readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ORACLE_COLUMNS, parseCsv, activeOracle, oracleLabel, readOracle, refuseWithoutOracle, requireVrOracle, } from "../oracle.js";
+import { activeOracle, ORACLE_COLUMNS, oracleLabel, parseCsv, readOracle, refuseWithoutOracle, requireVrOracle, } from "../oracle.js";
+import { itemCount, withCount } from "../violation-count.js";
 const here = dirname(fileURLToPath(import.meta.url));
 /** The vendored day159 SECOND-backend (VantageRegistry) snapshot — a FIXTURE for
  * this tool's tests, never a default (see oracle.ts resolveOracle).
@@ -30,7 +31,7 @@ export const FIXTURE_VR_ORACLE_PATH = join(here, "..", "..", "fixtures", "vr-by-
  * §2 [shared] contract columns are DERIVED from this file, never hardcoded.
  * Defined locally (not imported from coverage.ts) to avoid a registry ↔ coverage
  * import cycle. */
-export const VENDORED_STANDARD_PATH = join(here, "..", "..", "fixtures", "backend-standard-4bcd605.md");
+export const VENDORED_STANDARD_PATH = join(here, "..", "..", "fixtures", "backend-standard-2825122.md");
 /** Load any backend inventory CSV generically from its OWN header — the shared
  * fields are DERIVED from these real headers, never a prose illustration. */
 export function loadInventory(path) {
@@ -217,12 +218,12 @@ export function makeR40(vpProvider = readOracle, vrProvider = readVrInventory) {
             })
                 .join("; ");
             const reason = `R-40: ${sites.length} shared field(s) diverge BETWEEN VP and VR on their closed vocabulary — the mechanical compare names WHICH FIELD and WHICH value on VP vs VR, and none carries a written between-backend justification; non-conforming until each divergence is reconciled or carries a recorded justification. ${schemaFinding} ${breakdown} Field sites: ${examples}.`;
-            return {
+            return withCount({
                 id: R40_ID,
                 anchor: `${r40Anchor()} field=${sites[0]?.field ?? "schema"}`,
                 state: "non-conforming",
                 verdict: reason,
-            };
+            }, itemCount(sites.length));
         }),
     };
 }