@bramas/simulant-engine 0.0.0-stage → 0.1.0

package/dist/compile.js

@@ -0,0 +1,640 @@
+/**
+ * Compiles IR expressions to JavaScript closures.
+ *
+ * A deterministic expression becomes `(frame) => value`. An expression that
+ * contains a choice becomes `(frame, k) => void`, which calls `k` once per
+ * outcome, in the order of the choices (continuation-passing style). While
+ * `k` runs, `rt.witness` holds the choices that led to the outcome.
+ *
+ * Variables live in slots of a frame array, allocated statically. Because
+ * evaluation is synchronous and continuations finish before the next outcome
+ * is produced, a slot can simply be overwritten for each outcome.
+ */
+import { BUILTINS } from "@bramas/simulant-lang/builtins";
+import { fieldType, isCollection, resolvePub, showType, T } from "@bramas/simulant-lang/types";
+import { opposite } from "./topology.js";
+import { canonicalSort, encoder, equality, show } from "./values.js";
+/** At most this many calls are recorded (definitions called in lambdas over a whole ring add up). */
+const MAX_TRACED_CALLS = 2000;
+export class Runtime {
+    lay;
+    params = {};
+    topo;
+    topoState = null;
+    decisions = [];
+    witness = [];
+    /** Set only while an explanation evaluates (by a compiler built with `traced`). */
+    trace;
+    flagNames;
+    hiddenFlags;
+    neverFlags;
+    adversaryFlags;
+    constructor(lay) {
+        this.lay = lay;
+        this.flagNames = lay.flags.map(f => f.name);
+        this.hiddenFlags = lay.flags.filter(f => f.visibility === 'hidden').map(f => f.name);
+        this.neverFlags = lay.flags.filter(f => f.acts === 'never').map(f => f.name);
+        this.adversaryFlags = lay.flags.filter(f => f.acts === 'adversary').map(f => f.name);
+    }
+    correct(a) {
+        for (const f of this.flagNames)
+            if (a.f[f])
+                return false;
+        return true;
+    }
+    present(a) {
+        for (const f of this.hiddenFlags)
+            if (a.f[f])
+                return false;
+        return true;
+    }
+    /** Who decides for the agent: never > adversary > algorithm. */
+    acts(a) {
+        for (const f of this.neverFlags)
+            if (a.f[f])
+                return 'never';
+        for (const f of this.adversaryFlags)
+            if (a.f[f])
+                return 'adversary';
+        return 'algorithm';
+    }
+}
+const toND = (c) => c.nd ?? ((fr, k) => k(c.det(fr)));
+/** Evaluates expressions in order, possibly with choices, then calls `k` with their values. */
+function sequence(cs) {
+    const nds = cs.map(toND);
+    const vals = new Array(cs.length);
+    const step = (i, fr, k) => {
+        if (i === nds.length)
+            return k(vals.slice());
+        nds[i](fr, v => { vals[i] = v; step(i + 1, fr, k); });
+    };
+    return (fr, k) => step(0, fr, k);
+}
+export class CompileError extends Error {
+}
+export class Compiler {
+    rt;
+    lay;
+    paramTypes;
+    traced;
+    defFns = new Map();
+    constructor(rt, lay, paramTypes, 
+    /** Records, in `rt.trace`, the lines of values and the calls of definitions (explanations only). */
+    traced = false) {
+        this.rt = rt;
+        this.lay = lay;
+        this.paramTypes = paramTypes;
+        this.traced = traced;
+    }
+    /** Compiles `expr` with variables in slots 0, 1, ... in the order given. */
+    root(expr, vars, defs) {
+        const rc = { n: vars.length };
+        const scope = { vars: new Map() };
+        vars.forEach(([name, t], slot) => {
+            scope.vars.set(name, { slot, t: this.resolve(t) });
+            if (t.k === 'config')
+                scope.config = slot;
+        });
+        const c = this.compile(expr, scope, rc, defs);
+        return { t: c.t, nslots: rc.n, det: c.det, nd: c.nd };
+    }
+    resolve(t) {
+        return resolvePub(t, this.lay.pub);
+    }
+    fail(msg) {
+        throw new CompileError(msg);
+    }
+    compile(expr, scope, rc, defs) {
+        const out = this.compileNode(expr, scope, rc, defs);
+        const at = expr.at;
+        // A traced value remembers where it came from; conditionals and lets pass on their branch's.
+        if (!this.traced || at === undefined || expr.e === 'if' || expr.e === 'match' || expr.e === 'let')
+            return out;
+        const rt = this.rt;
+        const { det, nd } = out;
+        return {
+            t: out.t,
+            det: det && (fr => { const v = det(fr); if (rt.trace)
+                rt.trace.line = at; return v; }),
+            nd: nd && ((fr, k) => nd(fr, v => { if (rt.trace)
+                rt.trace.line = at; k(v); })),
+        };
+    }
+    compileNode(expr, scope, rc, defs) {
+        const rt = this.rt;
+        const c = (e, s = scope) => this.compile(e, s, rc, defs);
+        switch (expr.e) {
+            case 'lit': {
+                const t = this.resolve(expr.type);
+                const value = t.k === 'multiset' ? canonicalSort(t.of)(expr.value) : expr.value;
+                return { t, det: () => value };
+            }
+            case 'var': {
+                const v = scope.vars.get(expr.name) ?? this.fail(`unknown variable ${expr.name}`);
+                const slot = v.slot;
+                return { t: v.t, det: fr => fr[slot] };
+            }
+            case 'param': {
+                const t = this.paramTypes.get(expr.name) ?? this.fail(`unknown parameter ${expr.name}`);
+                const name = expr.name;
+                return { t, det: () => rt.params[name] };
+            }
+            case 'let': {
+                const v = c(expr.value);
+                const slot = rc.n++;
+                const inner = { vars: new Map(scope.vars).set(expr.name, { slot, t: v.t }), config: v.t.k === 'config' ? slot : scope.config };
+                const b = c(expr.body, inner);
+                if (v.det && b.det) {
+                    const vd = v.det, bd = b.det;
+                    return { t: b.t, det: fr => { fr[slot] = vd(fr); return bd(fr); } };
+                }
+                const vn = toND(v), bn = toND(b);
+                return { t: b.t, nd: (fr, k) => vn(fr, x => { fr[slot] = x; bn(fr, k); }) };
+            }
+            case 'if': {
+                const [cond, a, b] = [c(expr.cond), c(expr.then), c(expr.else)];
+                if (cond.det && a.det && b.det) {
+                    const cd = cond.det, ad = a.det, bd = b.det;
+                    return { t: a.t, det: fr => cd(fr) ? ad(fr) : bd(fr) };
+                }
+                const cn = toND(cond), an = toND(a), bn = toND(b);
+                return { t: a.t, nd: (fr, k) => cn(fr, v => (v ? an : bn)(fr, k)) };
+            }
+            case 'match': {
+                const on = c(expr.on);
+                const cases = Object.fromEntries(Object.entries(expr.cases).map(([ctor, e]) => [ctor, c(e)]));
+                const otherwise = expr.else ? c(expr.else) : undefined;
+                const branches = [...Object.values(cases), ...(otherwise ? [otherwise] : [])];
+                const t = branches[0].t;
+                if (on.det && branches.every(b => b.det)) {
+                    const od = on.det;
+                    const table = new Map(Object.entries(cases).map(([ctor, b]) => [ctor, b.det]));
+                    const dflt = otherwise?.det;
+                    return { t, det: fr => (table.get(od(fr)) ?? dflt)(fr) };
+                }
+                const onN = toND(on);
+                const table = new Map(Object.entries(cases).map(([ctor, b]) => [ctor, toND(b)]));
+                const dflt = otherwise && toND(otherwise);
+                return { t, nd: (fr, k) => onN(fr, v => (table.get(v) ?? dflt)(fr, k)) };
+            }
+            case 'fn':
+                return this.fail('a function is only allowed as an argument of a builtin');
+            case 'record': {
+                const names = Object.keys(expr.fields);
+                const cs = names.map(n => c(expr.fields[n]));
+                const t = T.record(names.map((name, i) => ({ name, type: cs[i].t })));
+                const build = (vs) => {
+                    const o = {};
+                    for (let i = 0; i < names.length; i++)
+                        o[names[i]] = vs[i];
+                    return o;
+                };
+                return this.lift(t, cs, build);
+            }
+            case 'with': {
+                const on = c(expr.on);
+                const names = Object.keys(expr.fields);
+                const cs = [on, ...names.map(n => c(expr.fields[n]))];
+                return this.lift(on.t, cs, ([base, ...vs]) => {
+                    const o = { ...base };
+                    for (let i = 0; i < names.length; i++)
+                        o[names[i]] = vs[i];
+                    return o;
+                });
+            }
+            case 'get':
+                return this.get(c(expr.on), expr.field, scope);
+            case 'choose':
+                return this.choose(expr, scope, rc, defs);
+            case 'effect':
+                return this.effect(expr, scope, rc, defs);
+            case 'call':
+                return BUILTINS[expr.fn] ? this.builtin(expr, scope, rc, defs) : this.callDef(expr, scope, rc, defs);
+        }
+    }
+    /** Applies a deterministic function to the values of `cs`, which may contain choices. */
+    lift(t, cs, f) {
+        if (cs.every(x => x.det)) {
+            const ds = cs.map(x => x.det);
+            if (ds.length === 1) {
+                const d = ds[0];
+                return { t, det: fr => f([d(fr)]) };
+            }
+            return { t, det: fr => f(ds.map(d => d(fr))) };
+        }
+        const seq = sequence(cs);
+        return { t, nd: (fr, k) => seq(fr, vs => k(f(vs))) };
+    }
+    configSlot(scope, what) {
+        if (scope.config === undefined)
+            this.fail(`${what} needs a configuration in scope`);
+        return scope.config;
+    }
+    get(on, field, scope) {
+        const t = on.t;
+        switch (t.k) {
+            case 'record': {
+                const ft = fieldType(t, field) ?? this.fail(`${showType(t)} has no field ${field}`);
+                return this.lift(ft, [on], ([v]) => v[field]);
+            }
+            case 'config':
+                if (field === 'world')
+                    return this.lift(this.lay.worldType, [on], ([C]) => C.world);
+                if (field === 'agents')
+                    return this.lift(T.multiset(T.agent), [on], ([C]) => agentIndices(C));
+                return this.fail(`a configuration has no field ${field}`);
+            case 'agent': {
+                const cs = this.configSlot(scope, `reading ${field} of an agent`);
+                let ft;
+                let read;
+                if (field === 'pos') {
+                    ft = T.node;
+                    read = a => a.pos;
+                }
+                else if (field === 'pub') {
+                    ft = this.lay.pub;
+                    read = a => a.pub;
+                }
+                else if (field === 'mem') {
+                    ft = this.lay.mem;
+                    read = a => a.mem;
+                }
+                else if (this.lay.flags.some(f => f.name === field)) {
+                    ft = T.bool;
+                    read = a => !!a.f[field];
+                }
+                else {
+                    ft = this.lay.agentFields.find(f => f.name === field)?.type ?? this.fail(`agents have no field ${field}`);
+                    read = a => a.f[field];
+                }
+                if (on.det) {
+                    const d = on.det;
+                    return { t: ft, det: fr => read(fr[cs].agents[d(fr)]) };
+                }
+                const n = toND(on);
+                return { t: ft, nd: (fr, k) => n(fr, i => k(read(fr[cs].agents[i]))) };
+            }
+            case 'decision': {
+                const ft = field === 'move' ? T.move : field === 'decided' ? T.bool
+                    : this.lay.actions.find(a => a.name === field)?.type ?? this.fail(`decisions have no action ${field}`);
+                return this.lift(ft, [on], ([d]) => d[field]);
+            }
+            default:
+                return this.fail(`${showType(t)} has no fields`);
+        }
+    }
+    /** A deterministic lambda: `(fr, ...args) => value`. */
+    lambda(e, params, scope, rc, defs) {
+        if (e.e !== 'fn')
+            this.fail('expected a function');
+        const vars = new Map(scope.vars);
+        const slots = e.params.map((p, i) => {
+            const slot = rc.n++;
+            vars.set(p.name, { slot, t: this.resolve(params[i]) });
+            return slot;
+        });
+        const body = this.compile(e.body, { vars, config: scope.config }, rc, defs);
+        if (!body.det)
+            this.fail('a function passed to a builtin cannot contain choices');
+        const d = body.det;
+        if (slots.length === 1) {
+            const s = slots[0];
+            return { t: body.t, fn: (fr, x) => { fr[s] = x; return d(fr); } };
+        }
+        return { t: body.t, fn: (fr, ...xs) => { slots.forEach((s, i) => { fr[s] = xs[i]; }); return d(fr); } };
+    }
+    choose(expr, scope, rc, defs) {
+        const rt = this.rt;
+        const from = this.compile(expr.from, scope, rc, defs);
+        if (!isCollection(from.t))
+            this.fail('choose: expected a collection');
+        const elem = from.t.of;
+        const such = expr.such && this.lambda(expr.such, [elem], scope, rc, defs).fn;
+        const label = expr.label ? this.lambda(expr.label, [elem], scope, rc, defs).fn : undefined;
+        const showElem = show(elem);
+        const fromN = toND(from);
+        const site = expr.site;
+        return {
+            t: elem,
+            nd: (fr, k) => fromN(fr, (xs) => {
+                for (let i = 0; i < xs.length; i++) {
+                    const x = xs[i];
+                    if (such && !such(fr, x))
+                        continue;
+                    rt.witness.push({ site, index: i, label: label ? label(fr, x) : showElem(x) });
+                    k(x);
+                    rt.witness.pop();
+                }
+            }),
+        };
+    }
+    effect(expr, scope, rc, defs) {
+        const worldNames = Object.keys(expr.world ?? {});
+        const world = worldNames.map(n => this.compile(expr.world[n], scope, rc, defs));
+        const raiseNames = Object.keys(expr.raise ?? {});
+        const cs = raiseNames.length ? this.configSlot(scope, 'raising flags') : -1;
+        // Each raise becomes a function from the frame to "which agents raise the flag".
+        const raises = raiseNames.map(n => {
+            const e = expr.raise[n];
+            if (e.e === 'fn') {
+                const pred = this.lambda(e, [T.agent], scope, rc, defs).fn;
+                return { t: T.unit, det: fr => fr[cs].agents.map((_, i) => !!pred(fr, i)) };
+            }
+            return this.lift(T.unit, [this.compile(e, scope, rc, defs)], ([idx]) => indexMarks(idx));
+        });
+        const all = [...world, ...raises];
+        return this.lift(T.effect, all, vs => {
+            const eff = { world: {}, raise: {} };
+            worldNames.forEach((n, i) => { eff.world[n] = vs[i]; });
+            raiseNames.forEach((n, j) => { eff.raise[n] = vs[worldNames.length + j]; });
+            return eff;
+        });
+    }
+    callDef(expr, scope, rc, defs) {
+        const def = defs.get(expr.fn) ?? this.fail(`unknown function ${expr.fn}`);
+        let fn = this.defFns.get(def);
+        if (!fn) {
+            fn = this.root(def.body, def.params.map(p => [p.name, p.type]), defs);
+            this.defFns.set(def, fn);
+        }
+        const { nslots, det, nd } = fn;
+        const args = expr.args.map(a => this.compile(a, scope, rc, defs));
+        if (det && args.every(a => a.det)) {
+            const ds = args.map(a => a.det);
+            const run = this.traced ? this.tracedCall(def.name, args.map(a => show(a.t, true)), show(this.resolve(def.ret), true), det) : det;
+            return {
+                t: this.resolve(def.ret),
+                det: fr => {
+                    const f2 = new Array(nslots);
+                    for (let i = 0; i < ds.length; i++)
+                        f2[i] = ds[i](fr);
+                    return run(f2);
+                },
+            };
+        }
+        const seq = sequence(args);
+        const body = nd ?? ((f2, k) => k(det(f2)));
+        return {
+            t: this.resolve(def.ret),
+            nd: (fr, k) => seq(fr, vs => {
+                const f2 = new Array(nslots);
+                vs.forEach((v, i) => { f2[i] = v; });
+                body(f2, k);
+            }),
+        };
+    }
+    /** A definition's body that records its call in `rt.trace` (arguments, result, line it returned from). */
+    tracedCall(fn, showArgs, showRet, body) {
+        const rt = this.rt;
+        return f2 => {
+            const trace = rt.trace;
+            if (!trace)
+                return body(f2);
+            const call = { fn, args: showArgs.map((s, i) => s(f2[i])), result: '', calls: [] };
+            trace.stack.push(call.calls);
+            let v;
+            try {
+                v = body(f2);
+            }
+            finally {
+                trace.stack.pop();
+            }
+            call.result = showRet(v);
+            call.line = trace.line;
+            if (trace.count++ < MAX_TRACED_CALLS)
+                trace.stack[trace.stack.length - 1].push(call);
+            return v;
+        };
+    }
+    builtin(expr, scope, rc, defs) {
+        if (expr.fn === 'correct' || expr.fn === 'present') {
+            // Like a field of the agent: read in the configuration in scope.
+            const cs = this.configSlot(scope, expr.fn);
+            const test = expr.fn === 'correct' ? (a) => this.rt.correct(a) : (a) => this.rt.present(a);
+            const a = this.compile(expr.args[0], scope, rc, defs);
+            if (a.det) {
+                const d = a.det;
+                return { t: T.bool, det: fr => test(fr[cs].agents[d(fr)]) };
+            }
+            const n = toND(a);
+            return { t: T.bool, nd: (fr, k) => n(fr, i => k(test(fr[cs].agents[i]))) };
+        }
+        const sig = BUILTINS[expr.fn];
+        const types = [];
+        const parts = [];
+        expr.args.forEach((arg, i) => {
+            const lam = sig.lambdas?.[i];
+            if (lam) {
+                const params = lam(types);
+                if (typeof params === 'string')
+                    this.fail(params);
+                const l = this.lambda(arg, params, scope, rc, defs);
+                types.push(T.fn(params, l.t));
+                parts.push({ kind: 'fn', fn: l.fn });
+            }
+            else {
+                const c = this.compile(arg, scope, rc, defs);
+                types.push(c.t);
+                parts.push({ kind: 'value', c });
+            }
+        });
+        const t = sig.ret(types);
+        if (typeof t === 'string')
+            this.fail(t);
+        const impl = this.impl(expr.fn, types, t, scope);
+        const values = parts.filter(p => p.kind === 'value').map(p => p.c);
+        const fns = parts.map(p => p.kind === 'fn' ? p.fn : undefined);
+        const hasFns = fns.some(f => f);
+        // Lambdas receive the current frame; values are evaluated first, in order.
+        const call = (fr, vs) => {
+            if (!hasFns)
+                return impl(vs);
+            let j = 0;
+            const args = fns.map(f => f ? (...xs) => f(fr, ...xs) : vs[j++]);
+            return impl(args);
+        };
+        if (values.every(v => v.det)) {
+            const ds = values.map(v => v.det);
+            if (expr.fn === 'and')
+                return { t, det: fr => { for (const d of ds)
+                        if (!d(fr))
+                            return false; return true; } };
+            if (expr.fn === 'or')
+                return { t, det: fr => { for (const d of ds)
+                        if (d(fr))
+                            return true; return false; } };
+            if (ds.length === 1) {
+                const d = ds[0];
+                return { t, det: fr => call(fr, [d(fr)]) };
+            }
+            if (ds.length === 2) {
+                const [d0, d1] = ds;
+                return { t, det: fr => call(fr, [d0(fr), d1(fr)]) };
+            }
+            return { t, det: fr => call(fr, ds.map(d => d(fr))) };
+        }
+        const seq = sequence(values);
+        return { t, nd: (fr, k) => seq(fr, vs => k(call(fr, vs))) };
+    }
+    /** The implementation of a builtin, specialised to its argument types. */
+    impl(fn, types, ret, scope) {
+        const rt = this.rt;
+        const elemOf = (t) => t.of;
+        const isMultiset = types[0]?.k === 'multiset';
+        const nat = types[0]?.k === 'nat';
+        switch (fn) {
+            case 'not': return ([x]) => !x;
+            case 'and': return xs => xs.every(Boolean);
+            case 'or': return xs => xs.some(Boolean);
+            case 'implies': return ([a, b]) => !a || b;
+            case 'eq': {
+                const eq = equality(types[0]);
+                return ([a, b]) => eq(a, b);
+            }
+            case 'ne': {
+                const eq = equality(types[0]);
+                return ([a, b]) => !eq(a, b);
+            }
+            case 'lt': return types[0].k === 'list' ? ([a, b]) => lexCompare(a, b) < 0 : ([a, b]) => a < b;
+            case 'le': return types[0].k === 'list' ? ([a, b]) => lexCompare(a, b) <= 0 : ([a, b]) => a <= b;
+            case 'gt': return types[0].k === 'list' ? ([a, b]) => lexCompare(a, b) > 0 : ([a, b]) => a > b;
+            case 'ge': return types[0].k === 'list' ? ([a, b]) => lexCompare(a, b) >= 0 : ([a, b]) => a >= b;
+            case 'add': return ([a, b]) => a + b;
+            case 'sub': return nat ? ([a, b]) => Math.max(0, a - b) : ([a, b]) => a - b;
+            case 'mul': return ([a, b]) => a * b;
+            // Lean: division by zero is zero; on Int, `/` and `%` are Euclidean.
+            case 'div': return nat ? ([a, b]) => b === 0 ? 0 : Math.floor(a / b) : ([a, b]) => b === 0 ? 0 : Math.sign(b) * Math.floor(a / Math.abs(b));
+            case 'mod': return nat ? ([a, b]) => b === 0 ? a : a % b : ([a, b]) => b === 0 ? a : ((a % Math.abs(b)) + Math.abs(b)) % Math.abs(b);
+            case 'min': return ([a, b]) => Math.min(a, b);
+            case 'max': return ([a, b]) => Math.max(a, b);
+            case 'toInt': return ([a]) => a;
+            case 'some': return ([x]) => x;
+            case 'isSome': return ([o]) => o !== null;
+            case 'isNone': return ([o]) => o === null;
+            case 'getD': return ([o, d]) => o === null ? d : o;
+            case 'length': return ([l]) => l.length;
+            case 'isEmpty': return ([l]) => l.length === 0;
+            case 'filter': return ([l, p]) => l.filter((x) => p(x));
+            case 'any': return ([l, p]) => l.some((x) => p(x));
+            case 'all': return ([l, p]) => l.every((x) => p(x));
+            case 'count': return ([l, p]) => { let n = 0; for (const x of l)
+                if (p(x))
+                    n++; return n; };
+            case 'map': {
+                if (!isMultiset)
+                    return ([l, f]) => l.map((x) => f(x));
+                const sort = canonicalSort(elemOf(ret));
+                return ([l, f]) => sort(l.map((x) => f(x)));
+            }
+            case 'sum': return ([l]) => l.reduce((a, b) => a + b, 0);
+            case 'mem': {
+                const eq = equality(types[0]);
+                return ([x, l]) => l.some((y) => eq(x, y));
+            }
+            case 'range': return ([n]) => Array.from({ length: n }, (_, i) => i);
+            case 'toMultiset': {
+                const sort = canonicalSort(elemOf(types[0]));
+                return ([l]) => sort(l);
+            }
+            case 'toList': return ([l]) => l.slice();
+            case 'subsets': return ([l]) => subsetsOf(l, l.length, types[0]);
+            case 'subsetsUpTo': return ([l, k]) => subsetsOf(l, k, types[0]);
+            case 'dedup': {
+                const enc = encoder(elemOf(types[0]));
+                return ([l]) => { const seen = new Set(); return l.filter((x) => { const e = enc(x); if (seen.has(e))
+                    return false; seen.add(e); return true; }); };
+            }
+            case 'diff': {
+                const enc = encoder(elemOf(types[0]));
+                return ([a, b]) => {
+                    const remove = new Map();
+                    for (const x of b) {
+                        const e = enc(x);
+                        remove.set(e, (remove.get(e) ?? 0) + 1);
+                    }
+                    return a.filter((x) => {
+                        const e = enc(x);
+                        const n = remove.get(e);
+                        if (!n)
+                            return true;
+                        remove.set(e, n - 1);
+                        return false;
+                    });
+                };
+            }
+            case 'list': return xs => xs;
+            case 'at': return ([l, i]) => { if (i >= l.length)
+                throw new Error(`at: index ${i} out of range`); return l[i]; };
+            case 'append': {
+                if (!isMultiset)
+                    return ([a, b]) => a.concat(b);
+                const sort = canonicalSort(elemOf(types[0]));
+                return ([a, b]) => sort(a.concat(b));
+            }
+            case 'ofFn': return ([n, f]) => Array.from({ length: n }, (_, i) => f(i));
+            case 'show': {
+                const s = show(types[0]);
+                return ([x]) => s(x);
+            }
+            case 'concat': return xs => xs.join('');
+            case 'agents': return ([C]) => agentIndices(C);
+            case 'nodes': return () => Array.from({ length: rt.topo.size }, (_, i) => i);
+            case 'size': return () => rt.topo.size;
+            case 'decisionOf': return ([a]) => rt.decisions[a];
+            case 'target': return ([n, m]) => rt.topo.target(n, m);
+            case 'advance': return ([n, m, i]) => {
+                const N = rt.topo.size;
+                return m === 'cw' ? (n + i) % N : m === 'ccw' ? (n + N - i % N) % N : n;
+            };
+            case 'edgePresent': return ([n, m]) => rt.topo.canMove(rt.topoState, n, m);
+            case 'offset': return ([n, f, i]) => rt.topo.offset(n, f, i);
+            case 'toGlobal': return ([f, m]) => rt.topo.toGlobal(f, m);
+            case 'opposite': return ([m]) => opposite(m);
+            case 'frames': return () => rt.topo.frames;
+            case 'node': return ([n]) => n % rt.topo.size;
+        }
+        return this.fail(`builtin ${fn} is not implemented`);
+    }
+}
+/** Lexicographic order on lists of Bool or Nat (`false < true`, a prefix first), as Lean's `List.lt`. */
+function lexCompare(a, b) {
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++)
+        if (a[i] !== b[i])
+            return a[i] < b[i] ? -1 : 1;
+    return a.length - b.length;
+}
+function agentIndices(C) {
+    return C.idx ??= C.agents.map((_, i) => i);
+}
+function indexMarks(idx) {
+    const marks = [];
+    for (const i of idx)
+        marks[i] = true;
+    return marks;
+}
+/** Sub-collections with at most `k` elements, smallest first, then in index order. */
+function subsetsOf(l, k, t) {
+    const out = [];
+    const pick = (size, from, current) => {
+        if (current.length === size) {
+            out.push(current.slice());
+            return;
+        }
+        for (let i = from; i < l.length; i++) {
+            current.push(l[i]);
+            pick(size, i + 1, current);
+            current.pop();
+        }
+    };
+    for (let size = 0; size <= Math.min(k, l.length); size++)
+        pick(size, 0, []);
+    if (t.k !== 'multiset')
+        return out;
+    // Equal elements of a multiset give equal sub-multisets: keep one of each.
+    const enc = encoder(t);
+    const seen = new Set();
+    return out.filter(s => { const e = enc(s); if (seen.has(e))
+        return false; seen.add(e); return true; });
+}

package/dist/conformance.js

@@ -0,0 +1,21 @@
+import { Explorer } from "./explorer.js";
+import { System } from "./system.js";
+export function conformanceGraph(name, experiment, params, maxStates = 40) {
+    const system = new System(experiment, params);
+    const explorer = new Explorer(system, { symmetry: false, maxStates });
+    explorer.run();
+    const ids = new Map(explorer.states.map(s => [s.key, s.id]));
+    const edges = [];
+    for (const s of explorer.states) {
+        if (!s.succ)
+            continue;
+        for (const t of system.successors(s.config)) {
+            edges.push({ from: s.id, to: ids.get(t.key), witness: t.witness.map(w => w.label), activated: [...t.activated].sort() });
+        }
+    }
+    return {
+        name, experiment, params, maxStates,
+        states: explorer.states.map(s => ({ config: { agents: s.config.agents, world: s.config.world }, verdict: s.verdict })),
+        edges,
+    };
+}