@vantageos/backend-doctor 0.1.0

package/dist/detectors/predicates.js

@@ -0,0 +1,334 @@
+import { LIST_VERBS, WRITE_VERBS, isMcpPublic } from "./shared.js";
+// ---- R-1 exposure declared ------------------------------------------------
+// §2 line 32: exposure -> `surface` = `public` (MCP surface) / `internal` /
+// `library-owned` — THREE canonical values. The oracle stores raw values, so
+// (mirroring R-5's collapse) the detector collapses raw→canonical FIRST, then
+// flags only a value that maps to none of the three.
+const SURFACE_COLLAPSE = {
+    "mcp-public": "public",
+    public: "public",
+    component: "library-owned",
+    "library-owned": "library-owned",
+    "hors-mcp": "internal",
+    internal: "internal",
+};
+/** Collapse a raw `surface` to one of the three canonical exposures, or null. */
+export function collapseSurface(raw) {
+    return SURFACE_COLLAPSE[raw.trim().toLowerCase()] ?? null;
+}
+export const r1 = {
+    ruleId: "R-1",
+    id: "R-1 exposure declared",
+    check: "raw `surface` collapses to one of the three canonical exposures {public/internal/library-owned}",
+    classify: (r) => collapseSurface(r.by.surface)
+        ? { kind: "conform" }
+        : { kind: "violate", note: `surface="${r.by.surface}" maps to none of {public, internal, library-owned}` },
+};
+// ---- R-2 operation verb, closed set, rpc refused --------------------------
+// §2 operation verb [shared] -> `crud`. §15: verb one of the closed set; no rpc.
+const VERB_MAP = {
+    "READ-LIST": "list",
+    "READ-GET": "get",
+    SEARCH: "search",
+    AGGREGATE: "aggregate",
+    CREATE: "create",
+    UPDATE: "update",
+    DELETE: "delete",
+    UPSERT: "upsert",
+    TRANSITION: "transition",
+    "BULK-WRITE": "bulk-write",
+    "EXTERNAL-EFFECT": "external-effect",
+};
+export const r2 = {
+    ruleId: "R-2",
+    id: "R-2 operation verb, rpc refused",
+    check: "verb one of the closed set; `rpc` refused",
+    classify: (r) => {
+        const v = r.by.crud;
+        if (v === "n/a" || v === "")
+            return { kind: "na" }; // component / non-exposed, no verb
+        if (v.toUpperCase() === "RPC")
+            return { kind: "violate", note: "crud=RPC — the closed set refuses rpc; it publishes nothing about effect" };
+        if (VERB_MAP[v.toUpperCase()])
+            return { kind: "conform" };
+        return { kind: "violate", note: `crud="${v}" is outside the closed verb set` };
+    },
+};
+// ---- R-3 pagination, tool-enforced ----------------------------------------
+// §2 pagination [shared] -> `search_mecanisme`. §15 line 392: "cursor declared;
+// `default`/`max` numeric and tool-set; truncated≠exhausted". All three clauses:
+//  - cursor declared (a `pas de curseur` cell is no cursor),
+//  - default numeric,
+//  - max numeric AND bounded (`non-borné` is the unbounded max R-30 refuses),
+//  - truncated≠exhausted is a RESPONSE-SHAPE property with no oracle column — a
+//    row otherwise fine is could-not-judge on that sub-clause, never a silent pass.
+export const r3 = {
+    ruleId: "R-3",
+    id: "R-3 pagination, tool-enforced",
+    check: "cursor declared; default numeric; max numeric-and-bounded; truncated≠exhausted (response-shape)",
+    classify: (r) => {
+        if (!LIST_VERBS.has(r.by.crud))
+            return { kind: "na" };
+        const cell = r.by.search_mecanisme;
+        const m = cell.toLowerCase();
+        const cursorDeclared = !m.includes("pas de curseur") && /curseur\s*:?\s*oui|cursor/.test(m);
+        const defaultMatch = /defaut\s*:?\s*(\d+)|default\s*:?\s*(\d+)/.exec(m);
+        const maxUnbounded = /max\s*:?\s*non-?bor/.test(m);
+        const maxMatch = /max\s*:?\s*(\d+)/.exec(m);
+        const fails = [];
+        if (!cursorDeclared)
+            fails.push("no cursor declared");
+        if (!defaultMatch)
+            fails.push("no numeric `default`");
+        if (maxUnbounded)
+            fails.push("`max: non-borné` — an unbounded max R-30 refuses");
+        else if (!maxMatch)
+            fails.push("no numeric `max`");
+        if (fails.length > 0)
+            return { kind: "violate", note: `${fails.join("; ")} (search_mecanisme="${cell || "<empty>"}")` };
+        // cursor + default + bounded max all present; the truncated≠exhausted clause
+        // is not expressible in the oracle columns — abstain on it, never pass.
+        return {
+            kind: "cnj",
+            note: "cursor + default + bounded max present, but truncated≠exhausted is a response-shape property absent from the oracle columns; deferred",
+        };
+    },
+};
+// ---- R-4 retrieval mechanism, unindexed scan refused ----------------------
+// §2 retrieval [shared] -> `search_mecanisme`. §15: mechanism one of the set,
+// every list included; no unindexed scan.
+const INDEXED = ["bm25", "vectoriel", "vector", "hybrid", "rrf", "indexed-range", "range", "searchindex"];
+export const r4 = {
+    ruleId: "R-4",
+    id: "R-4 retrieval, no unindexed scan",
+    check: "mechanism one of the indexed set; `unindexed-scan` refused",
+    classify: (r) => {
+        if (!LIST_VERBS.has(r.by.crud))
+            return { kind: "na" };
+        const m = r.by.search_mecanisme.toLowerCase();
+        if (m.includes("substring scan") || m.includes(".collect()") || m.includes("unindexed"))
+            return { kind: "violate", note: "unindexed-scan (.collect()+.includes()) — refused at publication" };
+        if (m.trim() === "")
+            return { kind: "violate", note: "empty retrieval cell — a list is a retrieval and must declare a mechanism" };
+        if (INDEXED.some((tok) => m.includes(tok)))
+            return { kind: "conform" };
+        return { kind: "violate", note: `retrieval mechanism "${r.by.search_mecanisme}" not in the closed set` };
+    },
+};
+// ---- R-5 reader authority, resolved from identity -------------------------
+// §2 reader authority [shared] -> `rbac_qui`. Standard line 61: reader authority
+// is one tier from public/org-member/org-admin/fleet-internal/master, and "VP's
+// eight raw rbac_qui values COLLAPSE to these five … resolved from a verified
+// identity, never a caller-supplied value — a tier read from an argument is not
+// a tier." So the detector FIRST collapses raw→tier (they all map, so "not a
+// tier" is ~0), THEN judges identity-resolution — the real violation half — by
+// the row's `namespace_ou_org` evidence (the same column R-6 reads).
+const TIER_MAP = {
+    fleet_interne: "fleet-internal",
+    "fleet-interne": "fleet-internal",
+    public: "public",
+    "org-member": "org-member",
+    "org-admin": "org-admin",
+    master: "master",
+};
+/** 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 function collapseTier(raw) {
+    const v = raw.trim().toLowerCase();
+    if (TIER_MAP[v])
+        return TIER_MAP[v];
+    if (v.startsWith("toutes_orgs"))
+        return "org-member";
+    return null;
+}
+/** rbac_qui variants whose value itself evidences identity-resolution. */
+function rbacEvidencesIdentity(rq) {
+    return /identity-gated|namespace-derived/.test(rq) || rq === "fleet_interne";
+}
+export const r5 = {
+    ruleId: "R-5",
+    id: "R-5 reader authority from identity",
+    check: "raw rbac_qui collapses to one of five tiers, resolved from a verified identity (not an argument)",
+    classify: (r) => {
+        if (!isMcpPublic(r))
+            return { kind: "na" }; // only the served surface carries a reader tier
+        // component / non-MCP rows are judged by R-26, not R-5 — exclude from the denominator.
+        if (r.by.rbac_qui === "n/a" || r.by.rbac_qui === "")
+            return { kind: "na" };
+        const tier = collapseTier(r.by.rbac_qui);
+        if (!tier)
+            return { kind: "violate", note: `rbac_qui="${r.by.rbac_qui}" maps to none of the five canonical tiers` };
+        const ns = r.by.namespace_ou_org;
+        // BOUNDARY EVIDENCE OUTRANKS THE TIER LABEL. `arg=` lives INSIDE the value as
+        // `(arg=<field>)`, never at the start (0 rows start with it; 46 contain it) —
+        // so we CONTAINS-match. A boundary derived from a caller argument is not
+        // identity-resolved however `rbac_qui` is LABELLED: standard line 71 names
+        // `create_briefing_note` (labelled `identity-gated`, boundary `arg=createdBy`)
+        // as the founding example — "the boundary is the argument, so there is no
+        // boundary". The label must never override the evidence.
+        if (/\(arg=|\barg=/.test(ns))
+            return {
+                kind: "violate",
+                note: `reader tier not resolved from a verified identity — boundary derives from a caller argument namespace_ou_org="${ns}" (label rbac_qui="${r.by.rbac_qui}" does not override the boundary evidence)`,
+            };
+        // no arg= in the boundary: NOW the identity-evidencing label may confirm.
+        if (rbacEvidencesIdentity(r.by.rbac_qui))
+            return { kind: "conform" };
+        // maps to a tier but the row evidences NEITHER identity nor arg — abstain, never a silent pass.
+        return {
+            kind: "cnj",
+            note: `tier maps to ${tier} but rbac_qui="${r.by.rbac_qui}"/namespace_ou_org="${ns}" do not evidence identity-resolution; R-11 flags the locus`,
+        };
+    },
+};
+// ---- R-9 per-tool token cost ----------------------------------------------
+// §2 token cost -> `tokens_estime_contexte`. §15 line 398: "a number — a measured
+// OR method-stated estimate — not merely non-empty (red: a placeholder such as
+// TBD/?/~)". So conform on a number OR a method-stated estimate; red ONLY on a
+// placeholder or empty.
+const TOKEN_PLACEHOLDERS = new Set(["", "tbd", "?", "~", "n/a", "todo"]);
+export const r9 = {
+    ruleId: "R-9",
+    id: "R-9 token cost declared",
+    check: "`tokens_estime_contexte` is a number or a method-stated estimate; red only a placeholder",
+    classify: (r) => {
+        const v = r.by.tokens_estime_contexte.trim();
+        if (TOKEN_PLACEHOLDERS.has(v.toLowerCase()))
+            return { kind: "violate", note: `tokens_estime_contexte="${v || "<empty>"}" is a placeholder, not an estimate` };
+        return { kind: "conform" };
+    },
+};
+// ---- R-10 writer authority, a distinct resolved tier ----------------------
+// §2 writer authority [shared] -> `rbac_qui`. §15: writer tier present, DISTINCT,
+// one of five. The oracle has a SINGLE `rbac_qui` column, so no write can carry
+// a writer tier distinct from its reader tier — the headline merge (R-14).
+export const r10 = {
+    ruleId: "R-10",
+    id: "R-10 writer authority, distinct tier",
+    check: "writer tier present, distinct from reader, one of five",
+    classify: (r) => {
+        if (!WRITE_VERBS.has(r.by.crud))
+            return { kind: "na" };
+        return {
+            kind: "violate",
+            note: "writer authority is not recorded as a field distinct from reader authority — both merged into the single `rbac_qui` column",
+        };
+    },
+};
+// ---- R-12 vector search declares namespace + topK -------------------------
+// §2 vector boundary -> `search_mecanisme`. §15: real namespace + numeric topK.
+export const r12 = {
+    ruleId: "R-12",
+    id: "R-12 vector namespace + topK",
+    check: "an indexed-vector tool declares a namespace and a numeric topK",
+    classify: (r) => {
+        const m = r.by.search_mecanisme.toLowerCase();
+        if (!m.includes("vectoriel") && !m.includes("vector"))
+            return { kind: "na" };
+        const hasTopK = /topk\s*=?\s*\d+|topk\s+\d+/i.test(r.by.search_mecanisme);
+        const hasNs = m.includes("rag") || m.includes("namespace");
+        if (hasTopK && hasNs)
+            return { kind: "conform" };
+        const missing = [!hasTopK ? "topK" : null, !hasNs ? "namespace" : null].filter(Boolean).join(" + ");
+        return { kind: "violate", note: `vector search missing ${missing} (search_mecanisme="${r.by.search_mecanisme}")` };
+    },
+};
+// ---- R-13 purpose & disposition declared ----------------------------------
+// §2 disposition -> table_purpose + table_conserver_supprimer + statut_suppression.
+// §15: purpose non-empty; disposition ∈ {stays, goes, undecided}; a bare
+// `undecided` (no owner + deadline) is refused.
+export const r13 = {
+    ruleId: "R-13",
+    id: "R-13 purpose & disposition",
+    check: "purpose non-empty; disposition decided, or undecided with owner + deadline",
+    classify: (r) => {
+        if (r.by.table_purpose.trim() === "")
+            return { kind: "violate", note: "table_purpose is empty — a table with no stated purpose is a deletion candidate" };
+        const d = r.by.table_conserver_supprimer;
+        if (d.trim() === "")
+            return { kind: "violate", note: "disposition (table_conserver_supprimer) is empty" };
+        // §15 line 402: an `undecided` (`a confirmer`) disposition CONFORMS when it
+        // carries an owner AND a deadline; only a BARE undecided is red.
+        if (/\(a confirmer\)|undecided/i.test(d)) {
+            const hasOwner = /owner\s*:/i.test(d);
+            const hasDeadline = /deadline\s*:|\b\d{4}-\d{2}-\d{2}\b/i.test(d);
+            if (hasOwner && hasDeadline)
+                return { kind: "conform" };
+            return {
+                kind: "violate",
+                note: `bare undecided disposition — missing ${!hasOwner ? "owner" : ""}${!hasOwner && !hasDeadline ? " + " : ""}${!hasDeadline ? "deadline" : ""}: "${d.slice(0, 60)}"`,
+            };
+        }
+        if (/^CONSERVER|^SUPPRIMER/.test(d))
+            return { kind: "conform" };
+        return { kind: "violate", note: `disposition "${d.slice(0, 40)}" outside {stays, goes}` };
+    },
+};
+// ---- R-27 removed tool names survivor + change ----------------------------
+// §2 disposition -> `statut_suppression`. §15 line 416: "the named survivor
+// RESOLVES to a tool in the current inventory and the change ref to a real
+// PR/commit, not merely non-empty strings (red: survivor absent, or an
+// unresolvable ref)". The survivor half is statically decidable (is it in the
+// inventory?). The change-ref RESOLUTION is NOT statically decidable — it needs
+// the target repo at a pin — so a row whose survivor resolves but whose ref is
+// only shape-valid is could-not-judge, NEVER conform (a bare shape test is what
+// the line refuses).
+export const r27 = {
+    ruleId: "R-27",
+    id: "R-27 removed tool names survivor",
+    check: "survivor resolves to a current tool (static); change-ref resolution needs the target repo (deferred)",
+    classify: (r, all) => {
+        const s = r.by.statut_suppression;
+        if (s.trim() === "")
+            return { kind: "na" }; // not a removed tool
+        const survivor = /survivor:\s*([^)]+)\)/.exec(s)?.[1]?.trim();
+        const hasRefShape = /PR#\d+|[0-9a-f]{7,40}/.test(s);
+        if (!survivor)
+            return { kind: "violate", note: `removed tool names no survivor: "${s}"` };
+        const resolves = all.some((row) => row.by.outil === survivor);
+        if (!resolves)
+            return { kind: "violate", note: `survivor "${survivor}" absent from the inventory — does not resolve` };
+        if (!hasRefShape)
+            return { kind: "violate", note: `removed tool names no PR/commit ref shape: "${s}"` };
+        return {
+            kind: "cnj",
+            note: `survivor "${survivor}" resolves; change ref shape valid but resolution requires the target repo at a pin — deferred (not statically decidable)`,
+        };
+    },
+};
+// ---- R-28 per-tool remediation --------------------------------------------
+// §2 remediation -> `rbac_adjustment_needed`. §15: a non-conforming tool names a
+// concrete CORRIGER/REVOIR remediation, not a bare placeholder.
+function isNonConforming(r) {
+    return /^INCOHERENT/i.test(r.by.rbac_coherence_table);
+}
+export const r28 = {
+    ruleId: "R-28",
+    id: "R-28 per-tool remediation",
+    check: "a non-conforming tool names a concrete CORRIGER/REVOIR remediation",
+    classify: (r) => {
+        if (!isNonConforming(r))
+            return { kind: "na" };
+        const fix = r.by.rbac_adjustment_needed;
+        if (/^(CORRIGER|REVOIR)/i.test(fix))
+            return { kind: "conform" };
+        return {
+            kind: "violate",
+            note: `non-conforming (${r.by.rbac_coherence_table.slice(0, 30)}) but remediation is not a concrete fix: "${fix.slice(0, 40)}"`,
+        };
+    },
+};
+export const PER_ROW_PREDICATES = [
+    r1,
+    r2,
+    r3,
+    r4,
+    r5,
+    r9,
+    r10,
+    r12,
+    r13,
+    r27,
+    r28,
+];

