@vantageos/backend-doctor 0.2.0 → 0.4.0

package/dist/detectors/structural.d.ts

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

package/dist/detectors/structural.js

@@ -1,54 +1,80 @@
 // The two STRUCTURAL detectors — R-14 and R-38. They judge the inventory SCHEMA
-// against the §2 contract, not a single row. Run against THIS oracle they MUST
-// return `non-conforming`, because §2 splits authority into two distinct fields
-// (reader R-5, writer R-10) and the oracle carries a SINGLE merged `rbac_qui`
-// column. Agreeing with the oracle here would be certifying the defect the
-// instrument exists to find — so these are NOT tuned to pass.
-import { CONTRACT_FIELDS, READER_AUTHORITY_COLUMN, WRITER_AUTHORITY_COLUMN, authorityIsMerged } from "../contract.js";
-import { ORACLE_COLUMNS, oracleLabel, readOracle, refuseWithoutOracle, requireOracle, } from "../oracle.js";
+// against the §2 contract, not a single row.
+//
+// §2 splits authority into two contract fields (reader R-5, writer R-10). The
+// oracle carries ONE authority column, `rbac_qui`; writer authority has a column
+// of its own only through the writer-tier side-car (`writer_tier`, joined on
+// `outil` — see resolveAuthoritySplit in src/contract.ts). So:
+//   side-car absent, or missing a write tool -> non-conforming (merged/omitted)
+//   side-car unreadable                      -> could-not-judge
+//   side-car complete over every write tool  -> the split is declared
+// An oracle alone is never green here: agreeing with a merged column would be
+// certifying the defect the instrument exists to find.
+import { CONTRACT_FIELDS, READER_AUTHORITY_COLUMN, resolveAuthoritySplit, SPLIT_WRITER_AUTHORITY_COLUMN, } from "../contract.js";
+import { isInventoryRow, ORACLE_COLUMNS, oracleLabel, readOracle, readWriterTier, refuseWithoutOracle, requireOracle, } from "../oracle.js";
+import { itemCount, withCount } from "../violation-count.js";
+import { WRITE_VERBS } from "./shared.js";
 const csvAnchor = () => `${oracleLabel()} col#9 rbac_qui`;
+function splitFor(rows, sideCar) {
+    const writeTools = rows
+        .filter(isInventoryRow)
+        .filter((r) => WRITE_VERBS.has(r.by.crud))
+        .map((r) => r.by.outil);
+    return resolveAuthoritySplit(writeTools, sideCar());
+}
+function unjudgeable(id, reason) {
+    const verdict = `${id.split(" ")[0]}: could not judge — ${reason}.`;
+    return { id, anchor: csvAnchor(), state: "could-not-judge", verdict, reason: verdict };
+}
 /**
  * R-14 — inventory-schema parity, contract → inventory, one direction.
  * A merged reader/writer authority column is "non-conforming by construction"
- * (§12). The oracle's column 9 `rbac_qui` is that single merged column.
+ * (§12). Writer authority is a separate column only when the side-car declares it.
  */
