@vantageos/backend-doctor 0.1.0

package/dist/detectors/oracle-axis1.js

@@ -0,0 +1,221 @@
+// AXIS-1 between-backend divergence — R-40. §18: "two backends' shared field
+// compared (mechanical); a divergence's written justification sound (human)."
+// Prose (~line 570): two backends governed by this standard fill the same
+// contract field from the same closed vocabulary; a divergence between two
+// backends on a shared field publishes only with a WRITTEN JUSTIFICATION.
+// Axis-2 (divergence WITHIN one backend) is R-37; Axis-1 (BETWEEN two backends)
+// is R-40 — it fires the moment a second backend's inventory exists.
+//
+// This is a JUDGEMENT rule with a mechanical half. Like R-7/R-8/R-37 the
+// instrument performs the mechanical half IN FULL — it names every concrete
+// between-backend divergence site (which shared field, which value on VP vs
+// which on VR) — and returns `could-not-judge`: whether each divergence carries
+// a SOUND written justification is the human half. It never claims `present`
+// (a clean bill) nor `absent` (does-not-apply) while real divergences exist.
+//
+// Both inputs are IN HAND (VP oracle + VR oracle, both vendored + hash-checked),
+// so this is NOT the input-absent could-not-judge — it is the human-verdict-owed
+// state, the acceptance property of a comparative judgement rule.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ORACLE_COLUMNS, parseCsv, readOracle, } from "../oracle.js";
+const here = dirname(fileURLToPath(import.meta.url));
+/** Absolute path to the pinned SECOND-backend (VantageRegistry) oracle fixture.
+ * Vendored at pin a74a042b, blob b53e2626954a887303d11d944b6132a11dbd34f6. */
+export const VR_ORACLE_PATH = join(here, "..", "..", "fixtures", "vr-by-tool-day159.csv");
+/** 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 const VENDORED_STANDARD_PATH = join(here, "..", "..", "fixtures", "backend-standard-51ec7af1.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) {
+    const raw = parseCsv(readFileSync(path, "utf8")).filter((r) => !(r.length === 1 && r[0] === ""));
+    const header = (raw[0] ?? []).map((h) => h.trim());
+    const rows = raw.slice(1).map((cells) => {
+        const by = {};
+        header.forEach((h, i) => {
+            by[h] = (cells[i] ?? "").trim();
+        });
+        return by;
+    });
+    return { header, rows };
+}
+let vrCache = null;
+/** Memoized read of the pinned VR inventory. */
+export function readVrInventory() {
+    if (vrCache)
+        return vrCache;
+    vrCache = loadInventory(VR_ORACLE_PATH);
+    return vrCache;
+}
+/** 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 function vpInventory(rowsProvider = readOracle) {
+    return {
+        header: [...ORACLE_COLUMNS],
+        rows: rowsProvider()
+            .filter((r) => !r.malformed)
+            .map((r) => ({ ...r.by })),
+    };
+}
+/** A real inventory row — the audit's trailing `TOTAL` aggregate is not a tool. */
+function isInventoryEntry(by) {
+    if (by.table === "TOTAL")
+        return false;
+    if ((by.outil ?? "") === "" &&
+        (by.crud ?? "") === "" &&
+        (by.surface ?? "") === "")
+        return false;
+    return true;
+}
+/** a value that actually FILLS the field — a blank or `n/a` is an omission, not a
+ * populated vocabulary member, so it never sources a between-backend divergence. */
+function isFilled(v) {
+    const t = (v ?? "").trim().toLowerCase();
+    return t !== "" && t !== "n/a";
+}
+/** 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 function sharedFields(vp, vr) {
+    const vrSet = new Set(vr);
+    return vp.filter((c) => vrSet.has(c));
+}
+/** 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 function sharedContractColumns(standardPath = VENDORED_STANDARD_PATH) {
+    const text = readFileSync(standardPath, "utf8");
+    const cols = [];
+    for (const line of text.split("\n")) {
+        if (!line.trim().startsWith("|"))
+            continue;
+        const cells = line.split("|").map((c) => c.trim());
+        const contractCell = cells[1] ?? "";
+        if (!contractCell.includes("[shared]"))
+            continue;
+        const m = /`([^`]+)`/.exec(cells[2] ?? "");
+        if (m)
+            cols.push(m[1]);
+    }
+    return [...new Set(cols)];
+}
+export function schemaDivergence(vp, vr) {
+    const vpSet = new Set(vp);
+    const vrSet = new Set(vr);
+    return {
+        vpOnlyColumns: vp.filter((c) => !vrSet.has(c)),
+        vrOnlyColumns: vr.filter((c) => !vpSet.has(c)),
+    };
+}
+/** A field is a divergence SITE iff one backend fills it with a vocabulary
+ * member the other never uses. */
+export function isSite(d) {
+    return d.vpOnly.length > 0 || d.vrOnly.length > 0;
+}
+/** 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 function compareFields(vp, vr) {
+    const contract = new Set(sharedContractColumns());
+    const fields = sharedFields(vp.header, vr.header).filter((c) => contract.has(c));
+    const vpRows = vp.rows.filter(isInventoryEntry);
+    const vrRows = vr.rows.filter(isInventoryEntry);
+    return fields.map((field) => {
+        const vpVals = new Set(vpRows.map((r) => r[field]).filter((v) => v !== undefined && isFilled(v)));
+        const vrVals = new Set(vrRows.map((r) => r[field]).filter((v) => v !== undefined && isFilled(v)));
+        const shared = [...vpVals].filter((v) => vrVals.has(v)).sort();
+        const vpOnly = [...vpVals].filter((v) => !vrVals.has(v)).sort();
+        const vrOnly = [...vrVals].filter((v) => !vpVals.has(v)).sort();
+        return { field, shared, vpOnly, vrOnly };
+    });
+}
+export function compareBackends(vpProvider = readOracle, vrProvider = readVrInventory) {
+    const vp = vpInventory(vpProvider);
+    const vr = vrProvider();
+    const fields = compareFields(vp, vr);
+    return {
+        schema: schemaDivergence(vp.header, vr.header),
+        fields,
+        sites: fields.filter(isSite),
+    };
+}
+const R40_ID = "R-40 between-backend divergence";
+const R40_ANCHOR = "oracle:vp-by-tool-day158.csv vs oracle:vr-by-tool-day159.csv";
+/** Wrap the Axis-1 compare into a Detector. Providers are injectable for tests;
+ * production reads the two memoized real oracles. */
+export function makeR40(vpProvider = readOracle, vrProvider = readVrInventory) {
+    return {
+        id: R40_ID,
+        run: () => {
+            const cmp = compareBackends(vpProvider, vrProvider);
+            const { schema, sites } = cmp;
+            // the schema (column) divergence is itself a site — surfaced, never dropped.
+            const schemaBits = [];
+            if (schema.vpOnlyColumns.length)
+                schemaBits.push(`VP-only column(s): ${schema.vpOnlyColumns.join(", ")}`);
+            if (schema.vrOnlyColumns.length)
+                schemaBits.push(`VR-only column(s): ${schema.vrOnlyColumns.join(", ")}`);
+            const schemaFinding = schemaBits.length
+                ? `Between-schema divergence (R-14-class): ${schemaBits.join("; ")} — a shared field absent on one backend; a human must judge whether the schema difference is justified.`
+                : "No between-schema column divergence.";
+            const totalValueDivergences = sites.reduce((n, s) => n + s.vpOnly.length + s.vrOnly.length, 0);
+            const breakdown = `[shared-field-sites=${sites.length} value-divergences=${totalValueDivergences} schema-col-divergences=${schema.vpOnlyColumns.length + schema.vrOnlyColumns.length}]`;
+            if (sites.length === 0 && schemaBits.length === 0) {
+                // The two backends agree on every shared field's vocabulary — still not a
+                // clean bill: R-40's disposition (is each divergence justified?) is human,
+                // and here there is simply nothing owed. The instrument abstains rather
+                // than claim the rule held.
+                const reason = `R-40: the VP and VR inventories agree on every shared field's closed vocabulary and share every column; the mechanical between-backend compare is exhausted with no divergence. Confirming the contract is human. ${breakdown}`;
+                return {
+                    id: R40_ID,
+                    anchor: R40_ANCHOR,
+                    state: "could-not-judge",
+                    verdict: reason,
+                    reason,
+                };
+            }
+            const examples = sites
+                .slice(0, 5)
+                .map((s) => {
+                const vp = s.vpOnly
+                    .slice(0, 2)
+                    .map((v) => `"${v.slice(0, 28)}"`)
+                    .join(", ");
+                const vr = s.vrOnly
+                    .slice(0, 2)
+                    .map((v) => `"${v.slice(0, 28)}"`)
+                    .join(", ");
+                return `${s.field}: VP-only {${vp || "—"}} vs VR-only {${vr || "—"}}`;
+            })
+                .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; a human must judge whether each between-backend divergence carries a SOUND written justification. This is NOT a clean bill. ${schemaFinding} ${breakdown} Field sites: ${examples}.`;
+            return {
+                id: R40_ID,
+                anchor: `${R40_ANCHOR} field=${sites[0]?.field ?? "schema"}`,
+                state: "could-not-judge",
+                verdict: reason,
+                reason,
+            };
+        },
+    };
+}

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

@@ -0,0 +1,22 @@
+import type { Detector } from "../engine-types.js";
+import { type OracleRow } from "../oracle.js";
+import type { RulePredicate } from "./shared.js";
+export declare const r7: RulePredicate;
+export declare const r8: RulePredicate;
+export interface DivergenceSite {
+    table: string;
+    field: string;
+    toolA: string;
+    valA: string;
+    toolB: string;
+    valB: string;
+}
+/**
+ * Group the inventory rows by table and, per shared field, name ONE diverging
+ * filled pair (the two tools whose filled values differ). The `n/a` pseudo-table
+ * groups unrelated tools and has no per-table contract, so it is excluded.
+ */
+export declare function findDivergences(rows: OracleRow[]): DivergenceSite[];
+/** Wrap the filled-neighbour compare into a Detector. `rowsProvider` is
+ * injectable for tests; production reads the memoized real oracle. */
+export declare function makeR37(rowsProvider?: () => OracleRow[]): Detector;

package/dist/detectors/oracle-axis2.js

@@ -0,0 +1,149 @@
+import { isInventoryRow, readOracle, } from "../oracle.js";
+// ---- R-7 read/write coherence divergence (INCOHERENT* table-aggregate flag) -
+// §18: "`INCOHERENT*` flag (mechanical); divergence justified (human)". The
+// oracle's `rbac_coherence_table` carries the audit's table-aggregate coherence
+// verdict; 105 rows are flagged `INCOHERENT...` (Finding 6). MECHANICAL: find
+// every flagged row. HUMAN: whether each incoherence carries a written
+// justification. So a flagged row is `cnj` (a human verdict is owed on it),
+// never `violate` (which would usurp the human disposition) and never a pass.
+export const r7 = {
+    ruleId: "R-7",
+    id: "R-7 read/write coherence divergence",
+    check: "row carries an `INCOHERENT*` coherence flag (mechanical); whether the read/write divergence is justified is human",
+    classify: (r) => {
+        const v = r.by.rbac_coherence_table;
+        if (/^INCOHERENT/i.test(v))
+            return {
+                kind: "cnj",
+                note: `rbac_coherence_table="${v}" — a read/write incoherence; a human must record whether this divergence is justified or the tool corrected`,
+            };
+        if (/^COHERENT/i.test(v))
+            return { kind: "conform" };
+        return { kind: "na" }; // no coherence verdict recorded on this row (e.g. n/a)
+    },
+};
+// ---- R-8 zero scope check on a data op (empty / `AUCUN`) --------------------
+// §18: "empty/`AUCUN` + a data op (mechanical); justification sound (human)".
+// MATERIAL: 5 rows carry `scope_enforcement=AUCUN(public_no_scope_check)` while
+// performing a data op. MECHANICAL: find every such row. HUMAN: whether the
+// stateless (no-scope) justification is sound. A matched row is `cnj`.
+export const r8 = {
+    ruleId: "R-8",
+    id: "R-8 zero scope check on a data op",
+    check: "empty/`AUCUN` scope enforcement on a row carrying a data op (mechanical); whether the stateless justification is sound is human",
+    classify: (r) => {
+        const scope = r.by.scope_enforcement.trim();
+        const crud = r.by.crud.trim();
+        const hasDataOp = crud !== "" && crud.toLowerCase() !== "n/a";
+        if (!hasDataOp)
+            return { kind: "na" }; // no data op — R-8 does not apply
+        const noScope = scope === "" || /AUCUN/i.test(scope);
+        if (noScope)
+            return {
+                kind: "cnj",
+                note: `scope_enforcement="${scope || "<empty>"}" on a data op crud="${crud}" — no scope check; a human must judge whether the stateless justification is sound`,
+            };
+        return { kind: "conform" }; // a genuine scope check is recorded
+    },
+};
+// ---- R-37 per-table filled-neighbour divergence ----------------------------
+// §17.5 detector spec: "For each table, group its tool rows and, for every
+// shared contract field (§2: exposure, verb effect-class, reader/writer
+// authority, retrieval mechanism, isolation locus, boundary key), flag any two
+// tools whose FILLED values differ." MECHANICAL: the filled-neighbour compare,
+// naming WHICH TWO TOOLS diverge (the attribution R-7's lossy union label
+// cannot carry). HUMAN: whether each divergence's per-tool justification is
+// sound. §2 field → oracle column, using the ACTUAL column names.
+const SHARED_FIELDS = [
+    { field: "exposure", col: "surface" },
+    { field: "verb effect-class", col: "crud" },
+    { field: "reader/writer authority", col: "rbac_qui" },
+    { field: "retrieval mechanism", col: "search_mecanisme" },
+    { field: "isolation locus", col: "scope_enforcement" },
+    { field: "boundary key", col: "namespace_ou_org" },
+];
+/** a value that actually FILLS the field — a blank or `n/a` is an omission
+ * (R-38's concern), not a filled neighbour, so it never sources a divergence. */
+function isFilled(v) {
+    const t = v.trim().toLowerCase();
+    return t !== "" && t !== "n/a";
+}
+/**
+ * Group the inventory rows by table and, per shared field, name ONE diverging
+ * filled pair (the two tools whose filled values differ). The `n/a` pseudo-table
+ * groups unrelated tools and has no per-table contract, so it is excluded.
+ */
+export function findDivergences(rows) {
+    const inv = rows.filter(isInventoryRow);
+    const byTable = new Map();
+    for (const r of inv) {
+        const t = r.by.table;
+        if (t === "" || t === "n/a")
+            continue; // not a real per-table contract
+        const g = byTable.get(t);
+        if (g)
+            g.push(r);
+        else
+            byTable.set(t, [r]);
+    }
+    const sites = [];
+    for (const [table, group] of byTable) {
+        if (group.length < 2)
+            continue; // a single tool has no neighbour
+        for (const { field, col } of SHARED_FIELDS) {
+            const filled = group.filter((r) => isFilled(r.by[col]));
+            if (filled.length < 2)
+                continue;
+            const first = filled[0];
+            const neighbour = filled.find((r) => r.by[col] !== first.by[col]);
+            if (neighbour)
+                sites.push({
+                    table,
+                    field,
+                    toolA: first.by.outil,
+                    valA: first.by[col],
+                    toolB: neighbour.by.outil,
+                    valB: neighbour.by[col],
+                });
+        }
+    }
+    return sites;
+}
+const R37_ID = "R-37 filled-neighbour divergence";
+const R37_ANCHOR = "oracle:vp-by-tool-day158.csv";
+/** Wrap the filled-neighbour compare into a Detector. `rowsProvider` is
+ * injectable for tests; production reads the memoized real oracle. */
+export function makeR37(rowsProvider = readOracle) {
+    return {
+        id: R37_ID,
+        run: () => {
+            const sites = findDivergences(rowsProvider());
+            const tables = new Set(sites.map((s) => s.table));
+            const breakdown = `[filled-neighbour-divergences=${sites.length} across tables=${tables.size}]`;
+            if (sites.length === 0) {
+                // No divergence anywhere — still not a clean bill: R-37's disposition is
+                // human, so the instrument abstains rather than claim the rule held.
+                const reason = `R-37: no filled-neighbour divergence found across the oracle's per-table groups; the mechanical compare is exhausted, but confirming the per-tool contract is human. ${breakdown}`;
+                return {
+                    id: R37_ID,
+                    anchor: R37_ANCHOR,
+                    state: "could-not-judge",
+                    verdict: reason,
+                    reason,
+                };
+            }
+            const examples = sites
+                .slice(0, 5)
+                .map((s) => `${s.table}.${s.field}: ${s.toolA} "${s.valA.slice(0, 32)}" vs ${s.toolB} "${s.valB.slice(0, 32)}"`)
+                .join("; ");
+            const reason = `R-37: ${sites.length} filled-neighbour divergence(s) across ${tables.size} tables — the mechanical compare names WHICH TWO TOOLS diverge on a shared contract field; a human must judge whether each per-tool justification is sound. This is NOT a clean bill. ${breakdown} Examples: ${examples}.`;
+            return {
+                id: R37_ID,
+                anchor: `oracle:vp-by-tool-day158.csv table=${sites[0].table}`,
+                state: "could-not-judge",
+                verdict: reason,
+                reason,
+            };
+        },
+    };
+}

package/dist/detectors/predicates.d.ts

@@ -0,0 +1,19 @@
+import { type RulePredicate } from "./shared.js";
+/** Collapse a raw `surface` to one of the three canonical exposures, or null. */
+export declare function collapseSurface(raw: string): string | null;
+export declare const r1: RulePredicate;
+export declare const r2: RulePredicate;
+export declare const r3: RulePredicate;
+export declare const r4: RulePredicate;
+/** Collapse a raw `rbac_qui` value to one of the five canonical tiers, or null
+ * if it maps to none. `fleet_interne` → fleet-internal; every `toutes_orgs(...)`
+ * variant → an org tier (the documented collapse, standard line 61). */
+export declare function collapseTier(raw: string): string | null;
+export declare const r5: RulePredicate;
+export declare const r9: RulePredicate;
+export declare const r10: RulePredicate;
+export declare const r12: RulePredicate;
+export declare const r13: RulePredicate;
+export declare const r27: RulePredicate;
+export declare const r28: RulePredicate;
+export declare const PER_ROW_PREDICATES: RulePredicate[];