@vantageos/backend-doctor 0.1.0

package/dist/registry.js

@@ -0,0 +1,140 @@
+// backend-doctor's OWN registry. Each entry pairs a detector with the rule id it
+// targets and the standard pin it was written against — machine-readably, so
+// coverage is a COMMAND over this array, never a human reading names.
+import { makeR40 } from "./detectors/oracle-axis1.js";
+import { makeR37, r7, r8 } from "./detectors/oracle-axis2.js";
+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 { IDENTITY_DETECTORS } from "./detectors/source/identity.js";
+import { SOURCE_JOBS_DETECTORS } from "./detectors/source/jobs.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_WRITESAFETY_DETECTORS } from "./detectors/source/writesafety.js";
+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";
+/** The standard both pins the whole wave against. */
+export const STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp)";
+export const REGISTRY = [
+    ...PER_ROW_PREDICATES.map((spec) => ({
+        detector: makeOracleDetector(spec),
+        ruleId: spec.ruleId,
+        standardPin: STANDARD_PIN,
+    })),
+    { 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.
+    {
+        detector: makeOracleDetector(r7),
+        ruleId: "R-7",
+        standardPin: STANDARD_PIN,
+    },
+    {
+        detector: makeOracleDetector(r8),
+        ruleId: "R-8",
+        standardPin: STANDARD_PIN,
+    },
+    { detector: makeR37(), ruleId: "R-37", standardPin: STANDARD_PIN },
+    // R-40 — the Axis-1 BETWEEN-backend divergence control. It fires the moment a
+    // second backend's inventory exists (VR, vendored @ a74a042b) and compares the
+    // two per-tool inventories on every SHARED field's closed vocabulary. Mechanical
+    // half runs in full (names each field + VP-vs-VR value + the statut_suppression
+    // schema divergence); human half (is each divergence justified?) → could-not-judge.
+    {
+        detector: makeR40(),
+        ruleId: "R-40",
+        standardPin: `${STANDARD_PIN} + oracle:vr-by-tool-day159.csv @ a74a042b`,
+    },
+    // 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
+    // standardPin is normalised to the registry's full pin string.
+    ...[
+        ...SOURCE_SECURITY_DETECTORS,
+        ...SOURCE_WRITESAFETY_DETECTORS,
+        ...SOURCE_JOBS_DETECTORS,
+        // R-43 — the admin-resource lifecycle-symmetry control. Reads the convex
+        // source: for every admin-provisionable table a create/upsert reaches
+        // (oauth_scope_profiles, oauth_clients, tenants, filter rules), it checks a
+        // delete/GC path exists (or a written out-of-scope reason). Its mechanical
+        // half runs in full and it returns could-not-judge naming the admin-create
+        // tables with NO delete — a work list, never present/absent while the create
+        // subject exists (Day-165 friction, task k172xe9re...).
+        ...SOURCE_LIFECYCLE_DETECTORS,
+        // R-44 / R-45 — the derived-structure backfill controls. R-44 reads the
+        // convex source: for every derived structure (a thin, foreign-keyed,
+        // index-bearing junction/side table like briefingNoteParticipants) it
+        // checks a same-tree backfill migration populates it from the existing
+        // source rows — present on a direct-insert loop, could-not-judge when the
+        // migration writes via a helper (idempotence/coverage undecidable),
+        // non-conforming when no backfill exists (the PR #1200 inert-fix defect).
+        // R-45 reads the tests: present when a fixture builds the source row via a
+        // direct ctx.db.insert (bypassing the write path), non-conforming when the
+        // subject is exercised only through create, could-not-judge otherwise.
+        ...SOURCE_BACKFILL_DETECTORS,
+        // R-31 — the runtime read-budget control. Reads the convex source: for
+        // every mutation/internalMutation over an unbounded set (a published
+        // bulk-write OR a hand-run one-shot migration) it flags a bare `.collect()`
+        // read — non-conforming because an unbounded read aborts on the
+        // per-execution read-byte cap INDEPENDENTLY of the write budget (an
+        // unbounded read that writes nothing still throws `Too many bytes read`).
+        // A read bounded by `.take(n)`/`.paginate` WITH a `ctx.scheduler.runAfter`
+        // self-reschedule is present; a bounded read with no reschedule is
+        // could-not-judge. This is the static instrument that could have caught the
+        // participants-backfill P0 that 1079 convex-test tests passed (convex-test
+        // does not enforce the runtime read-byte limit).
+        ...SOURCE_READBUDGET_DETECTORS,
+        // R-47 — the incompletable-read refusal control (judgement; static+dynamic).
+        // Reads the convex source: a wide, non-index-bounded `.collect()` in a QUERY
+        // whose handler carries no refusal path can be truncated by the read cap
+        // BEFORE its filter runs, returning a fraction indistinguishable from a full
+        // match (the 2026-08-19 tasks.list companion to R-46's get_task P0). Its
+        // mechanical half runs in full; it returns could-not-judge naming each such
+        // site (the human decides refusal vs a tighter index vs a declared bound),
+        // present on a wide scan that DOES refuse (the tasks.list SCAN_CAP shape).
+        ...SOURCE_REFUSAL_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,
+    })),
+    // 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
+    // all resolve; non-conforming on any dead pointer. Its pin cites the sibling
+    // documents (the second input), not only the backend standard.
+    {
+        detector: R41,
+        ruleId: "R-41",
+        standardPin: `${STANDARD_PIN} + ${SIBLING_PIN}`,
+    },
+    // R-46 — a read path's returns validator is DERIVED from its table's schema,
+    // never a hand-written restatement (the 2026-08-19 get_task ReturnsValidationError
+    // P0, origin e9a6a7e). UNLIKE every other detector, R-46 reads the TARGET
+    // backend's OWN schema.ts + returns validators from the tree the engine loads,
+    // derives the schema field set at analysis time, and classifies every
+    // document-returning validator as COVERS / written-PROJECTION / MISSING — so R-46
+    // is measured on EVERY backend the doctor is pointed at, not rediscovered per
+    // repository at production cost. It is the lift of vantage-peers'
+    // returnsValidatorSchemaCoverage.test.ts (#1206, d2c32ea) into the instrument.
+    ...STANDARD_SOURCE_DETECTORS.map((e) => ({
+        detector: e.detector,
+        ruleId: e.ruleId,
+        standardPin: R46_STANDARD_PIN,
+    })),
+];
+/** The rule ids this wave mechanically CHECKS — derived from the registry. */
+export function checkedRuleIds() {
+    return [...new Set(REGISTRY.map((e) => e.ruleId))].sort((a, b) => Number(a.slice(2)) - Number(b.slice(2)));
+}

