@githonllc/avouch 0.1.7 → 0.1.8

package/README.md

@@ -39,8 +39,10 @@ Read in this order:
 | `src/checker.ts` | `check(ontology, facts)` returns the violations |
 | `src/patch.ts` | JSON-pointer patch that the mutation tests use |
 | `src/query.ts` | read-only queries over an ontology (`avouch query`) |
+| `src/reconcile.ts` | runtime consistency: `reconcile`, `projectSnapshot` (SPEC section 9) |
+| `src/coverage.ts` | decision-row coverage of reconcile rows, with a baseline (`verifyCoverage`, `avouch gate verify`) |
 | `src/markdown.ts` | built-in adapter for plain Markdown sources (`avouch.json`); see `docs/adapter-guide.md` section 7 |
-| `cli/` | command line: `avouch check` (`check.ts`) and `avouch query` (`query.ts`) |
+| `cli/` | command line: `avouch check` (`check.ts`), `avouch query` (`query.ts`), `avouch reconcile` (`reconcile.ts`) and `avouch gate verify` (`gate.ts`) |
 | `tsconfig.build.json` | configuration for the JavaScript and type declaration build |
 | `dist/` | build output; not tracked in version control |
 | `examples/library/` | toy project: source document, ontology, mutations, adapter, profile, evidence |
@@ -60,6 +62,9 @@ A project supplies an adapter and a profile. The adapter reads the project's sou
 - `test/cli.test.ts`: command line results, schema errors, checker violations and adapter errors.
 - `test/query.test.ts`: the query functions on the toy ontology and on patched variants of it.
 - `test/query-cli.test.ts`: `avouch query`: the JSON envelope, the stamp (git and check), exit codes, text output, and that a query writes no file.
+- `test/coverage.test.ts`: `verifyCoverage` on the toy ontology and on patched variants of it: units, gaps, stale baseline entries, failing reconcile rows, and the shape checks.
+- `test/reconcile-cli.test.ts`: `avouch reconcile`: JSON lines in and out, exit codes, and the line number in each input error.
+- `test/gate-cli.test.ts`: `avouch gate verify`: the pipeline from cases to the gate, text and JSON output, the check with `--adapter`, and exit codes.
 - `test/markdown.test.ts`: the built-in Markdown adapter: the toy library gives the same findings as with its own adapter (outside the rules the generic adapter cannot check), and each parse convention.
 - `test/boundary.test.ts`: the runtime (`src/` and `examples/`) imports only relative paths inside this package. It imports no npm package and no file outside the package.
 
@@ -118,6 +123,71 @@ The stamp tells which specification answered:
 
 Exit code 0 means there is a result. 1 means there is no result: the id is not declared, or the list is empty (the envelope is still printed). 2 means invalid arguments, or a file, parsing or adapter error.
 
