@githonllc/avouch 0.0.0-stage → 0.1.0

package/dist/src/reconcile.d.ts

@@ -0,0 +1,53 @@
+import { type Actor, type Bindings, type Snapshot, type Value } from "./evaluate.js";
+import { type Stage1Ontology, type Type } from "./expr.js";
+/** A result as the runtime or a scenario states it. `reason` only for INVALID_BINDING. No `param`: runtimes do not report it. */
+export type Reported = {
+    result: string;
+    reason?: "missing" | "unknown_param" | "type" | "not_found";
+};
+export interface RuntimeCase {
+    id: string;
+    action: string;
+    snapshot: Snapshot | null;
+    inputs: {
+        bindings: Bindings;
+        actor: Actor;
+        scope: string | null;
+        now: number;
+    };
+    reported: Reported | null;
+    expected: Reported | null;
+}
+export type CannotReconcile = "envelope" | "runtime_missing" | "expectation_missing" | "snapshot_missing" | "evaluator_error" | "runtime_unmapped" | "indeterminate";
+export type ReconcileRow = {
+    id: string;
+    action: string;
+    status: "match";
+    result: Reported;
+} | {
+    id: string;
+    action: string;
+    status: "mismatch";
+    evaluator: Reported;
+    reported: Reported;
+    expected: Reported;
+} | {
+    id: string;
+    action: string;
+    status: "cannot_reconcile";
+    reason: CannotReconcile;
+    detail?: string;
+};
+/** Decodes one stored value of a property with a declared type; undefined = cannot decode. Never called with null. */
+export type Decode = (raw: unknown, type: Type) => Value | undefined;
+export type TypeDefect = {
+    object: string;
+    prop: string;
+    row: string;
+    value: unknown;
+};
+export declare function projectSnapshot(ont: Stage1Ontology, stores: Readonly<Record<string, readonly Readonly<Record<string, unknown>>[]>>, decode: Decode): {
+    snapshot: Snapshot;
+    defects: TypeDefect[];
+};
+export declare function reconcile(ont: Stage1Ontology, cases: readonly RuntimeCase[]): ReconcileRow[];

package/dist/src/reconcile.js

@@ -0,0 +1,78 @@
+// Runtime consistency: the evaluator, the runtime and the scenario must state one result for one invocation.
+import { decide, externalResult } from "./evaluate.js";
+import { fitsType, INVOCATION_RESULTS, own } from "./expr.js";
+// Stored rows (physical values) -> a typed snapshot. Each property with a declared type is decoded and then checked with
+// fitsType; a value that cannot be decoded or does not fit is a defect and keeps its raw value. Null is never decoded.
+// An absent column is not projected (decide throws when it reads it: an incomplete snapshot). Pure link tables fail closed.
+export function projectSnapshot(ont, stores, decode) {
+    const datasources = new Set(Object.values(ont.objectTypes).map((o) => o.datasource));
+    for (const l of ont.linkTypes)
+        if (l.table !== undefined && !datasources.has(l.table))
+            throw new Error(`pure link ${l.id} is not projected`);
+    const objects = {};
+    const defects = [];
+    for (const [object, o] of Object.entries(ont.objectTypes)) {
+        if (!Object.hasOwn(stores, o.datasource))
+            throw new Error(`snapshot lacks store ${o.datasource}`);
+        objects[object] = stores[o.datasource].map((stored) => {
+            const row = { ...stored };
+            for (const [prop, p] of Object.entries(o.properties)) {
+                const raw = row[prop];
+                if (p.type === undefined || raw === undefined || raw === null)
+                    continue;
+                const v = decode(raw, p.type);
+                if (v === undefined || !fitsType(v, p.type))
+                    defects.push({ object, prop, row: String(row.id), value: raw });
+                else
+                    row[prop] = v;
+            }
+            return row;
+        });
+    }
+    return { snapshot: { objects }, defects };
+}
+// Strict on reason: both absent is equal; INVALID_BINDING with different reasons is not.
+const same = (a, b) => a.result === b.result && a.reason === b.reason;
+const ENVELOPE = ["REPLAYED", "IDEMPOTENCY_CONFLICT"];
+const INVOCATION = INVOCATION_RESULTS;
+// The results a runtime may report for an action: the invocation results and the results its decision table gives.
+function mapped(ont, action, result) {
+    if (INVOCATION.includes(result))
+        return true;
+    const decision = own(ont.actionTypes, action)?.decision;
+    return (decision?.rows ?? []).some((r) => r.result === result) || decision?.otherwise?.result === result;
+}
+// One row per case, in input order. The evaluator result is computed only to compare: a missing runtime result or
+// expectation is reported as such, never filled in from the decision table. Envelope results are not decisions (the
+// evaluator does not implement the envelope; a replay does not recompute domain conditions), so decide is not called.
+// A reported result that the action cannot give (runtime_unmapped) means the runtime did not report its domain result.
+export function reconcile(ont, cases) {
+    return cases.map((c) => {
+        const head = { id: c.id, action: c.action };
+        const cannot = (reason, detail) => ({ ...head, status: "cannot_reconcile", reason, ...(detail !== undefined ? { detail } : {}) });
+        const { reported, expected, snapshot } = c;
+        if (reported === null)
+            return cannot("runtime_missing");
+        if (ENVELOPE.includes(reported.result))
+            return cannot("envelope");
+        if (expected === null)
+            return cannot("expectation_missing");
+        if (snapshot === null)
+            return cannot("snapshot_missing");
+        const { bindings, actor, scope, now } = c.inputs;
+        let d;
+        try {
+            d = decide(ont, c.action, snapshot, scope, bindings, actor, now);
+        }
+        catch (e) {
+            return cannot("evaluator_error", e instanceof Error ? e.message : String(e));
+        }
+        if (!mapped(ont, c.action, reported.result))
+            return cannot("runtime_unmapped", reported.result);
+        if (d.layer === "indeterminate")
+            return cannot("indeterminate", d.reason);
+        const { result, reason } = externalResult(d);
+        const evaluator = reason !== undefined ? { result, reason } : { result };
+        return same(evaluator, reported) && same(evaluator, expected) ? { ...head, status: "match", result: evaluator } : { ...head, status: "mismatch", evaluator, reported, expected };
+    });
+}