package/dist/detectors/shared.d.ts

@@ -0,0 +1,56 @@
+import type { Detector, DetectorResult } from "../engine-types.js";
+import { type OracleRow } from "../oracle.js";
+export type RowKind = "conform" | "violate" | "na" | "cnj";
+export interface RowVerdict {
+    kind: RowKind;
+    /** why the row violated / could-not-be-judged (for the report). */
+    note?: string;
+}
+export interface RulePredicate {
+    /** the rule id this detector targets, e.g. "R-1". */
+    ruleId: string;
+    /** the detector display id, e.g. "R-1 exposure declared". */
+    id: string;
+    /** what §15 says the check reads and the criterion that passes it. */
+    check: string;
+    /** classify ONE row. `all` is the full row set (for rules like R-27 that must
+     * resolve a reference against the rest of the inventory). Rows that are not
+     * this rule's concern return `na`. */
+    classify(row: OracleRow, all: OracleRow[]): RowVerdict;
+}
+export interface Tally {
+    conform: number;
+    violate: number;
+    cnj: number;
+    na: number;
+    violations: {
+        row: OracleRow;
+        note: string;
+    }[];
+    unjudged: {
+        row: OracleRow;
+        note: string;
+    }[];
+}
+/** Run a predicate over a row set, tallying per-kind. */
+export declare function tally(spec: RulePredicate, rows: OracleRow[]): Tally;
+/** Aggregate a tally into ONE engine DetectorResult.
+ *
+ * Precedence: any could-not-judge row makes the whole detector abstain (an
+ * abstain is never a silent pass); else any violation is non-conforming; else
+ * present. Every verdict carries the FULL breakdown so a reader sees the four
+ * counts regardless of the reduced state. */
+export declare function evaluate(spec: RulePredicate, rows: OracleRow[]): DetectorResult;
+/**
+ * Wrap a predicate into an engine Detector. `rows` is injectable for tests;
+ * production reads the memoized real oracle. The `run(tree)` ARGUMENT IS IGNORED
+ * — the tree is .ts-only and does not carry the CSV.
+ */
+export declare function makeOracleDetector(spec: RulePredicate, rowsProvider?: () => OracleRow[]): Detector;
+/** verbs that write (used by writer-authority / verb reasoning). */
+export declare const WRITE_VERBS: Set<string>;
+/** verbs that list/search (retrieval + pagination rules apply). */
+export declare const LIST_VERBS: Set<string>;
+export declare function isMcpPublic(row: OracleRow): boolean;
+/** placeholder tokens that are a declared-but-empty answer. */
+export declare function isPlaceholder(v: string): boolean;

