gdp-wired 0.12.7 → 0.13.0

package/README.md

@@ -60,6 +60,9 @@ 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`).
 - **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`).

package/dist/core/chart.d.ts

@@ -0,0 +1,86 @@
+import { type Cond, type Kind, type Rule, type Term, type TermLike, type Verdict, type Choice } from './dsl.js';
+import { type Law } from './machine.js';
+import type { StepLaw } from '../kernel/kernel.js';
+export type StateNode = {
+    states?: Record<string, StateNode>;
+    initial?: string;
+    history?: boolean;
+    final?: boolean;
+};
+type Obj = Record<string, any>;
+type Env<P, I, X> = P & I & X & {
+    event: Choice<string>;
+    in: (path: string) => Cond;
+    last: (compound: string) => Choice<string>;
+};
+type After<X> = X & {
+    in: (path: string) => Cond;
+    last: (compound: string) => Choice<string>;
+};
+export type Transition<P, I, X> = {
+    from: string | string[];
+    to: string;
+    when?: (env: Env<P, I, X>) => Cond;
+    set?: (env: Env<P, I, X>) => Partial<{
+        [k in keyof X]: TermLike | Cond | X[k];
+    }>;
+};
+export declare class Chart<P extends Obj = {}, I extends Obj = {}, X extends Obj = {}> {
+    private readonly s;
+    constructor(s: {
+        name: string;
+        params: Obj;
+        inputs: Obj;
+        context: Obj;
+        regions: [string, StateNode][];
+        on: [string, Transition<P, I, X>][];
+    });
+    private with;
+    params<K extends Record<string, Kind<unknown>>>(kinds: K): Chart<P & {
+        [k in keyof K]: K[k] extends Kind<infer V> ? V : never;
+    }, I, X>;
+    inputs<K extends Record<string, Kind<unknown>>>(kinds: K): Chart<P, I & {
+        [k in keyof K]: K[k] extends Kind<infer V> ? V : never;
+    }, X>;
+    context<T extends Record<string, number | {
+        kind: Kind<unknown>;
+        init: unknown;
+    }>>(init: T): Chart<P, I, X & {
+        [k in keyof T]: T[k] extends {
+            kind: Kind<infer V>;
+        } ? V : Term;
+    }>;
+    states(tree: Record<string, StateNode>, opts?: {
+        initial?: string;
+    }): Chart<P, I, X>;
+    regions(regions: Record<string, StateNode>): Chart<P, I, X>;
+    on(event: string, t: Transition<P, I, X>): Chart<P, I, X>;
+    private built?;
+    private build;
+    get rule(): Rule<Obj, Obj, Obj, Obj, Obj, Obj, Obj, Obj>;
+    in(env: Obj, path: string): Cond;
+    last(env: Obj, compound: string): Choice<string>;
+    private wrap;
+    law(name: string, f: (env: After<P & X>) => Cond): Law;
+    stepLaw(name: string, then: (before: Env<P, I, X>, after: After<X>) => Cond, when?: (before: Env<P, I, X>) => Cond): StepLaw;
+    chartLaws(): Law[];
+    prove(laws?: Law[], stepLaws?: StepLaw[]): Verdict;
+    check(opts?: {
+        params?: Obj;
+        bound?: number;
+        maxStates?: number;
+    }): {
+        ok: boolean;
+        reached: Record<string, {
+            run: Obj[];
+        } | 'unreachable' | 'unknown'>;
+        stuck: string[];
+        ambiguous: {
+            event: string;
+            transitions: [number, number];
+            verdict: Verdict;
+        }[];
+    };
+}
+export declare const chart: (name: string) => Chart;
+export {};

package/dist/core/chart.js

