@vantageos/backend-doctor 0.1.0

package/dist/detectors/source/writesafety.js

@@ -0,0 +1,345 @@
+import { base, code, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, srcDetector, } from "./_scan.js";
+// ---------------------------------------------------------------------------
+// R-17 — a schema migration is expand-contract: additive + multi-step, never a
+// destructive single-deploy rename a rollback cannot undo. (standard §15 line
+// 113 / detection heuristic line 406: "migration is multi-step additive")
+//
+// SOURCE READ: convex/migrations.ts backfills additively with `ctx.db.patch`
+// (backfillTaskTimes patches startedAt/completedAt at line 41; migrateMemories-
+// Namespace patches `namespace` at 195), and convex/oauthMigrations.ts
+// backfillTokenEndpointAuthMethod patches the new field at line 87 and documents
+// itself "Safe to re-run (idempotent)". PATTERN derived from that source: inside
+// a *migration* file, a DB write that `.patch(`es (additive backfill / dual-write)
+// is the expand-contract step and conforms; a `.replace(` rewrites a whole doc in
+// one deploy and can DROP unlisted fields — the destructive single-step violation.
+// A row-level `.delete(` is data cleanup (test rows), not a schema contract — out
+// of R-17's surface. No `.replace(` exists in a migration file today, so the
+// violation half is exercised by a crafted line.
+// ---------------------------------------------------------------------------
+const MIGRATION_FILE = /migration/i;
+const ADDITIVE_PATCH = /\.patch\s*\(/;
+const DESTRUCTIVE_REPLACE = /\.replace\s*\(/;
+function isMigrationFile(f) {
+    return MIGRATION_FILE.test(base(f.rel));
+}
+export function scanR17(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f) || !isMigrationFile(f))
+            continue;
+        for (const l of f.lines) {
+            if (!code(l))
+                continue;
+            if (DESTRUCTIVE_REPLACE.test(l.raw)) {
+                scan.violate.push({
+                    rel: f.rel,
+                    n: l.n,
+                    note: "migration uses ctx.db.replace — rewrites a whole doc in one deploy, can drop unlisted fields (not expand-contract)",
+                });
+            }
+            else if (ADDITIVE_PATCH.test(l.raw)) {
+                scan.conform.push({
+                    rel: f.rel,
+                    n: l.n,
+                    note: "migration backfills additively with ctx.db.patch (expand-contract migrate step)",
+                });
+            }
+        }
+    }
+    return scan;
+}
+// ---------------------------------------------------------------------------
+// R-18 — a retriable write is idempotent: a duplicate delivery is a no-op, not a
+// second row. (standard §15 line 115 / line 407)
+//
+// SOURCE READ: convex/licenses.ts findOrCreateForGumroad queries `by_gumroadOrderId`
+// `.unique()` (lines 312-317) BEFORE `ctx.db.insert("licenses"` (line 365) — a
+// duplicate sale_id returns the existing row. convex/gumroadWebhook.ts drives it
+// through `findOrCreateForGumroad`. convex/okfBundleNode.ts importOkfBundle takes
+// an `idempotencyKey` arg (line 884) and dedups each row via `findExisting…`
+// before insert. PATTERN: a RETRIABLE file (a webhook / license / bundle-import
+// path a client or job may replay) that INSERTs must carry an idempotency guard
+// somewhere in the file — a unique-key read, an idempotencyKey, or a findOrCreate/
+// findExisting dedup. An insert on a retriable path with no such guard is the
+// violation.
+// ---------------------------------------------------------------------------
+const RETRIABLE_FILE = /webhook|license|okfbundle/i;
+const INSERT_CALL = /ctx\.db\.insert\s*\(/;
+const IDEMPOTENCY_GUARD = /\.unique\s*\(\s*\)|idempotencykey|findorcreate|findexisting|by_gumroadorderid|by_keyhash|deliveryid|delivery_id/i;
+function isRetriableFile(f) {
+    return RETRIABLE_FILE.test(base(f.rel));
+}
+export function scanR18(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f) || !isRetriableFile(f))
+            continue;
+        let insertLine = 0;
+        let guard = false;
+        for (const l of f.lines) {
+            if (!code(l))
+                continue;
+            if (!insertLine && INSERT_CALL.test(l.raw))
+                insertLine = l.n;
+            if (IDEMPOTENCY_GUARD.test(l.raw))
+                guard = true;
+        }
+        if (!insertLine)
+            continue; // no retriable write in this file — nothing to judge here
+        if (guard) {
+            scan.conform.push({
+                rel: f.rel,
+                n: insertLine,
+                note: "retriable insert guarded by an idempotency/unique key (findOrCreate / .unique() / idempotencyKey)",
+            });
+        }
+        else {
+            scan.violate.push({
+                rel: f.rel,
+                n: insertLine,
+                note: "insert on a retriable (webhook/license/import) path with no idempotency guard — a replayed delivery writes a second row",
+            });
+        }
+    }
+    return scan;
+}
+// ---------------------------------------------------------------------------
+// R-29 — an atomic invariant runs in ONE mutation; an action never orchestrates
+// several mutations to fake a transaction. (standard §15 line 262 / line 418)
+//
+// SOURCE READ: convex/okfBundleNode.ts importOkfBundle is a public `action`
+// (line 874) whose handler calls `ctx.runMutation(internal.okfBundle._insert…)`
+// at THREE sites (lines 966, 989, 1014) inside its import loop — memories,
+// briefings, and tasks are inserted across separate transactions, so a mid-loop
+// failure leaves the bundle half-imported. PATTERN: an `action` handler that
+// issues MORE THAN ONE `ctx.runMutation(` orchestrates several mutations where an
+// atomic invariant (the bundle imported wholesale) is implied — flagged
+// non-conforming (judgement: a human confirms the invariant truly needs
+// atomicity). An action with ≤1 runMutation conforms.
+// ---------------------------------------------------------------------------
+const ACTION_OPEN = /export\s+const\s+(\w+)\s*=\s*action\s*\(/;
+const NEXT_EXPORT = /export\s+const\s+\w+\s*=/;
+const RUN_MUTATION = /ctx\.runMutation\s*\(/;
+export function scanR29(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f))
+            continue;
+        let inAction = "";
+        let openLine = 0;
+        let count = 0;
+        let firstMut = 0;
+        const flush = () => {
+            if (!inAction)
+                return;
+            if (count > 1) {
+                scan.violate.push({
+                    rel: f.rel,
+                    n: firstMut || openLine,
+                    note: `action ${inAction} orchestrates ${count} ctx.runMutation calls — several mutations across a race window, not one atomic transaction`,
+                });
+            }
+            else if (count === 1) {
+                scan.conform.push({
+                    rel: f.rel,
+                    n: firstMut,
+                    note: `action ${inAction} issues a single ctx.runMutation — no multi-mutation atomicity gap`,
+                });
+            }
+        };
+        for (const l of f.lines) {
+            if (!code(l))
+                continue;
+            const open = ACTION_OPEN.exec(l.raw);
+            if (open) {
+                flush();
+                inAction = open[1];
+                openLine = l.n;
+                count = 0;
+                firstMut = 0;
+                continue;
+            }
+            if (inAction && NEXT_EXPORT.test(l.raw) && !ACTION_OPEN.test(l.raw)) {
+                flush();
+                inAction = "";
+                continue;
+            }
+            if (inAction && RUN_MUTATION.test(l.raw)) {
+                count++;
+                if (!firstMut)
+                    firstMut = l.n;
+            }
+        }
+        flush();
+    }
+    return scan;
+}
+// ---------------------------------------------------------------------------
+// R-30 — the declared max is OURS, below the platform limit; a bare `.take(n)`
+// with no truncation signal has declared no bound at all. (standard §15 line 264
+// / line 419)
+//
+// SOURCE READ: convex/tasks.ts declares `TASK_LIST_SCAN_CAP = 2000` (line 359)
+// and every wide scan takes `TASK_LIST_SCAN_CAP + 1` (line 625) then throws
+// `SCAN_CAP_EXCEEDED` (line 719) — a named bound with a loud truncation signal.
+// The standard's illustrated violation is REAL and current: convex/dashboard.ts
+// `.take(500)`/`.take(1000)` (lines 65-163), convex/issues.ts (401-403),
+// convex/messages.ts (744), convex/memories.ts (386), convex/missionTemplates.ts
+// (72) are bare numeric literals ≥500 with no truncation signal. PATTERN: a
+// `.take(<identifier>)` or a small literal (<500) is a declared, ours-and-below
+// bound and conforms; a bare `.take(<literal ≥500>)` has merely inherited the
+// platform ceiling and is the violation.
+// ---------------------------------------------------------------------------
+const TAKE_LITERAL = /\.take\s*\(\s*(\d[\d_]*)\s*\)/;
+const BARE_LIMIT = 500;
+export function scanR30(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f))
+            continue;
+        for (const l of f.lines) {
+            if (!code(l))
+                continue;
+            const m = TAKE_LITERAL.exec(l.raw);
+            if (m) {
+                const n = Number(m[1].replace(/_/g, ""));
+                if (n >= BARE_LIMIT) {
+                    scan.violate.push({
+                        rel: f.rel,
+                        n: l.n,
+                        note: `bare .take(${n}) — a fixed numeric literal ≥${BARE_LIMIT} with no named cap or truncation signal; declares no bound of its own`,
+                    });
+                }
+                else {
+                    scan.conform.push({
+                        rel: f.rel,
+                        n: l.n,
+                        note: `.take(${n}) — a small declared max, ours and below the platform ceiling`,
+                    });
+                }
+            }
+            else if (/\.take\s*\(\s*[A-Za-z_]/.test(l.raw)) {
+                // .take(<identifier or expression>) — a NAMED bound (e.g. TASK_LIST_SCAN_CAP + 1, fetchCap).
+                const idx = l.raw.indexOf(".take(");
+                scan.conform.push({
+                    rel: f.rel,
+                    n: l.n,
+                    note: `.take(<named bound>) — a declared constant, not a bare literal (${l.raw.slice(idx, idx + 40).trim()})`,
+                });
+            }
+        }
+    }
+    return scan;
+}
+// ---------------------------------------------------------------------------
+// R-31 — a bulk write beyond one transaction self-schedules in batches:
+// `.take(n)` + `scheduler.runAfter(0, self, …)`. (standard §15 line 266 / 420)
+//
+// SOURCE READ (divergence, reported as R-33's §9a was): convex/tasks.ts
+// bulkComplete (line 2104) is bounded by `BULK_COMPLETE_HARD_CAP = 500` (line
+// 2084), drains one batch, and reports `remaining: true` (lines 2241/2281) so the
+// CALLER calls again to continue — a caller-driven drain, NOT the
+// `scheduler.runAfter(0, self)` self-scheduling the standard names as THE
+// mechanism. bulkComplete NEVER attempts an unbounded write (so it is not a
+// violation), but it does not self-schedule (so it is not a strict conform). The
+// detector reports could-not-judge with that divergence as its machine-readable
+// reason. PATTERN: a `bulk`-named write that pairs a `.take(`/cap with
+// `scheduler.runAfter(0, self)` conforms; one with an unbounded `.collect()`-and-
+// patch-all and no cap/continuation is the violation; a bounded one that
+// continues by a caller-driven `remaining`/`cappedAt` drain instead of
+// self-scheduling is the could-not-judge divergence.
+// ---------------------------------------------------------------------------
+const BULK_FN = /export\s+const\s+(bulk\w*)\s*=\s*(?:internal)?mutation\s*\(/i;
+const NEXT_EXPORT_R31 = /export\s+const\s+\w+\s*=/;
+const SELF_SCHEDULE = /scheduler\.runafter\s*\(\s*0\s*,/i;
+const CAP_TOKEN = /\.take\s*\(|hard_cap|_cap\b|slice\s*\(/i;
+const CALLER_DRAIN = /\bremaining\b|cappedat/i;
+const UNBOUNDED = /\.collect\s*\(\s*\)/;
+export function scanR31(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f))
+            continue;
+        let name = "";
+        let openLine = 0;
+        let selfSched = false;
+        let cap = false;
+        let drain = false;
+        let unbounded = false;
+        const flush = () => {
+            if (!name)
+                return;
+            if (selfSched && cap) {
+                scan.conform.push({
+                    rel: f.rel,
+                    n: openLine,
+                    note: `${name} continues via .take + scheduler.runAfter(0, self) — batched self-scheduling within the transaction limit`,
+                });
+            }
+            else if (unbounded && !cap) {
+                scan.violate.push({
+                    rel: f.rel,
+                    n: openLine,
+                    note: `${name} does an unbounded .collect()-and-write with no cap or continuation — can exceed the per-transaction limit`,
+                });
+            }
+            else if (cap && drain) {
+                scan.cnj.push({
+                    rel: f.rel,
+                    n: openLine,
+                    note: `${name} is bounded (cap + remaining/cappedAt) but continues by a CALLER-DRIVEN drain, not scheduler.runAfter(0, self) — the standard §15:420 names self-scheduling as THE mechanism; the source diverges (bounded, not a violation, but not the named mechanism)`,
+                });
+            }
+            else {
+                scan.cnj.push({
+                    rel: f.rel,
+                    n: openLine,
+                    note: `${name} bulk write — continuation mechanism could not be statically classified (no self-schedule, cap=${cap}, drain=${drain})`,
+                });
+            }
+        };
+        for (const l of f.lines) {
+            if (!code(l))
+                continue;
+            const open = BULK_FN.exec(l.raw);
+            if (open) {
+                flush();
+                name = open[1];
+                openLine = l.n;
+                selfSched = cap = drain = unbounded = false;
+                continue;
+            }
+            if (name && NEXT_EXPORT_R31.test(l.raw) && !BULK_FN.test(l.raw)) {
+                flush();
+                name = "";
+                continue;
+            }
+            if (!name)
+                continue;
+            if (SELF_SCHEDULE.test(l.raw))
+                selfSched = true;
+            if (CAP_TOKEN.test(l.raw))
+                cap = true;
+            if (CALLER_DRAIN.test(l.raw))
+                drain = true;
+            if (UNBOUNDED.test(l.raw))
+                unbounded = true;
+        }
+        flush();
+    }
+    return scan;
+}
+// ---- detectors ------------------------------------------------------------
+export const R17 = srcDetector("R-17", "R-17 migration is expand-contract additive, not a destructive single deploy", "a migration backfills additively with ctx.db.patch, never a whole-doc ctx.db.replace in one deploy", scanR17, "R-17: zero migration files matched in the scanned tree — cannot certify expand-contract migration. NOT a clean bill.");
+export const R18 = srcDetector("R-18", "R-18 retriable write is idempotent", "an insert on a webhook/license/import path carries an idempotency/unique guard", scanR18, "R-18: zero retriable insert sites matched (webhook/license/okfbundle) — cannot certify idempotency. NOT a clean bill.");
+export const R29 = srcDetector("R-29", "R-29 atomic invariant is one mutation, not an action orchestrating writes", "no action issues more than one ctx.runMutation to fake a transaction", scanR29, "R-29: no action handlers matched in the scanned tree — cannot certify single-mutation atomicity. NOT a clean bill.");
+export const R30 = srcDetector("R-30", "R-30 declared max is ours and below the platform limit", "no bare .take(literal>=500) as the only bound; a named cap or a small declared max instead", scanR30, "R-30: no .take(...) sites matched in the scanned tree — cannot certify the declared-bound rule. NOT a clean bill.");
+export const R31 = srcDetector("R-31", "R-31 bulk write self-schedules in batches within the transaction limit", "a bulk write pairs .take with scheduler.runAfter(0, self); a caller-driven drain is a reported divergence", scanR31, "R-31: no bulk-named mutation matched in the scanned tree — cannot certify batched self-scheduling. NOT a clean bill.");
+/** The five, in a form the orchestrator spreads into REGISTRY. */
+export const SOURCE_WRITESAFETY_DETECTORS = [
+    { detector: R17, ruleId: "R-17", standardPin: SOURCE_STANDARD_PIN },
+    { detector: R18, ruleId: "R-18", standardPin: SOURCE_STANDARD_PIN },
+    { detector: R29, ruleId: "R-29", standardPin: SOURCE_STANDARD_PIN },
+    { detector: R30, ruleId: "R-30", standardPin: SOURCE_STANDARD_PIN },
+    { detector: R31, ruleId: "R-31", standardPin: SOURCE_STANDARD_PIN },
+];

package/dist/detectors/standard/_doc.d.ts

@@ -0,0 +1,66 @@
+import type { Detector, DetectorResult } from "../../engine-types.js";
+/** The vendored-fixture basename used as the anchor file for every doc site. */
+export declare const STANDARD_FILE = "backend-standard-51ec7af1.md";
+export declare const VENDORED_STANDARD_PATH: string;
+/** The standard all four are pinned against (short hash a9d7877b). */
+export declare const STANDARD_DOC_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) \u00A714/\u00A711/\u00A710/\u00A73";
+/** Read the vendored standard's raw text. Injectable for tests. */
+export declare function readStandard(path?: string): string;
+export interface DocLine {
+    /** 1-based line number in the vendored file. */
+    n: number;
+    raw: string;
+}
+/** Split the standard text into 1-based numbered lines. */
+export declare function toLines(text: string): DocLine[];
+/**
+ * The lines belonging to a numbered section `## <num>.` — from its header to the
+ * next top-level `## <n>.` header (exclusive). Returns [] when the section is
+ * absent (a finding the caller surfaces, never a silent pass).
+ */
+export declare function sectionLines(lines: DocLine[], num: string): DocLine[];
+export interface DocRow {
+    n: number;
+    cells: string[];
+}
+/** Parse the pipe-table rows in a slice of lines — skipping the header separator
+ * (`|---|`). Each row keeps its 1-based line number so a site anchors to it. */
+export declare function tableRows(lines: DocLine[]): DocRow[];
+/** A placeholder / empty answer — never a real filled value. */
+export declare function isDocPlaceholder(v: string): boolean;
+export interface DocSite {
+    n: number;
+    note: string;
+}
+export interface DocScan {
+    conform: DocSite[];
+    violate: DocSite[];
+    cnj: DocSite[];
+}
+export declare function emptyDocScan(): DocScan;
+/**
+ * Reduce a doc scan to ONE engine DetectorResult. Precedence for the
+ * STANDARD-DOCUMENT kind:
+ *   - any STATIC violation (a source cell outside the known set, an unnamed
+ *     mechanism, a mismatched limit-governed set) is decisive → non-conforming;
+ *   - else any could-not-judge (the delivery-gate / human half surfaced PER
+ *     SITE) → could-not-judge WITH a reason enumerating the sites;
+ *   - else conform-only → present (these gate rules always add a gate cnj, so
+ *     this branch is the pure-static-rule fallback);
+ *   - else (zero applicable rows) → could-not-judge naming the empty scan.
+ *
+ * GREEN IS NOT the detection running — it is the human/gate half surfaced per
+ * site, named and countable (Eta's acceptance property). So on real material,
+ * with the static half clean, these detectors return could-not-judge naming the
+ * concrete sites a human/gate verdict is owed on — never `present`, never
+ * `absent`, while the subject exists in the material.
+ */
+export declare function decideDoc(ruleId: string, id: string, check: string, scan: DocScan, emptyReason: string): DetectorResult;
+/** Wrap a doc-scan into a Detector that ignores the tree and reads the vendored
+ * standard fixture. `textProvider` is injectable for tests. */
+export declare function docDetector(ruleId: string, id: string, check: string, scanFn: (lines: DocLine[]) => DocScan, emptyReason: string, textProvider?: () => string): Detector;
+export interface StandardDocEntry {
+    detector: Detector;
+    ruleId: string;
+    standardPin: string;
+}