package/dist/detectors/shared.js

@@ -0,0 +1,103 @@
+import { isInventoryRow, readOracle } from "../oracle.js";
+/** Run a predicate over a row set, tallying per-kind. */
+export function tally(spec, rows) {
+    const t = { conform: 0, violate: 0, cnj: 0, na: 0, violations: [], unjudged: [] };
+    for (const row of rows) {
+        // a malformed row is the third state before the predicate ever runs.
+        if (row.malformed) {
+            t.cnj++;
+            t.unjudged.push({ row, note: row.malformed });
+            continue;
+        }
+        if (!isInventoryRow(row)) {
+            t.na++;
+            continue;
+        }
+        const v = spec.classify(row, rows);
+        if (v.kind === "conform")
+            t.conform++;
+        else if (v.kind === "na")
+            t.na++;
+        else if (v.kind === "violate") {
+            t.violate++;
+            t.violations.push({ row, note: v.note ?? "violation" });
+        }
+        else {
+            t.cnj++;
+            t.unjudged.push({ row, note: v.note ?? "could not judge" });
+        }
+    }
+    return t;
+}
+function anchorFor(rows, fallback) {
+    if (rows.length === 0)
+        return fallback;
+    const first = rows.slice(0, 3).map((r) => `row#${r.row.n}`);
+    return `oracle:${first.join(",")}${rows.length > 3 ? ",…" : ""}`;
+}
+/** Aggregate a tally into ONE engine DetectorResult.
+ *
+ * Precedence: any could-not-judge row makes the whole detector abstain (an
+ * abstain is never a silent pass); else any violation is non-conforming; else
+ * present. Every verdict carries the FULL breakdown so a reader sees the four
+ * counts regardless of the reduced state. */
+export function evaluate(spec, rows) {
+    const t = tally(spec, rows);
+    const applicable = t.conform + t.violate + t.cnj;
+    const breakdown = `[applicable=${applicable} conform=${t.conform} non-conforming=${t.violate} could-not-judge=${t.cnj}]`;
+    if (t.cnj > 0) {
+        const reason = `${spec.ruleId}: ${t.cnj} oracle row(s) could not be judged — ${t.unjudged
+            .slice(0, 3)
+            .map((u) => `row#${u.row.n} (${u.note})`)
+            .join("; ")}. This is NOT a clean bill. ${breakdown}`;
+        return {
+            id: spec.id,
+            anchor: anchorFor(t.unjudged, "oracle:vp-by-tool-day158.csv"),
+            state: "could-not-judge",
+            verdict: reason,
+            reason,
+        };
+    }
+    if (t.violate > 0) {
+        const examples = t.violations
+            .slice(0, 3)
+            .map((v) => `row#${v.row.n} "${v.row.by.outil || v.row.by.table}" — ${v.note}`)
+            .join("; ");
+        return {
+            id: spec.id,
+            anchor: anchorFor(t.violations, "oracle:vp-by-tool-day158.csv"),
+            state: "non-conforming",
+            verdict: `${spec.ruleId}: ${t.violate} of ${applicable} applicable oracle rows VIOLATE (${spec.check}). ${breakdown} Examples: ${examples}.`,
+        };
+    }
+    return {
+        id: spec.id,
+        anchor: "oracle:vp-by-tool-day158.csv",
+        state: "present",
+        verdict: `${spec.ruleId}: ${t.conform} applicable oracle rows conform (${spec.check}); 0 violations. ${breakdown}`,
+    };
+}
+/**
+ * Wrap a predicate into an engine Detector. `rows` is injectable for tests;
+ * production reads the memoized real oracle. The `run(tree)` ARGUMENT IS IGNORED
+ * — the tree is .ts-only and does not carry the CSV.
+ */
+export function makeOracleDetector(spec, rowsProvider = readOracle) {
+    return {
+        id: spec.id,
+        run: () => evaluate(spec, rowsProvider()),
+    };
+}
+// ---- small shared classifiers over oracle vocabulary --------------------
+/** verbs that write (used by writer-authority / verb reasoning). */
+export const WRITE_VERBS = new Set(["CREATE", "UPDATE", "DELETE", "TRANSITION", "UPSERT", "BULK-WRITE"]);
+/** verbs that list/search (retrieval + pagination rules apply). */
+export const LIST_VERBS = new Set(["READ-LIST", "SEARCH"]);
+export function isMcpPublic(row) {
+    return row.by.surface === "MCP-public";
+}
+/** placeholder tokens that are a declared-but-empty answer. */
+export function isPlaceholder(v) {
+    const t = v.trim().toLowerCase();
+    return t === "" || t === "tbd" || t === "?" || t === "~" || t === "n/a";
+}

