avouch 0.1.22

package/dist/src/expr.js

@@ -0,0 +1,497 @@
+// Decision expressions: the AST, the semantic types, the part of an ontology the evaluator reads, and the static type check.
+// No imports. The evaluator (./evaluate) assumes every expression it runs has passed checkPredicate / valueType.
+export const SCALAR_TYPE_NAMES = ["enum", "timestamp", "duration", "date", "timezone", "id", "integer", "number", "boolean", "string"];
+export const EXPR_NODES = [
+    "ref", "lit", "plus", "dateIn", "derived",
+    "eq", "neq", "lt", "lte", "gt", "gte", "and", "or", "not", "in", "subsetOf", "isNull", "isNotNull",
+    "exists", "none", "all", "nav",
+];
+export const DISPOSITION_CLASSES = ["rejected", "recorded", "pending", "applied"];
+// The fixed invocation result set of the format. The first two belong to the idempotency envelope. A disposition id may
+// not be one of these names.
+// Every invocation-layer result, SCOPE_DENIED included. SCOPE_DENIED is internal and never reported (SPEC section 9).
+export const INVOCATION_RESULTS = ["REPLAYED", "IDEMPOTENCY_CONFLICT", "INVALID_BINDING", "SCOPE_DENIED", "PERMISSION_DENIED"];
+// The distinct request fields of a projected parameter, or null: only a scalar {ref: T} parameter with at least one field is
+// projected; on any other parameter projectedFrom has no effect.
+export function projectedFields(p) {
+    const fs = Array.isArray(p.projectedFrom) ? [...new Set(p.projectedFrom.filter((f) => typeof f === "string"))] : [];
+    return isObj(p.type) && typeof p.type.ref === "string" && fs.length > 0 ? fs : null;
+}
+// Whether an id of p that does not resolve binds to null (`unresolved: domain`): only on a required scalar {ref: T}
+// parameter (no optional key) without projectedFrom. On any other parameter the key has no effect, and R1 reports it.
+export function resolvesInDomain(p) {
+    return p.unresolved === "domain" && isObj(p.type) && typeof p.type.ref === "string" && !("set" in p.type) && p.optional === undefined && p.projectedFrom === undefined;
+}
+export class ExprError extends Error {
+    path;
+    constructor(path, msg) {
+        super(`${path}: ${msg}`);
+        this.path = path;
+        this.name = "ExprError";
+    }
+}
+export const newReads = () => ({ reads: [], literals: [], undefinedDerived: new Set() });
+const VALUE_NODES = new Set(["ref", "lit", "plus", "dateIn", "derived"]);
+const COMPARE = new Set(["eq", "neq", "lt", "lte", "gt", "gte"]);
+const ORDERED = new Set(["timestamp", "date", "duration", "integer", "number"]);
+// Names an expression reads without a declaration; no parameter or quantifier variable may take them.
+export const RESERVED_NAMES = ["now", "actor", "self"];
+const RESERVED = new Set(RESERVED_NAMES);
+export const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+// Timestamp bounds, inclusive: 0001-01-02T00:00:00.000Z .. 9999-12-30T23:59:59.999Z. The one-day margin covers every UTC
+// offset, so dateIn always gives a year from 1 to 9999.
+export const TIMESTAMP_MIN = -62135510400000;
+export const TIMESTAMP_MAX = 253402214399999;
+export const isObj = (x) => typeof x === "object" && x !== null && !Array.isArray(x);
+// Own keys only: a name such as `toString` must not resolve to an Object.prototype member.
+export const own = (r, k) => (r !== undefined && Object.hasOwn(r, k) ? r[k] : undefined);
+function nodeKey(e, path) {
+    if (!isObj(e))
+        throw new ExprError(path, "an expression must be a single-key map");
+    const ks = Object.keys(e);
+    if (ks.length !== 1)
+        throw new ExprError(path, `an expression must have exactly one key, found ${ks.length}`);
+    return ks[0];
+}
+function args(e, k, n, path) {
+    const a = e[k];
+    if (!Array.isArray(a))
+        throw new ExprError(path, `${k} takes an array of operands`);
+    if (n === "2+" ? a.length < 2 : a.length !== n)
+        throw new ExprError(path, `${k} takes ${n === "2+" ? "at least 2" : n} operands, found ${a.length}`);
+    return a;
+}
+const isLit = (e) => isObj(e) && Object.keys(e).length === 1 && "lit" in e;
+export function typeEquals(a, b) {
+    if (typeof a === "string" || typeof b === "string")
+        return a === b;
+    if ("ref" in a)
+        return "ref" in b && a.ref === b.ref;
+    if ("set" in a)
+        return "set" in b && typeEquals(a.set, b.set);
+    return false;
+}
+const showType = (t) => typeof t === "string" ? t : "ref" in t ? `{ref: ${t.ref}}` : `{set: ${showType(t.set)}}`;
+const isSet = (t) => typeof t !== "string" && "set" in t;
+export function validTimezone(v) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: v });
+        return true;
+    }
+    catch (err) {
+        if (err instanceof RangeError)
+            return false;
+        throw err;
+    }
+}
+// The one format table, for literals and for parameter values alike.
+export function fitsType(v, t) {
+    if (typeof t !== "string") {
+        if ("set" in t) {
+            const el = t.set;
+            return Array.isArray(v) && v.every((x) => fitsType(x, el));
+        }
+        return typeof v === "string" && v !== "";
+    }
+    switch (t) {
+        case "id":
+            return typeof v === "string" && v !== "";
+        case "enum":
+        case "string":
+            return typeof v === "string";
+        case "timezone":
+            return typeof v === "string" && validTimezone(v);
+        case "date":
+            return typeof v === "string" && DATE_RE.test(v);
+        case "timestamp":
+            return Number.isSafeInteger(v) && v >= TIMESTAMP_MIN && v <= TIMESTAMP_MAX;
+        case "duration":
+        case "integer":
+            return Number.isSafeInteger(v);
+        case "number":
+            return typeof v === "number" && Number.isFinite(v);
+        case "boolean":
+            return typeof v === "boolean";
+    }
+}
+// A literal is a string, a number, or an array of them; there are no Boolean literals.
+const isLitValue = (v) => typeof v === "string" || typeof v === "number" || (Array.isArray(v) && v.every((x) => typeof x === "string" || typeof x === "number"));
+const litFits = (v, t) => isLitValue(v) && fitsType(v, t);
+// A literal in a position of type t; a set literal is non-empty with elements of one JSON type. Records the literal.
+function literal(v, t, ctx, at) {
+    if (Array.isArray(v) && v.length === 0)
+        throw new ExprError(at, "a set literal must not be empty");
+    if (Array.isArray(v) && new Set(v.map((x) => typeof x)).size > 1)
+        throw new ExprError(at, `set literal ${JSON.stringify(v)} mixes element types`);
+    if (!litFits(v, t))
+        throw new ExprError(at, `literal ${JSON.stringify(v)} does not fit ${showType(t)}`);
+    if (ctx.collect && !ctx.nested)
+        ctx.collect.literals.push(...(Array.isArray(v) ? v : [v]));
+}
+// An object binding: a ref-typed parameter of the action, a quantifier variable, or `self`. Returns its object type.
+export function objectBinding(ont, name, ctx) {
+    if (name === "self")
+        return ctx.self;
+    if (Object.hasOwn(ctx.locals, name))
+        return ctx.locals[name];
+    if (ctx.action === undefined)
+        return undefined;
+    const t = own(ont.actionTypes[ctx.action]?.parameters, name)?.type;
+    return t !== undefined && typeof t !== "string" && "ref" in t ? t.ref : undefined;
+}
+function refType(ont, path, ctx, at) {
+    const parts = path.split(".");
+    if (parts.length > 2 || parts.some((p) => p === ""))
+        throw new ExprError(at, `ref ${path}: at most one dot`);
+    const [head, prop] = parts;
+    if (head === "now") {
+        if (prop !== undefined)
+            throw new ExprError(at, "now has no properties");
+        return "timestamp";
+    }
+    if (head === "actor") {
+        if (prop === "id")
+            return "id";
+        if (prop === "keys")
+            return { set: "string" };
+        if (prop === "kind")
+            return "enum";
+        throw new ExprError(at, `actor.${prop ?? ""} is not readable; use actor.id, actor.keys or actor.kind`);
+    }
+    if (head === "self" && ctx.self === undefined)
+        throw new ExprError(at, "self is valid only in a derived property expression");
+    const obj = objectBinding(ont, head, ctx);
+    if (obj !== undefined && own(ont.objectTypes, obj) === undefined)
+        throw new ExprError(at, `object type ${obj} is not declared`);
+    if (prop === undefined) {
+        if (obj !== undefined)
+            return { ref: obj };
+        if (ctx.action === undefined)
+            throw new ExprError(at, `${head} is not visible here`);
+        const p = own(ont.actionTypes[ctx.action]?.parameters, head);
+        if (p === undefined)
+            throw new ExprError(at, `${head} is not a parameter, a binding or a reserved name`);
+        if (p.type === undefined)
+            throw new ExprError(at, `parameter ${head} has no type`);
+        return p.type;
+    }
+    if (obj === undefined)
+        throw new ExprError(at, `${head} is not an object binding`);
+    if (own(ont.derivedProperties, prop)?.of === obj)
+        throw new ExprError(at, `${prop} is a derived property; read it with {derived: {id, of}}`);
+    const t = own(ont.objectTypes[obj].properties, prop)?.type;
+    if (t === undefined)
+        throw new ExprError(at, `${obj}.${prop} is not a declared property with a type`);
+    ctx.collect?.reads.push({ prop: `${obj}.${prop}` });
+    return t;
+}
+function bindingName(ont, from, ctx, at) {
+    if (!isObj(from) || typeof from.ref !== "string" || Object.keys(from).length !== 1)
+        throw new ExprError(at, "expected {ref: <binding name>}");
+    if (from.ref.includes("."))
+        throw new ExprError(at, `${from.ref}: a binding name has no dot`);
+    const t = objectBinding(ont, from.ref, ctx);
+    if (t === undefined)
+        throw new ExprError(at, `${from.ref} is not an object binding`);
+    return t;
+}
+// top: the derived property is the checked expression itself (its literals are recorded), not one reached from another.
+function derivedType(ont, id, at, stack, collect, top = false) {
+    const dp = own(ont.derivedProperties, id);
+    if (dp === undefined)
+        throw new ExprError(at, `derived property ${id} is not declared`);
+    if (dp.type === undefined)
+        throw new ExprError(at, `derived property ${id} has no type`);
+    if (dp.expr === undefined)
+        collect?.undefinedDerived.add(id);
+    else {
+        const ctx = { self: dp.of, locals: {}, collect, nested: !top };
+        if (stack.includes(id))
+            throw new ExprError(at, `derived properties form a cycle: ${[...stack, id].join(" -> ")}`);
+        const where = `${at}<${id}>`;
+        const k = nodeKey(dp.expr, where);
+        if (!VALUE_NODES.has(k)) {
+            // A predicate root is a Boolean expression: the declared type must be boolean.
+            if (dp.type !== "boolean")
+                throw new ExprError(at, `derived property ${id}: a predicate expression needs the declared type boolean, not ${showType(dp.type)}`);
+            checkPredicateIn(ont, dp.expr, ctx, where, [...stack, id]);
+        }
+        else {
+            // A boolean derived property has a predicate root (its definition is a Boolean expression).
+            if (dp.type === "boolean")
+                throw new ExprError(at, `derived property ${id}: declared boolean, so its expression root must be a predicate, not ${k}`);
+            const t = valueTypeIn(ont, dp.expr, ctx, dp.type, where, [...stack, id]);
+            if (!typeEquals(t, dp.type))
+                throw new ExprError(at, `derived property ${id}: expression type ${showType(t)} is not the declared ${showType(dp.type)}`);
+        }
+    }
+    return dp.type;
+}
+function operand(ont, e, ctx, want, at, stack) {
+    const t = valueTypeIn(ont, e, ctx, want, at, stack);
+    if (!typeEquals(t, want))
+        throw new ExprError(at, `expected ${showType(want)}, found ${showType(t)}`);
+}
+function valueTypeIn(ont, e, ctx, expected, at, stack) {
+    const k = nodeKey(e, at);
+    const node = e;
+    const p = `${at}.${k}`;
+    switch (k) {
+        case "ref":
+            if (typeof node.ref !== "string")
+                throw new ExprError(p, "ref takes a path string");
+            return refType(ont, node.ref, ctx, p);
+        case "lit":
+            if (expected === undefined)
+                throw new ExprError(p, "a literal takes its type from its position, and this position gives none");
+            if (expected === "boolean")
+                throw new ExprError(p, "there are no boolean literals; write x or not(x)");
+            if (expected === "string")
+                throw new ExprError(p, "there are no string literals; a string is read only by isNull and isNotNull");
+            literal(node.lit, expected, ctx, p);
+            return expected;
+        case "plus":
+        case "dateIn": {
+            const [a, b] = args(node, k, 2, p);
+            if (isLit(a) && isLit(b))
+                throw new ExprError(p, `${k} with two literal operands`);
+            operand(ont, a, ctx, "timestamp", `${p}[0]`, stack);
+            operand(ont, b, ctx, k === "plus" ? "duration" : "timezone", `${p}[1]`, stack);
+            return k === "plus" ? "timestamp" : "date";
+        }
+        case "derived": {
+            const d = node.derived;
+            if (!isObj(d) || typeof d.id !== "string")
+                throw new ExprError(p, "derived takes {id, of: {ref}}");
+            const of = bindingName(ont, d.of, ctx, `${p}.of`);
+            const dp = own(ont.derivedProperties, d.id);
+            if (dp !== undefined && dp.of !== of)
+                throw new ExprError(p, `derived property ${d.id} is of ${dp.of}, not ${of}`);
+            return derivedType(ont, d.id, p, stack, ctx.collect);
+        }
+        case "nav":
+            throw new ExprError(p, "nav is valid only as the `in` of a quantifier");
+        default:
+            if (EXPR_NODES.includes(k))
+                throw new ExprError(p, `predicate ${k} in a value position`);
+            throw new ExprError(p, `unknown expression node ${k}`);
+    }
+}
+// A literal compared with `{ref: P}`, where P (no dot) is a parameter of the action that declares `values`, must be one of
+// them. Quantifier variables cannot reuse parameter names, so such a ref is always the parameter.
+function checkValues(ont, e, xs, ctx, p) {
+    if (ctx.action === undefined || !isObj(e) || typeof e.ref !== "string" || e.ref.includes("."))
+        return;
+    const param = own(ont.actionTypes[ctx.action]?.parameters, e.ref);
+    const vs = param?.values;
+    if (param?.type !== "enum" || !Array.isArray(vs))
+        return;
+    for (const x of xs)
+        if (!vs.includes(x))
+            throw new ExprError(p, `literal ${JSON.stringify(x)} is not one of the values of parameter ${e.ref}`);
+}
+// Types the two operands of a binary operation; a literal takes the type of the other side.
+function pair(ont, a, b, ctx, p, stack) {
+    if (isLit(a) && isLit(b))
+        throw new ExprError(p, "both operands are literals");
+    if (isLit(a)) {
+        const tb = valueTypeIn(ont, b, ctx, undefined, `${p}[1]`, stack);
+        return [valueTypeIn(ont, a, ctx, tb, `${p}[0]`, stack), tb];
+    }
+    const ta = valueTypeIn(ont, a, ctx, undefined, `${p}[0]`, stack);
+    return [ta, valueTypeIn(ont, b, ctx, ta, `${p}[1]`, stack)];
+}
+function checkPredicateIn(ont, e, ctx, at, stack) {
+    const k = nodeKey(e, at);
+    const node = e;
+    const p = `${at}.${k}`;
+    if (COMPARE.has(k)) {
+        const [a, b] = args(node, k, 2, p);
+        const n0 = ctx.collect?.reads.length ?? 0;
+        const [ta, tb] = pair(ont, a, b, ctx, p, stack);
+        if (isSet(ta) || isSet(tb))
+            throw new ExprError(p, `${k} on a set; sets have only in and subsetOf`);
+        if (ta === "string" || tb === "string")
+            throw new ExprError(p, `${k} on a string; a string is read only by isNull and isNotNull`);
+        // a property read compared by eq / neq with a string literal: record the literal with the read
+        const [l, r] = isLit(a) ? [a, b] : [b, a];
+        if ((k === "eq" || k === "neq") && ctx.collect?.reads.length === n0 + 1 && isLit(l) && typeof l.lit === "string" && isObj(r) && "ref" in r)
+            ctx.collect.reads[n0].lit = l.lit;
+        if (k === "eq" || k === "neq") {
+            const idVsRef = (x, y) => x === "id" && typeof y !== "string" && "ref" in y;
+            if (!typeEquals(ta, tb) && !idVsRef(ta, tb) && !idVsRef(tb, ta))
+                throw new ExprError(p, `${k} compares ${showType(ta)} with ${showType(tb)}`);
+            if (isLit(l))
+                checkValues(ont, r, [l.lit], ctx, p);
+        }
+        else if (typeof ta !== "string" || !ORDERED.has(ta) || !typeEquals(ta, tb))
+            throw new ExprError(p, `${k} needs two operands of one type among timestamp, date, duration, integer, number; found ${showType(ta)} and ${showType(tb)}`);
+        return;
+    }
+    switch (k) {
+        case "and":
+        case "or":
+            args(node, k, "2+", p).forEach((x, i) => checkPredicateIn(ont, x, ctx, `${p}[${i}]`, stack));
+            return;
+        case "not":
+            checkPredicateIn(ont, args(node, k, 1, p)[0], ctx, `${p}[0]`, stack);
+            return;
+        case "in": {
+            const [a, s] = args(node, k, 2, p);
+            if (isLit(a) && isLit(s))
+                throw new ExprError(p, "both operands are literals");
+            if (isLit(a)) {
+                const ts = valueTypeIn(ont, s, ctx, undefined, `${p}[1]`, stack);
+                if (!isSet(ts))
+                    throw new ExprError(`${p}[1]`, `in needs a set, found ${showType(ts)}`);
+                literal(a.lit, ts.set, ctx, `${p}[0]`);
+                return;
+            }
+            const ta = valueTypeIn(ont, a, ctx, undefined, `${p}[0]`, stack);
+            if (isSet(ta))
+                throw new ExprError(`${p}[0]`, "in takes an element, found a set");
+            if (ta === "string")
+                throw new ExprError(`${p}[0]`, "in on a string; a string is read only by isNull and isNotNull");
+            const ts = valueTypeIn(ont, s, ctx, { set: ta }, `${p}[1]`, stack);
+            if (!isSet(ts) || !typeEquals(ts.set, ta))
+                throw new ExprError(p, `in needs {set: ${showType(ta)}}, found ${showType(ts)}`);
+            if (isLit(s) && Array.isArray(s.lit))
+                checkValues(ont, a, s.lit, ctx, p);
+            return;
+        }
+        case "subsetOf": {
+            const [a, b] = args(node, k, 2, p);
+            const [ta, tb] = pair(ont, a, b, ctx, p, stack);
+            if (!isSet(ta) || !typeEquals(ta, tb))
+                throw new ExprError(p, `subsetOf needs two sets of one element type, found ${showType(ta)} and ${showType(tb)}`);
+            return;
+        }
+        case "isNull":
+        case "isNotNull": {
+            const [a] = args(node, k, 1, p);
+            if (isLit(a))
+                throw new ExprError(`${p}[0]`, `${k} of a literal`);
+            valueTypeIn(ont, a, ctx, undefined, `${p}[0]`, stack);
+            return;
+        }
+        case "exists":
+        case "none":
+        case "all": {
+            const q = node[k];
+            if (!isObj(q) || typeof q.as !== "string")
+                throw new ExprError(p, `${k} takes {as, in, where?}`);
+            const as = q.as;
+            if (RESERVED.has(as))
+                throw new ExprError(`${p}.as`, `${as} is a reserved name`);
+            if (Object.hasOwn(ctx.locals, as))
+                throw new ExprError(`${p}.as`, `${as} is already bound by an outer quantifier`);
+            if (ctx.action !== undefined && own(ont.actionTypes[ctx.action]?.parameters, as) !== undefined)
+                throw new ExprError(`${p}.as`, `${as} is a parameter name`);
+            const elem = navType(ont, q.in, ctx, `${p}.in`);
+            if (q.where !== undefined)
+                checkPredicateIn(ont, q.where, { ...ctx, locals: { ...ctx.locals, [as]: elem } }, `${p}.where`, stack);
+            return;
+        }
+        default: {
+            if (!VALUE_NODES.has(k))
+                throw new ExprError(p, `unknown predicate node ${k}`);
+            // A value node of type boolean is a predicate: true / false / null give T / F / U.
+            if (k === "lit")
+                throw new ExprError(p, "a literal in a predicate position; there are no boolean literals");
+            const t = valueTypeIn(ont, e, ctx, undefined, at, stack);
+            if (t !== "boolean")
+                throw new ExprError(p, `value ${k} of type ${showType(t)} in a predicate position; only a boolean value is a predicate`);
+            return;
+        }
+    }
+}
+// A pure link: its table is no object's datasource (the evaluator reads snapshot.links[link.id]).
+export function isPureLink(ont, link) {
+    return link.table !== undefined && !(isObj(ont.objectTypes) && Object.values(ont.objectTypes).some((o) => isObj(o) && o.datasource === link.table));
+}
+// A navigation over a foreign-key link reads link.via on rows of link.from (forward: the source row; reverse: each target
+// row). Recorded only when via is a declared property of link.from and neither name has a dot (a read is `<Object>.<prop>`).
+function collectVia(ont, link, ctx) {
+    if (ctx.collect === undefined || isPureLink(ont, link) || typeof link.via !== "string" || link.via.includes(".") || String(link.from).includes(".") || !isObj(ont.objectTypes))
+        return;
+    const props = own(ont.objectTypes, link.from)?.properties;
+    if (isObj(props) && own(props, link.via) !== undefined)
+        ctx.collect.reads.push({ prop: `${link.from}.${link.via}` });
+}
+// Returns the element object type of a navigation.
+export function navType(ont, n, ctx, at) {
+    if (nodeKey(n, at) !== "nav")
+        throw new ExprError(at, "a quantifier ranges over a nav");
+    const v = n.nav;
+    const p = `${at}.nav`;
+    if (!isObj(v))
+        throw new ExprError(p, "nav takes {from, link, dir}");
+    const from = bindingName(ont, v.from, ctx, `${p}.from`);
+    const link = ont.linkTypes.find((l) => l.id === v.link);
+    if (link === undefined)
+        throw new ExprError(`${p}.link`, `link ${String(v.link)} is not declared`);
+    if (v.dir === "forward") {
+        if (from !== link.from)
+            throw new ExprError(p, `forward ${link.id} starts at ${link.from}, not ${from}`);
+        collectVia(ont, link, ctx);
+        return link.to;
+    }
+    if (v.dir === "reverse") {
+        if (from !== link.to)
+            throw new ExprError(p, `reverse ${link.id} starts at ${link.to}, not ${from}`);
+        collectVia(ont, link, ctx);
+        return link.from;
+    }
+    throw new ExprError(`${p}.dir`, "dir is forward or reverse");
+}
+// Throws ExprError when expr is not a well-typed predicate in ctx.
+export function checkPredicate(ont, expr, ctx) {
+    if (ctx.action !== undefined)
+        for (const name of Object.keys(ont.actionTypes[ctx.action]?.parameters ?? {}))
+            if (RESERVED.has(name))
+                throw new ExprError("$", `parameter ${name} uses a reserved name`);
+    checkPredicateIn(ont, expr, ctx, "$", []);
+}
+// A permission conditional_when: a predicate over request inputs only. The permission step runs after shape and before
+// binding and reads no snapshot, so only these nodes are allowed, a ref is actor.<x> or a parameter name without a dot,
+// and a projected parameter (not a request field) is not readable. Then the ordinary type check.
+const WHEN_NODES = new Set(["eq", "neq", "lt", "lte", "gt", "gte", "and", "or", "not", "in", "subsetOf", "isNull", "isNotNull", "ref", "lit"]);
+export function checkPermissionWhen(ont, expr, action, collect) {
+    const walk = (e, at) => {
+        const k = nodeKey(e, at);
+        const p = `${at}.${k}`;
+        if (!WHEN_NODES.has(k))
+            throw new ExprError(p, `${k} is not allowed in conditional_when; it reads only parameters, actor and literals`);
+        if (k === "lit")
+            return;
+        const v = e[k];
+        if (k === "ref") {
+            if (typeof v !== "string")
+                return; // the type check reports it
+            const [head, prop] = v.split(".");
+            if (head === "actor")
+                return; // the type check checks the property
+            if (head === "now")
+                throw new ExprError(p, "now is not allowed in conditional_when");
+            if (prop !== undefined)
+                throw new ExprError(p, `${v}: conditional_when reads no property; it reads a parameter as given`);
+            const param = own(ont.actionTypes[action]?.parameters, head);
+            if (param !== undefined && projectedFields(param) !== null)
+                throw new ExprError(p, `${head} is a projected parameter; conditional_when reads only request inputs`);
+            return;
+        }
+        if (Array.isArray(v))
+            v.forEach((x, i) => walk(x, `${p}[${i}]`));
+    };
+    walk(expr, "$");
+    checkPredicate(ont, expr, { action, locals: {}, collect });
+}
+// Type-checks a derived property on its own and returns its declared type; throws ExprError when it is not well typed.
+// With collect, its expression is the checked one (its literals are recorded).
+export function derivedPropertyType(ont, id, collect) {
+    return derivedType(ont, id, "$", [], collect, true);
+}
+// The type of a value expression; throws ExprError when it is not well typed. `expected` types a bare literal.
+export function valueType(ont, expr, ctx, expected) {
+    return valueTypeIn(ont, expr, ctx, expected, "$", []);
+}

