@vantageos/backend-doctor 0.1.0

package/dist/detectors/standard/standard-doc.js

@@ -0,0 +1,271 @@
+import { docDetector, emptyDocScan, isDocPlaceholder, STANDARD_DOC_PIN, sectionLines, tableRows, } from "./_doc.js";
+// ---- shared doc helpers ---------------------------------------------------
+/** Every rule id the standard DEFINES — a `**R-NN` rule-definition header. This
+ * is the resolution target: a rule cited elsewhere "resolves" iff it is here. */
+function definedRuleIds(lines) {
+    const ids = new Set();
+    for (const l of lines) {
+        const m = /^\*\*(R-\d+)\b/.exec(l.raw);
+        if (m)
+            ids.add(m[1]);
+    }
+    return ids;
+}
+/** The first line matching a regex, or undefined. */
+function findLine(lines, re) {
+    return lines.find((l) => re.test(l.raw));
+}
+// ===========================================================================
+// R-42 (process; static + delivery gate) — §18 line 431:
+// "each rule's §14 source cell names a source from the KNOWN SET, not merely
+//  non-empty (static); no raised subject left un-routed (delivery gate)."
+//
+// KNOWN SET (derived from the §14 table's own spellings): the two audits
+// (`audit`, `audit — Finding …`, `audit re-read`), established practice
+// (`practice …`), the platform (`platform`), the conformance ruling
+// (`self — the conformance ruling …`), and a named production incident
+// (`incident …`) — the provenance the merged standard added at R-44/R-45 (the
+// PR #1200 briefingNoteParticipants incident), on the same footing as an audit
+// finding: a concrete, cited defect the rule was written to stop.
+//
+// STATIC HALF: parse §14; flag a source cell that is empty, a placeholder, or
+// outside the known set. Parse §9b's routing table; flag a raised subject with
+// an empty "Routed to" cell (a subject left un-routed IN the document).
+// GATE HALF: a subject raised in review (D5 delivery gate) that ends neither a
+// numbered rule nor a written §10 exclusion — owed at D5's delivery surface,
+// not readable from the static document → one cnj site.
+// ===========================================================================
+const KNOWN_SOURCE = /^(audit\b|practice\b|platform\b|incident\b|self\s+—\s+the conformance ruling\b)/i;
+export function scanR42(lines) {
+    const scan = emptyDocScan();
+    const s14 = sectionLines(lines, "14");
+    for (const row of tableRows(s14)) {
+        if (!/^R-\d+$/.test(row.cells[0] ?? ""))
+            continue;
+        const ruleId = row.cells[0];
+        const source = row.cells[1] ?? "";
+        if (isDocPlaceholder(source)) {
+            scan.violate.push({
+                n: row.n,
+                note: `${ruleId} §14 source cell is empty/placeholder ("${source}") — a rule left un-sourced`,
+            });
+        }
+        else if (!KNOWN_SOURCE.test(source)) {
+            scan.violate.push({
+                n: row.n,
+                note: `${ruleId} §14 source "${source}" is not in the known set {the two audits, established practice, the platform, a named incident, the conformance ruling}`,
+            });
+        }
+        else {
+            scan.conform.push({
+                n: row.n,
+                note: `${ruleId} sourced from the known set ("${source}")`,
+            });
+        }
+    }
+    // §9b routing table — no raised subject left un-routed, in the document.
+    const s9 = sectionLines(lines, "9");
+    const i9b = s9.findIndex((l) => /^###\s+9b\b/.test(l.raw));
+    const s9b = i9b < 0 ? [] : s9.slice(i9b);
+    for (const row of tableRows(s9b)) {
+        if (row.cells.length < 4)
+            continue;
+        if (row.cells[0] === "#")
+            continue; // header
+        const subject = row.cells[1] ?? "";
+        const routed = row.cells[3] ?? "";
+        if (isDocPlaceholder(routed)) {
+            scan.violate.push({
+                n: row.n,
+                note: `§9b subject "${subject}" has an empty "Routed to" cell — a raised subject left un-routed`,
+            });
+        }
+        else {
+            scan.conform.push({
+                n: row.n,
+                note: `§9b "${subject}" routed to "${routed}"`,
+            });
+        }
+    }
+    // GATE HALF — the never-silence obligation over FUTURE raised subjects.
+    const gateAnchor = findLine(lines, /^##\s+14\./) ?? { n: 335 };
+    scan.cnj.push({
+        n: gateAnchor.n,
+        note: "delivery gate (D5): a subject raised in review that ends neither a numbered rule nor a written §10 exclusion blocks acceptance — the never-silence half runs at D5's delivery surface, not readable from the static document",
+    });
+    return scan;
+}
+// ===========================================================================
+// R-15 (process; delivery gate) — §18 line 404: "a new term/subject reconciled
+// before acceptance." The §3 four shared names (operation, retrieval,
+// pagination, authority) are its STANDING PRODUCT: each must end reconciled as a
+// numbered rule. STATIC HALF: parse the §3 header's four names and confirm each
+// binds to a `**R-NN — <name>` rule definition inside §3. GATE HALF: a NEW audit
+// term / practice subject reconciled before acceptance runs at D5's delivery
+// surface (a new audit being ingested) → one cnj site.
+// ===========================================================================
+export function scanR15(lines) {
+    const scan = emptyDocScan();
+    const s3 = sectionLines(lines, "3");
+    const header = findLine(s3, /^##\s+3\./);
+    // The four shared names live after the em-dash in the §3 header.
+    const namePart = header ? header.raw.split("—").slice(1).join("—") : "";
+    const names = namePart
+        .split(",")
+        .map((x) => x.trim().toLowerCase())
+        .filter((x) => x.length > 0);
+    for (const name of names) {
+        // authority is split into reader/writer bindings — a match on either half.
+        const bind = s3.find((l) => new RegExp(`\\*\\*R-\\d+ — [^*]*\\b${name}\\b`, "i").test(l.raw));
+        if (bind) {
+            scan.conform.push({
+                n: bind.n,
+                note: `shared name "${name}" reconciled to a numbered rule (${/\*\*(R-\d+)/.exec(bind.raw)?.[1] ?? "R-?"})`,
+            });
+        }
+        else {
+            scan.violate.push({
+                n: header?.n ?? 51,
+                note: `§3 shared name "${name}" has no reconciling **R-NN — ${name}** rule binding — a standing term left unreconciled`,
+            });
+        }
+    }
+    if (names.length === 0) {
+        scan.violate.push({
+            n: header?.n ?? 51,
+            note: "§3 header names no shared vocabulary — the standing product is absent",
+        });
+    }
+    // GATE HALF — a NEW term/subject reconciled before acceptance, at D5.
+    const gateAnchor = findLine(lines, /^\*\*R-15 \(process\)/) ?? { n: 278 };
+    scan.cnj.push({
+        n: gateAnchor.n,
+        note: "delivery gate (D5): a new audit term / practice subject must be reconciled to a numbered rule or a written §10 exclusion before the audit is accepted — the 'before acceptance' gate runs at D5's delivery surface",
+    });
+    return scan;
+}
+// ===========================================================================
+// R-32 (process; delivery gate) — §18 line 421: "a limit-governed rule's change
+// carries a real-deployment proof, not only convex-test." The limit-governed
+// rules are named in the R-32 prose (line 270): R-3, R-4, R-11, R-23, R-30,
+// R-31. STATIC HALF: parse that set from the prose, assert it equals the
+// expected set, and confirm each named rule resolves to a real numbered rule.
+// GATE HALF: the change-carries-real-deployment-proof check runs at D5 — surface
+// the limit-governed rule set as the sites the gate applies to (one cnj each).
+// ===========================================================================
+const R32_EXPECTED = ["R-3", "R-4", "R-11", "R-23", "R-30", "R-31"];
+export function scanR32(lines) {
+    const scan = emptyDocScan();
+    const prose = findLine(lines, /^\*\*R-32 \(process\)/);
+    const defined = definedRuleIds(lines);
+    if (!prose) {
+        scan.violate.push({
+            n: 270,
+            note: "R-32 prose not found — the limit-governed rule set cannot be read from the document",
+        });
+        return scan;
+    }
+    // the rule ids the prose names, excluding R-32 itself.
+    const named = [...prose.raw.matchAll(/R-\d+/g)]
+        .map((m) => m[0])
+        .filter((id) => id !== "R-32");
+    const uniq = [...new Set(named)];
+    const set = new Set(uniq);
+    const expected = new Set(R32_EXPECTED);
+    const drift = uniq.length !== R32_EXPECTED.length ||
+        R32_EXPECTED.some((id) => !set.has(id)) ||
+        uniq.some((id) => !expected.has(id));
+    if (drift) {
+        scan.violate.push({
+            n: prose.n,
+            note: `R-32 limit-governed set drifted — reads {${uniq.join(", ")}}, expected {${R32_EXPECTED.join(", ")}}`,
+        });
+    }
+    for (const id of uniq) {
+        if (!defined.has(id)) {
+            scan.violate.push({
+                n: prose.n,
+                note: `R-32 names limit-governed rule ${id}, which resolves to no numbered rule in the document`,
+            });
+        }
+        else {
+            const def = findLine(lines, new RegExp(`^\\*\\*${id}\\b`)) ?? {
+                n: prose.n,
+            };
+            scan.conform.push({
+                n: def.n,
+                note: `limit-governed rule ${id} named by R-32 resolves to a real numbered rule`,
+            });
+        }
+    }
+    // GATE HALF — the real-deployment-proof gate, per limit-governed rule, at D5.
+    for (const id of R32_EXPECTED) {
+        if (!set.has(id))
+            continue;
+        const def = findLine(lines, new RegExp(`^\\*\\*${id}\\b`)) ?? {
+            n: prose.n,
+        };
+        scan.cnj.push({
+            n: def.n,
+            note: `delivery gate (D5): a change to ${id} must carry a real-deployment proof (not only convex-test) — the change-carries-proof verdict is owed at D5's delivery surface`,
+        });
+    }
+    return scan;
+}
+// ===========================================================================
+// R-39 (judgement; static + delivery gate) — §18 line 428: "the platform
+// mechanism a rule depends on is named (mechanical); it resolves to a current
+// guarantee (delivery gate)." STATIC/MECHANICAL HALF: the §11 refinements table
+// names, per rule, the Convex mechanism it depends on — flag any §11-refined
+// rule that fails to NAME a mechanism. GATE/HUMAN HALF: whether each named
+// mechanism resolves to a real, current platform guarantee (a renamed API /
+// withdrawn guarantee fails) — surface each (rule, mechanism) pair as a site a
+// human/gate verdict is owed on (one cnj each).
+// ===========================================================================
+export function scanR39(lines) {
+    const scan = emptyDocScan();
+    const s11 = sectionLines(lines, "11");
+    for (const row of tableRows(s11)) {
+        const first = row.cells[0] ?? "";
+        const m = /^(R-\d+)\b/.exec(first);
+        if (!m)
+            continue; // not a refinements-table rule row (e.g. the header "Rule")
+        const ruleId = m[1];
+        const mechanism = row.cells[1] ?? "";
+        if (isDocPlaceholder(mechanism)) {
+            scan.violate.push({
+                n: row.n,
+                note: `§11-refined rule ${ruleId} names NO platform mechanism — a rule resting on an unnamed mechanism is unenforceable prose`,
+            });
+            continue;
+        }
+        scan.conform.push({
+            n: row.n,
+            note: `${ruleId} names its platform mechanism (${mechanism.slice(0, 48)}…)`,
+        });
+        // GATE/HUMAN HALF — does the named mechanism resolve to a CURRENT guarantee?
+        scan.cnj.push({
+            n: row.n,
+            note: `${ruleId} → "${mechanism.slice(0, 40)}…": a human/gate verdict is owed on whether this platform mechanism resolves to a real, current Convex guarantee (a renamed API / withdrawn guarantee fails)`,
+        });
+    }
+    if (scan.conform.length === 0 && scan.violate.length === 0) {
+        scan.violate.push({
+            n: 247,
+            note: "§11 refinements table not found or names no rule/mechanism pair — cannot certify platform-mechanism naming",
+        });
+    }
+    return scan;
+}
+// ---- detectors ------------------------------------------------------------
+export const R42 = docDetector("R-42", "R-42 every rule sourced; no raised subject left silent", "every §14 source cell names a source from the known set (static); no raised subject left un-routed (delivery gate)", scanR42, "R-42: §14 source table not found in the vendored standard — cannot certify the three-source discipline. NOT a clean bill.");
+export const R15 = docDetector("R-15 vocabulary & subject reconciliation", "R-15 vocabulary & subject reconciliation", "the §3 four shared names each reconcile to a numbered rule (static); a new term reconciled before acceptance (delivery gate)", scanR15, "R-15: §3 shared-vocabulary section not found — cannot certify reconciliation. NOT a clean bill.");
+export const R32 = docDetector("R-32 limit-governed rule proven on a real deployment", "R-32 limit-governed rule proven on a real deployment", "the R-32 limit-governed set {R-3,R-4,R-11,R-23,R-30,R-31} is named and each resolves (static); a change carries a real-deployment proof (delivery gate)", scanR32, "R-32: limit-governed rule set not found — cannot certify the real-deployment-proof discipline. NOT a clean bill.");
+export const R39 = docDetector("R-39 a rule's platform mechanism is named and resolves", "R-39 a rule's platform mechanism is named and resolves", "every §11-refined rule names its platform mechanism (mechanical); the named mechanism resolves to a current guarantee (delivery gate)", scanR39, "R-39: §11 refinements table not found — cannot certify platform-mechanism naming. NOT a clean bill.");
+/** The four, in a form the orchestrator spreads into REGISTRY. */
+export const STANDARD_DOC_DETECTORS = [
+    { detector: R42, ruleId: "R-42", standardPin: STANDARD_DOC_PIN },
+    { detector: R15, ruleId: "R-15", standardPin: STANDARD_DOC_PIN },
+    { detector: R32, ruleId: "R-32", standardPin: STANDARD_DOC_PIN },
+    { detector: R39, ruleId: "R-39", standardPin: STANDARD_DOC_PIN },
+];

package/dist/detectors/structural.d.ts

@@ -0,0 +1,14 @@
+import type { Detector } from "../engine-types.js";
+import { type OracleRow } from "../oracle.js";
+/**
+ * R-14 — inventory-schema parity, contract → inventory, one direction.
+ * A merged reader/writer authority column is "non-conforming by construction"
+ * (§12). The oracle's column 9 `rbac_qui` is that single merged column.
+ */
+export declare function makeR14(columns?: readonly string[]): Detector;
+/**
+ * R-38 — the completeness gate over the thirteen §2 fields. The oracle cannot
+ * satisfy the contract because reader and writer authority are not two separate
+ * fields (both map to `rbac_qui`).
+ */
+export declare function makeR38(columns?: readonly string[], rowsProvider?: () => OracleRow[]): Detector;

package/dist/detectors/structural.js

@@ -0,0 +1,83 @@
+// The two STRUCTURAL detectors — R-14 and R-38. They judge the inventory SCHEMA
+// against the §2 contract, not a single row. Run against THIS oracle they MUST
+// return `non-conforming`, because §2 splits authority into two distinct fields
+// (reader R-5, writer R-10) and the oracle carries a SINGLE merged `rbac_qui`
+// column. Agreeing with the oracle here would be certifying the defect the
+// instrument exists to find — so these are NOT tuned to pass.
+import { CONTRACT_FIELDS, READER_AUTHORITY_COLUMN, WRITER_AUTHORITY_COLUMN, authorityIsMerged } from "../contract.js";
+import { ORACLE_COLUMNS, readOracle } from "../oracle.js";
+const CSV_ANCHOR = "oracle:vp-by-tool-day158.csv col#9 rbac_qui";
+/**
+ * R-14 — inventory-schema parity, contract → inventory, one direction.
+ * A merged reader/writer authority column is "non-conforming by construction"
+ * (§12). The oracle's column 9 `rbac_qui` is that single merged column.
+ */
+export function makeR14(columns = ORACLE_COLUMNS) {
+    return {
+        id: "R-14 inventory-schema parity",
+        run: () => {
+            const authorityColumns = columns.filter((c) => c === "rbac_qui");
+            if (authorityIsMerged() || authorityColumns.length < 2) {
+                return {
+                    id: "R-14 inventory-schema parity",
+                    anchor: CSV_ANCHOR,
+                    state: "non-conforming",
+                    verdict: "R-14: the inventory holds a SINGLE merged authority column `rbac_qui` (col#9), " +
+                        "but §2 splits authority into two distinct contract fields — reader authority (R-5) " +
+                        "and writer authority (R-10). A merged authority column is non-conforming by construction: " +
+                        "the reader/writer divergence R-10 and R-7 exist to record cannot be written in it.",
+                };
+            }
+            return {
+                id: "R-14 inventory-schema parity",
+                anchor: "oracle:vp-by-tool-day158.csv",
+                state: "present",
+                verdict: "R-14: every §2 contract field present; reader and writer authority are two separate columns.",
+            };
+        },
+    };
+}
+/**
+ * R-38 — the completeness gate over the thirteen §2 fields. The oracle cannot
+ * satisfy the contract because reader and writer authority are not two separate
+ * fields (both map to `rbac_qui`).
+ */
+export function makeR38(columns = ORACLE_COLUMNS, rowsProvider = readOracle) {
+    return {
+        id: "R-38 thirteen-field completeness",
+        run: () => {
+            const colSet = new Set(columns);
+            const missing = [];
+            for (const f of CONTRACT_FIELDS) {
+                for (const col of f.columns) {
+                    if (!colSet.has(col))
+                        missing.push(`${f.field}→${col}`);
+                }
+            }
+            const authorityMerged = READER_AUTHORITY_COLUMN === WRITER_AUTHORITY_COLUMN && colSet.has(READER_AUTHORITY_COLUMN);
+            if (authorityMerged || missing.length > 0) {
+                const rows = rowsProvider();
+                const sample = rows
+                    .filter((r) => !r.malformed && r.by.rbac_qui && r.by.table !== "TOTAL")
+                    .slice(0, 3)
+                    .map((r) => `row#${r.n} "${r.by.outil || r.by.table}" rbac_qui="${r.by.rbac_qui}"`)
+                    .join("; ");
+                return {
+                    id: "R-38 thirteen-field completeness",
+                    anchor: CSV_ANCHOR,
+                    state: "non-conforming",
+                    verdict: `R-38: the oracle cannot satisfy the thirteen-field §2 contract — reader authority (R-5) and ` +
+                        `writer authority (R-10) are not two separate fields; both map to the single column ` +
+                        `\`rbac_qui\` (col#9).${missing.length ? ` Also missing: ${missing.join(", ")}.` : ""} ` +
+                        `Evidence: ${sample}.`,
+                };
+            }
+            return {
+                id: "R-38 thirteen-field completeness",
+                anchor: "oracle:vp-by-tool-day158.csv",
+                state: "present",
+                verdict: "R-38: all thirteen §2 contract fields present per table, each within its vocabulary.",
+            };
+        },
+    };
+}

package/dist/engine-types.d.ts

@@ -0,0 +1,10 @@
+import { runDoctor } from "@vantageos/mcp-doctor";
+/** A detector object the engine's runner accepts in its injectable list. */
+export type Detector = NonNullable<Parameters<typeof runDoctor>[1]>[number];
+/** One row of the engine's verdict table. */
+export type DetectorResult = ReturnType<typeof runDoctor>[number];
+/** The engine's decisive/undecidable state union — derived, not spelled out. */
+export type State = DetectorResult["state"];
+/** The tree shape the engine hands each detector's `run`. Detectors in this
+ * wave ignore it (they consult the oracle), so we only need its identity. */
+export type Tree = Parameters<Detector["run"]>[0];

package/dist/engine-types.js

@@ -0,0 +1 @@
+export {};

package/dist/not-checkable.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The deferral bucket. R-1..R-47 each carry an executable control (registry.ts),
+ * so none is deferred to "a human decides". R-48 (authority-totality, the #130
+ * class) was added to the standard at the 51ec7af1 re-pin AFTER its detector; its
+ * text is now pinned so coverage enumerates 48, but no detector exists yet — so it
+ * is reported here as NOT_MECHANICALLY_CHECKABLE with a written reason rather than
+ * silently omitted, which would let coverage pretend 47 is the whole document. The
+ * detector is task k17chpr4kzp399j3s7r7edpm4s8cscbz (after D5); when it lands, R-48
+ * moves to registry.ts and this entry is removed. The export is consumed by
+ * coverage.ts / coverage-cli.ts / cli.ts.
+ */
+import type { DetectorResult } from "./engine-types.js";
+export declare const NOT_MECHANICALLY_CHECKABLE: Record<string, string>;
+/**
+ * One `could-not-judge` DetectorResult per NOT_MECHANICALLY_CHECKABLE rule, so
+ * every rule the standard defines carries EXACTLY ONE result (the tally invariant)
+ * without inventing a mechanical verdict a detector has not earned. A pinned rule
+ * with no detector is an ABSTENTION — a human/gate verdict is owed — never a
+ * silent omission and never a synthesized `present`. Appended to the registry run
+ * alongside the executable detectors' results.
+ */
+export declare function notCheckableResults(bucket?: Record<string, string>): DetectorResult[];

package/dist/not-checkable.js

@@ -0,0 +1,37 @@
+// The deferral bucket — now EMPTY, and kept empty on purpose.
+//
+// Every rule the standard defines carries an executable control (registry.ts), so
+// no rule is deferred to "a human decides". The operator refused a deferral bucket
+// outright: nothing a script or shell command can decide is deferred, and nothing
+// is deferred at all without his explicit agreement. This file is the proof of that
+// refusal — an export that other modules consume but that holds no entries.
+//
+// History (why the bucket existed and why it is gone): the twenty source-tree rules
+// and the nine judgement/process/cross-document rules were each, at one point, filed
+// here under a label — "a machine cannot decide it". That label was false for all of
+// them: a source scan is mechanical; a judgement rule's DETECTION half is mechanical
+// and its human half is surfaced per site, not deferred; a cross-document resolution
+// (R-41) and an Axis-1 between-backend compare (R-40) are mechanical once their second
+// input is vendored. They were built, not relabelled. The bucket was not renamed to a
+// gentler word — it was emptied.
+import { STANDARD_FILE } from "./detectors/standard/_doc.js";
+export const NOT_MECHANICALLY_CHECKABLE = {
+    "R-48": "R-48 authority-totality detector pending — task k17chpr4kzp399j3s7r7edpm4s8cscbz; text pinned at 51ec7af1 so coverage cannot pretend 47 is complete. No mechanical control yet; R-48 is enumerated and visible, never silently dropped.",
+};
+/**
+ * One `could-not-judge` DetectorResult per NOT_MECHANICALLY_CHECKABLE rule, so
+ * every rule the standard defines carries EXACTLY ONE result (the tally invariant)
+ * without inventing a mechanical verdict a detector has not earned. A pinned rule
+ * with no detector is an ABSTENTION — a human/gate verdict is owed — never a
+ * silent omission and never a synthesized `present`. Appended to the registry run
+ * alongside the executable detectors' results.
+ */
+export function notCheckableResults(bucket = NOT_MECHANICALLY_CHECKABLE) {
+    return Object.entries(bucket).map(([ruleId, reason]) => ({
+        id: `${ruleId} not-mechanically-checkable`,
+        anchor: `${STANDARD_FILE}:0`,
+        state: "could-not-judge",
+        verdict: `${ruleId}: NOT_MECHANICALLY_CHECKABLE — ${reason}`,
+        reason,
+    }));
+}

package/dist/oracle.d.ts

@@ -0,0 +1,33 @@
+/** Absolute path to the pinned oracle fixture. */
+export declare const ORACLE_PATH: string;
+/** The eighteen audit columns, in file order. §2 of the standard maps contract
+ * fields onto these column names. */
+export declare const ORACLE_COLUMNS: readonly ["table", "outil", "T2_verdict", "T2_composant_cible", "crud", "operation_detail", "search_mecanisme", "surface", "rbac_qui", "scope_enforcement", "namespace_ou_org", "tokens_estime_contexte", "doublon_alias", "rbac_coherence_table", "rbac_adjustment_needed", "table_purpose", "table_conserver_supprimer", "statut_suppression"];
+export type OracleColumn = (typeof ORACLE_COLUMNS)[number];
+export interface OracleRow {
+    /** 1-based data-row index (header excluded). */
+    n: number;
+    /** the raw parsed cells, exactly as many as the parser found. */
+    cells: string[];
+    /** column-name → trimmed value; only populated when the row is well-formed. */
+    by: Record<OracleColumn, string>;
+    /** set when the row could NOT be parsed into the 18-column shape — a detector
+     * reads this as could-not-judge, never as a pass. */
+    malformed?: string;
+}
+/**
+ * RFC-4180-ish CSV parser: handles quoted fields with embedded commas and
+ * doubled quotes. The oracle CSV has quoted cells with commas (e.g. the
+ * `table_conserver_supprimer` prose), so a naive split on "," is wrong.
+ */
+export declare function parseCsv(text: string): string[][];
+/** Build typed rows from raw parsed cells (header already removed). */
+export declare function toRows(dataRows: string[][]): OracleRow[];
+/** Memoized read of the real pinned oracle fixture. */
+export declare function readOracle(): OracleRow[];
+/**
+ * A real inventory row is one tool/table entry. The audit's trailing `TOTAL`
+ * aggregate row (`table === "TOTAL"`, empty `outil`) is NOT an inventory entry;
+ * a per-row detector treats it as not-applicable, never judging it as a tool.
+ */
+export declare function isInventoryRow(row: OracleRow): boolean;

package/dist/oracle.js

@@ -0,0 +1,133 @@
+// The oracle reader. The oracle is the day158 per-tool audit CSV — a COMPARISON
+// TARGET, never an authority. Where the oracle and the pinned standard disagree,
+// the standard wins and the divergence is a FINDING about the oracle.
+//
+// The tree the engine's loadTree builds is .ts-only and does NOT contain this
+// CSV, so every first-wave detector ignores `tree` and consults this memoized
+// reader instead.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const here = dirname(fileURLToPath(import.meta.url));
+/** Absolute path to the pinned oracle fixture. */
+export const ORACLE_PATH = join(here, "..", "fixtures", "vp-by-tool-day158.csv");
+/** The eighteen audit columns, in file order. §2 of the standard maps contract
+ * fields onto these column names. */
+export const ORACLE_COLUMNS = [
+    "table",
+    "outil",
+    "T2_verdict",
+    "T2_composant_cible",
+    "crud",
+    "operation_detail",
+    "search_mecanisme",
+    "surface",
+    "rbac_qui",
+    "scope_enforcement",
+    "namespace_ou_org",
+    "tokens_estime_contexte",
+    "doublon_alias",
+    "rbac_coherence_table",
+    "rbac_adjustment_needed",
+    "table_purpose",
+    "table_conserver_supprimer",
+    "statut_suppression",
+];
+/**
+ * RFC-4180-ish CSV parser: handles quoted fields with embedded commas and
+ * doubled quotes. The oracle CSV has quoted cells with commas (e.g. the
+ * `table_conserver_supprimer` prose), so a naive split on "," is wrong.
+ */
+export function parseCsv(text) {
+    const rows = [];
+    let field = "";
+    let record = [];
+    let inQuotes = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (inQuotes) {
+            if (c === '"') {
+                if (text[i + 1] === '"') {
+                    field += '"';
+                    i++;
+                }
+                else {
+                    inQuotes = false;
+                }
+            }
+            else {
+                field += c;
+            }
+            continue;
+        }
+        if (c === '"') {
+            inQuotes = true;
+        }
+        else if (c === ",") {
+            record.push(field);
+            field = "";
+        }
+        else if (c === "\n") {
+            record.push(field);
+            rows.push(record);
+            record = [];
+            field = "";
+        }
+        else if (c === "\r") {
+            // swallow — the newline handler emits the record
+        }
+        else {
+            field += c;
+        }
+    }
+    // trailing field / record (file with no final newline)
+    if (field.length > 0 || record.length > 0) {
+        record.push(field);
+        rows.push(record);
+    }
+    return rows;
+}
+/** Build typed rows from raw parsed cells (header already removed). */
+export function toRows(dataRows) {
+    return dataRows.map((cells, idx) => {
+        const n = idx + 1;
+        if (cells.length !== ORACLE_COLUMNS.length) {
+            return {
+                n,
+                cells,
+                by: {},
+                malformed: `row ${n} has ${cells.length} cells, expected ${ORACLE_COLUMNS.length}`,
+            };
+        }
+        const by = {};
+        ORACLE_COLUMNS.forEach((col, i) => {
+            by[col] = (cells[i] ?? "").trim();
+        });
+        return { n, cells, by };
+    });
+}
+let cache = null;
+/** Memoized read of the real pinned oracle fixture. */
+export function readOracle() {
+    if (cache)
+        return cache;
+    const text = readFileSync(ORACLE_PATH, "utf8");
+    const raw = parseCsv(text).filter((r) => !(r.length === 1 && r[0] === ""));
+    const [, ...data] = raw; // drop header
+    cache = toRows(data);
+    return cache;
+}
+/**
+ * A real inventory row is one tool/table entry. The audit's trailing `TOTAL`
+ * aggregate row (`table === "TOTAL"`, empty `outil`) is NOT an inventory entry;
+ * a per-row detector treats it as not-applicable, never judging it as a tool.
+ */
+export function isInventoryRow(row) {
+    if (row.malformed)
+        return false;
+    if (row.by.table === "TOTAL")
+        return false;
+    if (row.by.outil === "" && row.by.crud === "" && row.by.surface === "")
+        return false;
+    return true;
+}

package/dist/registry.d.ts

@@ -0,0 +1,11 @@
+import type { Detector } from "./engine-types.js";
+/** The standard both pins the whole wave against. */
+export declare const STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp)";
+export interface RegistryEntry {
+    detector: Detector;
+    ruleId: string;
+    standardPin: string;
+}
+export declare const REGISTRY: RegistryEntry[];
+/** The rule ids this wave mechanically CHECKS — derived from the registry. */
+export declare function checkedRuleIds(): string[];