@@ -0,0 +1,241 @@
+// Statecharts as rules: states (nested, each compound with its initial child and, if asked, the child it was last in),
+// parallel regions, events with a payload, guarded transitions that set the chart's extended state, final states. A chart
+// compiles to one plain rule, its step a choice among transitions, so everything proven about rules holds of charts and
+// nothing here is trusted: the kernel proves the rule it builds.
+//
+//   const order = chart('order').context({retries: 0}).states({
+//     new: {}, active: {states: {paid: {}, shipped: {}}, history: true}, refunded: {final: true}, delivered: {final: true},
+//   })
+//     .on('pay', {from: 'new', to: 'active'})
+//     .on('ship', {from: 'active.paid', to: 'active.shipped'})
+//     .on('refund', {from: 'active.paid', to: 'refunded'})
+//     .on('deliver', {from: 'active.shipped', to: 'delivered'})
+//   order.check() // every state reached (with the run that reaches it), none stuck, no event ambiguous
+//
+// Semantics, per region and per event: of the transitions whose source holds and whose guard holds, the one with the
+// most specific source (an inner state over its parent) is taken, then the first declared; the regions react to the
+// same event at once. A transition into a compound state enters its initial child, or the child it was last in when the
+// compound keeps its history; `set` writes the extended state (a variable two regions both set takes the first region's).
+import { all, any, oneOf, proveRule, proveSteps, rule, when } from "./dsl.js";
+import { interpret, numbersOf } from "./machine.js";
+import { allowed } from "./watch.js";
+export class Chart {
+    s;
+    constructor(s) {
+        this.s = s;
+    }
+    with(more) { return new Chart({ ...this.s, ...more }); }
+    params(kinds) { return this.with({ params: { ...this.s.params, ...kinds } }); }
+    // The payload an event brings (every event brings the same fields; one reads those it needs).
+    inputs(kinds) { return this.with({ inputs: { ...this.s.inputs, ...kinds } }); }
+    // The extended state: a natural from a number, or any kind from `kind.from(init)`.
+    context(init) { return this.with({ context: { ...this.s.context, ...init } }); }
+    // One region's states (a chart of one region names its states plainly: 'active.paid').
+    states(tree, opts = {}) { return this.with({ regions: [['state', { states: tree, initial: opts.initial }]] }); }
+    // Parallel regions, each with its own states, reacting to the same events: paths start with the region ('payment.paid').
+    regions(regions) { return this.with({ regions: Object.entries(regions) }); }
+    on(event, t) { return this.with({ on: [...this.s.on, [event, t]] }); }
+    // --- the rule it compiles to -------------------------------------------------------------------------------------
+    built;
+    build() {
+        if (this.built)
+            return this.built;
+        const s = this.s, single = s.regions.length === 1 && s.regions[0][0] === 'state';
+        if (!s.regions.length)
+            throw new Error(`${s.name}: a chart needs states`);
+        const regions = s.regions.map(([name, root]) => {
+            const leaves = [], finals = new Set(), compounds = new Map();
+            const walk = (path, node) => {
+                const kids = Object.entries(node.states ?? {});
+                if (!kids.length) {
+                    leaves.push(path);
+                    if (node.final)
+                        finals.add(path);
+                    return;
+                }
+                const initial = node.initial ?? kids[0][0];
+                if (!node.states[initial])
+                    throw new Error(`${s.name}: ${path || name}'s initial state ${initial} isn't one of its states`);
+                compounds.set(path, { initial, history: !!node.history });
+                for (const [k, kid] of kids) {
+                    if (/[.*[\],:]/.test(k))
+                        throw new Error(`${s.name}: the state name ${k} has a reserved character`);
+                    walk(path ? `${path}.${k}` : k, kid);
+                }
+            };
+            walk('', root);
+            return { name, field: single ? 'state' : name, leaves, finals, compounds };
+        });
+        // A path as the region and the state within it.
+        const locate = (path) => {
+            if (single)
+                return [regions[0], path];
+            const [head, ...rest] = path.split('.'), r = regions.find(x => x.name === head);
+            if (!r)
+                throw new Error(`${s.name}: ${path} names no region (${regions.map(x => x.name).join(', ')})`);
+            return [r, rest.join('.')];
+        };
+        const under = (r, path) => {
+            const out = r.leaves.filter(l => path === '' || l === path || l.startsWith(`${path}.`));
+            if (!out.length)
+                throw new Error(`${s.name}: no state ${path} in ${r.name}`);
+            return out;
+        };
+        const events = [...new Set(s.on.map(([e]) => e))];
+        if (!events.length)
+            throw new Error(`${s.name}: a chart needs transitions`);
+        const placed = s.on.map(([event, t], order) => {
+            const froms = (Array.isArray(t.from) ? t.from : [t.from]).map(locate), [to] = locate(t.to);
+            if (froms.some(([r]) => r !== to))
+                throw new Error(`${s.name}: a transition on ${event} goes from one region to another (${t.to})`);
+            under(to, locate(t.to)[1]);
+            const sources = [...new Set(froms.flatMap(([r, p]) => under(r, p)))];
+            return { ...t, event, region: to.name, sources, depth: Math.min(...froms.map(([, p]) => (p === '' ? 0 : p.split('.').length))), order };
+        });
+        // Most specific source first, then the order declared: the first enabled in this order is taken.
+        placed.sort((a, b) => b.depth - a.depth || a.order - b.order);
+        const lastOf = (r, c) => `${r.field}.last${c ? `.${c}` : ''}`;
+        const state = {};
+        for (const r of regions) {
+            const kind = oneOf(...r.leaves), enter = (path) => { const c = r.compounds.get(path); return c ? enter(path ? `${path}.${c.initial}` : c.initial) : path; };
+            state[r.field] = kind.from(enter(''));
+            for (const [c, { history }] of r.compounds)
+                if (history && c)
+                    state[lastOf(r, c)] = kind.from(enter(c));
+        }
+        for (const [k, v] of Object.entries(s.context))
+            state[k] = v;
+        const inState = (env) => (path) => { const [r, p] = locate(path); return any(...under(r, p).map(l => env[r.field].is(l))); };
+        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) => {
+            const c = r.compounds.get(path), field = env[r.field];
+            if (!c)
+                return field.of(path);
+            if (c.history && path)
+                return env[lastOf(r, path)];
+            return entered(env, r, path ? `${path}.${c.initial}` : c.initial);
+        };
+        let built = rule(s.name).params(s.params).inputs({ event: oneOf(...events), ...s.inputs }).state(state);
+        built = built.flags((env) => Object.fromEntries(placed.map((t, i) => [`on${i}`, all(env.event.is(t.event), inState(env)(single ? '' : t.region), any(...t.sources.map(l => env[regions.find(r => r.name === t.region).field].is(l))), ...(t.when ? [t.when(guardEnv(env))] : []))])));
+        // A transition is taken when it is enabled and no transition before it in its region is.
+        built = built.flags((env) => Object.fromEntries(placed.map((t, i) => [`take${i}`, all(env[`on${i}`], ...placed.slice(0, i).flatMap((u, j) => (u.region === t.region && u.sources.some(l => t.sources.includes(l)) ? [env[`on${j}`].not()] : [])))])));
+        built = built.step((env) => {
+            const out = {};
+            for (const r of regions) {
+                // The transitions taken in a region exclude one another: a chain of `when`s, the first in order outermost.
+                out[r.field] = placed.map((t, i) => [t, i]).filter(([t]) => t.region === r.name).reverse()
+                    .reduce((acc, [t, i]) => when(env[`take${i}`], entered(env, r, locate(t.to)[1]), acc), 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)]);
+            }
+            for (const k of Object.keys(s.context)) {
+                const sets = placed.map((t, i) => [t, i]).filter(([t]) => t.set).map(([t, i]) => [i, t.set(guardEnv(env))[k]]).filter(([, v]) => v !== undefined);
+                if (sets.length)
+                    out[k] = sets.reverse().reduce((acc, [i, v]) => when(env[`take${i}`], v, acc), env[k]);
+            }
+            return out;
+        });
+        this.built = { rule: built, regions, placed, events };
+        return this.built;
+    }
+    // The rule the chart compiles to: its state is each region's state (`state`, or the region's name), each compound's
+    // last child where it keeps its history, and the context; its inputs the event and the payload.
+    get rule() { return this.build().rule; }
+    // Whether a region is in a state (a compound: any state within it), for laws: chart.in(env, 'active').
+    in(env, path) {
+        const { regions } = this.build(), single = regions.length === 1 && regions[0].name === 'state';
+        const [head, ...rest] = single ? ['state', ...path.split('.')] : path.split('.'), r = regions.find(x => x.name === head);
+        const p = rest.join('.'), leaves = r.leaves.filter(l => p === '' || l === p || l.startsWith(`${p}.`));
+        if (!leaves.length)
+            throw new Error(`${this.s.name}: no state ${path}`);
+        return any(...leaves.map(l => env[r.field].is(l)));
+    }
+    // A compound's history: the state it was last in (its initial one before it was ever left), for laws: chart.last(env, 'active').
+    last(env, compound) {
+        const { regions } = this.build(), single = regions.length === 1 && regions[0].name === 'state';
+        const [head, ...rest] = single ? ['state', ...compound.split('.')] : compound.split('.'), r = regions.find(x => x.name === head), c = rest.join('.');
+        if (!r?.compounds.get(c)?.history)
+            throw new Error(`${this.s.name}: ${compound} keeps no history`);
+        return env[`${r.field}.last.${c}`];
+    }
+    wrap(env) { return Object.assign(Object.create(null), env, { in: (p) => this.in(env, p), last: (c) => this.last(env, c) }); }
+    law(name, f) { return this.rule.law(name, (env) => f(this.wrap(env))); }
+    stepLaw(name, then, when) {
+        return this.rule.stepLaw(name, (b, a) => then(this.wrap(b), this.wrap(a)), when && ((b) => when(this.wrap(b))));
+    }
+    // What the chart keeps true by its construction: each compound's history is one of its own states. Proven beside the
+    // laws `prove` and `check` are given (as a rule's kind laws are), since a law about entering a compound may need it.
+    chartLaws() {
+        const { rule: r, regions } = this.build();
+        return regions.flatMap(reg => [...reg.compounds].filter(([c, { history }]) => history && c).map(([c]) => r.law(`${reg.name === 'state' ? '' : `${reg.name}.`}${c} remembers one of its own states`, (env) => any(...reg.leaves.filter(l => l.startsWith(`${c}.`)).map(l => env[`${reg.field}.last.${c}`].is(l))))));
+    }
+    prove(laws = [], stepLaws = []) { const given = [...this.chartLaws(), ...laws]; return stepLaws.length ? proveSteps(this.rule, given, stepLaws) : proveRule(this.rule, given); }
+    // --- the checks a chart's author expects -------------------------------------------------------------------------
+    // reached: each state, with the first run from the start that reaches it (a breadth-first walk of the compiled rule
+    // over every event and small payloads, `bound` the largest natural tried, under `params`), or `unreachable` where the
+    // prover proves no run reaches it, or `unknown`. stuck: states with no transition out that aren't final. ambiguous:
+    // two transitions of one region, as specific as each other, both enabled by one request (the first declared is taken;
+    // the check names the pair and a request that enables both), each pair proven apart otherwise.
+    check(opts = {}) {
+        const { rule: r, regions, placed, events } = this.build(), m = r.machine, run = interpret(m), bound = opts.bound ?? 2;
+        const single = regions.length === 1 && regions[0].name === 'state', label = (reg, l) => (single ? l : `${reg.name}.${l}`);
+        const params = opts.params ? r.encodeParams(opts.params) : Object.fromEntries(m.params.map(p => [p, bound]));
+        // Every request: each event, each payload variable over its range (a kind bounded by a small constant in full).
+        const tops = new Map();
+        const conj = (c) => (c === undefined ? [] : c.op === 'and' ? c.xs.flatMap(conj) : [c]);
+        for (const c of conj(m.assume))
+            if ((c.op === '<' || c.op === '<=') && c.a.op === 'var' && c.b.op === 'const')
+                tops.set(c.a.name, c.op === '<' ? c.b.value - 1 : c.b.value);
+        const requests = m.inputs.reduce((acc, n) => acc.flatMap(t => Array.from({ length: Math.min(tops.get(n) ?? bound, 15) + 1 }, (_, i) => ({ ...t, [n]: i }))), [{}]);
+        const key = (st) => JSON.stringify([st.scalars, Object.entries(st.maps).map(([n, c]) => [n, [...c]])]);
+        const start = run.init(params), seen = new Map([[key(start), { st: start }]]), queue = [key(start)];
+        const reachedAt = new Map();
+        const note = (k, st) => { for (const reg of regions) {
+            const l = reg.leaves[st.scalars[reg.field]];
+            if (!reachedAt.has(label(reg, l)))
+                reachedAt.set(label(reg, l), k);
+        } };
+        note(queue[0], start);
+        while (queue.length && seen.size < (opts.maxStates ?? 20_000)) {
+            const k = queue.shift(), st = seen.get(k).st;
+            for (const req of requests) {
+                if (!allowed(m, run, params, st, req))
+                    continue;
+                const next = run.step(params, st, req), nk = key(next);
+                if (seen.has(nk))
+                    continue;
+                seen.set(nk, { st: next, from: k, by: req });
+                queue.push(nk);
+                note(nk, next);
+            }
+        }
+        const runTo = (k) => { const out = []; for (let at = seen.get(k); at.by; at = seen.get(at.from))
+            out.unshift({ ...numbersOf(at.by), event: events[at.by.event] }); return out; };
+        const reached = {};
+        for (const reg of regions)
+            for (const l of reg.leaves) {
+                const name = label(reg, l), at = reachedAt.get(name);
+                if (at) {
+                    reached[name] = { run: runTo(at) };
+                    continue;
+                }
+                const never = r.law(`${name} is never reached`, (env) => env[reg.field].is(l).not());
+                const v = proveRule(r, [...this.chartLaws(), never]);
+                reached[name] = v.proven && v.checked ? 'unreachable' : 'unknown';
+            }
+        const stuck = regions.flatMap(reg => reg.leaves.filter(l => !reg.finals.has(l) && !placed.some(t => t.region === reg.name && t.sources.includes(l))).map(l => label(reg, l)));
+        const ambiguous = [];
+        placed.forEach((t, i) => placed.forEach((u, j) => {
+            if (j <= i || t.region !== u.region || t.event !== u.event || t.depth !== u.depth || !t.sources.some(l => u.sources.includes(l)))
+                return;
+            const apart = r.stepLaw(`transitions ${t.order} and ${u.order} on ${t.event} are never both enabled`, (env) => all(env[`on${i}`], env[`on${j}`]).not());
+            const v = proveSteps(r, this.chartLaws(), [apart]);
+            if (!(v.proven && v.checked))
+                ambiguous.push({ event: t.event, transitions: [t.order, u.order], verdict: v });
+        }));
+        return { ok: !stuck.length && !ambiguous.length && Object.values(reached).every(x => x !== 'unknown'), reached, stuck, ambiguous };
+    }
+}
+export const chart = (name) => new Chart({ name, params: {}, inputs: {}, context: {}, regions: [], on: [] });

