avouch 0.1.22

package/dist/src/contract.d.ts

@@ -0,0 +1,135 @@
+export type RuleId = "R1" | "R2" | "R3" | "R4" | "R5" | "R6" | "R7" | "R8" | "R9" | "R10" | "R11" | "R12";
+export declare const RULES: readonly RuleId[];
+/** A name as a whole identifier: not preceded or followed by a letter, a digit or `_`. The empty string matches nothing. */
+export declare const IDENT: (s: string) => RegExp;
+export interface Source {
+    anchor: string;
+    locator?: string;
+}
+export interface Fact<T> {
+    value: T;
+    source: Source;
+}
+/** Adapter finding (parse error, duplicate row, harness error). Reported and waived exactly like a violation. */
+export interface Diagnostic {
+    rule: RuleId;
+    kind: string;
+    key: string;
+    msg: string;
+}
+export interface Violation {
+    rule: string;
+    kind: string;
+    key: string;
+    msg: string;
+}
+export interface Report {
+    violations: Violation[];
+    waived: Violation[];
+    info: string[];
+}
+export type SectionLookup = {
+    title: string;
+    text: string;
+} | "missing" | "ambiguous";
+/** nodes = all states; initial = targets of initial pseudo-edges (exactly one expected, checked by R3); edges = "FROM->TO". */
+export interface StateMachineFact {
+    nodes: string[];
+    initial: string[];
+    edges: string[];
+}
+/** Stable row identity supplied by the adapter (for example a SQLite rowid); never a key column that an update may change. */
+export type RowId = string | number;
+/** Net committed change of one store, row by row: an insert keeps its after image, an update its changed columns, a delete its before image. */
+export interface StoreDelta {
+    inserted: {
+        row: RowId;
+        after: Record<string, unknown>;
+    }[];
+    updated: {
+        row: RowId;
+        changes: Record<string, {
+            before: unknown;
+            after: unknown;
+        }>;
+    }[];
+    deleted: {
+        row: RowId;
+        before: Record<string, unknown>;
+    }[];
+}
+/** Inputs the evaluation of one invocation depends on. Recorded only; no rule reads them yet. */
+export interface EvaluationInputs {
+    bindings: unknown;
+    actor: unknown;
+    scope: unknown;
+    now: unknown;
+}
+/** Committed net change of one invocation: changed stores and the event types written. */
+export interface InvocationDelta {
+    stores: Record<string, StoreDelta>;
+    events: string[];
+}
+/**
+ * One invocation of an operation, with an id that the harness generates. Plain records and arrays (no Map or Set), so the
+ * evidence serializes as JSON. Aggregates (changed stores, committed count) are derived by the checker, never stored.
+ * `delta` is non-null iff the outcome is committed (a rejected record has `delta: null`, not an omitted key); the checker
+ * reports any record that breaks this type (SPEC section 4) as an R7 info diagnostic and never throws on it.
+ */
+export type Invocation = {
+    id: string;
+    rolledBackAttempts: number;
+    snapshot: string | null;
+    inputs: EvaluationInputs;
+    disposition?: string;
+} & ({
+    outcome: "committed";
+    delta: InvocationDelta;
+} | {
+    outcome: "rejected";
+    delta: null;
+});
+export interface PermissionRow {
+    keys: Set<string>;
+    text: string;
+}
+export interface Permissions {
+    catalog: Fact<Set<string>>;
+    rows: Fact<Map<string, PermissionRow>>;
+    quoteNamesKey(quote: string, key: string): boolean;
+}
+export type RuleSwitch = true | {
+    disabled: string;
+};
+export interface FormatConfig {
+    actionIdPattern: RegExp;
+    linkFieldPattern: RegExp;
+    stateProperty: string;
+    crossContextMechanisms: string[];
+    requiredSource: Partial<Record<RuleId, string>>;
+    scenarioCoverage?: "printed" | "enforced";
+    rules: Record<RuleId, RuleSwitch>;
+    idempotencyDeclarationRequired?: boolean;
+    evidenceRequired?: boolean;
+}
+export interface SourceFacts {
+    config: FormatConfig;
+    diagnostics: Diagnostic[];
+    info: string[];
+    section(anchor: string): SectionLookup;
+    containsTerm(term: string): boolean;
+    fieldList(anchor: string, objectType: string): Fact<Map<string, {
+        nullable: boolean;
+    }>> | null;
+    storeCatalog?: Fact<Set<string>>;
+    stateMachines?: Map<string, Fact<StateMachineFact | null>>;
+    transitionTriggers?: Map<string, Map<string, Fact<Set<string>>>>;
+    contextMembers?: Map<string, Fact<Set<string>>>;
+    eventCatalog?: Fact<Set<string>>;
+    scenarios?: {
+        ids: Set<string>;
+        cites: Map<string, Set<string>>;
+    };
+    permissions?: Permissions;
+    evidence?: Map<string, Invocation[]>;
+}

