@vantageos/backend-doctor 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# backend-doctor
+
+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.
+
+## What it checks — every rule, one bucket, derived not typed
+
+Every mechanical rule of the standard carries an executable control. There is **no deferral bucket**: a rule is either CHECKED, or NOT_MECHANICALLY_CHECKABLE named with a written reason (never silently dropped). The rule count is **whatever the pinned fixture derives** — it is not typed in this README, because a typed count is stale the moment the pin moves (a rule with no detector yet must show as not-checkable against the true denominator, not vanish under a smaller one). Read the live coverage from the tool, never from prose:
+
+```bash
+# the coverage proof — prints "<N> CHECKED + <M> NOT_MECHANICALLY_CHECKABLE = <N+M> of <N+M>"
+# and exits 1 on any gap. This line, not this README, is the count.
+npx --yes @vantageos/backend-doctor@<version> --coverage   # or, from a checkout: npx tsx src/coverage-cli.ts
+```
+
+The detectors read four kinds of material, each a **comparison target, never an authority**:
+
+| 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 |
+| 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
+
+A rule whose control has a **mechanical detection half and a human/gate half** does not report `present` ("held") or `absent` ("N/A") while its subject exists in the material. It runs the mechanical half **in full** and returns `could-not-judge` naming the concrete sites a human or delivery-gate verdict is owed on — a **work list** where there was silence. Green is the human half surfaced per site, never the detection merely running.
+
+## Run it
+
+backend-doctor is its **own tool** (own package `@vantageos/backend-doctor`, own `bin`), like `react-doctor` / `mcp-doctor`. The **supported** invocation is the published, scoped package — so the instrument that judged is the instrument named, and every station runs the same pinned version without cloning:
+
+```bash
+npx --yes @vantageos/backend-doctor@<version> <path-to-a-convex-backend>
+```
+
+Do not type a stale version as the only pin — read the current one from the registry, never from this README:
+
+```bash
+npm view @vantageos/backend-doctor version                 # the current published version
+npx --yes @vantageos/backend-doctor@$(npm view @vantageos/backend-doctor version) <path-to-a-convex-backend>
+```
+
+Until the scoped package is first published (`npm view @vantageos/backend-doctor` returns 404 until then), the `npx @vantageos/…` form above cannot resolve — run from a checkout (below) in the meantime. Once published, the scoped package is the supported path from that version onward.
+
+For **development of the doctor itself**, or to run it before the package is published (not the long-term supported path), from a checkout:
+
+```bash
+npm ci && npm run build
+node dist/cli.js <path-to-a-convex-backend>       # the bin; the live verdict + named sites + tally
+npx tsx src/cli.ts <path-to-a-convex-backend>     # same, straight from source
+npx tsx src/coverage-cli.ts                       # the coverage proof; exits 1 on any gap
+npm test                                          # the detector suite (RED-first, both poles, mutation bite proofs)
+npx tsc --noEmit
+```
+
+### 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.
+
+It then prints a **severity-mapped verdict** in react-doctor's shape. Each rule's severity is **derived** from the standard's §13 objectives table (never hardcoded):
+
+| objective tag (§13) | severity |
+|---|---|
+| `multi-organisation multi-tenant` (tenant-boundary) | **critical** |
+| `highly secure` (without multi-tenant) | major-high |
+| `enterprise-grade` / `production-ready` | major |
+| `token-efficient` only | minor |
+
+Verdict mapping, computed from the tally (major = major-high + major):
+
+- 0 critical + 0 major violations → **approve** (exit 0)
+- 0 critical + 1..5 major violations → **revise recommended**
+- 0 critical + >5 major violations → **revise mandatory**
+- ≥1 critical violation → **revise mandatory, no bypass**
+
+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.
+
+## 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-51ec7af1.md` (48 rules, 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.
+
+## Discipline (how a detector is proven)
+
+Every detector is written RED-first against the **real** material (never the standard's prose illustration — the false-green law), proven to **bite** by a mutation injected on material it did not choose and grep-asserted as landed on an executing line before any verdict is read, and proven at **both poles** (a conforming site must pass; a detector that only ever fires is as broken as one that never does). Cross-document rules additionally carry a positive control per document so an unlisted identifier prefix cannot manufacture mass false positives.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// backend-doctor CLI. Runs the registry THROUGH the engine's runDoctor (reusing
+// its loud-fail trustworthiness contract), renders the results with the engine's
+// renderTable, then prints the coverage summary + the two non-checked lists
+// 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 { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runDoctor, renderTable } from "@vantageos/mcp-doctor";
+import { REGISTRY } from "./registry.js";
+import { coverage, coverageSummary } from "./coverage.js";
+import { NOT_MECHANICALLY_CHECKABLE, notCheckableResults } from "./not-checkable.js";
+import { tally, tallyLine, verdict } from "./tally.js";
+import { writeReport } from "./report.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) {
+    try {
+        return execFileSync("git", ["-C", target, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+    }
+    catch {
+        return "not a git repo";
+    }
+}
+/** Untracked INCLUDED — the short porcelain form is not a clean-tree check. */
+function treeStatus(target) {
+    try {
+        return execFileSync("git", ["-C", target, "status", "--porcelain", "--untracked-files=all"], {
+            encoding: "utf8",
+        }).trim();
+    }
+    catch {
+        return "not a git repo";
+    }
+}
+function toolVersion() {
+    const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+    return pkg.version;
+}
+function main() {
+    const target = resolve(process.argv[2] ?? process.cwd());
+    // Every derived rule carries EXACTLY ONE result: the executable detectors plus
+    // one could-not-judge abstention per NOT_MECHANICALLY_CHECKABLE rule (R-48's
+    // pending detector) — so the tally's rule total equals the 48 derived rules and
+    // nothing is silently dropped.
+    const results = [
+        ...runDoctor(target, REGISTRY.map((e) => e.detector)),
+        ...notCheckableResults(),
+    ];
+    console.log(renderTable("backend-doctor (VantagePeers oracle @ day158)", results));
+    console.log("");
+    const cov = coverage();
+    console.log(coverageSummary(cov));
+    console.log("");
+    console.log(`NOT MECHANICALLY CHECKABLE (${cov.notCheckable.length}) — a human decides, or it governs a document; NOT a clean bill:`);
+    for (const id of cov.notCheckable) {
+        console.log(`  ${id} — ${NOT_MECHANICALLY_CHECKABLE[id]}`);
+    }
+    // D6: the machine TALLY + the severity-mapped VERDICT. The distribution is
+    // DERIVED here (no human counts rows) and the verdict maps to a TRUTHFUL exit
+    // code — >=1 critical or a hard violation exits 1, a human-verdict-owed
+    // abstention exits 2, approve exits 0. See src/tally.ts + src/severity.ts.
+    const t = tally(results);
+    const v = verdict(t, results);
+    console.log("");
+    console.log(tallyLine(t));
+    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(", ")}`);
+    }
+    // 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.
+    const ctx = {
+        target,
+        targetCommit: targetCommit(target),
+        toolVersion: toolVersion(),
+        dateISO: new Date().toISOString().slice(0, 10),
+        treeStatus: treeStatus(target),
+    };
+    const reportDir = join(here, "..", "reports");
+    const path = writeReport(ctx, results, t, v, reportDir);
+    console.log(`\nreport written: ${path}`);
+    if (!cov.ok) {
+        console.log("\nNOTE: coverage is INCOMPLETE — a rule is in neither bucket. See the summary above.");
+        process.exit(1);
+    }
+    process.exit(v.exitCode);
+}
+main();

package/dist/contract.d.ts

@@ -0,0 +1,18 @@
+import type { OracleColumn } from "./oracle.js";
+export interface ContractField {
+    /** the §2 contract field name. */
+    field: string;
+    /** the audit column(s) §2 maps it onto. */
+    columns: OracleColumn[];
+    /** the rule the field carries. */
+    rule: string;
+}
+/** 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. */
+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;

package/dist/contract.js

@@ -0,0 +1,29 @@
+/** 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" },
+    { 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" },
+    { field: "isolation locus", columns: ["scope_enforcement"], rule: "R-11" },
+    { field: "boundary key", columns: ["namespace_ou_org"], rule: "R-6" },
+    { field: "read/write coherence", columns: ["rbac_coherence_table"], rule: "R-7" },
+    { field: "vector boundary", columns: ["search_mecanisme"], rule: "R-12" },
+    { field: "token cost", columns: ["tokens_estime_contexte"], rule: "R-9" },
+    { field: "remediation", columns: ["rbac_adjustment_needed"], rule: "R-28" },
+    {
+        field: "disposition & lifecycle",
+        columns: ["table_purpose", "table_conserver_supprimer", "statut_suppression"],
+        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. */
+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;
+}

package/dist/coverage-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/coverage-cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// Prints the coverage proof over the TWO buckets — CHECKED and
+// NOT_MECHANICALLY_CHECKABLE. Exits non-zero only if the union does not equal
+// the derived rule ids (a rule in no bucket, in two, or a stale bucket entry).
+import { coverage, coverageSummary } from "./coverage.js";
+import { NOT_MECHANICALLY_CHECKABLE } from "./not-checkable.js";
+const r = coverage();
+console.log(coverageSummary(r));
+console.log("");
+console.log(`CHECKED (${r.checked.length}): ${r.checked.join(" ")}`);
+console.log("");
+console.log(`NOT MECHANICALLY CHECKABLE (${r.notCheckable.length}) — a human decides, or it governs a document, not backend data:`);
+for (const id of r.notCheckable)
+    console.log(`  ${id} — ${NOT_MECHANICALLY_CHECKABLE[id]}`);
+console.log("");
+console.log(`derived rule ids (${r.ruleIds.length}): ${r.ruleIds.join(" ")}`);
+process.exit(r.ok ? 0 : 1);

package/dist/coverage.d.ts

@@ -0,0 +1,32 @@
+/** The standard is VENDORED at the pin as a fixture — DATA at 51ec7af1, a
+ * comparison target on the same footing as the oracle CSV. deriveRuleIds no
+ * longer shells out to any local repo, so it is CI-portable. Re-pinned from the
+ * stale 47-rule freeze (a9d7877b) to the canonical 48-rule standard (adds R-48,
+ * authority-totality) so coverage cannot pretend 47 is the whole document. */
+export declare const STANDARD_SHA = "51ec7af1bc84239aefd751d16389c65af6082c9f";
+export declare const VENDORED_STANDARD_PATH: string;
+/**
+ * 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`
+ * rule-definition headers from the file at the pin.
+ */
+export declare function deriveRuleIds(path?: string): string[];
+export interface CoverageReport {
+    ok: boolean;
+    ruleIds: string[];
+    checked: string[];
+    notCheckable: string[];
+    /** rules in NO bucket — the failure that names an incomplete doctor. */
+    uncovered: string[];
+    /** rules in MORE THAN ONE bucket — a rule cannot be two things at once. */
+    doubleCovered: string[];
+    /** bucket entries that are not a derived rule id — a stale bucket. */
+    unknown: string[];
+}
+/**
+ * Compute coverage over the three buckets. All inputs are injectable so a test
+ * can add a phantom uncovered rule and assert the mechanism fails.
+ */
+export declare function coverage(ruleIds?: string[], checked?: string[], notCheckable?: string[]): CoverageReport;
+/** A one-line assertion string naming any gap — used by the CLI and tests. */
+export declare function coverageSummary(r: CoverageReport): string;

package/dist/coverage.js

@@ -0,0 +1,77 @@
+// The coverage acceptance mechanism. Every rule derived from the pinned standard
+// is in EXACTLY ONE of TWO buckets: CHECKED (a registry entry tags it) or
+// NOT_MECHANICALLY_CHECKABLE (a human decides / governs a document). Their union
+// MUST equal the derived rule ids — none in two, none in neither.
+//
+// This is the assertion that stops backend-doctor silently becoming an
+// INCOMPLETE doctor when a rule is later added. There is no third bucket: a rule
+// a machine can decide is BUILT, not curated on a debt list.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { NOT_MECHANICALLY_CHECKABLE } from "./not-checkable.js";
+import { checkedRuleIds } from "./registry.js";
+const here = dirname(fileURLToPath(import.meta.url));
+/** The standard is VENDORED at the pin as a fixture — DATA at 51ec7af1, a
+ * comparison target on the same footing as the oracle CSV. deriveRuleIds no
+ * longer shells out to any local repo, so it is CI-portable. Re-pinned from the
+ * stale 47-rule freeze (a9d7877b) to the canonical 48-rule standard (adds R-48,
+ * authority-totality) so coverage cannot pretend 47 is the whole document. */
+export const STANDARD_SHA = "51ec7af1bc84239aefd751d16389c65af6082c9f";
+export const VENDORED_STANDARD_PATH = join(here, "..", "fixtures", "backend-standard-51ec7af1.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`
+ * rule-definition headers from the file at the pin.
+ */
+export function deriveRuleIds(path = VENDORED_STANDARD_PATH) {
+    const blob = readFileSync(path, "utf8");
+    const ids = new Set();
+    for (const line of blob.split("\n")) {
+        const m = /^\*\*(R-[0-9]+)/.exec(line);
+        if (m)
+            ids.add(m[1]);
+    }
+    return [...ids].sort((a, b) => Number(a.slice(2)) - Number(b.slice(2)));
+}
+function sortIds(ids) {
+    return [...new Set(ids)].sort((a, b) => Number(a.slice(2)) - Number(b.slice(2)));
+}
+/**
+ * Compute coverage over the three buckets. All inputs are injectable so a test
+ * can add a phantom uncovered rule and assert the mechanism fails.
+ */
+export function coverage(ruleIds = deriveRuleIds(), checked = checkedRuleIds(), notCheckable = Object.keys(NOT_MECHANICALLY_CHECKABLE)) {
+    const buckets = [checked, notCheckable];
+    const ruleSet = new Set(ruleIds);
+    const countIn = (r) => buckets.filter((b) => b.includes(r)).length;
+    const uncovered = ruleIds.filter((r) => countIn(r) === 0);
+    const doubleCovered = ruleIds.filter((r) => countIn(r) > 1);
+    const unknown = buckets.flat().filter((r) => !ruleSet.has(r));
+    return {
+        ok: uncovered.length === 0 &&
+            doubleCovered.length === 0 &&
+            unknown.length === 0,
+        ruleIds,
+        checked: sortIds(checked),
+        notCheckable: sortIds(notCheckable),
+        uncovered,
+        doubleCovered,
+        unknown,
+    };
+}
+/** A one-line assertion string naming any gap — used by the CLI and tests. */
+export function coverageSummary(r) {
+    const total = r.checked.length + r.notCheckable.length;
+    const head = `coverage: ${r.checked.length} CHECKED + ${r.notCheckable.length} NOT_MECHANICALLY_CHECKABLE = ${total} of ${r.ruleIds.length} derived rules`;
+    if (r.ok)
+        return `${head} — COMPLETE (no gap).`;
+    const gaps = [];
+    if (r.uncovered.length)
+        gaps.push(`UNCOVERED (in no bucket): ${r.uncovered.join(", ")}`);
+    if (r.doubleCovered.length)
+        gaps.push(`DOUBLE-COVERED (in >1 bucket): ${r.doubleCovered.join(", ")}`);
+    if (r.unknown.length)
+        gaps.push(`UNKNOWN (not a derived rule): ${r.unknown.join(", ")}`);
+    return `${head} — INCOMPLETE. ${gaps.join(" | ")}`;
+}

package/dist/detectors/oracle-axis1.d.ts

@@ -0,0 +1,86 @@
+import type { Detector } from "../engine-types.js";
+import { type OracleRow } from "../oracle.js";
+/** Absolute path to the pinned SECOND-backend (VantageRegistry) oracle fixture.
+ * Vendored at pin a74a042b, blob b53e2626954a887303d11d944b6132a11dbd34f6. */
+export declare const VR_ORACLE_PATH: string;
+/** The vendored standard (the R-5 law) — the SAME pin coverage.ts parses. The
+ * §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 declare const VENDORED_STANDARD_PATH: string;
+/** A backend inventory: its real header (in file order) + typed rows. Loaded the
+ * SAME way as the VP oracle — parseCsv, drop header, key cells by column name. */
+export interface Inventory {
+    /** the file's REAL column headers, never hardcoded. */
+    header: string[];
+    /** column-name → trimmed value, one entry per data row. */
+    rows: Record<string, string>[];
+}
+/** Load any backend inventory CSV generically from its OWN header — the shared
+ * fields are DERIVED from these real headers, never a prose illustration. */
+export declare function loadInventory(path: string): Inventory;
+/** Memoized read of the pinned VR inventory. */
+export declare function readVrInventory(): Inventory;
+/** The VP inventory, adapted from the memoized VP oracle reader — the SAME rows
+ * the axis-2 detectors read, exposed with VP's real header. */
+export declare function vpInventory(rowsProvider?: () => OracleRow[]): Inventory;
+/** The SHARED FIELDS: the columns present in BOTH backends' real headers —
+ * computed as the intersection, never hardcoded. Used for the STRUCTURAL
+ * (schema) compare; the VALUE compare is narrowed to the §2 [shared] contract
+ * columns (see `sharedContractColumns`). */
+export declare function sharedFields(vp: string[], vr: string[]): string[];
+/** The §2 CONTRACT columns the standard marks **[shared]** — DERIVED by parsing
+ * the vendored standard's §2 table (the R-5 law), never hardcoded. A [shared]
+ * row binds a contract field to its `audit column`, wrapped in backticks in the
+ * table's second cell. The five [shared] fields (operation verb, reader
+ * authority, writer authority, retrieval mechanism, pagination) resolve to the
+ * three audit columns `crud`, `rbac_qui`, `search_mecanisme` — reader/writer
+ * authority both live in the single merged `rbac_qui` (itself the R-14 defect),
+ * and retrieval mechanism + pagination both live in `search_mecanisme`.
+ *
+ * The R-40 VALUE compare runs ONLY over these closed-vocabulary columns. Free
+ * identifiers — `table`, `outil` (row identity) and `T2_verdict`,
+ * `T2_composant_cible` (audit bookkeeping) — are NOT vocabularies and are NEVER
+ * sited: comparing them counts row-identity noise as divergence and buries the
+ * one finding R-40 exists to catch. */
+export declare function sharedContractColumns(standardPath?: string): string[];
+/** The STRUCTURAL (between-schema) divergence: a column one backend carries and
+ * the other lacks. `statut_suppression` (VP) vs absent (VR) is the R-14-class
+ * finding the compare must SURFACE, not silently drop. */
+export interface SchemaDivergence {
+    vpOnlyColumns: string[];
+    vrOnlyColumns: string[];
+}
+export declare function schemaDivergence(vp: string[], vr: string[]): SchemaDivergence;
+/** Per shared field, the closed vocabularies of the two backends compared:
+ * `shared` values BOTH populate (agreeing — NEVER a site), `vpOnly` / `vrOnly`
+ * values populated by exactly one backend (the between-backend divergence). */
+export interface FieldDivergence {
+    field: string;
+    shared: string[];
+    vpOnly: string[];
+    vrOnly: string[];
+}
+/** A field is a divergence SITE iff one backend fills it with a vocabulary
+ * member the other never uses. */
+export declare function isSite(d: FieldDivergence): boolean;
+/** Compare two inventories on each §2 [shared] contract field present in BOTH
+ * real headers. The scope is the CLOSED-VOCABULARY columns the standard marks
+ * [shared] (`crud`, `rbac_qui`, `search_mecanisme`) intersected with the two
+ * real headers — never all shared columns (that counts `table`/`outil`/`T2_*`
+ * free identifiers as vocabularies). Returns the per-field vocabulary comparison
+ * for every in-scope field (sites and agreeing fields alike) so a caller can
+ * prove BOTH poles: an agreeing value is not a site, a diverging value is. */
+export declare function compareFields(vp: Inventory, vr: Inventory): FieldDivergence[];
+/** The full Axis-1 comparison result: schema-level (column) divergence + the
+ * per-field vocabulary divergences. */
+export interface Axis1Comparison {
+    schema: SchemaDivergence;
+    fields: FieldDivergence[];
+    /** the shared-field sites — fields where a value diverges between backends. */
+    sites: FieldDivergence[];
+}
+export declare function compareBackends(vpProvider?: () => OracleRow[], vrProvider?: () => Inventory): Axis1Comparison;
+/** Wrap the Axis-1 compare into a Detector. Providers are injectable for tests;
+ * production reads the two memoized real oracles. */
+export declare function makeR40(vpProvider?: () => OracleRow[], vrProvider?: () => Inventory): Detector;