package/dist/src/stage1-check.d.ts

@@ -0,0 +1,29 @@
+import { type SourceFacts, type Violation } from "./contract.js";
+import { type Expr, type ExprReads } from "./expr.js";
+type Any = any;
+export declare const quotesOf: (cites: unknown) => string[];
+export interface Scope {
+    by: string;
+    globals: Set<string>;
+    root: string | null;
+    isTenant(objectType: string): boolean;
+}
+export declare function parseScope(ont: Record<string, Any>): Scope | null;
+export type ConditionAnalysis = {
+    expr: Expr;
+} & ({
+    reads: ExprReads;
+} | {
+    error: string;
+});
+export type ConditionAnalyses = Map<string, Map<string, ConditionAnalysis>>;
+export declare function analyzeConditions(ont: Record<string, Any>): ConditionAnalyses;
+export declare function asReads(r: ExprReads): Any[];
+export interface Stage1Context {
+    ont: Record<string, Any>;
+    facts: SourceFacts;
+    scope: Scope | null;
+    conditions: ConditionAnalyses;
+}
+export declare function stage1Violations({ ont, facts, scope, conditions }: Stage1Context): Violation[];
+export {};

package/dist/src/stage1-check.js

@@ -0,0 +1,305 @@
+// Stage 1 static checks: derived properties and types (R1, R2, R4), scope (R1, R2), dispositions (R1, R2), condition
+// shape (R1) and decision tables (R1, R12). Pure: no I/O. check() (./checker) parses the scope and analyzes the expression
+// conditions once (parseScope, analyzeConditions), uses both itself (R4, R6) and passes them to stage1Violations.
+import { IDENT } from "./contract.js";
+import { checkPredicate, derivedPropertyType, DISPOSITION_CLASSES, INVOCATION_RESULTS, isObj, newReads } from "./expr.js";
+import { absorbingQuantifiers, mayNullIn, mayUnknown } from "./unknown.js";
+const isStr = (x) => typeof x === "string" && x.length > 0;
+const arr = (x) => (Array.isArray(x) ? x : []);
+const mapOf = (x) => (isObj(x) ? x : {});
+// a key of an ontology mapping: own keys only (`in` would follow the prototype chain, e.g. "toString")
+const hasKey = (m, k) => isObj(m) && typeof k === "string" && Object.hasOwn(m, k);
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+// The quotes of a `cites: [{cite}]` list.
+export const quotesOf = (cites) => arr(cites).map((x) => x?.cite?.quote).filter(isStr);
+// The declared scope, or null when there is none or it lacks `by` / `cite` (checkScope reports that as R1).
+export function parseScope(ont) {
+    const s = ont.scope;
+    if (!isObj(s) || !isStr(s.by) || !isObj(s.cite))
+        return null;
+    const globals = new Set(arr(s.global).filter((g) => isObj(g) && isStr(g.type)).map((g) => g.type));
+    const root = isObj(s.root) && isStr(s.root.type) ? s.root.type : null;
+    return { by: s.by, globals, root, isTenant: (o) => !globals.has(o) && o !== root };
+}
+// Type-checks every expression condition once and records what it reads.
+export function analyzeConditions(ont) {
+    const out = new Map();
+    for (const [cid, c] of Object.entries(mapOf(ont.actionTypes))) {
+        const m = new Map();
+        for (const pc of isObj(c) ? arr(c.conditions) : []) {
+            if (!isObj(pc) || !isStr(pc.id) || pc.expr === undefined)
+                continue;
+            const reads = newReads();
+            try {
+                checkPredicate(ont, pc.expr, { action: cid, locals: {}, collect: reads });
+                m.set(pc.id, { expr: pc.expr, reads });
+            }
+            catch (e) {
+                m.set(pc.id, { expr: pc.expr, error: errMsg(e) });
+            }
+        }
+        out.set(cid, m);
+    }
+    return out;
+}
+// The property reads of an expression in the shape of hand-written `reads`: a value read `{prop, values}` when every read
+// of the property is an eq / neq with a string literal, else `Object.prop`.
+export function asReads(r) {
+    const lits = new Map();
+    for (const x of r.reads)
+        lits.set(x.prop, [...(lits.get(x.prop) ?? []), x.lit]);
+    return [...lits].map(([prop, ls]) => (ls.every((l) => l !== undefined) ? { prop, values: [...new Set(ls)] } : prop));
+}
+const objType = (ont, o) => hasKey(ont.objectTypes, o) && isObj(ont.objectTypes[o]);
+// ------------------------------------------------------------------------------------------ derived properties and types
+function checkDerived({ ont, facts, v }) {
+    for (const [dn, dp] of Object.entries(mapOf(ont.derivedProperties))) {
+        if (!isObj(dp))
+            continue;
+        const key = `derivedProperties.${dn}`;
+        if (dp.expr === undefined) {
+            if (dp.type !== undefined && !isObj(dp.cite))
+                v("R2", key, "a declared type needs a cite", "type_without_provenance");
+            continue;
+        }
+        // with an expression, a missing type or cite is a shape error (R1 only)
+        if (dp.type === undefined)
+            v("R1", key, "a derived property with an expression needs a type");
+        if (!isObj(dp.cite))
+            v("R1", key, "a derived property with an expression needs a cite");
+        if (dp.type === undefined || !objType(ont, dp.of))
+            continue;
+        const reads = newReads();
+        try {
+            derivedPropertyType(ont, dn, reads);
+        }
+        catch (e) {
+            v("R1", key, errMsg(e));
+            continue;
+        }
+        // each quantifier body on its own: absorbingQuantifiers skips a body that reaches a derived property without expression
+        for (const q of absorbingQuantifiers(ont, facts, dp.expr, { self: dp.of, locals: {} }))
+            v("R12", `${key}:${q}`, absorbsMsg(q, `derived property ${dn}`), "quantifier_absorbs_unknown");
+        if (!isObj(dp.cite))
+            continue; // reported above (R1); its literals have nothing to be checked against
+        const quotes = isStr(dp.cite.quote) ? [dp.cite.quote] : [];
+        for (const x of new Set(reads.literals.map(String)))
+            if (!quotes.some((q) => IDENT(x).test(q)))
+                v("R4", `${key}:${x}`, `derived property ${dn} uses the literal ${x}, which does not appear in its cite quote`, "literal_unsupported");
+    }
+}
+function checkPropertyTypes({ ont, v }) {
+    for (const [name, o] of Object.entries(mapOf(ont.objectTypes)))
+        for (const [pn, pr] of Object.entries(mapOf(o?.properties)))
+            if (isObj(pr) && pr.type !== undefined && !isObj(pr.cite))
+                v("R2", `${name}.${pn}`, "a declared type needs a cite", "type_without_provenance");
+}
+// ------------------------------------------------------------------------------------------ scope
+function checkScope({ ont, facts, v }, scope) {
+    const s = ont.scope;
+    if (s === undefined)
+        return;
+    if (scope === null)
+        return v("R1", "scope", "scope needs by and cite");
+    if (s.global !== undefined && !(Array.isArray(s.global) && s.global.length > 0))
+        v("R1", "scope", "scope.global must be a non-empty list");
+    const entries = [...arr(s.global).map((g, i) => [`scope.global[${i}]`, g]), ...(s.root !== undefined ? [["scope.root", s.root]] : [])];
+    const seen = new Set();
+    for (const [where, g] of entries) {
+        if (!isObj(g) || !isObj(g.cite) || !objType(ont, g.type))
+            v("R1", "scope", `${where} needs a declared object type and a cite`);
+        else if (seen.has(g.type))
+            v("R1", "scope", `${g.type} is listed twice in scope`);
+        else
+            seen.add(g.type);
+    }
+    if (isStr(s.cite.quote) && !IDENT(scope.by).test(s.cite.quote))
+        v("R2", "scope", `the scope field ${scope.by} does not appear in the scope cite quote`, "scope_by_not_in_quote");
+    for (const [name, o] of Object.entries(mapOf(ont.objectTypes))) {
+        // the root type has no field rule; a missing field list is reported as field_list_missing
+        const fl = isObj(o) && isStr(o.doc) && name !== scope.root ? (facts.fieldList(o.doc, name)?.value ?? null) : null;
+        if (!fl)
+            continue;
+        if (scope.globals.has(name) && fl.has(scope.by))
+            v("R2", `${name}.${scope.by}`, `${name} is global, but its field list in ${o.doc} has ${scope.by}`, "scope_field_present");
+        if (!scope.globals.has(name) && !fl.has(scope.by))
+            v("R2", `${name}.${scope.by}`, `${name} is a tenant type, but its field list in ${o.doc} has no ${scope.by}`, "scope_field_missing");
+    }
+}
+// ------------------------------------------------------------------------------------------ dispositions
+function checkDispositions({ ont, v }) {
+    if (ont.dispositions !== undefined && !isObj(ont.dispositions))
+        v("R1", "dispositions", "must be a mapping result id -> {class, cite}");
+    for (const [id, d] of Object.entries(mapOf(ont.dispositions))) {
+        const key = `dispositions.${id}`;
+        if (INVOCATION_RESULTS.includes(id))
+            v("R1", key, `${id} is an invocation result; a disposition needs another name`);
+        if (!isObj(d) || !DISPOSITION_CLASSES.includes(d.class) || !isObj(d.cite))
+            v("R1", key, `needs class (${DISPOSITION_CLASSES.join(" | ")}) and cite`);
+        else if (isStr(d.cite.quote) && !IDENT(id).test(d.cite.quote))
+            v("R2", key, `${id} does not appear in its cite quote`, "disposition_not_in_quote");
+    }
+}
+// ------------------------------------------------------------------------------------------ conditions (shape)
+function checkConditions({ v }, cid, c, analyses) {
+    for (const pc of arr(c.conditions)) {
+        if (!isObj(pc) || !isStr(pc.id))
+            continue; // checker.ts reports it
+        const key = `actionTypes.${cid}.conditions.${pc.id}`;
+        const hasE = pc.expr !== undefined, hasU = pc.unspecified !== undefined;
+        if (hasE === hasU)
+            v("R1", key, "exactly one of expr / unspecified");
+        else if (hasU && !isStr(pc.unspecified))
+            v("R1", key, "unspecified must say what is not written");
+        if (hasE && (pc.reads !== undefined || pc.reads_unspecified !== undefined))
+            v("R1", key, "reads and reads_unspecified go only with unspecified");
+        const a = analyses.get(pc.id);
+        if (a !== undefined && "error" in a)
+            v("R1", key, a.error);
+    }
+}
+// ------------------------------------------------------------------------------------------ decision tables
+// The position cite of a row (implementation decision; facts carry no order across sections): among the cites whose
+// quote names the row's result, the doc of the first one listed, and the earliest of that doc's such quotes.
+function position(facts, r) {
+    const named = arr(r.cites).map((x) => x?.cite).filter((ci) => isObj(ci) && isStr(ci.doc) && isStr(ci.quote) && IDENT(r.result).test(ci.quote));
+    if (named.length === 0)
+        return null;
+    const doc = named[0].doc;
+    const s = facts.section(doc);
+    if (typeof s === "string")
+        return null;
+    const ps = named.filter((ci) => ci.doc === doc).map((ci) => s.text.indexOf(ci.quote)).filter((x) => x >= 0);
+    return ps.length ? { doc, pos: Math.min(...ps) } : null;
+}
+// Shape of one row or of otherwise (R1), its result support and an unspecified next (R12).
+function checkOutcome({ ont, v }, cid, label, r, condIds) {
+    const dk = `actionTypes.${cid}.decision`;
+    if (!isObj(r))
+        return v("R1", dk, `${label} must be a mapping`);
+    const w = r.when;
+    if (condIds && !(isObj(w) && Object.keys(w).length === 1 && condIds.has(w.passes ?? w.fails)))
+        v("R1", dk, `${label}: when must be {passes} or {fails} with a condition id of ${cid}`);
+    const d = hasKey(ont.dispositions, r.result) ? ont.dispositions[r.result] : undefined;
+    if (d === undefined)
+        v("R1", dk, `${label}: result ${r.result} is not a key of dispositions`);
+    if (!(Array.isArray(r.cites) && r.cites.length > 0 && r.cites.every((x) => isObj(x) && isObj(x.cite))))
+        v("R1", dk, `${label} needs cites[{cite}]`);
+    if (isObj(d) && (d.class === "pending") !== (r.next !== undefined))
+        v("R1", dk, `${label}: a pending result has next, and only a pending result has next`);
+    const n = r.next;
+    const ks = isObj(n) ? ["actions", "external", "unspecified"].filter((k) => k in n) : [];
+    const nextOk = n === undefined ||
+        (ks.length === 1 &&
+            (ks[0] === "actions" ? arr(n.actions).length > 0 && n.actions.every((a) => hasKey(ont.actionTypes, a)) : ks[0] === "external" ? isStr(n.external) && isObj(n.cite) : isStr(n.unspecified)));
+    if (!nextOk)
+        v("R1", dk, `${label}: next must be {actions: [declared actions]}, {external, cite} or {unspecified}`);
+    else if (ks[0] === "unspecified")
+        v("R12", `${cid}:${label}`, `${label} of ${cid}: the next step is unspecified: ${n.unspecified}`, "next_unspecified");
+    if (isStr(r.result) && !quotesOf(r.cites).some((q) => IDENT(r.result).test(q)))
+        v("R12", `${cid}:${label}`, `${label} of ${cid}: no cite quote names its result ${r.result}`, "result_unsupported");
+}
+// Rows i < j with different results whose position cites are in one section must follow source order there. Rows whose
+// position cites are in different sections are not compared.
+function checkRowOrder({ facts, v }, cid, rows) {
+    const pos = rows.map((r) => (isObj(r) && isStr(r.result) ? position(facts, r) : null));
+    for (let i = 0; i < rows.length; i++)
+        for (let j = i + 1; j < rows.length; j++) {
+            const a = pos[i], b = pos[j];
+            if (!a || !b || a.doc !== b.doc || rows[i].result === rows[j].result || a.pos < b.pos)
+                continue;
+            v("R12", `${cid}:rows.${i}:rows.${j}`, `rows.${i} (${rows[i].result}) comes before rows.${j} (${rows[j].result}), but its cite does not come earlier in ${a.doc}`, "row_order_mismatch");
+        }
+}
+function checkDecision(ctx, cid, c, analyses) {
+    const { v } = ctx;
+    const conds = arr(c.conditions).filter((pc) => isObj(pc) && isStr(pc.id));
+    const d = c.decision;
+    if (d === undefined) {
+        if (conds.length > 0)
+            v("R12", cid, `${cid} has conditions but no decision table`, "decision_table_missing");
+        return;
+    }
+    const dk = `actionTypes.${cid}.decision`;
+    if (!isObj(d))
+        return v("R1", dk, "must be {hitPolicy, order?, rows, otherwise?}");
+    if (d.hitPolicy !== "first")
+        v("R1", dk, "hitPolicy must be first");
+    if (!Array.isArray(d.rows))
+        v("R1", dk, "rows must be a list");
+    if (d.order !== undefined && !(isObj(d.order) && isObj(d.order.cite)))
+        v("R1", dk, "order must be {cite}");
+    const rows = arr(d.rows);
+    const condIds = new Set(conds.map((pc) => pc.id));
+    rows.forEach((r, i) => checkOutcome(ctx, cid, `rows.${i}`, r, condIds));
+    if (d.otherwise === undefined)
+        v("R12", cid, `the decision table of ${cid} has no otherwise`, "otherwise_missing");
+    else
+        checkOutcome(ctx, cid, "otherwise", d.otherwise, null);
+    if (new Set(rows.map((r) => r?.result)).size > 1 && d.order === undefined)
+        v("R12", cid, `the rows of ${cid} give different results, but no cite says that they are checked in order`, "row_order_uncited");
+    // condition_unspecified: a row uses a condition without expression, or one that reaches a derived property without one
+    const used = new Set(rows.map((r) => r?.when?.passes ?? r?.when?.fails).filter(isStr));
+    for (const pc of conds.filter((x) => used.has(x.id))) {
+        const a = analyses.get(pc.id);
+        const undef = a !== undefined && "reads" in a ? [...a.reads.undefinedDerived] : [];
+        if (pc.expr === undefined)
+            v("R12", `${cid}:${pc.id}`, `a row of ${cid} uses ${pc.id}, which is not written as an expression`, "condition_unspecified");
+        else if (undef.length)
+            v("R12", `${cid}:${pc.id}`, `a row of ${cid} uses ${pc.id}, which reads the derived ${undef.join(", ")} that has no expression`, "condition_unspecified");
+    }
+    checkRowOrder(ctx, cid, rows);
+}
+// ------------------------------------------------------------------------------------------ static UNKNOWN analysis
+const absorbsMsg = (q, where) => `the body of the quantifier at ${q} in ${where} may be UNKNOWN, and the quantifier turns UNKNOWN into T or F; guard its nullable reads with isNotNull`;
+// R12 unsafe_fallthrough and quantifier_absorbs_unknown on the expression conditions that type-check and reach no derived
+// property without an expression (the absent-expression rule; for a condition it excludes the whole expression).
+function checkUnknown({ ont, facts, v }, cid, c, analyses) {
+    const o = ont;
+    const byId = new Map();
+    for (const [id, a] of analyses)
+        if ("reads" in a && a.reads.undefinedDerived.size === 0)
+            byId.set(id, a.expr);
+    const ectx = { action: cid, locals: {} };
+    const mn = mayNullIn(o, facts, ectx);
+    for (const [id, expr] of byId)
+        for (const q of absorbingQuantifiers(o, facts, expr, ectx))
+            v("R12", `${cid}:${id}:${q}`, absorbsMsg(q, `condition ${id} of ${cid}`), "quantifier_absorbs_unknown");
+    if (!isObj(c.decision))
+        return;
+    const rows = arr(c.decision.rows);
+    // implementation decision: Stage 1 does not analyse the other conditions, so every later row is taken as reachable;
+    // but when c is U, a later fails(c) row matches, so the rows after it (and otherwise) are not reached
+    const appliesOrPends = (r) => hasKey(ont.dispositions, r.result) && ["applied", "pending"].includes(ont.dispositions[r.result]?.class);
+    rows.forEach((r, i) => {
+        const id = isObj(r) && isObj(r.when) ? r.when.passes : undefined;
+        if (!isStr(id) || !byId.has(id))
+            return;
+        if (!mayUnknown(o, byId.get(id), mn))
+            return;
+        if (rows.slice(0, i).some((x) => isObj(x) && isObj(x.when) && x.when.fails === id))
+            return;
+        const later = [...rows.slice(i + 1), c.decision.otherwise];
+        const stop = later.findIndex((x) => isObj(x) && isObj(x.when) && x.when.fails === id);
+        if (!(stop < 0 ? later : later.slice(0, stop + 1)).filter(isObj).some(appliesOrPends))
+            return;
+        v("R12", `${cid}:rows.${i}`, `rows.${i} of ${cid} uses passes(${id}), but ${id} may be UNKNOWN; then the table can fall through to an applied or pending result. Consume it with fails(${id}) first, or guard its nullable reads`, "unsafe_fallthrough");
+    });
+}
+export function stage1Violations({ ont, facts, scope, conditions }) {
+    const out = [];
+    const ctx = { ont, facts, v: (rule, key, msg, kind = "generic") => void out.push({ rule, key, msg, kind }) };
+    checkDerived(ctx);
+    checkPropertyTypes(ctx);
+    checkScope(ctx, scope);
+    checkDispositions(ctx);
+    for (const [cid, c] of Object.entries(mapOf(ont.actionTypes))) {
+        if (!isObj(c))
+            continue;
+        const analyses = conditions.get(cid) ?? new Map();
+        checkConditions(ctx, cid, c, analyses);
+        checkDecision(ctx, cid, c, analyses);
+        checkUnknown(ctx, cid, c, analyses);
+    }
+    return out;
+}