package/dist/src/contract.js

@@ -0,0 +1,3 @@
+export const RULES = ["R1", "R2", "R3", "R4", "R5", "R6", "R7", "R8", "R9", "R10", "R11", "R12"];
+/** A name as a whole identifier: not preceded or followed by a letter, a digit or `_`. The empty string matches nothing. */
+export const IDENT = (s) => (s === "" ? /(?!)/ : new RegExp(`(?<![A-Za-z0-9_])${s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![A-Za-z0-9_])`));

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" | "no_decision_table" | "permission_condition" | "indeterminate" | "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,237 @@
+// 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. An indeterminate case has an expectation that the action can give (reconcile steps 4 and 7 come
+// before step 8), and decide does not check it: it fails unless its detail is in DECLARED.
+const FAILS = {
+    envelope: false,
+    expectation_missing: false,
+    indeterminate: true,
+    runtime_missing: true,
+    runtime_unmapped: true,
+    expectation_unmapped: true,
+    snapshot_missing: true,
+    evaluator_error: true,
+};
+// INDETERMINATE details that do not fail: the details of a gap that an ontology can declare, a condition or a derived
+// property without an expression (a baseline gap, or R12 condition_unspecified), and permission: unknown (R10
+// permission_unknown). The detail of a row is not checked against the ontology.
+const DECLARED = ["unspecified", "permission_unknown"];
+// INDETERMINATE details that fail under their own name; another detail, or none, fails as "indeterminate".
+const NAMED = ["no_row_matched", "no_decision_table", "permission_condition"];
+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") {
+                if (!DECLARED.includes(r.detail))
+                    failed.push({ ...head, why: NAMED.includes(r.detail) ? r.detail : "indeterminate" });
+            }
+            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/evaluate.d.ts

@@ -0,0 +1,66 @@
+import { type DispositionClass, type Expr, type Stage1Ontology } from "./expr.js";
+export type Value = string | number | boolean | null | readonly (string | number | boolean)[];
+export type Row = Readonly<Record<string, Value>>;
+export interface Snapshot {
+    objects: Record<string, readonly Row[]>;
+    links?: Record<string, readonly Row[]>;
+}
+export type Actor = {
+    id: string;
+    keys: readonly string[];
+    kind: string;
+};
+export type Bindings = Readonly<Record<string, Value | undefined>>;
+export interface Env {
+    action: string;
+    snapshot: Snapshot;
+    scope: string | null;
+    bindings: Bindings;
+    actor: Actor;
+    now: number;
+}
+export type DecideResult = {
+    layer: "invocation";
+    result: "INVALID_BINDING";
+    param: string;
+    reason: "missing" | "unknown_param" | "type" | "not_found";
+} | {
+    layer: "invocation";
+    result: "SCOPE_DENIED";
+    param: string;
+} | {
+    layer: "invocation";
+    result: "PERMISSION_DENIED";
+} | {
+    layer: "domain";
+    result: string;
+    class: DispositionClass;
+    row: number | "otherwise";
+    next?: unknown;
+} | {
+    layer: "indeterminate";
+    reason: "unspecified";
+    row: number;
+    condition: string;
+    derived?: string;
+} | {
+    layer: "indeterminate";
+    reason: "no_row_matched" | "no_decision_table" | "permission_condition" | "permission_unknown";
+};
+export { INVOCATION_RESULTS } from "./expr.js";
+export declare class UndefinedDerived extends Error {
+    readonly derived: string;
+    constructor(derived: string);
+}
+type TV = "T" | "F" | "U";
+export declare function evalValue(ont: Stage1Ontology, expr: Expr, env: Env): Value;
+export declare function evalPredicate(ont: Stage1Ontology, expr: Expr, env: Env): TV;
+export declare function decide(ont: Stage1Ontology, actionId: string, snapshot: Snapshot, scope: string | null, bindings: Bindings, actor: Actor, now: number): DecideResult;
+export type ExternalResult = {
+    result: string;
+    param?: string;
+    reason?: "missing" | "unknown_param" | "type" | "not_found";
+};
+export declare function externalResult(r: Exclude<DecideResult, {
+    layer: "indeterminate";
+}>): ExternalResult;