package/dist/detectors/source/_scan.d.ts

@@ -0,0 +1,43 @@
+import type { Detector, DetectorResult, Tree } from "../../engine-types.js";
+/** The standard both wave-2 files are pinned against (short hash a9d7877b). */
+export declare const SOURCE_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) \u00A715";
+export type SrcFile = Tree["files"][number];
+export type SrcLine = SrcFile["lines"][number];
+/** A registrable entry — structurally the RegistryEntry the orchestrator spreads
+ * into REGISTRY. We do NOT import registry.ts; we mirror its shape so the
+ * orchestrator owns the integration. */
+export interface SourceDetectorEntry {
+    detector: Detector;
+    ruleId: string;
+    standardPin: string;
+}
+export interface Site {
+    rel: string;
+    n: number;
+    note: string;
+}
+export interface Scan {
+    conform: Site[];
+    violate: Site[];
+    cnj: Site[];
+}
+export declare function emptyScan(): Scan;
+/** basename of a `rel` path, lower-cased. */
+export declare function base(rel: string): string;
+/** a source file we should judge — never a test or generated file. */
+export declare function isJudgeable(f: SrcFile): boolean;
+/** an EXECUTING line (not a comment-only line). Predicates read code, not prose —
+ * this is what makes the neuter-proof land on an executing line. */
+export declare function code(l: SrcLine): boolean;
+/** convex/ or mcp-server/src source. */
+export declare function isConvexOrMcp(f: SrcFile): boolean;
+/**
+ * Reduce a scan to ONE engine DetectorResult. Precedence for the SOURCE kind:
+ * a concrete VIOLATION site is decisive (non-conforming) and outranks an
+ * abstain; else any could-not-judge → could-not-judge WITH a reason; else any
+ * conform → present; else (zero applicable sites) → could-not-judge naming the
+ * empty scan (an instrument that matched nothing has NOT certified a clean bill).
+ */
+export declare function decide(ruleId: string, id: string, check: string, scan: Scan, emptyReason: string): DetectorResult;
+/** wrap a files-scan into a Detector that reads `tree.files`. */
+export declare function srcDetector(ruleId: string, id: string, check: string, scanFn: (files: SrcFile[]) => Scan, emptyReason: string): Detector;