package/dist/src/unknown.d.ts

@@ -0,0 +1,10 @@
+import type { SourceFacts } from "./contract.js";
+import { type Expr, type ExprContext, type Stage1Ontology } from "./expr.js";
+export declare const MAX_NULLABLE_REFS = 8;
+export type Truth = "T" | "F" | "U";
+export type MayNull = (path: string) => boolean;
+export declare function freeNullableRefs(ont: Stage1Ontology, e: Expr, mayNull: MayNull): string[];
+export declare function abstractEval(ont: Stage1Ontology, e: Expr, isNull: (path: string) => boolean): ReadonlySet<Truth>;
+export declare function mayUnknown(ont: Stage1Ontology, e: Expr, mayNull: MayNull): boolean;
+export declare function mayNullIn(ont: Stage1Ontology, facts: SourceFacts, ctx: ExprContext): MayNull;
+export declare function absorbingQuantifiers(ont: Stage1Ontology, facts: SourceFacts, e: Expr, ctx: ExprContext): string[];

package/dist/src/unknown.js

@@ -0,0 +1,172 @@
+import { navType, objectBinding, own } from "./expr.js";
+export const MAX_NULLABLE_REFS = 8;
+class NoExpression extends Error {
+}
+// One domain for values and predicates: a null value is {U}, a non-null value is {T, F}.
+const U = new Set(["U"]);
+const TF = new Set(["T", "F"]);
+const QUANTIFIERS = new Set(["exists", "none", "all"]);
+const nodeKey = (e) => Object.keys(e)[0];
+const operands = (e) => e[nodeKey(e)];
+// `x.prop` -> ["x", "prop"]; `x` -> ["x", undefined]
+function split(path) {
+    const dot = path.indexOf(".");
+    return dot < 0 ? [path, undefined] : [path.slice(0, dot), path.slice(dot + 1)];
+}
+// A path with the head `self` replaced by the current self (an object binding name, or "self" at the root).
+function norm(path, self) {
+    const [head, prop] = split(path);
+    return head !== "self" ? path : prop === undefined ? self : `${self}.${prop}`;
+}
+const and3 = (a, b) => (a === "F" || b === "F" ? "F" : a === "U" || b === "U" ? "U" : "T");
+const or3 = (a, b) => (a === "T" || b === "T" ? "T" : a === "U" || b === "U" ? "U" : "F");
+const not3 = (a) => (a === "T" ? "F" : a === "F" ? "T" : "U");
+// a Kleene connective lifted to sets: the product of the operand sets
+function lift(xs, ys, f) {
+    const out = new Set();
+    for (const a of xs)
+        for (const b of ys)
+            out.add(f(a, b));
+    return out;
+}
+// The abstract result of e for one combination: isNull says which normalized paths are null. Every operand of every node
+// is evaluated (no short-circuit), and only isNull(of) of a derived property prunes: freeNullableRefs relies on both.
+function ev(ont, e, self, isNull) {
+    const k = nodeKey(e);
+    switch (k) {
+        case "lit":
+            return TF;
+        case "ref":
+            return isNull(norm(e.ref, self)) ? U : TF;
+        case "derived": {
+            // the only place a derived property is inlined: null without reading the expression when its `of` is null
+            const d = e.derived;
+            const of = norm(d.of.ref, self);
+            if (isNull(of))
+                return U;
+            const x = own(ont.derivedProperties, d.id)?.expr;
+            if (x === undefined)
+                throw new NoExpression(d.id);
+            return ev(ont, x, of, isNull);
+        }
+        case "exists":
+        case "none":
+        case "all":
+            return TF; // two-valued; the body is analysed on its own
+        case "and":
+        case "or": {
+            const [first, ...rest] = operands(e).map((x) => ev(ont, x, self, isNull));
+            return rest.reduce((acc, p) => lift(acc, p, k === "and" ? and3 : or3), first);
+        }
+        case "not":
+            return new Set([...ev(ont, operands(e)[0], self, isNull)].map(not3));
+        case "isNull":
+        case "isNotNull": {
+            const a = ev(ont, operands(e)[0], self, isNull);
+            const out = new Set();
+            if (a.has("U"))
+                out.add(k === "isNull" ? "T" : "F");
+            if (a.has("T") || a.has("F"))
+                out.add(k === "isNull" ? "F" : "T");
+            return out;
+        }
+        default: {
+            // strict nodes (comparisons, in, subsetOf, plus, dateIn): a null operand gives null; non-null operands give T or F
+            // (no narrowing by constants)
+            const xs = operands(e).map((x) => ev(ont, x, self, isNull));
+            const out = new Set();
+            if (xs.some((x) => x.has("U")))
+                out.add("U");
+            if (xs.every((x) => x.has("T") || x.has("F")))
+                (out.add("T"), out.add("F"));
+            return out;
+        }
+    }
+}
+// The distinct normalized paths that may be null and that the outer evaluation reads, sorted. One run of ev with no path
+// null reaches every read (ev evaluates every operand; only a null `of` prunes); quantifiers are not entered, and a
+// `nav.from` is never a read.
+export function freeNullableRefs(ont, e, mayNull) {
+    const seen = new Set();
+    ev(ont, e, "self", (p) => (seen.add(p), false));
+    return [...seen].filter(mayNull).sort();
+}
+// The predicate results of e for one combination: isNull says which paths are null.
+export function abstractEval(ont, e, isNull) {
+    return ev(ont, e, "self", isNull);
+}
+// Whether some combination of nulls over the free nullable reads of e may give U.
+export function mayUnknown(ont, e, mayNull) {
+    const refs = freeNullableRefs(ont, e, mayNull);
+    if (refs.length > MAX_NULLABLE_REFS)
+        return true;
+    for (let mask = 0; mask < 2 ** refs.length; mask++) {
+        const nulls = new Set(refs.filter((_, i) => (mask >> i) & 1));
+        if (abstractEval(ont, e, (p) => nulls.has(p)).has("U"))
+            return true;
+    }
+    return false;
+}
+// Nullability for any context of one ontology and its facts; the field lists are read once per object type.
+function nullability(ont, facts) {
+    const lists = new Map();
+    const fields = (objectType) => {
+        if (!lists.has(objectType)) {
+            const doc = own(ont.objectTypes, objectType)?.doc;
+            lists.set(objectType, typeof doc === "string" ? (facts.fieldList(doc, objectType)?.value ?? null) : null);
+        }
+        return lists.get(objectType);
+    };
+    return (ctx) => (path) => {
+        const [head, prop] = split(path);
+        if (head === "now" || head === "actor")
+            return false;
+        const local = head === "self" || Object.hasOwn(ctx.locals, head);
+        const param = local || ctx.action === undefined ? undefined : own(ont.actionTypes[ctx.action]?.parameters, head);
+        if (!local && param === undefined)
+            return true; // not reachable after the type check; conservative
+        if (param?.optional === true)
+            return true; // an optional parameter, and every property read through it
+        if (prop === undefined)
+            return false; // an object binding, or a required parameter
+        const o = objectBinding(ont, head, ctx);
+        return o === undefined || fields(o)?.get(prop)?.nullable !== false; // non-null only when the field list says so
+    };
+}
+// Nullability of the paths in ctx. A field is non-null only when its field list says so; a field that is not listed,
+// or an object without a field list, has unknown nullability and may be null. An optional parameter may be null; so
+// may every property read through it.
+export function mayNullIn(ont, facts, ctx) {
+    return nullability(ont, facts)(ctx);
+}
+// The quantifiers of e (preorder, through and / or / not and quantifier bodies) whose body may be UNKNOWN. Paths use
+// the type-error notation: `$.none`, `$.and[1].none`, `$.all.where.and[0].exists`. Derived property nodes are not
+// entered: a quantifier inside a derived property is reported once, for the derived property itself. A body that
+// reaches a derived property without an expression is not analysed (its nested quantifiers still are).
+export function absorbingQuantifiers(ont, facts, e, ctx) {
+    const out = [];
+    const mayNullFor = nullability(ont, facts);
+    const walk = (x, at, c) => {
+        const k = nodeKey(x);
+        const p = `${at}.${k}`;
+        if (k === "and" || k === "or" || k === "not")
+            operands(x).forEach((y, i) => walk(y, `${p}[${i}]`, c));
+        else if (QUANTIFIERS.has(k)) {
+            const q = x[k];
+            if (q.where === undefined)
+                return;
+            const c2 = { ...c, locals: { ...c.locals, [q.as]: navType(ont, q.in, c, `${p}.in`) } };
+            try {
+                if (mayUnknown(ont, q.where, mayNullFor(c2)))
+                    out.push(p);
+            }
+            catch (err) {
+                if (!(err instanceof NoExpression))
+                    throw err;
+            }
+            walk(q.where, `${p}.where`, c2);
+        }
+    };
+    walk(e, "$", ctx);
+    return out;
+}