package/dist/detectors/standard/_doc.js

@@ -0,0 +1,152 @@
+// Shared STANDARD-DOCUMENT scan primitives for the four process/judgement
+// detectors that read THE STANDARD ITSELF as their material — R-42, R-15, R-32,
+// R-39. Unlike the source-tree detectors (which read convex/ via `tree.files`)
+// and the oracle detectors (which read the CSV), these read the VENDORED standard
+// fixture `fixtures/backend-standard-a9d7877b.md` — the material at the pin. The
+// engine's contract types are DERIVED from engine-types.ts, never re-spelled.
+//
+// THE LAW (the one that caught R-5): every predicate is derived from the ACTUAL
+// text of the vendored standard — the §14 source table, the §11 refinements, the
+// §10 exclusions, the §3 vocabulary — NEVER from a prose illustration of what a
+// rule "should" find.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The vendored-fixture basename used as the anchor file for every doc site. */
+export const STANDARD_FILE = "backend-standard-51ec7af1.md";
+/** The vendored standard at the pin — DATA on the same footing as the oracle CSV.
+ * Resolved locally (not via coverage.ts) so this module carries no import cycle
+ * with registry.ts. Same file coverage.ts's VENDORED_STANDARD_PATH points at. */
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const VENDORED_STANDARD_PATH = join(HERE, "..", "..", "..", "fixtures", STANDARD_FILE);
+/** The standard all four are pinned against (short hash a9d7877b). */
+export const STANDARD_DOC_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) §14/§11/§10/§3";
+/** Read the vendored standard's raw text. Injectable for tests. */
+export function readStandard(path = VENDORED_STANDARD_PATH) {
+    return readFileSync(path, "utf8");
+}
+/** Split the standard text into 1-based numbered lines. */
+export function toLines(text) {
+    return text.split("\n").map((raw, i) => ({ n: i + 1, raw }));
+}
+/**
+ * The lines belonging to a numbered section `## <num>.` — from its header to the
+ * next top-level `## <n>.` header (exclusive). Returns [] when the section is
+ * absent (a finding the caller surfaces, never a silent pass).
+ */
+export function sectionLines(lines, num) {
+    const head = new RegExp(`^##\\s+${num.replace(".", "\\.")}\\.?\\s`);
+    const nextTop = /^##\s+\d+\./;
+    let start = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (start < 0) {
+            if (head.test(lines[i].raw))
+                start = i;
+            continue;
+        }
+        if (nextTop.test(lines[i].raw))
+            return lines.slice(start, i);
+    }
+    return start < 0 ? [] : lines.slice(start);
+}
+/** Parse the pipe-table rows in a slice of lines — skipping the header separator
+ * (`|---|`). Each row keeps its 1-based line number so a site anchors to it. */
+export function tableRows(lines) {
+    const rows = [];
+    for (const l of lines) {
+        const t = l.raw.trim();
+        if (!t.startsWith("|"))
+            continue;
+        if (/^\|[\s|:-]+\|?\s*$/.test(t) && /-/.test(t))
+            continue; // separator row
+        const cells = t
+            .replace(/^\|/, "")
+            .replace(/\|$/, "")
+            .split("|")
+            .map((c) => c.trim());
+        rows.push({ n: l.n, cells });
+    }
+    return rows;
+}
+/** A placeholder / empty answer — never a real filled value. */
+export function isDocPlaceholder(v) {
+    const t = v.trim().toLowerCase();
+    return (t === "" ||
+        t === "tbd" ||
+        t === "?" ||
+        t === "~" ||
+        t === "n/a" ||
+        t === "-" ||
+        t === "—");
+}
+export function emptyDocScan() {
+    return { conform: [], violate: [], cnj: [] };
+}
+/**
+ * Reduce a doc scan to ONE engine DetectorResult. Precedence for the
+ * STANDARD-DOCUMENT kind:
+ *   - any STATIC violation (a source cell outside the known set, an unnamed
+ *     mechanism, a mismatched limit-governed set) is decisive → non-conforming;
+ *   - else any could-not-judge (the delivery-gate / human half surfaced PER
+ *     SITE) → could-not-judge WITH a reason enumerating the sites;
+ *   - else conform-only → present (these gate rules always add a gate cnj, so
+ *     this branch is the pure-static-rule fallback);
+ *   - else (zero applicable rows) → could-not-judge naming the empty scan.
+ *
+ * GREEN IS NOT the detection running — it is the human/gate half surfaced per
+ * site, named and countable (Eta's acceptance property). So on real material,
+ * with the static half clean, these detectors return could-not-judge naming the
+ * concrete sites a human/gate verdict is owed on — never `present`, never
+ * `absent`, while the subject exists in the material.
+ */
+export function decideDoc(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, 4)
+        .map((x) => `${STANDARD_FILE}:${x.n} (${x.note})`)
+        .join("; ");
+    if (nV > 0) {
+        return {
+            id,
+            anchor: `${STANDARD_FILE}:${scan.violate[0].n}`,
+            state: "non-conforming",
+            verdict: `${ruleId}: ${nV} STATIC violation(s) in the standard document (${check}). ${breakdown} Violations: ${fmt(scan.violate)}.${nC ? ` Conform: ${fmt(scan.conform)}.` : ""}`,
+        };
+    }
+    if (nJ > 0) {
+        const reason = `${ruleId}: static half clean (${nC} conform); ${nJ} site(s) owe a human/gate verdict — ${fmt(scan.cnj)}. This is NOT a clean bill: GREEN is the gate half surfaced per site, not the detection running. ${breakdown}`;
+        return {
+            id,
+            anchor: `${STANDARD_FILE}:${scan.cnj[0].n}`,
+            state: "could-not-judge",
+            verdict: reason,
+            reason,
+        };
+    }
+    if (nC > 0) {
+        return {
+            id,
+            anchor: `${STANDARD_FILE}:${scan.conform[0].n}`,
+            state: "present",
+            verdict: `${ruleId}: ${nC} site(s) conform (${check}); 0 violations. ${breakdown} Conform: ${fmt(scan.conform)}.`,
+        };
+    }
+    return {
+        id,
+        anchor: `${STANDARD_FILE}:0`,
+        state: "could-not-judge",
+        verdict: emptyReason,
+        reason: emptyReason,
+    };
+}
+/** Wrap a doc-scan into a Detector that ignores the tree and reads the vendored
+ * standard fixture. `textProvider` is injectable for tests. */
+export function docDetector(ruleId, id, check, scanFn, emptyReason, textProvider = readStandard) {
+    return {
+        id,
+        run: () => decideDoc(ruleId, id, check, scanFn(toLines(textProvider())), emptyReason),
+    };
+}