package/dist/detectors/source/_scan.js

@@ -0,0 +1,82 @@
+/** The standard both wave-2 files are pinned against (short hash a9d7877b). */
+export const SOURCE_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) §15";
+export function emptyScan() {
+    return { conform: [], violate: [], cnj: [] };
+}
+/** basename of a `rel` path, lower-cased. */
+export function base(rel) {
+    return (rel.split("/").pop() ?? rel).toLowerCase();
+}
+/** a source file we should judge — never a test or generated file. */
+export function isJudgeable(f) {
+    const b = base(f.rel);
+    return (!b.endsWith(".test.ts") &&
+        !f.rel.includes("__tests__") &&
+        !f.rel.includes("_generated/"));
+}
+/** an EXECUTING line (not a comment-only line). Predicates read code, not prose —
+ * this is what makes the neuter-proof land on an executing line. */
+export function code(l) {
+    return !l.comment;
+}
+/** convex/ or mcp-server/src source. */
+export function isConvexOrMcp(f) {
+    return /(^|\/)convex\//.test(f.rel) || /(^|\/)mcp-server\/src\//.test(f.rel);
+}
+/**
+ * Reduce a scan to ONE engine DetectorResult. Precedence for the SOURCE kind:
+ * a concrete VIOLATION site is decisive (non-conforming) and outranks an
+ * abstain; else any could-not-judge → could-not-judge WITH a reason; else any
+ * conform → present; else (zero applicable sites) → could-not-judge naming the
+ * empty scan (an instrument that matched nothing has NOT certified a clean bill).
+ */
+export function decide(ruleId, id, check, scan, emptyReason) {
+    const nC = scan.conform.length;
+    const nV = scan.violate.length;
+    const nJ = scan.cnj.length;
+    const breakdown = `[conform=${nC} non-conforming=${nV} could-not-judge=${nJ}]`;
+    const fmt = (s) => s
+        .slice(0, 3)
+        .map((x) => `${x.rel}:${x.n} (${x.note})`)
+        .join("; ");
+    if (nV > 0) {
+        return {
+            id,
+            anchor: `${scan.violate[0].rel}:${scan.violate[0].n}`,
+            state: "non-conforming",
+            verdict: `${ruleId}: ${nV} site(s) VIOLATE (${check}). ${breakdown} Violations: ${fmt(scan.violate)}.${nC ? ` Conform site(s): ${fmt(scan.conform)}.` : ""}`,
+        };
+    }
+    if (nJ > 0) {
+        const reason = `${ruleId}: ${nJ} site(s) could not be judged — ${fmt(scan.cnj)}. This is NOT a clean bill. ${breakdown}`;
+        return {
+            id,
+            anchor: `${scan.cnj[0].rel}:${scan.cnj[0].n}`,
+            state: "could-not-judge",
+            verdict: reason,
+            reason,
+        };
+    }
+    if (nC > 0) {
+        return {
+            id,
+            anchor: `${scan.conform[0].rel}:${scan.conform[0].n}`,
+            state: "present",
+            verdict: `${ruleId}: ${nC} applicable site(s) conform (${check}); 0 violations. ${breakdown} Conform: ${fmt(scan.conform)}.`,
+        };
+    }
+    return {
+        id,
+        anchor: "source:no-applicable-site",
+        state: "could-not-judge",
+        verdict: emptyReason,
+        reason: emptyReason,
+    };
+}
+/** wrap a files-scan into a Detector that reads `tree.files`. */
+export function srcDetector(ruleId, id, check, scanFn, emptyReason) {
+    return {
+        id,
+        run: (tree) => decide(ruleId, id, check, scanFn(tree.files), emptyReason),
+    };
+}