-export function makeR14(columns = ORACLE_COLUMNS) {
+export function makeR14(columns = ORACLE_COLUMNS, rowsProvider = readOracle, sideCar = readWriterTier) {
+    const id = "R-14 inventory-schema parity";
     return {
-        id: "R-14 inventory-schema parity",
+        id,
         // The verdict is about the oracle's schema, so with no oracle bound there is
         // no subject: refuse (could-not-judge), never a verdict on the tool's own constant.
-        run: () => refuseWithoutOracle("R-14 inventory-schema parity", () => {
+        run: () => refuseWithoutOracle(id, () => {
             requireOracle();
-            const authorityColumns = columns.filter((c) => c === "rbac_qui");
-            if (authorityIsMerged() || authorityColumns.length < 2) {
-                return {
-                    id: "R-14 inventory-schema parity",
+            const missing = CONTRACT_FIELDS.flatMap((f) => f.columns.filter((c) => !columns.includes(c)).map((c) => `${f.field}→${c}`));
+            const split = splitFor(rowsProvider(), sideCar);
+            if (split.kind === "unjudgeable")
+                return unjudgeable(id, split.reason);
+            if (split.kind === "merged" || missing.length > 0) {
+                return withCount({
+                    id,
                     anchor: csvAnchor(),
                     state: "non-conforming",
-                    verdict: "R-14: the inventory holds a SINGLE merged authority column `rbac_qui` (col#9), " +
-                        "but §2 splits authority into two distinct contract fields — reader authority (R-5) " +
-                        "and writer authority (R-10). A merged authority column is non-conforming by construction: " +
-                        "the reader/writer divergence R-10 and R-7 exist to record cannot be written in it.",
-                };
+                    verdict: "R-14: §2 splits authority into two distinct contract fields — reader authority (R-5) " +
+                        `and writer authority (R-10) — but the inventory's only authority column is \`${READER_AUTHORITY_COLUMN}\` (col#9)` +
+                        (split.kind === "merged" ? `: ${split.reason}. ` : ". ") +
+                        "A merged authority column is non-conforming by construction: the reader/writer divergence " +
+                        "R-10 and R-7 exist to record cannot be written in it." +
+                        (missing.length ? ` Also missing: ${missing.join(", ")}.` : ""),
+                }, itemCount(1));
             }
             return {
-                id: "R-14 inventory-schema parity",
-                anchor: oracleLabel(),
+                id,
+                anchor: `${oracleLabel()} + ${split.sideCar}`,
                 state: "present",
-                verdict: "R-14: every §2 contract field present; reader and writer authority are two separate columns.",
+                verdict: `R-14: every §2 contract field present; reader authority is \`${READER_AUTHORITY_COLUMN}\`, writer authority is ` +
+                    `\`${SPLIT_WRITER_AUTHORITY_COLUMN}\` in ${split.sideCar}, recorded for all ${split.writeTools} write tools.`,
             };
         }),
     };
 }
 /**
- * R-38 — the completeness gate over the thirteen §2 fields. The oracle cannot
- * satisfy the contract because reader and writer authority are not two separate
- * fields (both map to `rbac_qui`).
+ * R-38 — the completeness gate over the thirteen §2 fields. Writer authority is
+ * complete only when the side-car records a tier for every write tool.
  */
-export function makeR38(columns = ORACLE_COLUMNS, rowsProvider = readOracle) {
+export function makeR38(columns = ORACLE_COLUMNS, rowsProvider = readOracle, sideCar = readWriterTier) {
+    const id = "R-38 thirteen-field completeness";
     return {
-        id: "R-38 thirteen-field completeness",
-        run: () => refuseWithoutOracle("R-38 thirteen-field completeness", () => {
+        id,
+        run: () => refuseWithoutOracle(id, () => {
             requireOracle();
             const colSet = new Set(columns);
             const missing = [];
@@ -58,29 +84,35 @@ export function makeR38(columns = ORACLE_COLUMNS, rowsProvider = readOracle) {
                         missing.push(`${f.field}→${col}`);
                 }
             }
-            const authorityMerged = READER_AUTHORITY_COLUMN === WRITER_AUTHORITY_COLUMN && colSet.has(READER_AUTHORITY_COLUMN);
-            if (authorityMerged || missing.length > 0) {
-                const rows = rowsProvider();
+            const rows = rowsProvider();
+            const split = splitFor(rows, sideCar);
+            if (split.kind === "unjudgeable")
+                return unjudgeable(id, split.reason);
+            if (split.kind === "merged" || missing.length > 0) {
+                const uncovered = split.kind === "merged" ? new Set(split.uncovered) : new Set();
                 const sample = rows
-                    .filter((r) => !r.malformed && r.by.rbac_qui && r.by.table !== "TOTAL")
+                    .filter((r) => isInventoryRow(r) && r.by.rbac_qui && (uncovered.size === 0 || uncovered.has(r.by.outil)))
                     .slice(0, 3)
                     .map((r) => `row#${r.n} "${r.by.outil || r.by.table}" rbac_qui="${r.by.rbac_qui}"`)
                     .join("; ");
-                return {
-                    id: "R-38 thirteen-field completeness",
+                return withCount({
+                    id,
                     anchor: csvAnchor(),
                     state: "non-conforming",
-                    verdict: `R-38: the oracle cannot satisfy the thirteen-field §2 contract — reader authority (R-5) and ` +
-                        `writer authority (R-10) are not two separate fields; both map to the single column ` +
-                        `\`rbac_qui\` (col#9).${missing.length ? ` Also missing: ${missing.join(", ")}.` : ""} ` +
-                        `Evidence: ${sample}.`,
-                };
+                    verdict: "R-38: the oracle cannot satisfy the thirteen-field §2 contract — reader authority (R-5) and " +
+                        `writer authority (R-10) are not two separate fields for every tool; writer authority falls back to ` +
+                        `\`${READER_AUTHORITY_COLUMN}\` (col#9)` +
+                        (split.kind === "merged" ? `: ${split.reason}.` : ".") +
+                        (missing.length ? ` Also missing: ${missing.join(", ")}.` : "") +
+                        ` Evidence: ${sample}.`,
+                }, itemCount(1));
             }
             return {
-                id: "R-38 thirteen-field completeness",
-                anchor: oracleLabel(),
+                id,
+                anchor: `${oracleLabel()} + ${split.sideCar}`,
                 state: "present",
-                verdict: "R-38: all thirteen §2 contract fields present per table, each within its vocabulary.",
+                verdict: "R-38: all thirteen §2 contract fields present per table; writer authority is " +
+                    `\`${SPLIT_WRITER_AUTHORITY_COLUMN}\` in ${split.sideCar} for all ${split.writeTools} write tools.`,
             };
         }),
     };

package/dist/not-checkable.d.ts

@@ -1,3 +1,4 @@
+import type { DetectorResult } from "./engine-types.js";
 /**
  * The deferral bucket. R-1..R-47 each carry an executable control (registry.ts),
  * so none is deferred to "a human decides". R-48 (authority-totality, the #130
@@ -9,7 +10,6 @@
  * moves to registry.ts and this entry is removed. The export is consumed by
  * coverage.ts / coverage-cli.ts / cli.ts.
  */
-import type { DetectorResult } from "./engine-types.js";
 export declare const NOT_MECHANICALLY_CHECKABLE: Record<string, string>;
 /**
  * One `could-not-judge` DetectorResult per NOT_MECHANICALLY_CHECKABLE rule, so

package/dist/not-checkable.js

@@ -15,8 +15,20 @@
 // input is vendored. They were built, not relabelled. The bucket was not renamed to a
 // gentler word — it was emptied.
 import { STANDARD_FILE } from "./detectors/standard/_doc.js";
+/**
+ * The deferral bucket. R-1..R-47 each carry an executable control (registry.ts),
+ * so none is deferred to "a human decides". R-48 (authority-totality, the #130
+ * class) was added to the standard at the 51ec7af1 re-pin AFTER its detector; its
+ * text is now pinned so coverage enumerates 48, but no detector exists yet — so it
+ * is reported here as NOT_MECHANICALLY_CHECKABLE with a written reason rather than
+ * silently omitted, which would let coverage pretend 47 is the whole document. The
+ * detector is task k17chpr4kzp399j3s7r7edpm4s8cscbz (after D5); when it lands, R-48
+ * moves to registry.ts and this entry is removed. The export is consumed by
+ * coverage.ts / coverage-cli.ts / cli.ts.
+ */
 export const NOT_MECHANICALLY_CHECKABLE = {
     "R-48": "R-48 authority-totality detector pending — task k17chpr4kzp399j3s7r7edpm4s8cscbz; text pinned at 4bcd605 so coverage cannot pretend 47 is complete. No mechanical control yet; R-48 is enumerated and visible, never silently dropped.",
+    "R-57": "R-57 no local identity primitive is MEASURED, under the doctor-owned id CR-2 (src/detectors/source/local-identity.ts, PR #61): the standard at bacc54a numbers as R-57 the rule CR-2 already enforces. Its count is reported once, under the key CR-2, because the vantage-peers deploy-gate baseline reads CR-2; reporting it under both ids would count one defect as two rules. Renaming CR-2 to R-57 in the evidence output is a follow-up that must move that baseline in the same delivery. R-57 is enumerated and visible here, never silently dropped, and never reported present.",
 };
 /**
  * One `could-not-judge` DetectorResult per NOT_MECHANICALLY_CHECKABLE rule, so

package/dist/registry.d.ts

@@ -1,6 +1,6 @@
 import type { Detector } from "./engine-types.js";
 /** The standard both pins the whole wave against. */
-export declare const STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ 4bcd605656ceff52d4f1593a9176cd6b988471be (elpiarthera/ElPi-Corp)";
+export declare const STANDARD_PIN = "vantagepeers/backend-standard/backend-standard.md @ bacc54a53d5f6f9f20e5254908e2b46807902faa (elpiarthera/ElPi-Corp main; the door-audit rules R-54..R-57, merged as ElPi-Corp #239 = 7d7df89 before the 2026-10-10 history rewrite, same blob 85d8530e)";
 export interface RegistryEntry {
     detector: Detector;
     ruleId: string;

package/dist/registry.js

@@ -7,13 +7,18 @@ 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_CREDENTIAL_HYGIENE_DETECTORS } from "./detectors/source/credential-hygiene.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_NARROW_THEN_BOUND_DETECTORS } from "./detectors/source/narrow-then-bound.js";
 import { SOURCE_LIFECYCLE_DETECTORS } from "./detectors/source/lifecycle.js";
 import { SOURCE_READBUDGET_DETECTORS } from "./detectors/source/readbudget.js";
 import { SOURCE_REFUSAL_DETECTORS } from "./detectors/source/refusal.js";
 import { SOURCE_SECURITY_DETECTORS } from "./detectors/source/security.js";
+import { SOURCE_SERVICE_ACCOUNT_CLAIM_DETECTORS } from "./detectors/source/service-account-claim.js";
 import { SOURCE_WRITE_ISOLATION_DETECTORS } from "./detectors/source/write-isolation.js";
 import { SOURCE_WRITESAFETY_DETECTORS } from "./detectors/source/writesafety.js";
 import { R41, SIBLING_PIN } from "./detectors/standard/r41-frontier.js";
@@ -21,8 +26,9 @@ import { R46_STANDARD_PIN, STANDARD_SOURCE_DETECTORS, } from "./detectors/standa
 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 @ bacc54a53d5f6f9f20e5254908e2b46807902faa (elpiarthera/ElPi-Corp main; the door-audit rules R-54..R-57, merged as ElPi-Corp #239 = 7d7df89 before the 2026-10-10 history rewrite, same blob 85d8530e)";
 /**
  * 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
@@ -40,7 +46,7 @@ export function mergeHalves(ruleId, a, b) {
             const reasons = [ra, rb]
                 .filter((r) => r.state === "could-not-judge")
                 .map((r) => r.reason ?? r.verdict);
-            return {
+            const merged = {
                 id: b.id,
                 anchor: decider.anchor,
                 state: decider.state,
@@ -49,6 +55,13 @@ export function mergeHalves(ruleId, a, b) {
                     ? { 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);
         },
     };
 }
@@ -61,7 +74,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",
@@ -145,8 +160,45 @@ 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,
+        // R-54 — a door the fleet service account can reach acts only inside an
+        // organisation the transport verified for this call. Reads the convex source:
+        // a public door that resolves its caller through the organisation-scope
+        // resolver and declares no claim argument (A), or declares one but never
+        // refuses the claimless service-account call (B), is red; a claim-bound door
+        // and the three listed exits are present; an unreadable caller resolution is
+        // could-not-judge. The door audit's cause 1 (standard bacc54a §4 R-54).
+        ...SOURCE_SERVICE_ACCOUNT_CLAIM_DETECTORS,
+        // R-55 — a read narrows by every predicate before it bounds the result, and an
+        // aggregate is computed over the narrowed set. Reads the convex source: a
+        // bounded read (.take / .paginate over a DB query, or a re-bounding .slice)
+        // whose rows are narrowed AFTER the bound by a caller-dependent predicate is
+        // red; a fill loop or a refusal on a full window between the bound and the
+        // narrowing is listed as covered. An unbounded .collect() is R-11 / R-47's.
+        // The door audit's cause 4 (standard bacc54a §4 R-55).
+        ...SOURCE_NARROW_THEN_BOUND_DETECTORS,
+        // R-56 — credentials at rest, refresh tokens, bearers and verification tokens.
+        // Reads the convex source: a credential-named column stored without a digest or
+        // as the digest of a chosen secret (1); a refresh-token table read by hash with
+        // no consuming door (2); a bearer table with no revocation door (3a) or a mint
+        // that neither revokes prior bearers nor caps them (3b); a request-supplied
+        // commit identifier matched by substring without a full-length check (4) or a
+        // response echoing stored content (4e). The door audit's cause 5
+        // (standard bacc54a §4 R-56).
+        ...SOURCE_CREDENTIAL_HYGIENE_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.

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-bacc54a.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 bacc54a: the table lists all 56; 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,
+    };
+}