package/dist/detectors/standard/r41-frontier.d.ts

@@ -0,0 +1,58 @@
+import type { Detector, DetectorResult } from "../../engine-types.js";
+import { type DocLine } from "./_doc.js";
+/** The four frontier prefixes and the sibling document each resolves against. */
+export type Prefix = "S" | "C" | "E" | "A";
+/** prefix → { the sibling fixture basename, its recorded upstream blob hash }.
+ * The blob hash is the PINS.txt record — a vendored document that cannot be
+ * hash-checked is an authority granted to oneself, so the hash travels here and
+ * the integrity test asserts `git hash-object` reproduces it. */
+export declare const SIBLING: Record<Prefix, {
+    file: string;
+    blob: string;
+    label: string;
+}>;
+/** The pin all four siblings are fixed against. */
+export declare const SIBLING_PIN = "the four MCP-standard-family documents @ a74a042b53c71a095ab88b3073bd47728eeda814 (elpiarthera/ElPi-Corp) \u2014 S-/C-/E-/A- defined-id sets";
+/** Absolute path of a sibling fixture. */
+export declare function siblingPath(prefix: Prefix): string;
+/** Read a sibling document's raw text. Injectable for tests (mutation bite). */
+export declare function readSibling(prefix: Prefix): string;
+/**
+ * Every id a sibling document DEFINES — matched by the NUMBERED-LIST-ITEM form
+ * `N. **`X-N` — title.**` (a heading- or `^\*\*`-anchored matcher finds zero).
+ * Returns the set for whatever prefix the file defines; the resolver only ever
+ * asks a file for its own prefix, so a single form suffices.
+ */
+export declare function definedIds(text: string): Set<string>;
+export interface Cite {
+    id: string;
+    prefix: Prefix;
+    n: number;
+}
+/**
+ * Every `S-`/`C-`/`E-`/`A-` identifier CITED in a frontier statement of the
+ * backend standard — DERIVED from the real text by matching the citation form
+ * (a backtick-wrapped id on a line that opens `Frontier — MCP standard.`), never
+ * hardcoded. Deduped per id, keeping the first citing line as its site.
+ */
+export declare function citedIds(lines: DocLine[]): Cite[];
+export interface FrontierResolution {
+    cited: Cite[];
+    /** cited ids that do NOT resolve in their sibling — the dead pointers. */
+    dead: Cite[];
+    /** cited ids that resolve — the conforming sites. */
+    resolved: Cite[];
+    /** the count of defined ids per prefix — for the enumeration proof. */
+    definedCounts: Record<Prefix, number>;
+}
+/** Resolve every cited frontier id against its sibling's defined-id set.
+ * `standardText` and `siblingReader` are injectable for the mutation bite. */
+export declare function resolveFrontier(standardText?: string, siblingReader?: (p: Prefix) => string): FrontierResolution;
+/** Build R-41's single DetectorResult from a resolution. Present when every
+ * cited id resolves; non-conforming on any dead pointer (a red, not a note);
+ * could-not-judge ONLY if an input yields no cited/defined ids at all (an
+ * absent input, not a clean bill). */
+export declare function decideR41(r: FrontierResolution): DetectorResult;
+/** The R-41 detector — ignores the tree; reads the vendored standard + the four
+ * vendored siblings. Fully mechanical, no human half. */
+export declare const R41: Detector;