gdp-wired 0.13.3 → 0.14.0

package/README.md

@@ -60,9 +60,15 @@ All of these are proven automatically, and each proof is also a Lean theorem:
 - **Step laws**: what one step does ("a balance only goes down", "a grant adds one"), and laws over up to 64 steps in
   a row (`examples/steps.ts`).
 - **Histories**: sums and queries over a log of requests, like a sliding-window rate limit.
-- **Statecharts**: `chart(name).states({...}).on(event, {from, to, when, set})`, with nested states, parallel regions,
-  a compound's history, guards and extended state, compiled to a rule; `check()` shows every state reached by a run (or
-  proves it unreachable), no state stuck and no event ambiguous, and its laws prove like any rule's (`examples/charts.ts`).
+- **Statecharts**: `chart(name).states({...}).on(event, {from, to, when, set})`, with states nested to any depth,
+  parallel regions (at the top of the chart), a compound's history (deep), guards and extended state, compiled to a rule;
+  `check()` shows every state reached by a run (or proves it unreachable), no state stuck and no event ambiguous, and its
+  laws prove like any rule's (`examples/charts.ts`). Not yet: parallel regions inside a state, entry and exit actions,
+  eventless and delayed transitions.
+- **XState machines** (`gdp-wired/xstate`): `fromXState(machine, {guards, actions})` builds the chart an XState v5
+  machine runs as, with each guard and action it names given again in gdp-wired's terms, and `conforms(chart, machine,
+  createActor)` drives XState's own actor and the compiled rule with the same random events, comparing every state and
+  context; what a chart can't run the same way is refused when built, with the reason (`examples/xstate.ts`).
 - **Orderings at any distance**: "a refund never follows a release", through ghost state that watches the rule.
 - **Liveness**: "every ticket issued is served", in every run that keeps sending the requests that help, including under
   weak fairness (`examples/liveness.ts`).
@@ -372,7 +378,7 @@ The npm package is built from `core/`, `kernel/` and `lean-kernel/` alone; nothi
 ## Running
 
 The npm package is the library: the builders (`gdp-wired`), the runtimes (`gdp-wired/machine`), composition
-(`gdp-wired/compose`), the Lean export (`gdp-wired/lean`), the kernel
+(`gdp-wired/compose`), XState machines as charts (`gdp-wired/xstate`), the Lean export (`gdp-wired/lean`), the kernel
 (`gdp-wired/kernel`), the prover (`gdp-wired/prove`), the derivation checker and solver (`gdp-wired/check`,
 `gdp-wired/solver`). Everything else here (examples, comparisons, the Lean twin, the GPU searches) runs from a clone and
 needs [Bun](https://bun.sh); Lean 4.34.0 for `lean/` and `lean-kernel/`; a WebGPU runtime (Chrome, or Dawn's node

package/dist/core/chart.d.ts

@@ -20,6 +20,7 @@ type After<X> = X & {
 export type Transition<P, I, X> = {
     from: string | string[];
     to?: string;
+    fresh?: boolean;
     when?: (env: Env<P, I, X>) => Cond;
     set?: (env: Env<P, I, X>) => Partial<{
         [k in keyof X]: X[k] extends Choice<infer K> ? K | X[k] : TermLike | Cond | X[k];

package/dist/core/chart.js

@@ -119,14 +119,14 @@ export class Chart {
         for (const [k, v] of Object.entries({ ...s.context, ...s.outputs }))
             state[k] = v;
         const guardEnv = (env) => this.wrap(env);
-        // Entering a path: a leaf, or a compound's last child (with history) or its initial one.
-        const entered = (env, r, path) => {
+        // Entering a path: a leaf, or a compound's last child (with history, unless fresh) or its initial one.
+        const entered = (env, r, path, fresh = false) => {
             const c = r.compounds.get(path), field = env[r.field];
             if (!c)
                 return field.of(path);
-            if (c.history && path)
+            if (c.history && path && !fresh)
                 return env[lastOf(r, path)];
-            return entered(env, r, path ? `${path}.${c.initial}` : c.initial);
+            return entered(env, r, path ? `${path}.${c.initial}` : c.initial, fresh);
         };
         let built = rule(s.name).params(s.params).inputs({ event: oneOf(...events), ...s.inputs }).state(state);
         // A set of a region's states as ranges of their indices (n <= 2, 3 <= n <= 4): a few comparisons, where one test per
@@ -153,7 +153,7 @@ export class Chart {
                 // The transitions taken in a region exclude one another, so those entering one state share a `when` (any of
                 // them taken), and an internal one needs none (the state stays).
                 out[r.field] = grouped(placed.map((t, i) => [t, i]).filter(([t]) => t.region === r.name && t.to !== undefined)
-                    .map(([t, i]) => ({ i, region: r.name, value: entered(env, r, locate(t.to)[1]) })), env, env[r.field]);
+                    .map(([t, i]) => ({ i, region: r.name, value: entered(env, r, locate(t.to)[1], t.fresh) })), env, env[r.field]);
                 for (const [c, { history }] of r.compounds)
                     if (history && c)
                         out[lastOf(r, c)] = when(any(...under(r, c).map(l => out[r.field].is(l))), out[r.field], env[lastOf(r, c)]);

package/dist/core/xstate.d.ts

@@ -0,0 +1,66 @@
+import { type Kind, type Cond } from './dsl.js';
+import { type Chart } from './chart.js';
+type Obj = Record<string, any>;
+type XAction = string | {
+    type: string;
+    params?: unknown;
+} | ((...args: never[]) => unknown);
+type XTransition = string | {
+    target?: string | string[];
+    guard?: unknown;
+    actions?: XAction | XAction[];
+    reenter?: boolean;
+    description?: string;
+};
+export type XNode = {
+    id?: string;
+    type?: 'atomic' | 'compound' | 'parallel' | 'final' | 'history';
+    history?: 'shallow' | 'deep';
+    initial?: string;
+    target?: string;
+    states?: Record<string, XNode>;
+    on?: Record<string, XTransition | XTransition[] | undefined>;
+    entry?: XAction | XAction[];
+    exit?: XAction | XAction[];
+    always?: unknown;
+    after?: unknown;
+    invoke?: unknown;
+    onDone?: unknown;
+    context?: unknown;
+    [k: string]: unknown;
+};
+export type Guard = (env: Obj, params?: unknown) => Cond;
+export type Action = ((env: Obj, params?: unknown) => Obj) | null;
+export type Bridge = {
+    params?: Record<string, Kind<unknown>>;
+    inputs?: Record<string, Kind<unknown>>;
+    context?: Record<string, number | {
+        kind: Kind<unknown>;
+        init: unknown;
+    }>;
+    guards?: Record<string, Guard>;
+    actions?: Record<string, Action>;
+    events?: string[];
+};
+export type MachineLike = object;
+export declare function fromXState(machine: MachineLike, opts?: Bridge): Chart<Obj, Obj, Obj>;
+export type XActor = {
+    send: (e: never) => void;
+    getSnapshot: () => {
+        value: unknown;
+        context?: unknown;
+    };
+};
+export declare function conforms(c: Chart<Obj, Obj, Obj>, machine: MachineLike, createActor: (machine: never) => {
+    start: () => XActor;
+}, opts?: {
+    runs?: number;
+    depth?: number;
+    seed?: number;
+    params?: Obj;
+    payload?: (event: string, rand: (n: number) => number) => Obj;
+}): {
+    checked: number;
+    failure?: string;
+};
+export {};

package/dist/core/xstate.js

@@ -0,0 +1,218 @@
+// XState machines as charts (core/chart.ts): `fromXState(machine, {guards, actions})` reads an XState v5 machine's
+// config (states, nesting, a parallel root, history nodes, final states, transitions with named guards and actions) and
+// builds the chart that runs the same way, so its laws are proven of the machine you ship. XState's guards and actions
+// are JavaScript, so each one the machine names is given again in gdp-wired's terms: a guard as a condition, an action
+// as the context it writes (or null, for one that writes none). `conforms(chart, machine, createActor)` then drives the
+// real XState actor and the compiled rule with the same random events and compares every state and context, so a
+// guard or an action given wrongly shows up as a run where the two part.
+//
+//   const machine = setup({guards: {canRetry: ...}, actions: {count: assign(...)}}).createMachine({...})
+//   const c = fromXState(machine, {
+//     guards: {canRetry: ({retries}) => retries.lt(2)},
+//     actions: {count: ({retries}) => ({retries: retries.plus(1)}), notify: null},
+//   })
+//   c.check(); c.prove([c.law('retries stay within 2', ({retries}) => retries.atMost(2))])
+//   conforms(c, machine, createActor) // {checked, failure?}
+//
+// What a chart can't run the same way is refused when the chart is built, with the reason: a parallel state below the
+// root, eventless (`always`) and delayed (`after`) transitions, invoked actors and done events, wildcard events, several
+// targets at once, inline guards and actions, entry and exit actions that write the context, two regions writing the
+// context on one event (XState runs their actions one after another; a chart's regions write in one step), and a
+// shallow history over nested states.
+import { Choice, bool, int } from "./dsl.js";
+import { chart } from "./chart.js";
+const list = (x) => (x === undefined ? [] : Array.isArray(x) ? x : [x]);
+const configOf = (machine) => ('config' in machine && machine.config && typeof machine.config === 'object' ? machine.config : machine);
+export function fromXState(machine, opts = {}) {
+    const root = configOf(machine), name = root.id ?? 'machine', parallel = root.type === 'parallel';
+    const refuse = (where, what) => { throw new Error(`${name}: ${where || 'the machine'}: ${what}`); };
+    const infos = [], ids = new Map();
+    const walk = (node, segs, parent) => {
+        const info = { node, segs, parent }, where = segs.join('.');
+        infos.push(info);
+        ids.set(node.id ?? (segs.length ? `${name}.${where}` : name), info);
+        for (const k of ['always', 'after', 'invoke', 'onDone'])
+            if (node[k] !== undefined)
+                refuse(where, `\`${k}\` has no chart counterpart`);
+        if (node.type === 'parallel' && segs.length)
+            refuse(where, 'a parallel state below the root (a chart runs regions only at the top)');
+        for (const [k, kid] of Object.entries(node.states ?? {}))
+            walk(kid, [...segs, k], info);
+        const hist = Object.entries(node.states ?? {}).filter(([, kid]) => kid.type === 'history');
+        if (hist.length) {
+            const deep = hist.every(([, h]) => h.history === 'deep'), kids = Object.entries(node.states).filter(([, kid]) => kid.type !== 'history');
+            if (!deep && kids.some(([, kid]) => Object.values(kid.states ?? {}).some(g => g.type !== 'history')))
+                refuse(where, 'a shallow history over nested states (a chart keeps the innermost state)');
+            for (const [k, h] of hist)
+                if (h.target !== undefined && h.target !== (node.initial ?? kids[0]?.[0]))
+                    refuse(`${where}.${k}`, 'a history with its own default target');
+            info.history = { deep };
+        }
+        return info;
+    };
+    walk(root, []);
+    const pathOf = (i) => i.segs.join('.');
+    const descend = (from, segs, t) => segs.reduce((at, seg) => {
+        const kid = infos.find(x => x.parent === at && x.segs.at(-1) === seg);
+        return kid ?? refuse(pathOf(from), `no state ${t}`);
+    }, from);
+    // A target as XState reads it: #id(.path), .child(.path) from the state itself, or a sibling(.path).
+    const resolve = (from, t) => {
+        let at;
+        if (t.startsWith('#')) {
+            const parts = t.slice(1).split('.');
+            let k = parts.length;
+            while (k > 0 && !ids.has(parts.slice(0, k).join('.')))
+                k--;
+            if (!k)
+                refuse(pathOf(from), `no state with the id in ${t}`);
+            at = descend(ids.get(parts.slice(0, k).join('.')), parts.slice(k), t);
+        }
+        else if (t.startsWith('.'))
+            at = descend(from, t.slice(1).split('.'), t);
+        else
+            at = descend(from.parent ?? from, t.split('.'), t);
+        return at.node.type === 'history' ? { to: at.parent, viaHistory: true } : { to: at, viaHistory: false };
+    };
+    // Guards and actions, named and given again.
+    const guardOf = (where, g) => {
+        if (g === undefined)
+            return undefined;
+        const [n, params] = typeof g === 'string' ? [g, undefined] : typeof g === 'object' && g && typeof g.type === 'string' ? [g.type, g.params] : [undefined, undefined];
+        if (n === undefined)
+            return refuse(where, `an inline guard${typeof g === 'function' && g.type ? ` (${g.type})` : ''}: name it in setup({guards}) and give its condition in guards`);
+        const f = opts.guards?.[n] ?? refuse(where, `the guard ${n}: give its condition in guards`);
+        return env => f(env, params);
+    };
+    const actionsOf = (where, as) => as.flatMap(a => {
+        const [n, params] = typeof a === 'string' ? [a, undefined] : typeof a === 'object' && a && typeof a.type === 'string' ? [a.type, a.params] : [undefined, undefined];
+        if (n === undefined)
+            return refuse(where, `an inline action${typeof a === 'function' && a.type ? ` (${a.type})` : ''}: name it in setup({actions}) and give the context it writes in actions`);
+        if (!opts.actions || !(n in opts.actions))
+            return refuse(where, `the action ${n}: give the context it writes in actions (null if it writes none)`);
+        const f = opts.actions[n];
+        return f ? [(env) => f(env, params)] : [];
+    });
+    for (const i of infos)
+        for (const k of ['entry', 'exit'])
+            if (actionsOf(pathOf(i), list(i.node[k])).length)
+                refuse(pathOf(i), `${k} actions that write the context (a chart writes the context on transitions only)`);
+    // Several actions run one after another, each reading the context the one before wrote.
+    const composed = (fs) => (fs.length ? (env) => {
+        let cur = env;
+        const out = {};
+        for (const f of fs) {
+            const o = f(cur);
+            Object.assign(out, o);
+            cur = Object.assign(Object.create(null), cur, Object.fromEntries(Object.entries(o).map(([k, v]) => [k, typeof v === 'string' && cur[k] instanceof Choice ? cur[k].of(v) : v])));
+        }
+        return out;
+    } : undefined);
+    // The states, as a chart's.
+    const nodeOf = (i) => {
+        const kids = infos.filter(x => x.parent === i && x.node.type !== 'history');
+        if (!kids.length)
+            return i.node.type === 'final' ? { final: true } : {};
+        return { states: Object.fromEntries(kids.map(k => [k.segs.at(-1), nodeOf(k)])), ...(i.node.initial ? { initial: i.node.initial } : {}), ...(i.history ? { history: true } : {}) };
+    };
+    const top = infos.filter(x => x.parent === infos[0]);
+    let c = chart(name).params((opts.params ?? {})).inputs((opts.inputs ?? {})).context(contextOf(root, opts.context, refuse));
+    if (parallel) {
+        for (const r of top)
+            if (!infos.some(x => x.parent === r && x.node.type !== 'history'))
+                refuse(pathOf(r), 'a region with no states of its own');
+        c = c.regions(Object.fromEntries(top.map(r => [r.segs[0], nodeOf(r)])));
+    }
+    else
+        c = c.states(nodeOf(infos[0]).states ?? refuse('', 'no states'), root.initial ? { initial: root.initial } : {});
+    if (opts.events)
+        c = c.events(...opts.events);
+    // The transitions, in document order (the chart takes the most specific source first, then the first declared, as
+    // XState does).
+    const writers = new Map();
+    for (const i of infos)
+        for (const [event, spec] of Object.entries(i.node.on ?? {})) {
+            const where = `${pathOf(i) || 'the root'} on ${event}`;
+            if (event.includes('*'))
+                refuse(where, 'a wildcard event');
+            if (spec === undefined)
+                refuse(where, 'a forbidden event (an undefined transition)');
+            for (const t of list(spec)) {
+                const o = typeof t === 'string' ? { target: t } : t, targets = list(o.target);
+                if (targets.length > 1)
+                    refuse(where, 'several targets at once');
+                const to = targets[0] === undefined ? undefined : resolve(i, targets[0]);
+                const set = composed(actionsOf(where, list(o.actions))), when = guardOf(where, o.guard);
+                // Where it applies: its state; for the root, every top state but a final one (XState stops there), or in a
+                // parallel machine the region its target is in (the first region, for one with no target).
+                const from = i.segs.length ? pathOf(i) : parallel ? (to ? to.to.segs[0] : top[0].segs[0]) : top.filter(x => x.node.type !== 'final' && x.node.type !== 'history').map(pathOf);
+                if (set) {
+                    const region = parallel ? String(list(from)[0]).split('.')[0] : 'state';
+                    writers.set(event, (writers.get(event) ?? new Set()).add(region));
+                }
+                c = c.on(event, { from, ...(to ? { to: pathOf(to.to), fresh: !to.viaHistory } : {}), ...(when ? { when } : {}), ...(set ? { set: set } : {}) });
+            }
+        }
+    for (const [event, regions] of writers)
+        if (regions.size > 1)
+            refuse(`on ${event}`, `regions ${[...regions].join(' and ')} both write the context (XState runs their actions one after another)`);
+    return c;
+}
+function contextOf(root, given, refuse) {
+    const out = {};
+    if (root.context !== undefined && typeof root.context !== 'object') {
+        if (!given)
+            refuse('', 'a context computed by a function: give its kinds in context');
+        return { ...given };
+    }
+    for (const [k, v] of Object.entries((root.context ?? {}))) {
+        if (given && k in given)
+            continue;
+        if (typeof v === 'number' && Number.isSafeInteger(v))
+            out[k] = v >= 0 ? v : int.from(v);
+        else if (typeof v === 'boolean')
+            out[k] = bool.from(v);
+        else
+            refuse('', `the context's ${k} (${JSON.stringify(v)}): give its kind in context`);
+    }
+    return { ...out, ...given };
+}
+const canonical = (v) => (v && typeof v === 'object' ? `{${Object.keys(v).sort().map(k => `${k}:${canonical(v[k])}`).join(',')}}` : JSON.stringify(v));
+export function conforms(c, machine, createActor, opts = {}) {
+    const root = configOf(machine), events = [];
+    const walk = (n) => { for (const e of Object.keys(n.on ?? {}))
+        if (!events.includes(e))
+            events.push(e); Object.values(n.states ?? {}).forEach(walk); };
+    walk(root);
+    const r = c.rule, g = r.compiled(), ps = r.encodeParams((opts.params ?? {}));
+    // dsl.ts's generator: the high bits of a linear congruence (the low ones repeat with a short period)
+    let x = opts.seed ?? 1;
+    const rand = (k) => { x = (x * 1103515245 + 12345) % 2 ** 31; return Math.floor(x / 2 ** 31 * k); };
+    const valueOf = (d) => {
+        const nest = (path) => path.split('.').reduceRight((acc, seg) => (acc === undefined ? seg : { [seg]: acc }), undefined);
+        if (root.type === 'parallel')
+            return Object.fromEntries(Object.keys(root.states ?? {}).filter(k => root.states[k].type !== 'history').map(k => [k, nest(String(d[k]))]));
+        return nest(String(d.state));
+    };
+    const contextKeys = Object.keys((root.context && typeof root.context === 'object' ? root.context : {}));
+    let checked = 0;
+    for (let run = 0; run < (opts.runs ?? 100); run++) {
+        const actor = createActor(machine).start();
+        let st = g.init(ps);
+        const sent = [];
+        for (let d = 0; d < (opts.depth ?? 12); d++) {
+            const type = events[rand(events.length)], payload = opts.payload?.(type, rand) ?? {};
+            sent.push(Object.keys(payload).length ? `${type}${JSON.stringify(payload)}` : type);
+            actor.send({ type, ...payload });
+            st = g.step(ps, st, r.encodeInput({ event: type, ...payload }));
+            const snap = actor.getSnapshot(), d2 = r.decode(st), want = valueOf(d2);
+            if (canonical(snap.value) !== canonical(want))
+                return { checked, failure: `after ${sent.join(', ')}: XState is in ${JSON.stringify(snap.value)}, the chart in ${JSON.stringify(want)}` };
+            for (const k of contextKeys)
+                if (JSON.stringify(snap.context?.[k]) !== JSON.stringify(d2[k]))
+                    return { checked, failure: `after ${sent.join(', ')}: XState's ${k} is ${JSON.stringify(snap.context?.[k])}, the chart's ${JSON.stringify(d2[k])}` };
+            checked++;
+        }
+    }
+    return { checked };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdp-wired",
-  "version": "0.13.3",
+  "version": "0.14.0",
   "description": "An automatic prover for stateful rules (budgets, caps, windows, workflows, policies): laws proven with no proof to write, checked again in Lean, counterexamples found on the GPU, the rule shipped as code",
   "keywords": [
     "verification",
@@ -52,6 +52,10 @@
       "types": "./dist/kernel/prove.d.ts",
       "default": "./dist/kernel/prove.js"
     },
+    "./xstate": {
+      "types": "./dist/core/xstate.d.ts",
+      "default": "./dist/core/xstate.js"
+    },
     "./check": {
       "types": "./dist/core/check.d.ts",
       "default": "./dist/core/check.js"
@@ -89,7 +93,7 @@
     "build": "bun scripts/build.ts",
     "prepublishOnly": "bun scripts/build.ts",
     "smoke": "sh scripts/smoke.sh",
-    "test": "bun scripts/gen-lean-library.ts --check && cd core && bun test solver.test.ts dsl.test.ts conformance.test.ts compose.test.ts quantifiers.test.ts functions.test.ts keyterms.test.ts lists.test.ts liveness.test.ts sizes.test.ts values.test.ts builders.test.ts gdp.test.ts datatypes.test.ts lemmas.test.ts invoices.test.ts folds.test.ts trees.test.ts pairs.test.ts chart.test.ts && cd ../kernel && bun test tamper.test.ts refusals.test.ts steplaw.test.ts sets.test.ts && cd ../examples && bun test examples.test.ts && cd .. && bun examples/readme.ts && bun examples/guide.ts && bun examples/composition.ts && bun examples/sets.ts && bun examples/quantifiers.ts && bun examples/functions.ts && bun examples/datatypes.ts && bun examples/lemmas.ts && bun examples/invoices.ts && bun examples/folds.ts && bun examples/trees.ts && bun examples/pairs.ts && bun examples/groups.ts && bun examples/charts.ts && bun examples/lists.ts && bun examples/sizes.ts && bun examples/liveness.ts && bun examples/budget.ts && bun examples/gdp.ts && bun examples/steps.ts && bun examples/jev-fabric/run.ts"
+    "test": "bun scripts/gen-lean-library.ts --check && cd core && bun test solver.test.ts dsl.test.ts conformance.test.ts compose.test.ts quantifiers.test.ts functions.test.ts keyterms.test.ts lists.test.ts liveness.test.ts sizes.test.ts values.test.ts builders.test.ts gdp.test.ts datatypes.test.ts lemmas.test.ts invoices.test.ts folds.test.ts trees.test.ts pairs.test.ts chart.test.ts xstate.test.ts && cd ../kernel && bun test tamper.test.ts refusals.test.ts steplaw.test.ts sets.test.ts && cd ../examples && bun test examples.test.ts && cd .. && bun examples/readme.ts && bun examples/guide.ts && bun examples/composition.ts && bun examples/sets.ts && bun examples/quantifiers.ts && bun examples/functions.ts && bun examples/datatypes.ts && bun examples/lemmas.ts && bun examples/invoices.ts && bun examples/folds.ts && bun examples/trees.ts && bun examples/pairs.ts && bun examples/groups.ts && bun examples/charts.ts && bun examples/xstate.ts && bun examples/lists.ts && bun examples/sizes.ts && bun examples/liveness.ts && bun examples/budget.ts && bun examples/gdp.ts && bun examples/steps.ts && bun examples/jev-fabric/run.ts"
   },
   "devDependencies": {
     "@gdp-ts/core": "0.1.0",
@@ -97,6 +101,7 @@
     "@webgpu/types": "0.1.66",
     "oxlint": "1.88.0",
     "oxlint-tsgolint": "7.0.2004",
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "xstate": "5.33.2"
   }
 }