package/dist/report.d.ts

@@ -0,0 +1,35 @@
+import type { DetectorResult } from "./engine-types.js";
+import { type Tally, type Verdict } from "./tally.js";
+import { type Severity } from "./severity.js";
+/** The run-time facts the CLI gathers (clock + git) and hands to the renderer. */
+export interface ReportContext {
+    /** the audited target directory (absolute). */
+    target: string;
+    /** `git -C <target> rev-parse HEAD`, or the literal "not a git repo". */
+    targetCommit: string;
+    /** the tool version, from package.json. */
+    toolVersion: string;
+    /** the run date, YYYY-MM-DD, from the OS clock at CLI runtime. */
+    dateISO: string;
+    /**
+     * `git status --porcelain --untracked-files=all` of the target — untracked
+     * INCLUDED (the short form is not a clean-tree check; a doubled untracked dir
+     * bit a reviewer). Empty string means a clean tree.
+     */
+    treeStatus: string;
+}
+/** Derive the committed report path from the target basename + the run date. */
+export declare function reportPath(target: string, dateISO: string, dir: string): string;
+/**
+ * Render the full report markdown. PURE — no clock, no git, no fs. The tally line
+ * printed in the header is the SAME `tallyLine(t)` the CLI prints to the terminal
+ * (one source of truth — the header can never silently diverge from the printed
+ * tally), and its sum invariant was already asserted by `tally()`.
+ */
+export declare function buildReport(ctx: ReportContext, results: DetectorResult[], t: Tally, v: Verdict, severity?: Map<string, Severity>): string;
+/**
+ * Write the report to `<dir>/backend-doctor-<target-basename>-<date>.md`, creating
+ * <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;

package/dist/report.js

@@ -0,0 +1,138 @@
+// The REPORT-WRITER — "a report he cannot see, he cannot believe."
+//
+// backend-doctor's verdict must survive the terminal: every run WRITES a report
+// file, ALWAYS (not behind a flag), to a path the repo keeps. The header carries
+// what makes the report checkable months later (target path + commit, the pinned
+// standard commit, the tool version, the machine tally with its sum asserted, and
+// a tree-cleanliness proof). Per rule the body carries the SITES — the row / table
+// / tool / file:line — not a count, because a count tells a number while the sites
+// tell the owner what to fix. The CRITICAL rows are separated at the TOP so a
+// reader who stops after one screen has still seen them.
+//
+// PURITY / SANDBOX: this module is a PURE renderer + a filesystem writer. It does
+// NOT read the clock and does NOT shell git — the CLI (a real process) gathers the
+// date via `new Date()` and the git facts via child_process and hands them in as a
+// ReportContext. Nothing here calls Date.now()/execSync, so it is safe to build the
+// report string inside a workflow-script sandbox where those are unavailable.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { ruleIdOf, tallyLine } from "./tally.js";
+import { deriveSeverityMap } from "./severity.js";
+import { STANDARD_SHA } from "./coverage.js";
+/** Derive the committed report path from the target basename + the run date. */
+export function reportPath(target, dateISO, dir) {
+    return join(dir, `backend-doctor-${basename(target)}-${dateISO}.md`);
+}
+/** All results for one ruleId, in registry order. */
+function resultsForRule(ruleId, results) {
+    return results.filter((r) => ruleIdOf(r) === ruleId);
+}
+/** The SITES line for a rule — anchor + verdict per result, never a count. */
+function sitesFor(ruleId, results) {
+    return resultsForRule(ruleId, results)
+        .map((r) => {
+        const anchor = r.anchor?.trim() ? r.anchor.trim() : "(no anchor)";
+        return `${anchor} — ${r.verdict.trim()}`;
+    })
+        .join("<br>");
+}
+/** One markdown table row for a rule in a non-clean state. */
+function ruleRow(ruleId, state, sev, results) {
+    return `| ${ruleId} | ${state} | ${sev} | ${sitesFor(ruleId, results)} |`;
+}
+/**
+ * Render the full report markdown. PURE — no clock, no git, no fs. The tally line
+ * printed in the header is the SAME `tallyLine(t)` the CLI prints to the terminal
+ * (one source of truth — the header can never silently diverge from the printed
+ * tally), and its sum invariant was already asserted by `tally()`.
+ */
+export function buildReport(ctx, results, t, v, severity = deriveSeverityMap()) {
+    const sevOf = (id) => {
+        const s = severity.get(id);
+        if (s === undefined)
+            throw new Error(`buildReport: no severity for ${id}`);
+        return s;
+    };
+    // The CRITICAL rows — non-conforming first, then abstentions — separated at the
+    // TOP. Ordered by rule number within each group.
+    const byNum = (a, b) => Number(a.slice(2)) - Number(b.slice(2));
+    const criticalViolations = [...v.violations.critical].sort(byNum);
+    const criticalAbstentions = [...v.abstentions.critical].sort(byNum);
+    const nonConforming = [];
+    const couldNotJudge = [];
+    const present = [];
+    const absent = [];
+    for (const [id, state] of [...t.ruleState].sort((a, b) => byNum(a[0], b[0]))) {
+        if (state === "non-conforming")
+            nonConforming.push(id);
+        else if (state === "could-not-judge")
+            couldNotJudge.push(id);
+        else if (state === "present")
+            present.push(id);
+        else
+            absent.push(id);
+    }
+    const tableHead = "| rule | state | severity | sites |\n| --- | --- | --- | --- |";
+    const rowsFor = (ids, state) => ids.length === 0 ? "_none._" : `${tableHead}\n${ids.map((id) => ruleRow(id, state, sevOf(id), results)).join("\n")}`;
+    const treeProof = ctx.treeStatus.trim() === "" ? "(clean — no tracked or untracked change)" : ctx.treeStatus;
+    const criticalCount = criticalViolations.length + criticalAbstentions.length;
+    const criticalRows = criticalCount === 0
+        ? "_no critical violation or abstention._"
+        : [
+            tableHead,
+            ...criticalViolations.map((id) => ruleRow(id, "non-conforming", "critical", results)),
+            ...criticalAbstentions.map((id) => ruleRow(id, "could-not-judge", "critical", results)),
+        ].join("\n");
+    return `# backend-doctor report — ${basename(ctx.target)} — ${ctx.dateISO}
+
+> A report he cannot see, he cannot believe. This file is written on EVERY run,
+> never behind a flag — an absent file is never a clean result.
+
+## Header — what makes this checkable months later
+
+- **target**: \`${ctx.target}\`
+- **target commit**: \`${ctx.targetCommit}\`
+- **standard commit** (pinned): \`${STANDARD_SHA}\`
+- **tool version**: \`${ctx.toolVersion}\`
+- **run date**: ${ctx.dateISO}
+- **machine tally**: \`${tallyLine(t)}\`
+- **verdict**: ${v.summary}
+
+Tree-cleanliness proof — \`git status --porcelain --untracked-files=all\` (untracked INCLUDED):
+
+\`\`\`
+${treeProof}
+\`\`\`
+
+## CRITICAL (${criticalCount}) — read these first
+
+${criticalRows}
+
+## Non-conforming (${nonConforming.length})
+
+${rowsFor(nonConforming, "non-conforming")}
+
+## Could-not-judge (${couldNotJudge.length})
+
+${rowsFor(couldNotJudge, "could-not-judge")}
+
+## Absent (${absent.length})
+
+${rowsFor(absent, "absent")}
+
+## Present (${present.length})
+
+${present.length === 0 ? "_none._" : present.join(", ")}
+`;
+}
+/**
+ * Write the report to `<dir>/backend-doctor-<target-basename>-<date>.md`, creating
+ * <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()) {
+    mkdirSync(dir, { recursive: true });
+    const path = reportPath(ctx.target, ctx.dateISO, dir);
+    writeFileSync(path, buildReport(ctx, results, t, v, severity), "utf8");
+    return path;
+}

package/dist/severity.d.ts

@@ -0,0 +1,30 @@
+export type Severity = "critical" | "major-high" | "major" | "minor";
+/** Ordering for "worst wins" reductions and threshold comparisons. */
+export declare const SEVERITY_RANK: Record<Severity, number>;
+/**
+ * Resolve a rule's severity from its objective tags, by precedence. Throws in
+ * two distinct ways, both a finding about the parse or the standard and never a
+ * silent default-to-minor:
+ *   1. UNMAPPABLE tag present — a tag outside the five known objectives. This is
+ *      checked FIRST, before precedence, because the critical rows carry BOTH
+ *      "highly secure" AND the tenant tag: if the tenant tag were mangled (a
+ *      case/spacing variant that fails `includes(MULTI_TENANT_TAG)`) and we let
+ *      precedence resolve on the surviving "highly secure" sibling, a CRITICAL
+ *      rule would silently downgrade to major-high with no throw. Asserting the
+ *      set is a SUBSET of the five and throwing on the unmappable tag closes that.
+ *   2. EMPTY / all-absent — no tag matches any of the five (the vacuous-scope
+ *      hole): still a throw, never minor.
+ */
+export declare function severityOf(tags: readonly string[], ruleId?: string): Severity;
+/**
+ * Parse the objectives table (§13) of the VENDORED standard into ruleId -> tags.
+ * A table row is `| R-N <desc> | <tag> · <tag> · … |`. Returns an empty map only
+ * if the table is absent — which `deriveSeverityMap` treats as a hard failure.
+ */
+export declare function parseObjectives(path?: string): Map<string, string[]>;
+/**
+ * The ruleId -> severity map for every rule the standard defines. Throws (the
+ * neuter guard) if the objectives parse yields NOTHING — an empty scope must go
+ * RED, never make every rule minor by vacuity.
+ */
+export declare function deriveSeverityMap(path?: string): Map<string, Severity>;