+## Runtime consistency on the command line
+
+`avouch reconcile` compares the result that the runtime reported with the result of the evaluator and with the scenario expectation (SPEC section 9, Runtime consistency). `avouch gate verify` checks that the reconciled cases cover each decision row. Both commands read files and write no file. They do not run project code: the project's test harness writes the cases.
+
+```sh
+avouch reconcile <ontology.yaml> --cases <cases.jsonl>
+avouch gate verify <ontology.yaml> --rows <rows.jsonl> [--baseline <baseline.json>] [--json] [--adapter <module|config.json>]
+```
+
+### reconcile
+
+The cases file has one `RuntimeCase` (SPEC section 9) per line, as JSON. Empty lines are skipped. A case can have more keys than `RuntimeCase`; they are ignored. The command prints one `ReconcileRow` per case, as one JSON line, in input order. For example, `avouch reconcile library.ontology.yaml --cases cases.jsonl > rows.jsonl` writes the input of `gate verify`.
+
+Exit code 0 means that each case gave a row, also a `mismatch` or a `cannot_reconcile` row: the command does not judge the rows. 2 means invalid arguments, a file or parse error, or a line that is not a `RuntimeCase`; the message gives the file and the line number. The command does not use exit code 1.
+
+### gate verify
+
+The unit of coverage is the decision row. Each row of a decision table and its `otherwise` is one unit. A unit has the name `<action>:rows.<i>` (`i` from 0) or `<action>:otherwise`, as in the R12 keys. A unit is verified when a `match` row has its action, its `row` and the result of that row. A `mismatch` row does not verify its unit. An action without a decision table has no units; it is printed as `no_table` and does not change the result. The command checks every action of the ontology.
+
+Verified means: for one case, `decide` reached this row, and the runtime result and the expected result are the same as the result of `decide`. The runtime does not report which row it ran. A case without an expected result never verifies a unit: `reconcile` gives `expectation_missing` for it, and the gate prints it as `unasserted`. An action with `permission: unknown` never reaches its decision table in `decide`, so all its units stay as `uncovered` entries until the permission is written.
+
+A gap is a condition that a decision row names and that is declared without an expression (`unspecified`). `decide` stops at the first row that names a gap, so the units from that row to `otherwise` are blocked: they are printed as `blocked` and are not reported as uncovered. Each gap needs an exemption with a reason in the baseline. When a gap gets an expression, the units it blocked become ordinary units. The change that adds the expression must also add cases or `uncovered` entries for them.
+
+The baseline is a JSON file. In this example, the condition `loan_active` has no expression:
+
+```json
+{
+  "avouchCoverage": 1,
+  "uncovered": [
+    { "action": "BORROW", "row": 3, "when": { "fails": "returns_in_good_condition" }, "result": "REFERRED" },
+    { "action": "BORROW", "row": "otherwise", "when": null, "result": "BORROWED" }
+  ],
+  "exempt": [
+    { "action": "RETURN", "condition": "loan_active", "kind": "unspecified", "reason": "the source does not state when a loan is active" }
+  ]
+}
+```
+
+- `uncovered` lists units that have no `match` yet, each with the `when` and `result` of its row. An entry for a unit that is now verified fails the gate. The tool does not stop new entries; review the baseline diff for that.
+- `exempt` lists gaps, each with a non-empty `reason`.
+- Both keys are required. A key that is not shown above is an error (exit code 2).
+- Without `--baseline`, both lists are empty.
+- Units are named by position. When rows are added, removed or moved, the positions change; an `uncovered` entry whose `when` or `result` is not the same as in the ontology is stale (`moved`).
+
+The canonical form of the file is `JSON.stringify(baseline, null, 2)` with a final line break, the keys in the order shown above, `uncovered` in unit order (actions in code-unit order, then rows from 0, then `otherwise`) and `exempt` in action order, then condition order. The gate does not check the form. `--json` prints `uncovered` and `unexempted` in the shape and order of the baseline entries; to make a first baseline, copy them and add a reason to each `unexempted` entry.
+
+The gate fails (exit code 1) when:
+
+| Output | Cause |
+|---|---|
+| `uncovered` | a unit has no `match`, is not blocked, and is not in `uncovered` of the baseline |
+| `unexempted` | a gap has no entry in `exempt` |
+| `unreasoned` | an `exempt` entry has no reason, or only white space |
+| `stale` | an `uncovered` entry names a unit that does not exist, that has another `when` or `result` (`moved`), that is verified or that is blocked, or repeats an entry; an `exempt` entry names a condition that is not a gap, or repeats an entry |
+| `failed` | a reconcile row names an action that the ontology does not have (`action_unknown`); a reconcile row is a `mismatch`; a `cannot_reconcile` row has the reason `runtime_missing`, `runtime_unmapped`, `expectation_unmapped`, `snapshot_missing` or `evaluator_error`, or the reason `indeterminate` with the detail `no_row_matched`; a `match` row names a row that the action does not have, or a result that is not the result of that row (`row_unknown`) |
+| `check` | with `--adapter`, the same check as `avouch check` fails |
+
+The reasons `envelope`, `expectation_missing` and `indeterminate` with another detail do not fail the gate. A replay is not a decision; a case without an expectation states nothing to compare. An `indeterminate` result does not fail the gate, except `no_row_matched`; the units that it leaves unverified stay `uncovered` or `blocked`, so the gate still sees them. `no_row_matched` means that no row applies and the table has no `otherwise`.
+
+Known limit: when a case has no expected result, `reconcile` gives `expectation_missing` before it checks the runtime result. So the gate does not see a runtime result that the action cannot give (`runtime_unmapped`) in such a case.
+
+Exit code 0 means the gate passes. 1 means it fails. 2 means invalid arguments (also a repeated option), a file or parse error, an ontology without an `actionTypes` mapping, or a rows or baseline file with a wrong shape. Without `--json`, the command prints one `FAIL` line for each failure, `INFO` lines (`check`, `blocked`, `no_table`, `unasserted`), and a summary line that starts with `PASS` or `FAIL`. `--json` prints `{avouchGate: 1, gate: "verify", check, result}`.
+
+The same gate is a function in the package root, for tests that run without a file system or child processes: `verifyCoverage(ontology, rows, baseline)` returns the `result` object (`src/coverage.ts`). The command is a thin wrapper around it. The function does not run the check.
+
 ## Claude Code plugin
 
 This repository is also a Claude Code plugin marketplace. Install the plugin:

package/SPEC.md

@@ -332,6 +332,8 @@ The physical type mapping is checked here: the profile supplies `decode`, which
 
 `Invocation.disposition` stays the optional Stage 0 field of the fact contract. `reconcile` does not read it.
 
+The command line reads and writes these types as JSON lines, one `RuntimeCase` or one `ReconcileRow` per line (`avouch reconcile`, `avouch gate verify`; README, "Runtime consistency on the command line"). A `Value` is a JSON string, number, boolean, null or array. An optional field that is absent (`reason`, `detail`, `row`, a binding that is not given) is an absent key; a binding with the value null is `null`. The coverage rule of `avouch gate verify` is a rule of the tool, not of this format.
+
 ### Existence is not revealed
 
 `SCOPE_DENIED` is internal. `externalResult` maps it and `INVALID_BINDING` `not_found` to one value, `{result: INVALID_BINDING, param, reason: not_found}`, so a caller cannot learn that an id exists in another tenant. Other reasons, such as `type`, are reported as they are. A runtime must not report `SCOPE_DENIED`; `reconcile` gives `runtime_unmapped` for it. A scenario must not expect it either; `reconcile` gives `expectation_unmapped` for it (step 7).

package/dist/cli/avouch.js

@@ -2,7 +2,9 @@
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { CONFIG_FILE, runCheck } from "./check.js";
+import { GATE_USAGE, runGate } from "./gate.js";
 import { QUERY_USAGE, runQuery } from "./query.js";
