@vantageos/backend-doctor 0.1.14 → 0.3.0

package/dist/registry.js

@@ -7,7 +7,9 @@ import { PER_ROW_PREDICATES } from "./detectors/predicates.js";
 import { makeOracleDetector } from "./detectors/shared.js";
 import { SOURCE_BACKFILL_DETECTORS } from "./detectors/source/backfill.js";
 import { SOURCE_CONTRACT_DETECTORS } from "./detectors/source/contract.js";
+import { SOURCE_CROSS_TENANT_WRITE_DETECTORS } from "./detectors/source/cross-tenant-write.js";
 import { IDENTITY_DETECTORS } from "./detectors/source/identity.js";
+import { SOURCE_IDENTITY_BY_ID_DETECTORS } from "./detectors/source/identity-by-id.js";
 import { SOURCE_ISOLATION_DETECTORS } from "./detectors/source/isolation.js";
 import { SOURCE_JOBS_DETECTORS } from "./detectors/source/jobs.js";
 import { SOURCE_LIFECYCLE_DETECTORS } from "./detectors/source/lifecycle.js";
@@ -20,8 +22,46 @@ import { R41, SIBLING_PIN } from "./detectors/standard/r41-frontier.js";
 import { R46_STANDARD_PIN, STANDARD_SOURCE_DETECTORS, } from "./detectors/standard/r46-returns-validator.js";
 import { STANDARD_DOC_DETECTORS } from "./detectors/standard/standard-doc.js";
 import { makeR14, makeR38 } from "./detectors/structural.js";
+import { STATE_RANK } from "./state-rank.js";
+import { countOf, sumCounts, withCount } from "./violation-count.js";
 /** The standard both pins the whole wave against. */