package/dist/detectors/source/backfill.d.ts

@@ -0,0 +1,27 @@
+import type { Detector } from "../../engine-types.js";
+import { type Scan, type SourceDetectorEntry, type SrcFile } from "./_scan.js";
+/** A DERIVED STRUCTURE discovered in the schema: a thin junction / index-bearing
+ * side table whose rows are computed from another table. */
+interface Derived {
+    /** the derived table name. */
+    table: string;
+    /** the source table its rows are computed from (the FK target). */
+    source: string;
+    rel: string;
+    n: number;
+}
+/**
+ * Parse schema.ts defineTable blocks and select the DERIVED STRUCTURES: a thin
+ * side/junction table (≤4 fields) that carries a foreign-key v.id("<other>")
+ * AND is index-bearing. This is the junction / index-bearing side-table class
+ * R-44 names — deliberately NOT a rich domain table (tasks, missions) which
+ * carries many fields, and NOT a table that is its own FK target.
+ */
+export declare function derivedStructures(files: SrcFile[]): Derived[];
+export declare function scanR44(files: SrcFile[]): Scan;
+export declare const R44: Detector;
+export declare function scanR45(files: SrcFile[]): Scan;
+export declare const R45: Detector;
+/** In the form the orchestrator spreads into REGISTRY. */
+export declare const SOURCE_BACKFILL_DETECTORS: SourceDetectorEntry[];
+export {};