package/dist/core/dsl.d.ts

@@ -197,10 +197,10 @@ export declare class VariantKind<C extends Cases, T extends string = 'tag'> exte
     make(write: VariantWrite<C, T>): Variant<C, T>;
     store(name: string, value: unknown): Record<string, TermLike>;
     decode(name: string, vars: Record<string, number>): {
-        [x: string]: (keyof C & string) | Raw;
+        [x: string]: Raw | (keyof C & string);
     };
     empty(): {
-        [x: string]: (keyof C & string) | Raw;
+        [x: string]: Raw | (keyof C & string);
     };
     encode(name: string, raw: Raw): {
         [x: string]: number;
@@ -209,7 +209,7 @@ export declare class VariantKind<C extends Cases, T extends string = 'tag'> exte
         [x: string]: number;
     };
     sample(rand: Rand, bound: number): {
-        [x: string]: (keyof C & string) | Raw;
+        [x: string]: Raw | (keyof C & string);
     };
 }
 export declare function variant<const C extends Cases>(cases: C): VariantKind<C>;
@@ -874,3 +874,4 @@ export declare class RoseFold<P extends Obj = {}, I extends Obj = {}, S extends
         rand?: Rand;
     }): Agreement;
 }
+export { Chart, chart, type StateNode, type Transition } from './chart.js';

package/dist/core/dsl.js

@@ -2742,3 +2742,5 @@ export class RoseFold {
         return { checked };
     }
 }
+// Statecharts (core/chart.ts): states nested and in parallel regions, compiled to a rule.
+export { Chart, chart } from "./chart.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdp-wired",
-  "version": "0.12.7",
+  "version": "0.13.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",
@@ -89,7 +89,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 && 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/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 && 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"
   },
   "devDependencies": {
     "@gdp-ts/core": "0.1.0",