worldvm 0.0.0-stage → 0.1.0

package/dist/_internal/reconciler/evaluation.js

@@ -0,0 +1,704 @@
+import { noticeCopiesFor } from "./notices.js";
+import { evidenceSuperseded } from "./evidence-history.js";
+import { resourceGeneration, resourceProofRecords, resourceMachineScope, } from "./resource-generation.js";
+import { signatureValid } from "./signatures.js";
+import { signedFilesAllowed } from "./files.js";
+import { policyParameter } from "./policies.js";
+import { isInstant, isLocalDate } from "../ir-checks/index.js";
+import { normalizeInstant, localDateAt, shiftTime, timeOrder } from "./instants.js";
+import { readValidity } from "./evidence-validity.js";
+import { emptyBasis } from "./basis.js";
+import { addDays, addMonths, addYears, businessDaysAfter, formatDate, } from "./dates.js";
+import { validApprovalCount } from "./decision-records.js";
+import { decisionApprovalCount, selectedDecision, withinProofPeriod, selectedAddition, legacyAcceptance, } from "./decision-evaluation.js";
+export { selectedDecision, selectedAddition, legacyAcceptance } from "./decision-evaluation.js";
+import { ReadSet } from "./dependencies.js";
+import { Unknown, } from "./model.js";
+import { clockCutoffs } from "./temporal.js";
+export const assertSnapshot = (b, now) => {
+    if (b.now !== now)
+        throw new Error(`Basis snapshot is at ${b.now}; evaluation requested ${now}`);
+};
+export const emptyEnv = { get: () => undefined, snapshot: () => ({ bindings: [] }) };
+export const vars = (entries, parent = emptyEnv) => {
+    const own = new Map(entries);
+    return {
+        get: (name, statusRead, parameter) => own.has(name) ? own.get(name) : parent.get(name, statusRead, parameter),
+        snapshot: () => ({
+            bindings: [...own].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+            parent: parent.snapshot(),
+        }),
+    };
+};
+export const componentNames = new WeakMap();
+/** An instance's names: its inputs, its component's params, self, attached, machines and
+ * requirements (whose statuses come from `status`). */
+export const instanceEnv = (p, inst, status, reads) => {
+    const component = p.components.get(inst.component);
+    let names = componentNames.get(component);
+    if (!names) {
+        names = {
+            params: new Set(component.params.map((x) => x.name)),
+            machines: new Set(component.machines.map((x) => x.name)),
+            requirements: new Set(component.requirements.map((x) => x.name)),
+        };
+        componentNames.set(component, names);
+    }
+    const { params, machines, requirements } = names;
+    return {
+        snapshot: () => ({ instance: inst.id }),
+        get: (name, statusRead, parameter) => {
+            const input = inst.inputs.get(name);
+            if (input !== undefined) {
+                reads?.add({ kind: "input", instance: inst.id, name, value: input });
+                return input;
+            }
+            if (name === "attached") {
+                reads?.add({ kind: "members", instance: inst.id, value: inst.attached });
+                return inst.attached;
+            }
+            if (name === "self")
+                return { inst: inst.id };
+            if (params.has(name)) {
+                const base = inst.params?.get(name) ?? p.params.get(name);
+                if (inst.params?.has(name))
+                    reads?.add({ kind: "input", instance: inst.id, name, value: base });
+                return parameter ? parameter(name, base) : (base ?? new Unknown(`no ${name}`));
+            }
+            if (machines.has(name))
+                return { machine: name };
+            if (requirements.has(name)) {
+                const value = statusRead ? statusRead(inst, name) : status(name);
+                if (!statusRead)
+                    reads?.add({ kind: "status", instance: inst.id, name, value });
+                return value;
+            }
+            return undefined;
+        },
+    };
+};
+export const isUnknown = (v) => v instanceof Unknown;
+export const isInst = (v) => typeof v === "object" && v !== null && "inst" in v;
+export const isDuration = (v) => typeof v === "object" && v !== null && "unit" in v;
+export const truth = (v) => (v === true ? true : v === false ? false : "unknown");
+export const kleene = (t) => (t === "unknown" ? new Unknown("undetermined") : t);
+export const and = (ts) => ts.includes(false) ? false : ts.includes("unknown") ? "unknown" : true;
+export const or = (ts) => ts.includes(true) ? true : ts.includes("unknown") ? "unknown" : false;
+export const plus = (date, d, sign = 1) => date.length === 10 && (d.unit === "days" || d.unit === "months" || d.unit === "years")
+    ? d.unit === "years"
+        ? addYears(date, sign * d.n)
+        : d.unit === "months"
+            ? addMonths(date, sign * d.n)
+            : addDays(date, sign * d.n)
+    : shiftTime(date.length === 10 ? `${date}T00:00:00.000Z` : date, sign * d.n, d.unit);
+/** Evaluate an expression that reads no facts (account parameters). */
+export const constant = (p, e) => {
+    const b = emptyBasis("1970-01-01");
+    return evaluateIn({ p, b, inst: undefined, env: emptyEnv }, e);
+};
+export const keyText = (v) => isInst(v) ? v.inst : isUnknown(v) ? "?" : Array.isArray(v) ? v.map(keyText).join(" ") : String(v);
+export const instanceId = (component, key, cycle) => `${component}[${key.map(keyText).join(", ")}]${cycle > 1 ? `#${cycle}` : ""}`;
+export const lookup = (cx, name) => {
+    const v = cx.env.get(name, cx.statusRead, (key, base) => policyParameter(cx, key, base));
+    if (v === undefined)
+        throw new Error(`Unbound ${name}`);
+    return v;
+};
+export const describe = (v) => isUnknown(v)
+    ? "Unknown"
+    : v === null
+        ? "—"
+        : typeof v === "string" && /^\d{4}-\d{2}-\d{2}$/.test(v)
+            ? formatDate(v)
+            : isDuration(v)
+                ? `${v.n} ${v.unit}`
+                : isInst(v)
+                    ? v.inst
+                    : Array.isArray(v)
+                        ? `[${v.map(describe).join(", ")}]`
+                        : typeof v === "object"
+                            ? JSON.stringify(v)
+                            : String(v);
+export const describeValue = describe;
+const evaluateList = (cx, items, evaluate) => {
+    if (!cx.trace)
+        return items.map(evaluate);
+    const trace = cx.trace;
+    let last = trace.witness;
+    const witnesses = [];
+    const values = items.map((item) => {
+        // A branch without a witness must not inherit one from its predecessor.
+        delete trace.witness;
+        const value = evaluate(item);
+        witnesses.push(trace.witness);
+        if (trace.witness)
+            last = trace.witness;
+        return value;
+    });
+    // Ordinary list evaluation retains its last witness; combinators use the per-item trace.
+    if (last)
+        trace.witness = last;
+    (trace.listWitnesses ??= new WeakMap()).set(values, witnesses);
+    return values;
+};
+export const evaluateIn = (cx, e) => {
+    switch (e.k) {
+        case "lit":
+            return e.v;
+        case "kw":
+            return e.v;
+        case "var":
+            if (e.name === "today") {
+                return localDateAt(cx.b.now);
+            }
+            if (e.name === "now")
+                return cx.b.now.length === 10 ? `${cx.b.now}T00:00:00.000Z` : cx.b.now;
+            return lookup(cx, e.name);
+        case "ref":
+            return { ref: e.kind, name: e.name };
+        case "read":
+            throw new Error(`Unlinked read of ${e.role}.${e.field}`);
+        case "attr": {
+            const of = evaluateIn(cx, e.of);
+            if (isUnknown(of))
+                return of;
+            if (typeof of !== "string")
+                return new Unknown(`${e.meta.path}: not a reference`);
+            const f = cx.b.fact(of, e.attr);
+            return f ? f.v : new Unknown(`no current fact ${e.attr} for ${of}`);
+        }
+        case "inst": {
+            const of = evaluateIn(cx, e.of);
+            if (isUnknown(of))
+                return of;
+            const inst = isInst(of) ? cx.k?.instances.get(of.inst) : undefined;
+            if (!inst || !cx.k)
+                return new Unknown(`${e.field}: no such instance`);
+            if (e.field === "attached") {
+                cx.reads?.add({ kind: "members", instance: inst.id, value: inst.attached });
+                return inst.attached;
+            }
+            const input = inst.inputs.get(e.field);
+            if (input !== undefined) {
+                cx.reads?.add({ kind: "input", instance: inst.id, name: e.field, value: input });
+                return input;
+            }
+            const value = cx.statusRead ? cx.statusRead(inst, e.field) : cx.k.status(inst, e.field);
+            if (!cx.statusRead)
+                cx.reads?.add({ kind: "status", instance: inst.id, name: e.field, value });
+            return value;
+        }
+        case "if": {
+            const test = evaluateIn(cx, e.test);
+            cx.trace?.steps.push({
+                at: e.at,
+                value: test,
+                branch: isUnknown(test) ? "Unknown" : test === true ? "true" : "false",
+            });
+            if (isUnknown(test))
+                return test;
+            return evaluateIn(cx, test === true ? e.then : e.else);
+        }
+        case "fn":
+            return { params: e.params, body: e.body, env: cx.env };
+        case "list":
+            return evaluateList(cx, e.items, (x) => evaluateIn(cx, x));
+        case "call":
+            return call(cx, e);
+    }
+};
+export const apply = (cx, fn, args) => {
+    if (!fn || typeof fn !== "object" || !("body" in fn))
+        throw new Error("Not a function");
+    const env = vars(fn.params.map((p, i) => [p, args[i] ?? null]), fn.env);
+    return evaluateIn({ ...cx, env }, fn.body);
+};
+export const timeOf = (v) => isUnknown(v)
+    ? v
+    : typeof v === "string" && isLocalDate(v)
+        ? v
+        : (normalizeInstant(v) ?? new Unknown("Invalid date or instant"));
+export const dateOf = (v) => isUnknown(v) ? v : typeof v === "string" ? v : new Unknown("not a date");
+export const call = (cx, e) => {
+    if (e.derive) {
+        const d = cx.p.derives.get(e.fn);
+        const args = e.args.map((a) => evaluateIn(cx, a));
+        const env = vars(d.params.map((p, i) => [p.name, args[i] ?? null]));
+        const value = evaluateIn({ ...cx, env }, d.body);
+        cx.trace?.steps.push({ at: e.at, value });
+        return value;
+    }
+    const ev = (i) => evaluateIn(cx, e.args[i]);
+    switch (e.fn) {
+        case "table": {
+            const selector = ev(0);
+            if (isUnknown(selector))
+                return selector;
+            for (let i = 1; i < e.args.length; i += 2) {
+                const key = e.args[i];
+                if (key?.k === "kw" && (key.v === "else" || key.v === selector))
+                    return ev(i + 1);
+            }
+            return new Unknown(`No table row for ${String(selector)}`);
+        }
+        case "=":
+        case "not=": {
+            const [a, b] = [ev(0), ev(1)];
+            if (isUnknown(a))
+                return a;
+            if (isUnknown(b))
+                return b;
+            const clock = (arg) => arg?.k === "var" && ["today", "now"].includes(arg.name);
+            for (const at of clockCutoffs(e.fn, clock(e.args[0]), clock(e.args[1]), a, b, e.args.some((arg) => arg.k === "var" && arg.name === "now") ? "instant" : "date"))
+                cx.temporal?.add(at);
+            const point = (value) => typeof value === "string" && (isLocalDate(value) || isInstant(value));
+            return ((point(a) && point(b)
+                ? timeOrder(a, b) === 0
+                : String(a) === String(b)) ===
+                (e.fn === "="));
+        }
+        case "<":
+        case "<=":
+        case ">":
+        case ">=": {
+            const [a, b] = [ev(0), ev(1)];
+            if (isUnknown(a))
+                return a;
+            if (isUnknown(b))
+                return b;
+            const [x, y] = [Number(a), Number(b)];
+            return e.fn === "<" ? x < y : e.fn === "<=" ? x <= y : e.fn === ">" ? x > y : x >= y;
+        }
+        case "in?": {
+            const [a, list] = [ev(0), ev(1)];
+            if (isUnknown(a))
+                return a;
+            return Array.isArray(list) && list.some((x) => String(x) === String(a));
+        }
+        case "all?":
+        case "any?": {
+            // Evaluate every branch: later branches still contribute reads and time cutoffs.
+            const values = ev(0);
+            const ts = values.map(truth);
+            const result = e.fn === "all?" ? and(ts) : or(ts);
+            if (cx.trace) {
+                const witnesses = cx.trace.listWitnesses?.get(values);
+                const branch = (i) => {
+                    const value = values[i];
+                    return (witnesses?.[i] ?? {
+                        evidence: null,
+                        via: "",
+                        detail: isUnknown(value) ? `Unknown: ${value.why}` : String(ts[i]),
+                    });
+                };
+                const deciding = ts.indexOf(e.fn === "all?" ? false : true);
+                cx.trace.witness =
+                    deciding >= 0
+                        ? branch(deciding)
+                        : values.length === 1
+                            ? branch(0)
+                            : {
+                                evidence: null,
+                                via: "",
+                                detail: values.length
+                                    ? values.map((_, i) => branch(i).detail).join("; ")
+                                    : String(result),
+                            };
+            }
+            return kleene(result);
+        }
+        case "negate": {
+            const t = truth(ev(0));
+            return t === "unknown" ? kleene(t) : !t;
+        }
+        case "true?":
+            return ev(0) === true;
+        case "false?":
+            return ev(0) === false;
+        case "unknown?":
+            return isUnknown(ev(0));
+        case "known?": {
+            const v = ev(0);
+            return !isUnknown(v) && v !== null;
+        }
+        case "earliest":
+        case "latest": {
+            const dates = ev(0).map(dateOf);
+            const unknown = dates.find(isUnknown);
+            if (unknown)
+                return unknown;
+            if (dates.length === 0)
+                return new Unknown(`${e.fn} of nothing`);
+            return dates.reduce((a, b) => e.fn === "earliest" ? (a < b ? a : b) : a > b ? a : b);
+        }
+        case "instant": {
+            const value = ev(0);
+            if (isUnknown(value))
+                return value;
+            return normalizeInstant(value) ?? new Unknown("Invalid explicitly zoned instant");
+        }
+        case "hours-after":
+        case "minutes-after": {
+            const value = ev(0), count = ev(1);
+            if (isUnknown(value))
+                return value;
+            if (isUnknown(count))
+                return count;
+            const point = normalizeInstant(value);
+            if (!point || typeof count !== "number" || !Number.isSafeInteger(count))
+                return new Unknown("Invalid instant or offset");
+            try {
+                return shiftTime(point, count, e.fn === "hours-after" ? "hours" : "minutes");
+            }
+            catch (error) {
+                if (!(error instanceof RangeError))
+                    throw error;
+                return new Unknown("Instant offset is outside the supported calendar");
+            }
+        }
+        case "days":
+        case "months":
+        case "years":
+        case "hours":
+        case "minutes": {
+            const n = ev(0);
+            return isUnknown(n)
+                ? n
+                : typeof n === "number" && Number.isSafeInteger(n)
+                    ? { n, unit: e.fn }
+                    : new Unknown("Invalid duration count");
+        }
+        case "years-after":
+        case "months-after":
+        case "days-after":
+        case "days-before": {
+            const d = dateOf(ev(0));
+            const count = ev(1);
+            if (isUnknown(d))
+                return d;
+            if (isUnknown(count))
+                return count;
+            const n = Number(count);
+            if (!Number.isFinite(n))
+                return new Unknown("Invalid date offset");
+            if (e.fn === "years-after")
+                return addYears(d, n);
+            if (e.fn === "months-after")
+                return Number.isSafeInteger(n) ? addMonths(d, n) : new Unknown("Invalid date offset");
+            return addDays(d, e.fn === "days-after" ? n : -n);
+        }
+        case "business-days-after": {
+            const d = dateOf(ev(0));
+            const count = ev(1);
+            if (isUnknown(count))
+                return count;
+            const n = Number(count);
+            if (!Number.isFinite(n))
+                return new Unknown("Invalid business-day offset");
+            const ref = ev(3);
+            const calendar = cx.p.calendars.get(ref.name);
+            if (isUnknown(d))
+                return d;
+            const { date, skipped } = businessDaysAfter(d, n, calendar);
+            cx.trace?.steps.push({
+                at: e.at,
+                value: date,
+                note: `${n} business days after ${formatDate(d, false)} on ${calendar.id}@${calendar.version}${skipped.length ? `; skips ${skipped.map((s) => s.why).join(", ")}` : ""}`,
+            });
+            return date;
+        }
+        case "before?":
+        case "on-or-after?": {
+            const [a, b] = [timeOf(ev(0)), timeOf(ev(1))];
+            if (isUnknown(a))
+                return a;
+            if (isUnknown(b))
+                return b;
+            const clock = (arg) => arg?.k === "var" && ["today", "now"].includes(arg.name);
+            for (const at of clockCutoffs(e.fn, clock(e.args[0]), clock(e.args[1]), a, b, e.args.some((arg) => arg.k === "var" && arg.name === "now") ? "instant" : "date"))
+                cx.temporal?.add(at);
+            return e.fn === "before?" ? timeOrder(a, b) < 0 : timeOrder(a, b) >= 0;
+        }
+        case "asserted-at": {
+            const read = e.args[0];
+            if (read.k !== "attr")
+                return new Unknown("asserted-at needs a fact read");
+            const of = evaluateIn(cx, read.of);
+            if (isUnknown(of) || typeof of !== "string")
+                return new Unknown(`${read.meta.path}: unknown`);
+            const f = cx.b.fact(of, read.attr);
+            const value = f ? localDateAt(f.at) : new Unknown(`no current fact ${read.attr} for ${of}`);
+            cx.trace?.steps.push({ at: e.at, value });
+            return value;
+        }
+        case "spells": {
+            const items = ev(0);
+            const [start, end] = [ev(1), ev(2)];
+            const gap = ev(3);
+            const dated = items
+                .map((item) => ({ item, s: apply(cx, start, [item]), e: apply(cx, end, [item]) }))
+                .sort((x, y) => (String(x.s) < String(y.s) ? -1 : 1));
+            // Retain existing spell keys while resource hosts hold effects on uncertain membership.
+            if (cx.k && dated.some((x) => isUnknown(x.s) || x.s === null))
+                cx.k.uncertainMembership = true;
+            const spells = [];
+            // undefined: no spell yet; Unknown: the current spell is open-ended (still running).
+            let until;
+            for (const x of dated) {
+                const current = spells.at(-1);
+                const s = String(x.s);
+                if (current && (isUnknown(until) || s <= plus(until, gap))) {
+                    current.push(x.item);
+                    until =
+                        isUnknown(until) || isUnknown(x.e)
+                            ? new Unknown("open")
+                            : String(x.e) > until
+                                ? String(x.e)
+                                : until;
+                }
+                else {
+                    spells.push([x.item]);
+                    until = isUnknown(x.e) || x.e === null ? new Unknown("open") : String(x.e);
+                }
+            }
+            return spells;
+        }
+        case "resource-generation":
+            return cx.inst
+                ? resourceGeneration(cx.p, cx.b, cx.inst)
+                : new Unknown("No resource occurrence");
+        case "entered-at": {
+            if (!cx.inst)
+                return new Unknown("No machine occurrence");
+            const m = ev(0), target = ev(1), scope = resourceMachineScope(cx.p, cx.b, cx.inst, m.machine);
+            const history = cx.b
+                .history(cx.inst.id, m.machine)
+                .filter((r) => !scope ||
+                ((r.generation ?? 1) === scope.generation &&
+                    (r.account === undefined || r.account === scope.account)));
+            let entry;
+            for (let i = history.length - 1; i >= 0; i--) {
+                const record = history[i];
+                if (record.state === target)
+                    entry = record.at;
+                else if (entry)
+                    break;
+            }
+            return entry
+                ? localDateAt(entry)
+                : new Unknown(scope
+                    ? "No observed entry for this state in the current generation"
+                    : "No observed entry for this state");
+        }
+        case "attested-for": {
+            if (!cx.inst)
+                return new Unknown("No resource occurrence");
+            const m = ev(0), type = ev(1).name;
+            const { proofPeriod: _period, ...sourceContext } = cx;
+            return attested(sourceContext, type, resourceProofRecords(cx.p, cx.b, cx.inst, m.machine, type));
+        }
+        case "notice-delivered?":
+        case "notice-acknowledged?": {
+            const ref = ev(0), notice = cx.p.ir.notices?.find((n) => n.name === ref.name && n.of === cx.inst?.component);
+            if (!notice)
+                return new Unknown("No owned notice");
+            const recipient = evaluateIn(cx, notice.to);
+            if (typeof recipient !== "string" || !recipient || !cx.b.nsOf(recipient))
+                return new Unknown("Unknown notice recipient");
+            const copy = noticeCopiesFor(cx, ref.name)[0];
+            return !!(e.fn === "notice-delivered?" ? copy?.delivery : copy?.acknowledgment);
+        }
+        case "attested":
+            return attested(cx, ev(0).name);
+        case "valid":
+            return readValidity(cx, ev(0).name).value;
+        case "added-on": {
+            const target = ev(0);
+            const addition = typeof target === "string"
+                ? selectedAddition(cx, target, (date) => cx.temporal?.add(date))
+                : null;
+            return addition?.record.at ?? new Unknown("No standing addition for this item");
+        }
+        case "status-is?": {
+            const status = ev(0);
+            return (isUnknown(status) ? "Unknown" : status) === ev(1);
+        }
+        case "satisfied?": {
+            const s = ev(0);
+            if (isUnknown(s))
+                return s;
+            if (s === "Unknown")
+                return new Unknown("status Unknown");
+            return s === "Satisfied" || s === "Waived";
+        }
+        case "met?": {
+            // Satisfied, Waived or NotApplicable: "nothing is owed here".
+            const s = ev(0);
+            if (isUnknown(s))
+                return s;
+            if (s === "Unknown")
+                return new Unknown("status Unknown");
+            return s === "Satisfied" || s === "Waived" || s === "NotApplicable";
+        }
+        case "carried-over?": {
+            const arg = e.args[0];
+            if (arg.k !== "var" || !cx.inst)
+                return false;
+            const requirement = cx.p.components
+                .get(cx.inst.component)
+                .requirements.find((r) => r.name === arg.name);
+            const decision = selectedDecision(cx, arg.name, (date) => cx.temporal?.add(date));
+            return decision
+                ? decision.record.effect === "accept"
+                : !!requirement && legacyAcceptance(cx, requirement)?.decision === "accepted";
+        }
+        case "started?":
+        case "final?":
+        case "in-state?": {
+            const m = ev(0);
+            if (!cx.inst)
+                return false;
+            const state = machineState(cx.b, cx.inst.id, m.machine, resourceMachineScope(cx.p, cx.b, cx.inst, m.machine));
+            const protocol = machineProtocol(cx.p, cx.inst.component, m.machine);
+            if (protocol) {
+                const connector = [...cx.p.connectors.values()].find((c) => c.owns.includes(protocol.name));
+                if (connector && cx.trace)
+                    cx.trace.awaits = `signal ${connector.name}/${protocol.signal}`;
+            }
+            if (cx.trace)
+                cx.trace.witness = {
+                    evidence: null,
+                    via: state ? "signal" : "",
+                    detail: state
+                        ? `${m.machine} is ${protocol?.states.find((s) => s.name === state)?.label ?? state}`
+                        : `No ${m.machine} yet`,
+                };
+            if (e.fn === "started?")
+                return state !== null;
+            if (!state)
+                return false;
+            if (e.fn === "final?")
+                return protocol?.final.includes(state) ?? false;
+            return ev(1).some((s) => s === state);
+        }
+        case "decided": {
+            const ref = ev(0), definition = cx.p.ir.decisions?.find((d) => d.name === ref.name && d.of === cx.inst?.component);
+            if (!definition)
+                return false;
+            if (definition.approvals && !validApprovalCount(decisionApprovalCount(cx, definition)))
+                return new Unknown("Decision approval count is unknown or not a positive integer");
+            const selected = selectedDecision(cx, definition.applies, (date) => cx.temporal?.add(date));
+            const approved = selected?.definition.name === definition.name &&
+                (selected.definition.effect === "approve" || selected.definition.effect === "accept");
+            if (cx.trace && selected)
+                cx.trace.witness = {
+                    evidence: null,
+                    via: `decision:${selected.record.id}`,
+                    detail: `Decision ${selected.record.id} by ${selected.record.by}: ${selected.definition.effect}`,
+                };
+            return approved;
+        }
+        case "members":
+            return ev(0);
+        case "map":
+            return evaluateList(cx, ev(1), (x) => apply(cx, ev(0), [x]));
+        case "filter":
+            return ev(1).filter((x) => apply(cx, ev(0), [x]) === true);
+        case "count":
+            return ev(0).length;
+    }
+    throw new Error(`Unknown function ${e.fn}`);
+};
+/** Attested evidence of a type: for the requirement being evaluated, or anywhere in the instance. */
+export const attested = (cx, type, pinned) => {
+    const evidence = cx.p.evidence.get(type);
+    const label = evidence?.label ?? type;
+    const records = pinned ??
+        (cx.occurrence
+            ? cx.b.evidence(cx.occurrence).filter((e) => e.type === type)
+            : cx.inst
+                ? cx.b.evidenceOf(cx.inst.id).filter((e) => e.type === type)
+                : []);
+    const signed = records
+        .filter((r) => r.status === "attested" &&
+        !evidenceSuperseded(cx.b, r) &&
+        signatureValid(r) &&
+        withinProofPeriod(cx, r.at) &&
+        signedFilesAllowed(cx, type, r.values))
+        .at(-1);
+    if (signed) {
+        if (cx.trace)
+            cx.trace.witness = {
+                evidence: signed,
+                via: "evidence",
+                type,
+                detail: `${label} attested by ${signed.by} on ${formatDate(signed.at, false)}`,
+            };
+        return true;
+    }
+    const unsigned = records.find((r) => r.status === "submitted");
+    if (cx.trace)
+        cx.trace.witness = {
+            evidence: unsigned ?? null,
+            via: "",
+            type,
+            detail: unsigned
+                ? `${label} was submitted on ${formatDate(unsigned.at, false)} but not attested. A completed task is not proof.`
+                : `No attested ${label}`,
+        };
+    return false;
+};
+export const machineProtocol = (p, component, machine) => {
+    const use = p.components.get(component)?.machines.find((m) => m.name === machine);
+    return use ? p.machines.get(use.protocol) : undefined;
+};
+/** A machine's current state: the last accepted signal, or null before it starts. */
+export const machineState = (b, instance, machine, scope) => (scope
+    ? b
+        .history(instance, machine)
+        .filter((r) => (r.generation ?? 1) === scope.generation &&
+        (r.account === undefined || r.account === scope.account))
+    : b.history(instance, machine)).at(-1)?.state ?? null;
+/** May a signal move this machine to `state`? Only along declared transitions. */
+export const canTransition = (p, b, instance, machine, state) => {
+    const protocol = machineProtocol(p, instance.component, machine);
+    if (!protocol)
+        return false;
+    const current = machineState(b, instance.id, machine, resourceMachineScope(p, b, instance, machine));
+    return current === null
+        ? state === protocol.initial
+        : protocol.transitions.some((t) => t.from === current && t.to === state);
+};
+/** The evaluation context of one reconciled instance, for writes outside reconcile. */
+export const instanceContext = (recon, b, inst, reads) => {
+    const p = recon.programs.find((x) => x.account.name === inst.account);
+    const component = p.components.get(inst.component);
+    // Settled results: a name is a requirement or an output (self.<output>).
+    const settled = (id, name) => {
+        const result = recon.results.get(id);
+        return (result?.requirements.find((r) => r.name === name)?.status ??
+            result?.outputs.find((o) => o.name === name)?.status ??
+            "Unknown");
+    };
+    return {
+        p,
+        b,
+        inst,
+        ...(reads ? { reads } : {}),
+        env: instanceEnv(p, inst, (name) => settled(inst.id, name), reads),
+        k: {
+            instances: recon.instances,
+            status: (i, name) => settled(i.id, name),
+        },
+    };
+};
+/** Evaluate an expression in a reconciled instance's scope. */
+export const evaluateFor = (recon, b, now, instance, e, occurrence) => {
+    assertSnapshot(b, now);
+    const inst = recon.instances.get(instance);
+    if (!inst)
+        return new Unknown(`no instance ${instance}`);
+    return evaluateIn({ ...instanceContext(recon, b, inst), ...(occurrence === undefined ? {} : { occurrence }) }, e);
+};
+/** Evaluate an expression over plain values (a draft's fields), with no facts. */
+export const evaluateValues = (p, values, now, e) => evaluateIn({ p, b: emptyBasis(now), inst: undefined, env: vars(Object.entries(values)) }, e);