gdp-wired 0.6.0 → 0.7.0

package/README.md

@@ -1,4 +1,7 @@
-<img src="https://raw.githubusercontent.com/monotykamary/gdp-wired/main/static/banner-ink.svg" alt="gdp-wired" width="100%" />
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/monotykamary/gdp-wired/main/static/banner-dark.svg">
+  <img src="https://raw.githubusercontent.com/monotykamary/gdp-wired/main/static/banner-light.svg" alt="gdp-wired: an automatic prover for stateful rules" width="100%">
+</picture>
 
 # gdp-wired
 
@@ -27,8 +30,10 @@ proveRule(budget, [bounded]) // {proven: true, checked: true}
 Names are typed: `({s, bb}) => …` or a law that reads the request `c` is a TypeScript error, not a runtime surprise.
 Forget the cap (`s.plus(c)`) and the kernel refuses the proof; a search from the start turns it into a real run:
 `{params: {b: 1, m: 0}, trace: [{c: 2}]}`. `bun examples/budget.ts` runs all of it, including the generated JavaScript,
-and `examples/domains/` holds 92 rules from nine domains (finance, access control, public services, operations,
-protocols, commerce, supply chains, games, education), each checked three ways.
+and `examples/domains/` holds 187 rules from 21 domains (finance, access control, public services, operations,
+protocols, commerce, supply chains, games, education, healthcare, energy, networking, AI agents, cloud, ad tech,
+governance, insurance, bookings, safety and IoT, mobility, media), each checked three ways: the kernel proves every law
+and refutes every broken variant, random runs of both runtimes agree, and Lean checks the trees.
 
 ## Where it fits
 
@@ -101,6 +106,39 @@ The untrusted parts are held to the trusted ones by the test suite:
   tests, and the few that survive are equivalent (`kernel/MUTANTS.md`).
 - **Fuzz**: the kernel never accepts a refutation of something that has a model.
 