+import { RECONCILE_USAGE, runReconcile } from "./reconcile.js";
 const CHECK_USAGE = "usage: avouch check <ontology.yaml> [--adapter <module|config.json>]";
 async function check(args) {
     let adapter;
@@ -38,8 +40,14 @@ async function main() {
         return check(args.slice(1));
     if (args[0] === "query")
         return runQuery(args.slice(1));
+    if (args[0] === "reconcile")
+        return runReconcile(args.slice(1));
+    if (args[0] === "gate")
+        return runGate(args.slice(1));
     console.error(CHECK_USAGE);
     console.error(QUERY_USAGE);
+    console.error(RECONCILE_USAGE);
+    console.error(GATE_USAGE);
     return 2;
 }
 try {

package/dist/cli/gate.d.ts

@@ -0,0 +1,2 @@
+export declare const GATE_USAGE = "usage: avouch gate verify <ontology.yaml> --rows <rows.jsonl> [--baseline <baseline.json>] [--json] [--adapter <module|config.json>]";
+export declare function runGate(args: string[]): Promise<number>;

package/dist/cli/gate.js

@@ -0,0 +1,88 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { verifyCoverage } from "../src/coverage.js";
+import { runCheck } from "./check.js";
+import { readJsonLines } from "./jsonl.js";
+import { parseOptions, readOntology } from "./reconcile.js";
+export const GATE_USAGE = "usage: avouch gate verify <ontology.yaml> --rows <rows.jsonl> [--baseline <baseline.json>] [--json] [--adapter <module|config.json>]";
+const unitText = (row) => (row === "otherwise" ? "otherwise" : `rows.${row}`);
+function text(check, r, pass) {
+    const lines = [];
+    if (check.status === "fail")
+        lines.push(`FAIL check: ${check.schemaErrors} schema error(s), ${check.violations} violation(s)`);
+    for (const u of r.uncovered)
+        lines.push(`FAIL uncovered ${u.action}:${unitText(u.row)}`);
+    for (const g of r.unexempted)
+        lines.push(`FAIL unexempted ${g.action}:${g.condition}`);
+    for (const g of r.unreasoned)
+        lines.push(`FAIL unreasoned ${g.action}:${g.condition}`);
+    for (const s of r.stale)
+        lines.push(s.list === "uncovered" ? `FAIL stale uncovered ${s.action}:${unitText(s.row)} ${s.why}` : `FAIL stale exempt ${s.action}:${s.condition} ${s.why}`);
+    for (const f of r.failed)
+        lines.push(`FAIL case ${f.id} ${f.action} ${f.why}`);
+    lines.push(`INFO check ${check.status}`);
+    for (const b of r.blocked)
+        lines.push(`INFO blocked ${b.action}:${unitText(b.row)} by ${b.condition}`);
+    for (const a of r.noTable)
+        lines.push(`INFO no_table ${a}`);
+    for (const c of r.unasserted)
+        lines.push(`INFO unasserted ${c.id} ${c.action}`);
+    lines.push(`${pass ? "PASS" : "FAIL"}: ${r.units} unit(s), ${r.verified.length} verified, ${r.baselined.length} baselined, ${r.blocked.length} blocked, ` +
+        `${r.uncovered.length} uncovered; ${r.unexempted.length} unexempted, ${r.unreasoned.length} unreasoned, ${r.stale.length} stale, ` +
+        `${r.failed.length} failed case(s), ${r.unasserted.length} unasserted`);
+    return lines.join("\n") + "\n";
+}
+async function verify(args) {
+    const { pos, opts } = parseOptions(args, ["--rows", "--baseline", "--adapter"], ["--json"]);
+    if (pos.length !== 1)
+        throw new Error(`expected 1 argument, found ${pos.length}`);
+    const rowsFile = opts.get("--rows");
+    if (typeof rowsFile !== "string")
+        throw new Error("--rows is required");
+    const baselineFile = opts.get("--baseline");
+    const adapter = opts.get("--adapter");
+    const ont = readOntology(pos[0]);
+    const rows = readJsonLines(rowsFile);
+    let baseline = null;
+    if (baselineFile !== undefined) {
+        const raw = readFileSync(resolve(baselineFile), "utf8");
+        try {
+            baseline = JSON.parse(raw);
+        }
+        catch (error) {
+            throw new Error(`${baselineFile}: invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    let result;
+    try {
+        result = verifyCoverage(ont, rows, baseline);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(`${msg.startsWith("baseline:") ? baselineFile : msg.startsWith("ontology:") ? pos[0] : rowsFile}: ${msg}`);
+    }
+    let check = { status: "not_run" };
+    if (adapter !== undefined) {
+        const { schemaErrors, report } = await runCheck(pos[0], adapter);
+        const pass = schemaErrors.length === 0 && report.violations.length === 0;
+        check = { status: pass ? "pass" : "fail", adapter, schemaErrors: schemaErrors.length, violations: report.violations.length, waived: report.waived.length };
+    }
+    const pass = result.ok && check.status !== "fail";
+    process.stdout.write(opts.get("--json") === true ? `${JSON.stringify({ avouchGate: 1, gate: "verify", check, result }, null, 2)}\n` : text(check, result, pass));
+    return pass ? 0 : 1;
+}
+// Exit 0: the gate passes; 1: it fails; 2: a usage, file, parse or shape error, or an adapter error (one stderr line).
+export async function runGate(args) {
+    try {
+        if (args.length === 0)
+            throw new Error("missing gate");
+        if (args[0] !== "verify")
+            throw new Error(`unknown gate ${args[0]}`);
+        return await verify(args.slice(1));
+    }
+    catch (error) {
+        const msg = (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " ");
+        console.error(`${msg}; ${GATE_USAGE}`);
+        return 2;
+    }
+}

package/dist/cli/jsonl.d.ts

@@ -0,0 +1,5 @@
+export declare function jsonLines(file: string): {
+    line: number;
+    value: unknown;
+}[];
+export declare function readJsonLines(file: string): unknown[];

package/dist/cli/jsonl.js

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+// One JSON value per line, with its line number (from 1). Lines that are empty or only white space are skipped; the
+// line numbers count them.
+export function jsonLines(file) {
+    return readFileSync(file, "utf8")
+        .split("\n")
+        .flatMap((text, i) => {
+        if (text.trim() === "")
+            return [];
+        try {
+            return [{ line: i + 1, value: JSON.parse(text) }];
+        }
+        catch (error) {
+            throw new Error(`${file}:${i + 1}: invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+}
+export function readJsonLines(file) {
+    return jsonLines(file).map((x) => x.value);
+}

package/dist/cli/reconcile.d.ts

@@ -0,0 +1,7 @@
+export declare const RECONCILE_USAGE = "usage: avouch reconcile <ontology.yaml> --cases <cases.jsonl>";
+export declare function parseOptions(args: string[], values: readonly string[], flags: readonly string[]): {
+    pos: string[];
+    opts: Map<string, string | true>;
+};
+export declare function readOntology(file: string): Record<string, unknown>;
+export declare function runReconcile(args: string[]): Promise<number>;

package/dist/cli/reconcile.js

@@ -0,0 +1,110 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parse } from "yaml";
+import { isObj } from "../src/expr.js";
+import { reconcile } from "../src/reconcile.js";
+import { jsonLines } from "./jsonl.js";
+export const RECONCILE_USAGE = "usage: avouch reconcile <ontology.yaml> --cases <cases.jsonl>";
+const REASONS = ["missing", "unknown_param", "type", "not_found"];
+// Options in any position. Returns the positional arguments and the value of each option.
+export function parseOptions(args, values, flags) {
+    const pos = [];
+    const opts = new Map();
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (opts.has(a))
+            throw new Error(`repeated option ${a}`);
+        if (flags.includes(a))
+            opts.set(a, true);
+        else if (values.includes(a)) {
+            if (i + 1 >= args.length)
+                throw new Error(`${a} needs a file`);
+            opts.set(a, args[++i]);
+        }
+        else if (a.startsWith("--"))
+            throw new Error(`unknown option ${a}`);
+        else
+            pos.push(a);
+    }
+    return { pos, opts };
+}
+export function readOntology(file) {
+    const ont = parse(readFileSync(resolve(file), "utf8"));
+    if (!isObj(ont))
+        throw new Error(`${file}: the root is not a mapping`);
+    return ont;
+}
+// The shape of a RuntimeCase (SPEC section 9). Extra keys are allowed; the snapshot content is not checked.
+function checkCase(x) {
+    if (!isObj(x))
+        return "case is not an object";
+    const c = x;
+    if (typeof c.id !== "string" || c.id === "")
+        return "id is not a non-empty string";
+    if (typeof c.action !== "string" || c.action === "")
+        return "action is not a non-empty string";
+    if (!Object.hasOwn(c, "snapshot"))
+        return "snapshot is missing";
+    if (c.snapshot !== null && !isObj(c.snapshot))
+        return "snapshot is not null or an object";
+    const i = c.inputs;
+    if (!isObj(i))
+        return "inputs is not an object";
+    if (!isObj(i.bindings))
+        return "inputs.bindings is not an object";
+    if (!isObj(i.actor))
+        return "inputs.actor is not an object";
+    if (typeof i.actor.id !== "string")
+        return "inputs.actor.id is not a string";
+    if (typeof i.actor.kind !== "string")
+        return "inputs.actor.kind is not a string";
+    if (!Array.isArray(i.actor.keys) || !i.actor.keys.every((k) => typeof k === "string"))
+        return "inputs.actor.keys is not a list of strings";
+    if (i.scope !== null && typeof i.scope !== "string")
+        return "inputs.scope is not a string or null";
+    if (typeof i.now !== "number" || !Number.isFinite(i.now))
+        return "inputs.now is not a finite number";
+    for (const k of ["reported", "expected"]) {
+        if (!Object.hasOwn(c, k))
+            return `${k} is missing`;
+        const r = c[k];
+        if (r === null)
+            continue;
+        if (!isObj(r))
+            return `${k} is not null or an object`;
+        if (typeof r.result !== "string" || r.result === "")
+            return `${k}.result is not a non-empty string`;
+        if (r.reason !== undefined && !REASONS.includes(r.reason))
+            return `${k}.reason is not one of ${REASONS.join(", ")}`;
+    }
+    return null;
+}
+async function main(args) {
+    const { pos, opts } = parseOptions(args, ["--cases"], []);
+    if (pos.length !== 1)
+        throw new Error(`expected 1 argument, found ${pos.length}`);
+    const cases = opts.get("--cases");
+    if (typeof cases !== "string")
+        throw new Error("--cases is required");
+    const ont = readOntology(pos[0]);
+    const lines = jsonLines(cases);
+    for (const { line, value } of lines) {
+        const problem = checkCase(value);
+        if (problem !== null)
+            throw new Error(`${cases}:${line}: ${problem}`);
+    }
+    const rows = reconcile(ont, lines.map((x) => x.value));
+    process.stdout.write(rows.map((r) => `${JSON.stringify(r)}\n`).join(""));
+    return 0;
+}
+// Exit 0: one row per case (the command does not judge the rows); 2: a usage, file, parse or shape error (one stderr line).
+export async function runReconcile(args) {
+    try {
+        return await main(args);
+    }
+    catch (error) {
+        const msg = (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " ");
+        console.error(`${msg}; ${RECONCILE_USAGE}`);
+        return 2;
+    }
+}

package/dist/src/coverage.d.ts

@@ -0,0 +1,65 @@
+import type { ReconcileRow } from "./reconcile.js";
+/** One coverage unit: a row of a decision table (index from 0) or its otherwise. Key text: `<action>:rows.<i>` / `<action>:otherwise`. */
+export type CoverageUnit = {
+    action: string;
+    row: number | "otherwise";
+};
+/** A unit with the `when` and `result` of its row, so that an entry for a row that moved is stale. */
+export type CoverageDebt = CoverageUnit & {
+    when: {
+        passes: string;
+    } | {
+        fails: string;
+    } | null;
+    result: string;
+};
+/** A condition that a decision row names and that is declared without an expression. */
+export type CoverageGap = {
+    action: string;
+    condition: string;
+    kind: "unspecified";
+};
+export type CoverageExemption = CoverageGap & {
+    reason?: string;
+};
+export type CoverageBaseline = {
+    avouchCoverage: 1;
+    uncovered: CoverageDebt[];
+    exempt: CoverageExemption[];
+};
+export type CoverageStale = {
+    list: "uncovered";
+    action: string;
+    row: number | "otherwise";
+    why: "duplicate" | "no_such_row" | "moved" | "verified" | "blocked";
+} | {
+    list: "exempt";
+    action: string;
+    condition: string;
+    why: "duplicate" | "not_a_gap";
+};
+export type CoverageFailure = {
+    id: string;
+    action: string;
+    why: "mismatch" | "action_unknown" | "row_unknown" | "no_row_matched" | "runtime_missing" | "runtime_unmapped" | "expectation_unmapped" | "snapshot_missing" | "evaluator_error";
+};
+export interface CoverageResult {
+    ok: boolean;
+    units: number;
+    verified: CoverageUnit[];
+    baselined: CoverageUnit[];
+    blocked: (CoverageUnit & {
+        condition: string;
+    })[];
+    noTable: string[];
+    unasserted: {
+        id: string;
+        action: string;
+    }[];
+    uncovered: CoverageDebt[];
+    unexempted: CoverageGap[];
+    unreasoned: CoverageGap[];
+    stale: CoverageStale[];
+    failed: CoverageFailure[];
+}
+export declare function verifyCoverage(ont: unknown, rows: readonly ReconcileRow[], baseline: CoverageBaseline | null): CoverageResult;

package/dist/src/coverage.js

@@ -0,0 +1,229 @@
+// Decision-row coverage of reconcile rows (`avouch gate verify`). A rule of the tool, not of the format. A pure function:
+// it reads only its arguments, and the order of each output list is fixed.
+import { isObj } from "./expr.js";
+import { queryAction } from "./query.js";
+// Which reasons of cannot_reconcile fail the gate. A replay is not a decision; a case without an expectation states
+// nothing to compare; INDETERMINATE does not fail (except no_row_matched: see below), and the units that it leaves
+// unverified stay uncovered or blocked, so the gate still sees them.
+const FAILS = {
+    envelope: false,
+    expectation_missing: false,
+    indeterminate: false,
+    runtime_missing: true,
+    runtime_unmapped: true,
+    expectation_unmapped: true,
+    snapshot_missing: true,
+    evaluator_error: true,
+};
+const sortStr = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const show = (x) => JSON.stringify(x) ?? String(x);
+const isRow = (x) => x === "otherwise" || (typeof x === "number" && Number.isSafeInteger(x) && x >= 0);
+const sameWhen = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function checkKeys(o, path, required, allowed) {
+    for (const k of required)
+        if (!Object.hasOwn(o, k))
+            throw new Error(`baseline: ${path}${k}: missing`);
+    for (const k of Object.keys(o))
+        if (!allowed.includes(k))
+            throw new Error(`baseline: ${path}${k}: unknown key`);
+}
+function checkRows(rows) {
+    if (!Array.isArray(rows))
+        throw new Error("rows: not an array");
+    rows.forEach((x, i) => {
+        const at = `rows[${i}]:`;
+        if (!isObj(x))
+            throw new Error(`${at} not an object`);
+        if (typeof x.id !== "string")
+            throw new Error(`${at} id is not a string`);
+        if (typeof x.action !== "string")
+            throw new Error(`${at} action is not a string`);
+        if (x.status === "match" || x.status === "mismatch") {
+            if (x.row !== undefined && !isRow(x.row))
+                throw new Error(`${at} row ${show(x.row)} is not a row index or "otherwise"`);
+        }
+        else if (x.status === "cannot_reconcile") {
+            if (typeof x.reason !== "string" || !Object.hasOwn(FAILS, x.reason))
+                throw new Error(`${at} reason ${show(x.reason)} is not a reason of cannot_reconcile`);
+        }
+        else
+            throw new Error(`${at} status ${show(x.status)} is not match, mismatch or cannot_reconcile`);
+    });
+}
+function checkBaseline(b) {
+    if (!isObj(b))
+        throw new Error("baseline: not an object");
+    checkKeys(b, "", ["avouchCoverage", "uncovered", "exempt"], ["avouchCoverage", "uncovered", "exempt"]);
+    if (b.avouchCoverage !== 1)
+        throw new Error(`baseline: avouchCoverage: ${show(b.avouchCoverage)} is not 1`);
+    if (!Array.isArray(b.uncovered))
+        throw new Error("baseline: uncovered: not an array");
+    if (!Array.isArray(b.exempt))
+        throw new Error("baseline: exempt: not an array");
+    b.uncovered.forEach((x, i) => {
+        const at = `uncovered[${i}]`;
+        if (!isObj(x))
+            throw new Error(`baseline: ${at}: not an object`);
+        checkKeys(x, `${at}.`, ["action", "row", "when", "result"], ["action", "row", "when", "result"]);
+        if (typeof x.action !== "string")
+            throw new Error(`baseline: ${at}.action: not a string`);
+        if (!isRow(x.row))
+            throw new Error(`baseline: ${at}.row: ${show(x.row)} is not a row index or "otherwise"`);
+        const w = x.when;
+        const when = w === null || (isObj(w) && Object.keys(w).length === 1 && (typeof w.passes === "string" || typeof w.fails === "string"));
+        if (!when)
+            throw new Error(`baseline: ${at}.when: not null, {passes: <condition>} or {fails: <condition>}`);
+        if (typeof x.result !== "string")
+            throw new Error(`baseline: ${at}.result: not a string`);
+    });
+    b.exempt.forEach((x, i) => {
+        const at = `exempt[${i}]`;
+        if (!isObj(x))
+            throw new Error(`baseline: ${at}: not an object`);
+        checkKeys(x, `${at}.`, ["action", "condition", "kind"], ["action", "condition", "kind", "reason"]);
+        if (typeof x.action !== "string")
+            throw new Error(`baseline: ${at}.action: not a string`);
+        if (typeof x.condition !== "string")
+            throw new Error(`baseline: ${at}.condition: not a string`);
+        if (x.kind !== "unspecified")
+            throw new Error(`baseline: ${at}.kind: ${show(x.kind)} is not supported by this version`);
+        if (x.reason !== undefined && typeof x.reason !== "string")
+            throw new Error(`baseline: ${at}.reason: not a string`);
+    });
+}
+// Coverage of the decision rows of every action of the ontology by the match rows. baseline null = both lists empty.
+// Throws for an ontology without an actionTypes object, or rows or a baseline with a wrong shape (the message starts
+// with "ontology:", "rows" or "baseline:").
+export function verifyCoverage(ont, rows, baseline) {
+    if (!isObj(ont) || !isObj(ont.actionTypes))
+        throw new Error("ontology: actionTypes is not an object");
+    const actionTypes = ont.actionTypes;
+    checkRows(rows);
+    if (baseline !== null)
+        checkBaseline(baseline);
+    const base = baseline ?? { avouchCoverage: 1, uncovered: [], exempt: [] };
+    // 1. Units and gaps. A gap: a condition that a row names (as its own or as an earlier row's) and that has no expression.
+    const units = [];
+    const unitOf = new Map();
+    const gaps = [];
+    const noTable = [];
+    const key = (action, x) => JSON.stringify([action, x]);
+    for (const action of Object.keys(actionTypes).sort(sortStr)) {
+        const q = queryAction(ont, action);
+        if (q === null)
+            continue;
+        if (q.decision === null) {
+            noTable.push(action);
+            continue;
+        }
+        const isGap = (c) => q.conditions.find((x) => x.id === c)?.expr === null;
+        const named = new Set();
+        for (const r of q.decision.rows) {
+            const u = { action, q: r, gap: r.requires.find((x) => isGap(x.condition))?.condition ?? null };
+            units.push(u);
+            unitOf.set(key(action, r.row), u);
+            for (const x of r.requires)
+                if (isGap(x.condition))
+                    named.add(x.condition);
+        }
+        for (const condition of [...named].sort(sortStr))
+            gaps.push({ action, condition, kind: "unspecified" });
+    }
+    const gapKeys = new Set(gaps.map((g) => key(g.action, g.condition)));
+    // 2. Case rows, in input order.
+    const verified = new Set();
+    const failed = [];
+    const unasserted = [];
+    for (const r of rows) {
+        const head = { id: r.id, action: r.action };
+        if (!Object.hasOwn(actionTypes, r.action))
+            failed.push({ ...head, why: "action_unknown" });
+        else if (r.status === "mismatch")
+            failed.push({ ...head, why: "mismatch" });
+        else if (r.status === "cannot_reconcile") {
+            if (r.reason === "indeterminate" && r.detail === "no_row_matched")
+                failed.push({ ...head, why: "no_row_matched" });
+            else if (FAILS[r.reason])
+                failed.push({ ...head, why: r.reason });
+            else if (r.reason === "expectation_missing")
+                unasserted.push(head);
+        }
+        else if (r.row !== undefined) {
+            // a match on a row: the unit must exist and give the same result
+            const u = unitOf.get(key(r.action, r.row));
+            const result = isObj(r.result) ? r.result.result : undefined;
+            if (u === undefined || u.q.result !== result)
+                failed.push({ ...head, why: "row_unknown" });
+            else
+                verified.add(u);
+        }
+    }
+    // 3. Exemptions, in baseline order.
+    const stale = [];
+    const exempted = new Set();
+    const unreasonedKeys = new Set();
+    const seenExempt = new Set();
+    for (const e of base.exempt) {
+        const k = key(e.action, e.condition);
+        const out = { list: "exempt", action: e.action, condition: e.condition };
+        if (seenExempt.has(k))
+            stale.push({ ...out, why: "duplicate" });
+        else if (!gapKeys.has(k))
+            stale.push({ ...out, why: "not_a_gap" });
+        else {
+            exempted.add(k);
+            if (e.reason === undefined || e.reason.trim() === "")
+                unreasonedKeys.add(k);
+        }
+        seenExempt.add(k);
+    }
+    // 4. Uncovered entries, in baseline order. The baseline must have no dead entries.
+    const owed = new Set();
+    const seenDebt = new Set();
+    for (const d of base.uncovered) {
+        const k = key(d.action, d.row);
+        const u = unitOf.get(k);
+        const out = { list: "uncovered", action: d.action, row: d.row };
+        if (seenDebt.has(k))
+            stale.push({ ...out, why: "duplicate" });
+        else if (u === undefined)
+            stale.push({ ...out, why: "no_such_row" });
+        else if (!sameWhen(d.when, u.q.when) || d.result !== u.q.result)
+            stale.push({ ...out, why: "moved" });
+        else if (verified.has(u))
+            stale.push({ ...out, why: "verified" });
+        else if (u.gap !== null)
+            stale.push({ ...out, why: "blocked" });
+        else
+            owed.add(u);
+        seenDebt.add(k);
+    }
+    // 5. Each unit, in unit order.
+    const result = {
+        ok: false,
+        units: units.length,
+        verified: [],
+        baselined: [],
+        blocked: [],
+        noTable,
+        unasserted,
+        uncovered: [],
+        unexempted: gaps.filter((g) => !exempted.has(key(g.action, g.condition))),
+        unreasoned: gaps.filter((g) => unreasonedKeys.has(key(g.action, g.condition))),
+        stale,
+        failed,
+    };
+    for (const u of units) {
+        const id = { action: u.action, row: u.q.row };
+        if (verified.has(u))
+            result.verified.push(id);
+        else if (u.gap !== null)
+            result.blocked.push({ ...id, condition: u.gap });
+        else if (owed.has(u))
+            result.baselined.push(id);
+        else
+            result.uncovered.push({ ...id, when: u.q.when, result: u.q.result });
+    }
+    result.ok = [result.uncovered, result.unexempted, result.unreasoned, result.stale, result.failed].every((x) => x.length === 0);
+    return result;
+}

package/dist/src/index.d.ts

@@ -7,3 +7,4 @@ export * from "./patch.js";
 export * from "./query.js";
 export * from "./markdown.js";
 export * from "./unknown.js";
+export * from "./coverage.js";

package/dist/src/index.js

@@ -7,3 +7,4 @@ export * from "./patch.js";
 export * from "./query.js";
 export * from "./markdown.js";
 export * from "./unknown.js";
+export * from "./coverage.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githonllc/avouch",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",