package/dist/severity.js

@@ -0,0 +1,121 @@
+// Severity is DERIVED from the standard's objectives table (§13, the
+// "every rule to the objective it serves" table), never hardcoded per rule —
+// the R-5 law: a machine reads the standard, a human does not maintain a list.
+//
+// THE TAG -> SEVERITY MAP (the one place it is written):
+//
+//   objective tag on a rule            => severity
+//   ---------------------------------------------------------------
+//   "multi-organisation multi-tenant"  => critical    (the tenant-boundary rules)
+//   "highly secure" (no multi-tenant)  => major-high
+//   "enterprise-grade"                 => major
+//   "production-ready"                 => major
+//   "token-efficient" (only)           => minor
+//
+// Resolution is by PRECEDENCE (a rule carries several tags): the highest tag wins.
+// A rule whose objectives cell resolves to NONE of the five is a FINDING (the
+// standard promises "no blank cell"), and severityOf THROWS — it never silently
+// collapses an unmapped rule to minor (the vacuous-scope hole).
+import { readFileSync } from "node:fs";
+import { VENDORED_STANDARD_PATH } from "./coverage.js";
+/** Ordering for "worst wins" reductions and threshold comparisons. */
+export const SEVERITY_RANK = {
+    critical: 3,
+    "major-high": 2,
+    major: 1,
+    minor: 0,
+};
+/** The tenant-boundary tag — its presence alone makes a rule CRITICAL. */
+const MULTI_TENANT_TAG = "multi-organisation multi-tenant";
+/**
+ * The five objectives the §13 table is allowed to carry. A parsed tag outside
+ * this set is an UNREADABLE cell (a mangled/variant spelling, e.g. wrong case),
+ * never an absent one — and the two must not be conflated (see severityOf).
+ */
+const KNOWN_OBJECTIVES = new Set([
+    MULTI_TENANT_TAG,
+    "highly secure",
+    "enterprise-grade",
+    "production-ready",
+    "token-efficient",
+]);
+/**
+ * Resolve a rule's severity from its objective tags, by precedence. Throws in
+ * two distinct ways, both a finding about the parse or the standard and never a
+ * silent default-to-minor:
+ *   1. UNMAPPABLE tag present — a tag outside the five known objectives. This is
+ *      checked FIRST, before precedence, because the critical rows carry BOTH
+ *      "highly secure" AND the tenant tag: if the tenant tag were mangled (a
+ *      case/spacing variant that fails `includes(MULTI_TENANT_TAG)`) and we let
+ *      precedence resolve on the surviving "highly secure" sibling, a CRITICAL
+ *      rule would silently downgrade to major-high with no throw. Asserting the
+ *      set is a SUBSET of the five and throwing on the unmappable tag closes that.
+ *   2. EMPTY / all-absent — no tag matches any of the five (the vacuous-scope
+ *      hole): still a throw, never minor.
+ */
+export function severityOf(tags, ruleId = "<unknown>") {
+    const unmappable = tags.filter((t) => !KNOWN_OBJECTIVES.has(t));
+    if (unmappable.length > 0) {
+        throw new Error(`severityOf(${ruleId}): objective tag(s) ${JSON.stringify(unmappable)} are not among the five known ` +
+            `objectives ${JSON.stringify([...KNOWN_OBJECTIVES])} — an unreadable objectives cell must NOT be ` +
+            `absorbed by a recognised sibling tag (a mangled tenant tag alongside "highly secure" would silently ` +
+            `downgrade a critical rule); refusing to resolve severity while any tag is unmappable.`);
+    }
+    if (tags.includes(MULTI_TENANT_TAG))
+        return "critical";
+    if (tags.includes("highly secure"))
+        return "major-high";
+    if (tags.includes("enterprise-grade") || tags.includes("production-ready"))
+        return "major";
+    if (tags.includes("token-efficient"))
+        return "minor";
+    throw new Error(`severityOf(${ruleId}): objectives ${JSON.stringify(tags)} match none of the five — ` +
+        `the standard promises no blank cell; refusing to default an unmapped rule to minor.`);
+}
+/**
+ * Parse the objectives table (§13) of the VENDORED standard into ruleId -> tags.
+ * A table row is `| R-N <desc> | <tag> · <tag> · … |`. Returns an empty map only
+ * if the table is absent — which `deriveSeverityMap` treats as a hard failure.
+ */
+export function parseObjectives(path = VENDORED_STANDARD_PATH) {
+    const blob = readFileSync(path, "utf8");
+    const out = new Map();
+    // Scope to §13 "Objective traceability" ONLY — later sections (§14 traceability)
+    // also carry `| R-N … |` rows with a different vocabulary ("mechanical"), which
+    // must NOT be read as objectives.
+    const start = blob.indexOf("## 13. Objective traceability");
+    if (start === -1)
+        return out; // section absent -> empty -> deriveSeverityMap goes RED
+    const after = blob.indexOf("\n## ", start + 1);
+    const section = blob.slice(start, after === -1 ? undefined : after);
+    for (const line of section.split("\n")) {
+        // `| R-5 reader authority… | highly secure · multi-organisation multi-tenant |`
+        const m = /^\|\s*(R-\d+)\b[^|]*\|\s*([^|]+?)\s*\|/.exec(line);
+        if (!m)
+            continue;
+        const [, ruleId, cell] = m;
+        const tags = cell
+            .split("·")
+            .map((t) => t.trim())
+            .filter((t) => t.length > 0);
+        if (tags.length > 0)
+            out.set(ruleId, tags);
+    }
+    return out;
+}
+/**
+ * The ruleId -> severity map for every rule the standard defines. Throws (the
+ * neuter guard) if the objectives parse yields NOTHING — an empty scope must go
+ * RED, never make every rule minor by vacuity.
+ */
+export function deriveSeverityMap(path = VENDORED_STANDARD_PATH) {
+    const objectives = parseObjectives(path);
+    if (objectives.size === 0) {
+        throw new Error(`deriveSeverityMap: objectives parse of ${path} returned EMPTY — ` +
+            `refusing to build a severity map that would make every rule minor by vacuity.`);
+    }
+    const map = new Map();
+    for (const [ruleId, tags] of objectives)
+        map.set(ruleId, severityOf(tags, ruleId));
+    return map;
+}