+## With gdp-ts
+
+[gdp-ts](https://github.com/rauchg/gdp-ts) makes every call site present a proof that a check ran on exactly these
+values, and trusts the module that performs the check. `gdp-wired/gdp` proves that check: the trusted module hands its
+private prover to a `guard` (a function's condition) or a `gate` (a rule's flag), which proves the laws when the module
+loads, refuses to load if one fails, and mints a proof only where the proven condition holds. gdp-ts then holds every
+call site to it: the policy is proven, every caller is held to it, and Lean checks the proof again.
+
+```ts
+// proofs/can-set-protection.ts (trusted: the only module that can mint this proof)
+import {defineProof, type Named, type Proof} from '@gdp-ts/core'
+import {fun, no, oneOf} from 'gdp-wired'
+import {guard} from 'gdp-wired/gdp'
+
+const canSet = fun('can set password protection')
+  .inputs({role: oneOf('owner', 'member', 'viewer', 'none'), plan: oneOf('free', 'pro', 'enterprise')})
+  .returns(({role, plan}) => ({allow: role.is('owner').or(role.is('member')).and(plan.is('free').not())}))
+const laws = [canSet.law('the free plan never has protection', ({plan}, out) => [plan.is('free'), out.allow], () => no)]
+
+const CanSetProtection = defineProof('CanSetProtection') // not exported
+export interface CanSetProtection<U, P> extends Proof<'CanSetProtection', [U, P]> {}
+const mint = guard(CanSetProtection, canSet, 'allow', {laws}) // proven here, or the module doesn't load
+
+export async function canSetProtection<U, P>(user: Named<U, UserId>, project: Named<P, ProjectId>): Promise<CanSetProtection<U, P> | null> {
+  return mint({role: await db.role(user.value, project.value), plan: await db.plan(project.value)}, user, project)
+}
+```
+
+A `gate` does the same for a rule with state: each request takes the rule's step, and a proof is minted when the step
+takes the flag (a one-time token redeemed, a sign-in while the account is unlocked, an email within the hourly cap).
+Requests outside what was proven (a failed `assume`, a history read out of order) mint nothing and leave the state as it
+was. `examples/gdp.ts` runs gdp-ts's own example this way; `@gdp-ts/core` is an optional peer dependency.
+
 ## Writing laws
 
 The builders (`core/dsl.ts`) hand out typed values for every name you declare; everything compiles to the plain machine
@@ -230,7 +268,7 @@ Lean, compiled natively, wins where the state stays small. Details in [`docs/com
 | `core/` | Machines, the interpreter and JS compiler, the builders, composition (`compose.ts`), the linear solver and its checker, Houdini invariants, models, the first Lean export |
 | `kernel/` | The trusted kernel and the untrusted prover, with soundness fuzz (`kernel.test.ts`, `history.test.ts`) |
 | `lean-kernel/` | The kernel's Lean twin, its soundness proofs, and the exported trees |
-| `examples/` | The builders at work: `domains/` (92 rules across nine domains, each with laws and broken variants), `harness.ts` (the triple check), `readme.ts`, `budget.ts`, `composition.ts`, `sets.ts`, `quantifiers.ts`, `functions.ts`, `lists.ts`, `sizes.ts`, `liveness.ts`, `steps.ts` (laws over up to 16 steps), and `jev-fabric/` (a Bend project's 59 proven laws, ported) |
+| `examples/` | The builders at work: `domains/` (187 rules across 21 domains, each with laws and broken variants), `harness.ts` (the triple check), `readme.ts`, `budget.ts`, `gdp.ts` (gdp-ts's example, its checks proven), `composition.ts`, `sets.ts`, `quantifiers.ts`, `functions.ts`, `lists.ts`, `sizes.ts`, `liveness.ts`, `steps.ts` (laws over up to 16 steps), and `jev-fabric/` (a Bend project's 59 proven laws, ported) |
 | `docs/` | The comparison with Bend and Lean, and the full scope |
 | `compare/` | The same three rules in gdp-wired, Bend and plain Lean, checked and measured |
 | `research/` | Everything around the library ([`research/README.md`](research/README.md)): the GPU searches (`search/`, `hw/`, `modal-gpu/`), invariant and rank synthesis (`synth/`), relational laws and guard synthesis (`next/`), bit-vector laws (`sat/`), the enumeration and benchmarks (`enum/`, `gpu/`, `perf/`), the first Lean checker (`lean/`) and the first prototype, the audit path (`audit/`) |
@@ -266,10 +304,24 @@ modal run modal/run.py --jobs modal/suite.json --out runs/modal/suite && sh moda
 
 Each directory's README has its own runs and results.
 
+## The skill
+
+`npx skills add monotykamary/gdp-wired` installs a skill that guides coding agents (and people) through writing a rule
+the way the code does it, stating its laws, reading a refused proof and handing a claim to Lean:
+
+- [**Workflow**](skills/gdp-wired/SKILL.md#workflow): the checklist for adding or changing a rule whose invariants matter.
+- [**Writing rules**](skills/gdp-wired/references/writing-rules.md): kinds, maps, step and k-step laws, histories,
+  liveness, decisions, two-run laws, loops.
+- [**Reading verdicts**](skills/gdp-wired/references/reading-verdicts.md): a bug or a missing invariant, and what to
+  change.
+- [**Shipping**](skills/gdp-wired/references/shipping.md): running the proven rule, and holding existing code to it.
+- [**The Lean handoff**](skills/gdp-wired/references/lean-handoff.md): exporting the proofs, and functions proven in Lean.
+- [**Where it fits**](skills/gdp-wired/references/where-it-fits.md): gdp-wired, Lean or Bend.
+
 ## Credits
 
 [gdp-ts](https://github.com/rauchg/gdp-ts) by Guillermo Rauch (Ghosts of Departed Proofs for TypeScript) is where the
-audit path starts; [Handwired](https://github.com/chenglou/handwired) by Cheng Lou is the circuit and GPU runtime this
+audit path starts, and what `gdp-wired/gdp` mints proofs for; [Handwired](https://github.com/chenglou/handwired) by Cheng Lou is the circuit and GPU runtime this
 builds on, through a fork; [Bend](https://github.com/bendlang/bend) is the language the laws were first written in,
 and the yardstick for the benchmarks.
 

package/dist/core/dsl.d.ts

@@ -469,6 +469,7 @@ export declare class Fun<P extends Obj = {}, I extends Obj = {}, O extends Obj =
     }): Value<O>;
 }
 export declare const fun: (name: string) => Fun;
+export declare const funOf: (d: Decision) => Fun<Obj, Obj, Obj> | undefined;
 export type Agreement = {
     checked: number;
     failure?: string;

package/dist/core/dsl.js

@@ -1457,11 +1457,11 @@ export class Fun {
     }
     // Whenever the arguments (and the result) meet `given`, the result meets `then`.
     law(name, given, then) {
-        return this.r.decide(name, env => given(env, this.result(env)), env => then(this.result(env), env));
+        return lawOfFun(this, this.r.decide(name, env => given(env, this.result(env)), env => then(this.result(env), env)));
     }
     // A law about two calls under the same params: `then(outA, outB, a, b)` given `given(a, b)` (noninterference, say).
     relate(name, given, then) {
-        return this.r.relate(name, given, (a, b) => then(this.result(a), this.result(b), a, b));
+        return lawOfFun(this, this.r.relate(name, given, (a, b) => then(this.result(a), this.result(b), a, b)));
     }
     // Against the code it describes: `reference` called with the same arguments (drawn by their kinds, or by `draw`, the
     // `edges` first) must return the same value for every field it returns (a field it leaves out is not compared). The
@@ -1499,6 +1499,11 @@ export class Fun {
     }
 }
 export const fun = (name) => new Fun(rule(name));
+// The function a law was stated about. Variants of one function share its arguments, so a law's terms alone don't say
+// which result it is about; a guard (gdp.ts) takes only laws stated about the function it runs.
+const lawsOfFuns = new WeakMap();
+const lawOfFun = (f, d) => { lawsOfFuns.set(d, f); return d; };
+export const funOf = (d) => lawsOfFuns.get(d);
 // A loop runs `body` while `while` holds, each turn with fresh inputs; it halts if a rank over the state and params
 // (or a tuple of them, compared in order) drops on every turn.
 export class LoopRule {

package/dist/core/gdp.d.ts

@@ -0,0 +1,35 @@
+import type { Named, NamesOf, Proof, Prover } from '@gdp-ts/core';
+import { type Decision, type Fun, type Rule, type StepLaw, type Verdict } from './dsl.js';
+import { type Law, type State } from './machine.js';
+type AnyNamed = Named<any, any>;
+export type Mint<K extends string, A> = <S extends AnyNamed[]>(args: A, ...about: S) => Proof<K, NamesOf<S>> | null;
+export declare class Unproven extends Error {
+    readonly verdict: Verdict;
+    constructor(what: string, verdict: Verdict);
+}
+type AnyFun = Fun<any, any, any>;
+type Conditions<O> = {
+    [k in keyof O]: O[k] extends boolean ? k : never;
+}[keyof O] & string;
+type ArgsOf<F extends AnyFun> = Parameters<F['run']>[0];
+type ParamsOf<F extends AnyFun> = NonNullable<Parameters<F['run']>[1]>;
+export declare function guard<K extends string, F extends AnyFun>(prover: Prover<K>, fn: F, field: Conditions<ReturnType<F['run']>>, opts: {
+    laws: Decision[];
+    params?: ParamsOf<F>;
+}): Mint<K, ArgsOf<F>>;
+type AnyRule = Rule<any, any, any, any, any, any, any, any>;
+type FlagOf<R> = R extends Rule<any, any, any, any, infer F, any, any, any> ? keyof F & string : never;
+type InputOf<R extends AnyRule> = Parameters<R['encodeInput']>[0];
+type RuleParams<R extends AnyRule> = Parameters<R['encodeParams']>[0];
+export type Gate<K extends string, I> = {
+    request: Mint<K, I>;
+    readonly state: State;
+    values(): Record<string, unknown>;
+};
+export declare function gate<K extends string, R extends AnyRule>(prover: Prover<K>, r: R, flag: FlagOf<R>, opts: {
+    laws: Law[];
+    stepLaws?: StepLaw[];
+    params?: RuleParams<R>;
+    state?: State;
+}): Gate<K, InputOf<R>>;
+export {};

package/dist/core/gdp.js

@@ -0,0 +1,66 @@
+import { funOf, proveDecision, proveSteps } from "./dsl.js";
+import { evalC, interpret } from "./machine.js";
+import { allowed, requestEnv } from "./watch.js";
+// A verdict that isn't a checked proof, as the error a guard or gate is refused with (the verdict on `.verdict`).
+export class Unproven extends Error {
+    verdict;
+    constructor(what, verdict) {
+        const found = [verdict.goal && `goal ${verdict.goal}`, verdict.stuck, verdict.witness && `a counterexample: ${JSON.stringify(verdict.witness)}`, verdict.why].filter(Boolean).join('; ');
+        super(`${what}: ${verdict.proven ? 'proven, but the kernel did not check the proof' : `not proven${found ? ` (${found})` : ''}`}`);
+        this.verdict = verdict;
+    }
+}
+const proven = (what, v) => { if (!(v.proven && v.checked))
+    throw new Unproven(what, v); };
+// A proof wherever `fn`'s result `field` holds. Every law in `laws` must have been stated about `fn` (fn.law or
+// fn.relate) and is proven now; the arguments it is later called with must meet the function's kinds and `assume`.
+//   const access = fun('document access').inputs({...}).returns(env => ({permit: permit(env)}))
+//   const mint = guard(CanRead, access, 'permit', {laws: [access.law('...', ...)]})
+export function guard(prover, fn, field, opts) {
+    if (opts.laws.length === 0)
+        throw new Error(`${fn.name}: a guard needs a law to prove`);
+    for (const d of opts.laws) {
+        if (funOf(d) !== fn)
+            throw new Error(`${fn.name}: "${d.name}" was not stated about this function (state it with ${fn.name}.law)`);
+        proven(`${fn.name}: "${d.name}"`, proveDecision(d));
+    }
+    const r = fn.rule, m = r.machine, params = (opts.params ?? {}), ps = r.encodeParams(params);
+    if (m.pre && !evalC(m.pre, ps, { scalars: {}, maps: {} }, m))
+        throw new Error(`${fn.name}: the params ${JSON.stringify(params)} don't meet its precondition`);
+    return (args, ...about) => {
+        const input = r.encodeInput(args);
+        if (m.assume && !evalC(m.assume, { ...ps, ...input }, { scalars: {}, maps: {} }, m))
+            return null;
+        return fn.run(args, params)[field] === true ? prover.prove(...about) : null;
+    };
+}
+// A proof for each request whose step takes `flag`, the rule's laws (and step laws) proven now. One gate holds one
+// run's state: keep one per state it guards (per process, or loaded and saved around each request in a transaction).
+//   const tokens = rule('one-time tokens').inputs({...}).maps({...}).flags(env => ({redeem: ...})).step(...)
+//   const redeem = gate(Redeemed, tokens, 'redeem', {laws: tokenLaws})
+//   redeem.request({op: 'redeem', token: 7}, user, token) // a Redeemed proof the first time, null after
+export function gate(prover, r, flag, opts) {
+    const m = r.machine;
+    if (!(flag in (m.step.flags ?? {})))
+        throw new Error(`${m.name}: no flag ${flag}`);
+    if (opts.laws.length + (opts.stepLaws?.length ?? 0) === 0)
+        throw new Error(`${m.name}: a gate needs a law to prove`);
+    proven(m.name, proveSteps(r, opts.laws, opts.stepLaws ?? []));
+    const params = (opts.params ?? {}), ps = r.encodeParams(params);
+    if (m.pre && !evalC(m.pre, ps, { scalars: {}, maps: {} }, m))
+        throw new Error(`${m.name}: the params ${JSON.stringify(params)} don't meet its precondition`);
+    const run = interpret(m), compiled = r.compiled();
+    let st = opts.state ?? compiled.init(ps);
+    return {
+        request: (args, ...about) => {
+            const input = r.encodeInput(args);
+            if (!allowed(m, run, ps, st, input))
+                return null;
+            const granted = requestEnv(m, run, ps, st, input)[`?${flag}`] === 1;
+            st = compiled.step(ps, st, input);
+            return granted ? prover.prove(...about) : null;
+        },
+        get state() { return st; },
+        values: () => r.decode(st),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdp-wired",
-  "version": "0.6.0",
+  "version": "0.7.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",
@@ -9,6 +9,7 @@
     "state-machine",
     "rate-limiting",
     "policy",
+    "gdp-ts",
     "lean",
     "automatic-prover",
     "theorem-prover",
@@ -59,6 +60,10 @@
       "types": "./dist/core/solver.d.ts",
       "default": "./dist/core/solver.js"
     },
+    "./gdp": {
+      "types": "./dist/core/gdp.d.ts",
+      "default": "./dist/core/gdp.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -69,6 +74,14 @@
   "engines": {
     "node": ">=20"
   },
+  "peerDependencies": {
+    "@gdp-ts/core": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@gdp-ts/core": {
+      "optional": true
+    }
+  },
   "scripts": {
     "typecheck": "tsc -p .",
     "lint": "oxlint --type-aware --deny-warnings --disable-nested-config",
@@ -76,13 +89,14 @@
     "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 && 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/composition.ts && bun examples/sets.ts && bun examples/quantifiers.ts && bun examples/functions.ts && bun examples/lists.ts && bun examples/sizes.ts && bun examples/liveness.ts && bun examples/budget.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 && 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/composition.ts && bun examples/sets.ts && bun examples/quantifiers.ts && bun examples/functions.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",
     "@types/bun": "1.3.1",
-    "typescript": "5.9.3",
     "@webgpu/types": "0.1.66",
     "oxlint": "1.88.0",
-    "oxlint-tsgolint": "7.0.2004"
+    "oxlint-tsgolint": "7.0.2004",
+    "typescript": "5.9.3"
   }
 }