-export const STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ 4bcd605656ceff52d4f1593a9176cd6b988471be (elpiarthera/ElPi-Corp)";
+export const STANDARD_PIN = "vantagepeers/backend-standard/backend-standard.md @ 2825122a3ab1e4ddb4b955cfb136b7e8ab04f8f3 (elpiarthera/ElPi-Corp, merge of PR #228 on origin/main, after #226 at 9f7d789)";
+/**
+ * Merge two detectors that judge halves of the SAME rule into one result: the
+ * worst state wins (non-conforming > could-not-judge > absent > present, the
+ * tally's own ranking), the anchor is the deciding half's, the title is the LATER
+ * (refined) half's, and both halves' verdicts are kept — nothing is dropped.
+ */
+export function mergeHalves(ruleId, a, b) {
+    return {
+        id: b.id,
+        run: (tree) => {
+            const ra = a.run(tree);
+            const rb = b.run(tree);
+            const decider = STATE_RANK[ra.state] > STATE_RANK[rb.state] ? ra : rb;
+            const verdict = `${ruleId} (two halves, worst wins): [${ra.id}] ${ra.state} — ${ra.verdict} || [${rb.id}] ${rb.state} — ${rb.verdict}`;
+            const reasons = [ra, rb]
+                .filter((r) => r.state === "could-not-judge")
+                .map((r) => r.reason ?? r.verdict);
+            const merged = {
+                id: b.id,
+                anchor: decider.anchor,
+                state: decider.state,
+                verdict,
+                ...(decider.state === "could-not-judge"
+                    ? { reason: reasons.join(" || ") }
+                    : {}),
+            };
+            // The per-rule count of a red merge is the sum over its RED halves — the
+            // halves whose `N site(s) VIOLATE` the merged verdict prints. An abstaining
+            // half contributes nothing; a red half with no count leaves it uncounted.
+            if (merged.state !== "non-conforming")
+                return merged;
+            const c = sumCounts([ra, rb].filter((r) => r.state === "non-conforming").map(countOf));
+            return c === undefined ? merged : withCount(merged, c);
+        },
+    };
+}
 export const REGISTRY = [
     ...PER_ROW_PREDICATES.map((spec) => ({
         detector: makeOracleDetector(spec),
@@ -31,7 +71,9 @@ export const REGISTRY = [
     { detector: makeR14(), ruleId: "R-14", standardPin: STANDARD_PIN },
     { detector: makeR38(), ruleId: "R-38", standardPin: STANDARD_PIN },
     // Axis-2 coherence detectors (R-7/R-8/R-37): each performs its mechanical half
-    // IN FULL and returns could-not-judge, naming the sites a human verdict is owed.
+    // IN FULL and decides on the written justification token's PRESENCE in the
+    // remediation cell (task k179jnhx, §23) — non-conforming without the token,
+    // present with it; could-not-judge only on a row the instrument cannot read.
     {
         detector: makeOracleDetector(r7),
         ruleId: "R-7",
@@ -51,7 +93,7 @@ export const REGISTRY = [
     {
         detector: makeR40(),
         ruleId: "R-40",
-        standardPin: `${STANDARD_PIN} + oracle:vr-by-tool-day159.csv @ a74a042b`,
+        standardPin: `${STANDARD_PIN} + second-backend oracle derived from the target (vr-by-tool.csv / --vr-oracle)`,
     },
     // The twenty source-tree detectors (built all at once — the wave plan cancelled).
     // Each reads the REAL convex/ source; R-6/R-16 also carry a live half. Their
@@ -115,17 +157,41 @@ export const REGISTRY = [
         // documents a client contract; a gated customMutation wrapper (writeMutation) is
         // refused (could-not-judge) since client reachability is not visible from convex/.
         ...SOURCE_WRITE_ISOLATION_DETECTORS,
+        // R-52 — a write that reaches a row carrying no tenant value through a
+        // caller-choosable key (an argument, or a stored field the caller set
+        // through a public write) is dominated by a guard reading a server-stamped
+        // tenant. Reads schema.ts tenant columns and every public mutation/action
+        // handler on the AST (the vantage-peers 45e40c8 tasks.complete auto-link).
+        ...SOURCE_CROSS_TENANT_WRITE_DETECTORS,
+        // R-53 — an actor and a target are identified by ID through
+        // @vantageos/cloud-identity: per public write door, the principal's
+        // source (a), the admission predicate (b), the unresolved branch (c);
+        // per helper / MCP gate, a local identity layer (d). Reads convex/ and
+        // mcp-server/src (the PR #1464 ten doors + org-less bulk_complete path).
+        ...SOURCE_IDENTITY_BY_ID_DETECTORS,
         ...SOURCE_CONTRACT_DETECTORS,
         ...IDENTITY_DETECTORS,
         // The four STANDARD-DOCUMENT detectors (R-42/R-15/R-32/R-39): each reads the
         // VENDORED standard itself, performs its mechanical/static half in full, and
         // returns could-not-judge naming the sites a human/gate verdict is owed on.
         ...STANDARD_DOC_DETECTORS,
-    ].map((e) => ({
-        detector: e.detector,
-        ruleId: e.ruleId,
-        standardPin: STANDARD_PIN,
-    })),
+    ].reduce((acc, e) => {
+        // ONE result per rule. Two modules carry an R-31 half (writesafety: the
+        // bulk-WRITE self-schedule; readbudget: the refined read+write budget), and
+        // both used to print as two R-31 rows under two different titles. They are
+        // merged into one row titled by the refined standard text (4bcd605 :266).
+        const prev = acc.find((x) => x.ruleId === e.ruleId);
+        if (prev) {
+            prev.detector = mergeHalves(e.ruleId, prev.detector, e.detector);
+            return acc;
+        }
+        acc.push({
+            detector: e.detector,
+            ruleId: e.ruleId,
+            standardPin: STANDARD_PIN,
+        });
+        return acc;
+    }, []),
     // R-41 — the ONE fully-mechanical rule of the nine: it reads the backend
     // standard's §9 frontier AND the four vendored MCP-family siblings, resolving
     // every cited S-/C-/E-/A- id against its sibling's defined-id set. present when

package/dist/report.d.ts

@@ -17,6 +17,8 @@ export interface ReportContext {
      * bit a reviewer). Empty string means a clean tree.
      */
     treeStatus: string;
+    /** which oracle files the run used and where each came from (describeOracle). Optional so older callers still compile. */
+    oracle?: string;
 }
 /** Derive the committed report path from the target basename + the run date. */
 export declare function reportPath(target: string, dateISO: string, dir: string): string;
@@ -32,4 +34,12 @@ export declare function buildReport(ctx: ReportContext, results: DetectorResult[
  * <dir> if needed. Returns the absolute path written. The caller (CLI) supplies the
  * ReportContext (clock + git) and the computed tally/verdict.
  */
-export declare function writeReport(ctx: ReportContext, results: DetectorResult[], t: Tally, v: Verdict, dir: string, severity?: Map<string, Severity>): string;
+export declare function writeReport(ctx: ReportContext, results: DetectorResult[], t: Tally, v: Verdict, dir: string, severity?: Map<string, Severity>, 
+/**
+ * Doctor-owned sections appended VERBATIM after the rule tables, each in its
+ * own fence. CR-1 renders through here: its contract is that every member of
+ * every class is NAMED, and the truncation that hid thirteen of fourteen
+ * violations is the defect that contract exists not to repeat — so this
+ * carries the section's own text rather than re-deriving or summarising it.
+ */
+extraSections?: string[]): string;

package/dist/report.js

@@ -94,6 +94,7 @@ export function buildReport(ctx, results, t, v, severity = deriveSeverityMap())
 - **target commit**: \`${ctx.targetCommit}\`
 - **standard commit** (pinned): \`${STANDARD_SHA}\`
 - **tool version**: \`${ctx.toolVersion}\`
+- **oracle**: ${ctx.oracle ?? "(not recorded)"}
 - **run date**: ${ctx.dateISO}
 - **machine tally**: \`${tallyLine(t)}\`
 - **verdict**: ${v.summary}
@@ -130,9 +131,21 @@ ${present.length === 0 ? "_none._" : present.join(", ")}
  * <dir> if needed. Returns the absolute path written. The caller (CLI) supplies the
  * ReportContext (clock + git) and the computed tally/verdict.
  */
-export function writeReport(ctx, results, t, v, dir, severity = deriveSeverityMap()) {
+export function writeReport(ctx, results, t, v, dir, severity = deriveSeverityMap(), 
+/**
+ * Doctor-owned sections appended VERBATIM after the rule tables, each in its
+ * own fence. CR-1 renders through here: its contract is that every member of
+ * every class is NAMED, and the truncation that hid thirteen of fourteen
+ * violations is the defect that contract exists not to repeat — so this
+ * carries the section's own text rather than re-deriving or summarising it.
+ */
+extraSections = []) {
     mkdirSync(dir, { recursive: true });
     const path = reportPath(ctx.target, ctx.dateISO, dir);
-    writeFileSync(path, buildReport(ctx, results, t, v, severity), "utf8");
+    const body = [
+        buildReport(ctx, results, t, v, severity),
+        ...extraSections.map((sec) => `\n\n\`\`\`\n${sec}\n\`\`\`\n`),
+    ].join("");
+    writeFileSync(path, body, "utf8");
     return path;
 }

package/dist/rule-class.d.ts

@@ -0,0 +1,85 @@
+import type { State } from "./engine-types.js";
+export declare const RULE_CLASS_PATH: string;
+export type GateClass = "mechanical" | "judgement";
+export interface RuleClassFile {
+    standard_sha: string;
+    standard_kind_to_class: Record<string, string>;
+    rules: Record<string, {
+        class: string;
+        basis: string;
+    }>;
+}
+export declare function loadRuleClassFile(path?: string): RuleClassFile;
+/**
+ * The build kind the PINNED STANDARD itself states per rule: every row of the
+ * section 15 table (`| R-N | mechanical|judgement|process | … |`), then, for a rule the
+ * table does not list, the `*kind:* <word>` token inside that rule's own text (up
+ * to the next rule definition). A rule the standard classifies nowhere is absent
+ * from the map — classifyRules reports it as unclassified.
+ */
+export declare function parseStandardKinds(path?: string): Map<string, string>;
+export interface Unclassified {
+    id: string;
+    reason: string;
+}
+export interface Classification {
+    classOf: Map<string, GateClass>;
+    basisOf: Map<string, string>;
+    /** could-not-judge: rules the classification cannot place. Never defaulted. */
+    unclassified: Unclassified[];
+    /** sidecar entries naming no rule of this run — reported, a stale sidecar. */
+    stale: string[];
+}
+/**
+ * Place every id in exactly one class, or name it unclassified with its reason.
+ * `ids` is the derived rule set PLUS the doctor-owned ids (CR-1). An R- id is
+ * cross-checked against the standard; a non-R id (CR-1) is not in the standard and
+ * stands on the sidecar alone.
+ */
+export declare function classifyRules(ids: readonly string[], file?: RuleClassFile, standardKinds?: Map<string, string>, standardSha?: string): Classification;
+export interface MechanicalCount {
+    /** the gate's count, or `null` when it cannot be certified (could-not-judge). */
+    count: number | null;
+    mechanicalViolations: string[];
+    judgementViolations: string[];
+    /** could-not-judge rule states — NOT violations; reported, never folded into 0. */
+    mechanicalAbstentions: string[];
+    judgementAbstentions: string[];
+    unclassified: Unclassified[];
+    /** every reason the count is null (empty when it is an integer). */
+    cannotCertify: string[];
+}
+/**
+ * Count the non-conforming rules whose class is mechanical. The count is `null`
+ * — never 0 — when any rule is unclassified (its violation, present or future,
+ * could be mechanical) or when the instrument names a self-defect that voids the
+ * run (`instrumentDefects`, e.g. incomplete coverage or a dirty judged tree).
+ */
+export declare function countMechanical(ruleState: ReadonlyMap<string, State>, classification: Classification, instrumentDefects?: readonly string[]): MechanicalCount;
+/** The human line printed next to the VERDICT line. */
+export declare function mechanicalLine(m: MechanicalCount): string;
+/** The deploy hook's evidence schema, key for key and nothing else. */
+export interface Evidence {
+    sha: string;
+    cli_commit: string;
+    convex_path: string;
+    exit_code: number;
+    checked: number;
+    total: number;
+    mechanical_violations: number | null;
+    /**
+     * Each RED mechanical rule -> the non-conforming count its report line prints
+     * (sites for a source rule, rows for an oracle rule). Its key count equals
+     * `mechanical_violations`; null whenever that is null or a red rule carries no
+     * count (src/violation-count.ts). Additive: the seven keys above are unchanged.
+     */
+    mechanical_rule_counts: Record<string, number> | null;
+    /**
+     * Per site-based red mechanical rule: module -> count, where a convex/ file's
+     * module is its basename without extension and any other file's is its path
+     * without extension (`mcp-server/src/tools`). Values sum to that rule's
+     * `mechanical_rule_counts` entry. Row-based rules are absent. Null with the above.
+     */
+    mechanical_rule_module_counts: Record<string, Record<string, number>> | null;
+}
+export declare function buildEvidence(e: Evidence): Evidence;

package/dist/rule-class.js

@@ -0,0 +1,218 @@
+// The GATE CLASS of every rule — mechanical or judgement — and the one count the
+// deploy gate refuses on: `mechanical_violations`.
+//
+// The vantage-peers deploy hook (`enforce-backend-doctor-before-deploy.py`) reads
+// `qa/backend-doctor-<sha>.json` and refuses ONLY on mechanical non-conformance,
+// never on a judgement/process rule. This module is where that distinction is made,
+// and it is made from DATA, never from TS logic:
+//
+//   - the per-rule class lives in the sidecar `fixtures/rule-classes-<pin>.json`
+//     (one entry per numbered rule plus CR-1, each with a one-phrase basis);
+//   - every R- entry is CROSS-CHECKED against the pinned standard's own build kind
+//     (the section 15 "Build kind" column, and the `*kind:*` token of a Detector spec
+//     for a rule the table does not list — R-50/R-51), through the sidecar's
+//     `standard_kind_to_class` vocabulary (`process` -> judgement);
+//   - a rule with no entry, an entry outside the two classes, an entry with no
+//     basis, a rule the standard gives no build kind, or a sidecar class that
+//     DISAGREES with the standard is UNCLASSIFIED — a could-not-judge. It is never
+//     defaulted to either class; the count it would feed becomes `null`.
+//
+// COUNT GRANULARITY — by RULE, the same granularity as the TALLY and the VERDICT
+// line: a rule whose reduced state is `non-conforming` is one violation, however
+// many sites it names. CR-1 (doctor-owned, outside the pinned rule set) counts as
+// one rule.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { STANDARD_SHA, VENDORED_STANDARD_PATH } from "./coverage.js";
+const here = dirname(fileURLToPath(import.meta.url));
+export const RULE_CLASS_PATH = join(here, "..", "fixtures", "rule-classes-2825122.json");
+const GATE_CLASSES = new Set(["mechanical", "judgement"]);
+export function loadRuleClassFile(path = RULE_CLASS_PATH) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+/**
+ * The build kind the PINNED STANDARD itself states per rule: every row of the
+ * section 15 table (`| R-N | mechanical|judgement|process | … |`), then, for a rule the
+ * table does not list, the `*kind:* <word>` token inside that rule's own text (up
+ * to the next rule definition). A rule the standard classifies nowhere is absent
+ * from the map — classifyRules reports it as unclassified.
+ */
+export function parseStandardKinds(path = VENDORED_STANDARD_PATH) {
+    const blob = readFileSync(path, "utf8");
+    const out = new Map();
+    const start = blob.indexOf("## 15. Build column");
+    if (start !== -1) {
+        const after = blob.indexOf("\n## ", start + 1);
+        const section = blob.slice(start, after === -1 ? undefined : after);
+        for (const line of section.split("\n")) {
+            const m = /^\|\s*(R-\d+)\s*\|\s*(mechanical|judgement|process)\s*\|/.exec(line);
+            if (m)
+                out.set(m[1], m[2]);
+        }
+    }
+    // Detector-spec `*kind:*` for rules outside the table (none at 2825122: the table lists all 52; kept for a future rule defined outside it).
+    const lines = blob.split("\n");
+    let current;
+    for (const line of lines) {
+        const def = /^\*\*(R-\d+)\b/.exec(line);
+        if (def)
+            current = def[1];
+        if (current === undefined || out.has(current))
+            continue;
+        const k = /\*kind:\*\s*(mechanical|judgement|process)\b/.exec(line);
+        if (k)
+            out.set(current, k[1]);
+    }
+    return out;
+}
+/**
+ * Place every id in exactly one class, or name it unclassified with its reason.
+ * `ids` is the derived rule set PLUS the doctor-owned ids (CR-1). An R- id is
+ * cross-checked against the standard; a non-R id (CR-1) is not in the standard and
+ * stands on the sidecar alone.
+ */
+export function classifyRules(ids, file = loadRuleClassFile(), standardKinds = parseStandardKinds(), standardSha = STANDARD_SHA) {
+    const classOf = new Map();
+    const basisOf = new Map();
+    const unclassified = [];
+    const pinMismatch = file.standard_sha !== standardSha
+        ? `sidecar is pinned to standard ${String(file.standard_sha).slice(0, 12)}, the instrument to ${standardSha.slice(0, 12)}`
+        : undefined;
+    for (const id of ids) {
+        if (pinMismatch) {
+            unclassified.push({ id, reason: pinMismatch });
+            continue;
+        }
+        const entry = file.rules?.[id];
+        if (entry === undefined) {
+            unclassified.push({ id, reason: "no class in the sidecar" });
+            continue;
+        }
+        if (!GATE_CLASSES.has(entry.class)) {
+            unclassified.push({
+                id,
+                reason: `sidecar class ${JSON.stringify(entry.class)} is neither mechanical nor judgement`,
+            });
+            continue;
+        }
+        if (typeof entry.basis !== "string" || entry.basis.trim() === "") {
+            unclassified.push({
+                id,
+                reason: "sidecar class carries no basis phrase",
+            });
+            continue;
+        }
+        if (/^R-\d+$/.test(id)) {
+            const kind = standardKinds.get(id);
+            if (kind === undefined) {
+                unclassified.push({
+                    id,
+                    reason: "the pinned standard states no build kind for this rule",
+                });
+                continue;
+            }
+            const expected = file.standard_kind_to_class?.[kind];
+            if (expected !== entry.class) {
+                unclassified.push({
+                    id,
+                    reason: `sidecar says ${entry.class}, the pinned standard says ${kind} (-> ${expected ?? "no mapping"}) — CONFLICT`,
+                });
+                continue;
+            }
+        }
+        classOf.set(id, entry.class);
+        basisOf.set(id, entry.basis);
+    }
+    const wanted = new Set(ids);
+    const stale = Object.keys(file.rules ?? {}).filter((id) => !wanted.has(id));
+    return { classOf, basisOf, unclassified, stale };
+}
+const byRuleId = (a, b) => {
+    const prefix = (s) => s.replace(/\d+$/, "");
+    const n = (s) => Number(/\d+$/.exec(s)?.[0] ?? 0);
+    return prefix(a).localeCompare(prefix(b)) || n(a) - n(b);
+};
+/**
+ * Count the non-conforming rules whose class is mechanical. The count is `null`
+ * — never 0 — when any rule is unclassified (its violation, present or future,
+ * could be mechanical) or when the instrument names a self-defect that voids the
+ * run (`instrumentDefects`, e.g. incomplete coverage or a dirty judged tree).
+ */
+export function countMechanical(ruleState, classification, instrumentDefects = []) {
+    const out = {
+        count: null,
+        mechanicalViolations: [],
+        judgementViolations: [],
+        mechanicalAbstentions: [],
+        judgementAbstentions: [],
+        unclassified: classification.unclassified,
+        cannotCertify: [...instrumentDefects],
+    };
+    const unclassifiedIds = new Set(classification.unclassified.map((u) => u.id));
+    for (const [id, state] of ruleState) {
+        const cls = classification.classOf.get(id);
+        if (cls === undefined) {
+            if (!unclassifiedIds.has(id)) {
+                out.unclassified = [
+                    ...out.unclassified,
+                    {
+                        id,
+                        reason: "a result exists for a rule the classification never saw",
+                    },
+                ];
+                unclassifiedIds.add(id);
+            }
+            continue;
+        }
+        if (state === "non-conforming") {
+            (cls === "mechanical"
+                ? out.mechanicalViolations
+                : out.judgementViolations).push(id);
+        }
+        else if (state === "could-not-judge") {
+            (cls === "mechanical"
+                ? out.mechanicalAbstentions
+                : out.judgementAbstentions).push(id);
+        }
+    }
+    for (const list of [
+        out.mechanicalViolations,
+        out.judgementViolations,
+        out.mechanicalAbstentions,
+        out.judgementAbstentions,
+    ])
+        list.sort(byRuleId);
+    if (out.unclassified.length > 0) {
+        out.cannotCertify.push(`${out.unclassified.length} rule(s) unclassified: ${out.unclassified.map((u) => `${u.id} (${u.reason})`).join("; ")}`);
+    }
+    if (out.cannotCertify.length === 0)
+        out.count = out.mechanicalViolations.length;
+    return out;
+}
+/** The human line printed next to the VERDICT line. */
+export function mechanicalLine(m) {
+    const head = m.count === null
+        ? "MECHANICAL VIOLATIONS: COULD-NOT-JUDGE (no count certified; the evidence file records null)"
+        : `MECHANICAL VIOLATIONS: ${m.count}`;
+    const list = (ids) => (ids.length ? ids.join(", ") : "none");
+    const lines = [
+        `${head} — mechanical [${list(m.mechanicalViolations)}]; judgement violations (printed, not counted) [${list(m.judgementViolations)}]; abstentions (not violations, not 0): mechanical [${list(m.mechanicalAbstentions)}], judgement [${list(m.judgementAbstentions)}]`,
+    ];
+    for (const why of m.cannotCertify)
+        lines.push(`  CANNOT CERTIFY: ${why}`);
+    return lines.join("\n");
+}
+export function buildEvidence(e) {
+    return {
+        sha: e.sha,
+        cli_commit: e.cli_commit,
+        convex_path: e.convex_path,
+        exit_code: e.exit_code,
+        checked: e.checked,
+        total: e.total,
+        mechanical_violations: e.mechanical_violations,
+        mechanical_rule_counts: e.mechanical_rule_counts,
+        mechanical_rule_module_counts: e.mechanical_rule_module_counts,
+    };
+}

package/dist/state-rank.d.ts

@@ -0,0 +1,5 @@
+import type { State } from "./engine-types.js";
+/** The four states, worst highest — every reduction (tally, a merged rule) picks
+ * the worst. A module of its own so registry.ts can use it without a cycle
+ * through tally -> coverage -> registry. */
+export declare const STATE_RANK: Record<State, number>;

package/dist/state-rank.js

@@ -0,0 +1,9 @@
+/** The four states, worst highest — every reduction (tally, a merged rule) picks
+ * the worst. A module of its own so registry.ts can use it without a cycle
+ * through tally -> coverage -> registry. */
+export const STATE_RANK = {
+    "non-conforming": 3,
+    "could-not-judge": 2,
+    absent: 1,
+    present: 0,
+};

package/dist/tally.d.ts

@@ -23,7 +23,7 @@ export interface Verdict {
     exitCode: number;
     /** non-conforming rules bucketed by severity. */
     violations: Record<Severity, string[]>;
-    /** could-not-judge rules bucketed by severity — abstentions, a human owes a verdict. */
+    /** could-not-judge rules bucketed by severity — abstentions: the instrument did not decide, and each names why. A disposition-only abstention is retired (k179jnhx); see the ABSTENTIONS note below for what remains. */
     abstentions: Record<Severity, string[]>;
     /** derived counts the wording turns on. */
     criticalViolations: number;
@@ -40,14 +40,22 @@ export interface Verdict {
  *   0 critical + 1..5 major violations              -> revise recommended
  *   0 critical + >5 major violations                -> revise mandatory
  *   >=1 critical violation                          -> revise mandatory (NO bypass)
- * ABSTENTIONS: a could-not-judge is a human verdict owed. Any abstention blocks
- * "approve" (the outcome becomes at least revise-recommended); an abstention on a
- * CRITICAL rule can never be silently approved and is reported first.
+ * ABSTENTIONS: a could-not-judge means the instrument did NOT decide, and says
+ * why. Task k179jnhx retired judgement as an acceptance kind: a rule whose
+ * DISPOSITION used to wait on a person now decides on a written justification
+ * token's PRESENCE. What still abstains is named per rule, never relabelled:
+ * an unreadable input (unparseable file, unreachable tree, absent oracle), a
+ * rule with no detector yet (pinned NOT_MECHANICALLY_CHECKABLE), a population
+ * the source cannot decide statically, or a recorded marker claim the standard
+ * itself sends to a reviewer (R-51's write-contract marker).
+ * Any abstention still blocks "approve" (the outcome becomes at least
+ * revise-recommended); an abstention on a CRITICAL rule can never be silently
+ * approved and is reported first.
  *
  * EXIT CODE preserves the engine's honesty:
  *   >=1 critical OR revise-mandatory                -> 1 (a violation IS wrong)
  *   1..5 major violations (revise-recommended)      -> 1 (hard violations exist)
- *   no hard violation, abstention owed              -> 2 (not looked = never a clean 0)
+ *   no hard violation, input unreadable somewhere   -> 2 (not read = never a clean 0)
  *   approve                                         -> 0
  * We cross-check against the engine's computeExitCode and never print "approve"
  * on an exit that means abstention.

package/dist/tally.js

@@ -12,13 +12,7 @@
 import { computeExitCode } from "@vantageos/mcp-doctor";
 import { deriveRuleIds } from "./coverage.js";
 import { deriveSeverityMap } from "./severity.js";
-/** The four states, in worst-first order — the reduction picks the worst. */
-const STATE_RANK = {
-    "non-conforming": 3,
-    "could-not-judge": 2,
-    absent: 1,
-    present: 0,
-};
+import { STATE_RANK } from "./state-rank.js";
 const ALL_STATES = [
     "present",
     "non-conforming",
@@ -77,14 +71,22 @@ function emptyBySeverity() {
  *   0 critical + 1..5 major violations              -> revise recommended
  *   0 critical + >5 major violations                -> revise mandatory
  *   >=1 critical violation                          -> revise mandatory (NO bypass)
- * ABSTENTIONS: a could-not-judge is a human verdict owed. Any abstention blocks
- * "approve" (the outcome becomes at least revise-recommended); an abstention on a
- * CRITICAL rule can never be silently approved and is reported first.
+ * ABSTENTIONS: a could-not-judge means the instrument did NOT decide, and says
+ * why. Task k179jnhx retired judgement as an acceptance kind: a rule whose
+ * DISPOSITION used to wait on a person now decides on a written justification
+ * token's PRESENCE. What still abstains is named per rule, never relabelled:
+ * an unreadable input (unparseable file, unreachable tree, absent oracle), a
+ * rule with no detector yet (pinned NOT_MECHANICALLY_CHECKABLE), a population
+ * the source cannot decide statically, or a recorded marker claim the standard
+ * itself sends to a reviewer (R-51's write-contract marker).
+ * Any abstention still blocks "approve" (the outcome becomes at least
+ * revise-recommended); an abstention on a CRITICAL rule can never be silently
+ * approved and is reported first.
  *
  * EXIT CODE preserves the engine's honesty:
  *   >=1 critical OR revise-mandatory                -> 1 (a violation IS wrong)
  *   1..5 major violations (revise-recommended)      -> 1 (hard violations exist)
- *   no hard violation, abstention owed              -> 2 (not looked = never a clean 0)
+ *   no hard violation, input unreadable somewhere   -> 2 (not read = never a clean 0)
  *   approve                                         -> 0
  * We cross-check against the engine's computeExitCode and never print "approve"
  * on an exit that means abstention.
@@ -119,7 +121,7 @@ export function verdict(t, results, severity = deriveSeverityMap()) {
         exitCode = 1; // hard violations present — a caller must not read a clean 0
     }
     else if (abstentionTotal > 0) {
-        // no hard violation, but a human verdict is owed (critical abstention first)
+        // no hard violation, but some input could not be READ (critical abstention first)
         outcome = "revise-recommended";
         exitCode = 2;
     }
@@ -131,7 +133,7 @@ export function verdict(t, results, severity = deriveSeverityMap()) {
     const criticalNote = criticalViolations > 0
         ? `${criticalViolations} CRITICAL violation(s) — revise mandatory, NO bypass.`
         : criticalAbstentions > 0
-            ? `${criticalAbstentions} CRITICAL abstention(s) — a human verdict is owed; approve is blocked.`
+            ? `${criticalAbstentions} CRITICAL abstention(s) — not decided (each rule names why); approve is blocked.`
             : "no critical violation or abstention.";
     const summary = `VERDICT: ${outcome} (exit ${exitCode}) — ${criticalNote} ` +
         `major violations=${majorViolations}, abstentions=${abstentionTotal} ` +

package/dist/target.d.ts

@@ -0,0 +1,32 @@
+import type { Detector, Tree } from "./engine-types.js";
+export interface TargetScope {
+    /** the argument as given, resolved to an absolute path. */
+    input: string;
+    /** the repository root every `rel` is computed against. */
+    repoRoot: string;
+    /** which marker made `repoRoot` the root. */
+    repoRootBy: "package.json" | ".git" | "no marker (argument used as-is)";
+    /** the convex functions dir, or undefined when the repository has none. */
+    convexDir: string | undefined;
+    /** the directories actually walked, absolute, in order. */
+    scanRoots: string[];
+}
+/** Resolve a CLI argument to the backend it names. Pure over the filesystem. */
+export declare function resolveTarget(arg: string): TargetScope;
+/** The ONE tree every detector judges: the scan roots' files, `rel` relative to
+ * the repository root, `root` = the repository root. */
+export declare function loadScopedTree(scope: TargetScope): Tree;
+/** Files scanned per top-level directory (two segments under the repo root), so a
+ * reader sees WHAT was judged — an empty or surprising surface is visible. */
+export declare function coverageInventory(tree: Tree): Map<string, number>;
+export declare function describeScope(scope: TargetScope, tree: Tree): string;
+/** Wrap detectors so each judges the scoped tree instead of the engine's
+ * per-argument tree. runDoctor still owns the loud-fail contract. */
+export declare function onScopedTree(tree: Tree, detectors: Detector[]): Detector[];
+/** Absolute convex dir for a scoped tree (tree.root = repo root) or for a tree
+ * rooted AT a convex dir (direct detector tests). `prefix` is what the tree's
+ * rels carry in front of a convex-relative path. */
+export declare function convexRootOf(tree: Tree): {
+    dir: string;
+    prefix: string;
+};