package/dist/tally.d.ts

@@ -0,0 +1,57 @@
+import type { DetectorResult, State } from "./engine-types.js";
+import { type Severity } from "./severity.js";
+/** Extract the ruleId (`R-N`) a result belongs to, from its leading id token. */
+export declare function ruleIdOf(result: DetectorResult): string;
+export interface Tally {
+    /** rule-level state counts — the four sum to `ruleTotal`. */
+    byState: Record<State, number>;
+    ruleTotal: number;
+    /** the number of raw DetectorResults reduced (>= ruleTotal). */
+    resultTotal: number;
+    /** reduced rule-level state, per ruleId. */
+    ruleState: Map<string, State>;
+}
+/**
+ * Reduce the engine's DetectorResults to a rule-level tally. Asserts the four
+ * state counts sum to the rule total (the derive-never-type invariant) and that
+ * every rule the standard defines is present in the results.
+ */
+export declare function tally(results: DetectorResult[], ruleIds?: string[]): Tally;
+export type Outcome = "approve" | "revise-recommended" | "revise-mandatory";
+export interface Verdict {
+    outcome: Outcome;
+    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. */
+    abstentions: Record<Severity, string[]>;
+    /** derived counts the wording turns on. */
+    criticalViolations: number;
+    majorViolations: number;
+    criticalAbstentions: number;
+    /** the engine's honest three-way exit over the raw results. */
+    engineExitCode: number;
+    summary: string;
+}
+/**
+ * Map the tally to react-doctor's verdict shape, severity DERIVED from the
+ * standard. Verdict rules (major = major-high + major combined for the gate):
+ *   0 critical + 0 major violations                 -> approve
+ *   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.
+ *
+ * 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)
+ *   approve                                         -> 0
+ * We cross-check against the engine's computeExitCode and never print "approve"
+ * on an exit that means abstention.
+ */
+export declare function verdict(t: Tally, results: DetectorResult[], severity?: Map<string, Severity>): Verdict;
+/** The one-line machine tally string the CLI prints. */
+export declare function tallyLine(t: Tally): string;