package/dist/src/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./contract.js";
+export * from "./checker.js";
+export * from "./expr.js";
+export * from "./evaluate.js";
+export * from "./reconcile.js";
+export * from "./patch.js";
+export * from "./query.js";
+export * from "./markdown.js";
+export * from "./unknown.js";
+export * from "./coverage.js";
+export * from "./ledger.js";

package/dist/src/index.js

@@ -0,0 +1,11 @@
+export * from "./contract.js";
+export * from "./checker.js";
+export * from "./expr.js";
+export * from "./evaluate.js";
+export * from "./reconcile.js";
+export * from "./patch.js";
+export * from "./query.js";
+export * from "./markdown.js";
+export * from "./unknown.js";
+export * from "./coverage.js";
+export * from "./ledger.js";

package/dist/src/ledger.d.ts

@@ -0,0 +1,96 @@
+export type Sha256 = (text: string) => string;
+/** The key of a unit: the document, the titles from the top-level ancestor to the heading, and the occurrence (from 1) of that path. */
+export interface UnitKey {
+    doc: string;
+    path: string[];
+    n: number;
+}
+/** A unit: the text from one heading line to the next heading line of any level (or from the start, heading null). */
+export interface DocUnit extends UnitKey {
+    heading: string | null;
+    text: string;
+    sha256: string;
+    empty: boolean;
+}
+export interface LedgerDoc {
+    doc: string;
+    text: string;
+}
+export type LedgerUnitEntry = UnitKey & {
+    sha256: string;
+} & ({
+    claims: string[];
+} | {
+    noClaim: string;
+});
+export interface LedgerOutlineEntry {
+    doc: string;
+    outline: string;
+}
+export type LedgerEntry = (LedgerUnitEntry | LedgerOutlineEntry) & {
+    line: number;
+};
+/** `entry`: the ledger line of the unit as it is now, without `claims` and `noClaim`; the writer adds the decision. */
+export interface LedgerUnitFailure extends UnitKey {
+    sha256: string;
+    firstLine: string;
+    entry: string;
+}
+export interface LedgerResult {
+    ok: boolean;
+    docs: number;
+    units: number;
+    emptyUnits: number;
+    changed: LedgerUnitFailure[];
+    unreviewed: LedgerUnitFailure[];
+    stale: (UnitKey | {
+        doc: string;
+        outline: true;
+    })[];
+    outline: {
+        doc: string;
+        sha256: string;
+    }[];
+    dangling: (UnitKey & {
+        pointer: string;
+    })[];
+}
+/** The text of a key: `<doc> <path as JSON> <n>`. */
+export declare const unitKeyText: (k: UnitKey) => string;
+/**
+ * The units of one document. The text is normalized first: the BOM is removed and CRLF becomes LF. Generated blocks
+ * are not removed: their text is hashed as other text, so a change in it re-opens its unit (fail closed). Then the text
+ * is cut at each ATX heading outside fences. The units keep their line breaks, so together they are exactly the
+ * normalized text. The text before the first heading is the unit with heading null and path []; it is always the first unit.
+ */
+export declare function docUnits(d: LedgerDoc, sha256: Sha256): DocUnit[];
+/**
+ * The outline of a document: the sha256 of the JSON text of the ordered list of `[path, n, heading line]` of all its
+ * units, empty units included. The heading line is the exact first line (null for the text before the first heading),
+ * so a change of level or of closing #s changes the outline, also for an empty unit.
+ */
+export declare const outlineHash: (units: DocUnit[], sha256: Sha256) => string;
+/** Ledger order: doc, then the outline entry before the unit entries, then path element by element (a prefix first), then n. */
+export declare function compareEntries(a: UnitKey | {
+    doc: string;
+    outline: unknown;
+}, b: UnitKey | {
+    doc: string;
+    outline: unknown;
+}): number;
+/**
+ * Checks the shape of the ledger lines (`{line, value}` from a JSON Lines file, blank lines skipped) and returns the
+ * entries. The first line is `{"avouchLedger":1}`; the entries follow in ledger order, each key once.
+ * Throws `<line>: <reason>` on the first error.
+ */
+export declare function parseLedger(lines: readonly {
+    line: number;
+    value: unknown;
+}[]): LedgerEntry[];
+/**
+ * Resolves a JSON Pointer (RFC 6901: `~1` is `/`, `~0` is `~`; a `~` before another character, and the root "", do not resolve) in a value. One extension: on an array, a segment
+ * selects the element whose `id` is the segment, or else the string element equal to it. A numeric index does not select.
+ */
+export declare function resolvePointer(value: unknown, pointer: string): boolean;
+/** The gate: the current units of the documents against the ledger entries, and the claims against the ontology. */
+export declare function verifyLedger(docs: readonly LedgerDoc[], entries: readonly LedgerEntry[], ontology: unknown, sha256: Sha256): LedgerResult;