@milkenjoyer/toolchain 0.12.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -46,9 +46,9 @@ In the PR job, set `permissions: contents: read` and `GH_TOKEN: ${{ github.token
46
46
 
47
47
  ## Formal check
48
48
 
49
- `vp exec formal` checks every tracked TLA+ module against the standard in agent-kit#276. Run it from anywhere in the repository with no arguments. It exits 0 when every check passes. Each finding goes to stderr as `<file>: <check>: <message>`, sorted by file and then by check order, and the command exits 1. Each passing step logs one line to stdout.
49
+ `vp exec formal` checks every tracked TLA+ module and arithmetic proof against the standard in agent-kit#276. Run it from anywhere in the repository with no arguments. It exits 0 when every check passes. Each finding goes to stderr as `<file>: <check>: <message>`, sorted by file and then by check order, and the command exits 1. Each passing step logs one line to stdout.
50
50
 
51
- It needs Java 17 on `PATH`. In CI, add `actions/setup-java` with `distribution: temurin` and `java-version: "17"` before the step that runs it. The first run downloads TLC 1.8.0 (`tla2tools-1.8.0.jar`) and CommunityModules 202611060952 (`CommunityModules-deps-202611060952.jar`) into `$XDG_CACHE_HOME/tla`, or `~/.cache/tla`. Every run checks both jars against their pinned SHA-256 digests. A cached jar with the wrong digest stops the run, and deleting it makes the next run fetch it again.
51
+ It needs Java 17 on `PATH`. In CI, add `actions/setup-java` with `distribution: temurin` and `java-version: "17"` before the step that runs it. The first run downloads TLC 1.8.0 (`tla2tools-1.8.0.jar`) and CommunityModules 202611060952 (`CommunityModules-deps-202611060952.jar`) into `$XDG_CACHE_HOME/tla`, or `~/.cache/tla`. Each jar falls back to its GitHub REST API asset URL when its release download fails, with the same SHA-256 check. Every run checks both jars against their pinned SHA-256 digests. A cached jar with the wrong digest stops the run, and deleting it makes the next run fetch it again.
52
52
 
53
53
  ### `specs.json`
54
54
 
@@ -101,7 +101,7 @@ The root `specs.json` is decoded strictly, so an unknown key fails.
101
101
  }
102
102
  ```
103
103
 
104
- - `critical` lists globs for the repo's money, auth, concurrency, retry, lifecycle and protocol code. Each one must match a tracked file, and every tracked file it matches must match the `covers` of some gate, manual or Kani entry.
104
+ - `critical` lists globs for the repo's money, auth, concurrency, retry, lifecycle and protocol code. Each one must match a tracked file, and every tracked file it matches must match the `covers` of some gate, manual, Kani or proof entry.
105
105
  - `specs` maps each tracked `.tla` path to its entry. `covers` is a non-empty list of globs, each matching a tracked file. `synced` is a 40-hex commit.
106
106
  - `mode` is `gate`, `manual` or `library`.
107
107
  - A `gate` or `manual` spec `X.tla` has exactly one config, `X.cfg`, beside it. It names at least one witness and one break for every `INVARIANT` and `PROPERTY` in `X.cfg`, `TypeOK` included. Only a gate spec runs TLC.
@@ -111,14 +111,16 @@ The root `specs.json` is decoded strictly, so an unknown key fails.
111
111
  - `witnesses` lists operators that must be violated: a state or behavior the spec claims to reach.
112
112
  - Each break is `{ violates, find, replace, file? }`. `file` defaults to the spec and may name a tracked `.tla` in the spec's directory or the spec's `X.cfg`.
113
113
  - `traces` is optional on a gate spec. `steer` maps an action to n (2 to 1000) and keeps a step by that action with probability 1/n, so runs reach rare paths. A second constant set needs a second module.
114
- - `kani` maps each tracked `.rs` harness to `synced`, `covers`, `mode` (`gate` or `manual`) and `timeoutSeconds`. The command doesn't run Kani, but its `covers` count for `critical`.
114
+ - `kani` maps each tracked `.rs` harness to `synced`, `covers`, `mode` (`gate` or `manual`) and `timeoutSeconds`. The command doesn't run Kani, but its `covers` count for `critical` and `arithmetic`.
115
+ - `proofs` and `arithmetic` are optional. See [Arithmetic proofs](#arithmetic-proofs).
115
116
 
116
117
  ### Checks
117
118
 
118
119
  The checks run in this order:
119
120
 
120
- - `specs`: `specs.json` decodes, every tracked `.tla` has an entry, every entry names a tracked file, and the configs follow the one-config layout.
121
+ - `specs`: `specs.json` decodes, every tracked `.tla` and `*.proof.ts` has an entry, every entry names a tracked file, and the configs follow the one-config layout.
121
122
  - `critical`: every `critical` and `covers` glob matches a tracked file, and every tracked file a `critical` glob matches is covered.
123
+ - `arithmetic`: every `arithmetic` glob matches a tracked file, and a proof or Kani entry covers every tracked file one matches.
122
124
  - `sany`: SANY parses every `.tla` with no error and no warning.
123
125
  - `typeok`: every config lists `TypeOK` under `INVARIANT`, and each module's `TypeOK` types every variable, including variables from modules it extends. A variable counts as typed when a conjunct of `TypeOK`, or of an operator without arguments that it names, reads `v \in S` or `v \subseteq S` and `S` doesn't mention `v`.
124
126
  - `deadlock`: no config sets `CHECK_DEADLOCK FALSE`. Give a bounded spec an explicit finished step instead.
@@ -130,10 +132,11 @@ The checks run in this order:
130
132
  - `witnesses`: each witness is a defined operator without arguments that isn't an action and that `X.cfg` doesn't already check. TLC checks it alone and must exit 12 or 13 with a violation. The config checks nothing else, so the violation is the witness's, even when TLC names an operator inside it.
131
133
  - `breaks`: each break's `find` occurs exactly once in its file. TLC checks the edited copy with only `violates` checked and must report a violation.
132
134
  - `traces`: the command generates the seeded traces and runs the conformance test.
135
+ - `proofs`: each arithmetic proof passes, and then each of its breaks makes it fail.
133
136
 
134
137
  When a gate run fails, its spec's `coverage`, `witnesses`, `breaks` and `traces` don't run; the `tlc` finding already fails the command.
135
138
 
136
- Breaks run only for a gate spec that changed since the base. The base is `git merge-base $BASE HEAD`, with `BASE` defaulting to `origin/main`. A change to `specs.json` reruns every break. A change to any tracked `.tla` or `.cfg` in a spec's directory, or to a break's `file`, reruns that spec's breaks. Uncommitted edits count. When the base doesn't resolve, every break runs.
139
+ A spec's breaks run only for a gate spec that changed since the base. The base is `git merge-base $BASE HEAD`, with `BASE` defaulting to `origin/main`. A change to `specs.json` reruns every break. A change to any tracked `.tla` or `.cfg` in a spec's directory, or to a break's `file`, reruns that spec's breaks. Uncommitted edits count. When the base doesn't resolve, every break runs.
137
140
 
138
141
  ### Traces
139
142
 
@@ -160,3 +163,89 @@ replayTraces("indexer pass", async (trace) => {
160
163
  A `Trace` has `index`, `constants` (the config's value constants, integers as numbers and other values as their config text) and `steps`. `steps[0]` is the init state. Each step has `action`, `args` (the action's arguments by parameter name) and `state` (every variable). The same seed gives byte-identical traces, and the passing log line prints their SHA-256.
161
164
 
162
165
  The command runs `vp test run` on the conformance file from the package that holds it (the nearest directory with a tracked `package.json`), with `FORMAL_TRACES` set to the trace file. The file must match that package's vitest `include`. The conformance check passes only when vitest exits 0 and `replayTraces` reports that every trace replayed to its last step. Under a plain `vp test`, `FORMAL_TRACES` is unset and `replayTraces` registers one skipped test.
166
+
167
+ ### Arithmetic proofs
168
+
169
+ Rule 16 proves pure money, rounding and random-number code in TypeScript, with money kept in whole numbers. A proof is a `*.proof.ts` file whose default export is one `every(...)` or `z3(...)` from `@milkenjoyer/toolchain/arithmetic`. Each proof has a `proofs` entry in `specs.json`:
170
+
171
+ ```json
172
+ {
173
+ "arithmetic": [
174
+ "packages/database/src/credits.ts",
175
+ "packages/domain/src/sim/random.ts"
176
+ ],
177
+ "proofs": {
178
+ "packages/database/formal/credits.proof.ts": {
179
+ "kind": "every",
180
+ "covers": ["packages/database/src/credits.ts"],
181
+ "breaks": [
182
+ {
183
+ "file": "packages/database/src/credits.ts",
184
+ "find": "Math.round((micro",
185
+ "replace": "Math.floor((micro"
186
+ }
187
+ ]
188
+ },
189
+ "packages/domain/formal/next-below.proof.ts": {
190
+ "kind": "z3",
191
+ "covers": ["packages/domain/src/sim/random.ts"],
192
+ "samples": 10000,
193
+ "breaks": [
194
+ {
195
+ "file": "packages/domain/src/sim/random.ts",
196
+ "find": "value: draw.value % bound",
197
+ "replace": "value: draw.value % (bound + 1)"
198
+ }
199
+ ]
200
+ }
201
+ }
202
+ }
203
+ ```
204
+
205
+ - `kind` is `every` or `z3`, and it must match the file's export. `covers` works as for specs. `timeoutSeconds` defaults to 60 and bounds the whole proof run. `samples`, on `z3` only, defaults to 10,000, which is also the minimum.
206
+ - Each break is `{ file, find, replace }`. `file` must match the entry's `covers`, and `find` must occur exactly once in it. The edited proof must fail with a counterexample, a mismatch between model and code, or a throw. The command applies the edit in memory, so the working tree never changes. Breaks run on every invocation.
207
+ - Each proof and each break runs in its own `bun` process. The proof must load every module file its `covers` match.
208
+
209
+ Use `every` when a schema bounds each input. The command reads each input's range from the decoded type of its Effect schema. That type must be an integer with a minimum and a maximum, and a file the proof covers must export the schema. The proof never states a range, so it can't check less than the code accepts. `holds` must return `true` for every input tuple, up to 2^32 tuples.
210
+
211
+ ```ts
212
+ import { every } from "@milkenjoyer/toolchain/arithmetic";
213
+
214
+ import { Centicredits, creditsOf, microOf } from "../src/credits.ts";
215
+
216
+ export default every({
217
+ inputs: { centi: Centicredits },
218
+ holds: ({ centi }) =>
219
+ microOf(centi / 100) === centi * 50 &&
220
+ creditsOf(centi * 50) === centi / 100,
221
+ });
222
+ ```
223
+
224
+ Use `z3` when the range is too large to check value by value. `model` states the function in z3, `code` calls the real function, and `holds` is the claim about the model's output. Each input is `int(min, max)`, `uint(bits)` or an exported integer schema. `assume` limits the claim to the inputs it is about.
225
+
226
+ ```ts
227
+ import { int, z3 } from "@milkenjoyer/toolchain/arithmetic";
228
+
229
+ import { nextBelow } from "../src/sim/random.ts";
230
+
231
+ const RANGE = 2 ** 32;
232
+ export default z3({
233
+ inputs: { draw: int(0, RANGE - 1), bound: int(1, RANGE) },
234
+ assume: ({ draw, bound }, Z3) =>
235
+ draw.lt(Z3.Int.val(RANGE).sub(Z3.Int.val(RANGE).mod(bound))),
236
+ model: ({ draw, bound }) => draw.mod(bound),
237
+ code: ({ draw, bound }) => nextBelow([draw, 0, 0, 0], bound).value,
238
+ holds: ({ bound }, out, Z3) => Z3.And(out.ge(0), out.lt(bound)),
239
+ });
240
+ ```
241
+
242
+ A `z3` proof passes only when all of these hold:
243
+
244
+ - `code` returns a whole number equal to the model's output on `samples` seeded inputs, edge values first.
245
+ - The claim uses only Int and BitVec arithmetic. Real and Float arithmetic fail.
246
+ - `holds` is false for some output, so the claim constrains the model.
247
+ - z3 answers `unsat` for the negated claim. `unknown`, a timeout or a crash fails.
248
+
249
+ The toolchain pins `z3-solver` 5.3.3, and the command starts and stops its worker threads. Division or remainder by a symbolic value is slow over BitVec, so state it over Int.
250
+
251
+ Rule 16 applies once `specs.json` has an `arithmetic` key. Each `arithmetic` glob must match a tracked file, and a proof or Kani entry must cover every tracked file one matches. Without the key, the `arithmetic` check logs that rule 16 is off. A repo adds the key in the same PR as its proofs.
@@ -0,0 +1,45 @@
1
+ import * as Schema from "effect/Schema";
2
+ import { Arith, BitVec, Bool, Context } from "z3-solver";
3
+ type IntSchema = Schema.Top & {
4
+ readonly Type: number;
5
+ };
6
+ type Literal = {
7
+ readonly kind: "int";
8
+ readonly min: number;
9
+ readonly max: number;
10
+ } | {
11
+ readonly kind: "uint";
12
+ readonly bits: number;
13
+ };
14
+ type Sym<D> = D extends {
15
+ readonly kind: "uint";
16
+ } ? BitVec<number, "main"> : Arith<"main">;
17
+ type Syms<I> = { readonly [K in keyof I]: Sym<I[K]>; };
18
+ type Values<I> = { readonly [K in keyof I]: I[K] extends IntSchema ? I[K]["Type"] : number; };
19
+ type Term = Arith<"main"> | BitVec<number, "main"> | Bool<"main">;
20
+ type Output = Term | {
21
+ readonly [key: string]: Term;
22
+ };
23
+ type Concrete<O> = O extends Bool<"main"> ? boolean : O extends Term ? number : { readonly [K in keyof O]: Concrete<O[K]>; };
24
+ export type Every<I extends Record<string, IntSchema>> = {
25
+ readonly kind: "every";
26
+ readonly inputs: I;
27
+ readonly holds: (values: Values<I>) => boolean;
28
+ };
29
+ export type Z3Proof<I extends Record<string, IntSchema | Literal>, O extends Output> = {
30
+ readonly kind: "z3";
31
+ readonly inputs: I;
32
+ readonly assume?: (s: Syms<I>, Z3: Context<"main">) => Bool<"main">;
33
+ readonly model: (s: Syms<I>, Z3: Context<"main">) => O;
34
+ readonly code: (values: Values<I>) => Concrete<O>;
35
+ readonly holds: (s: Syms<I>, out: O, Z3: Context<"main">) => Bool<"main">;
36
+ };
37
+ export declare const every: <I extends Record<string, IntSchema>>(proof: Omit<Every<I>, "kind">) => Every<I>;
38
+ export declare const z3: <I extends Record<string, IntSchema | Literal>, O extends Output>(proof: Omit<Z3Proof<I, O>, "kind">) => Z3Proof<I, O>;
39
+ export declare const int: (min: number, max: number) => Extract<Literal, {
40
+ kind: "int";
41
+ }>;
42
+ export declare const uint: (bits: number) => Extract<Literal, {
43
+ kind: "uint";
44
+ }>;
45
+ export {};
@@ -0,0 +1,25 @@
1
+ // src/arithmetic.ts
2
+ const every = (proof) => ({
3
+ kind: "every",
4
+ ...proof
5
+ });
6
+ const z3 = (proof) => ({
7
+ kind: "z3",
8
+ ...proof
9
+ });
10
+ const int = (min, max) => {
11
+ if (!Number.isSafeInteger(min) || !Number.isSafeInteger(max) || min > max) throw new Error("int needs safe integer bounds with min <= max");
12
+ return {
13
+ kind: "int",
14
+ min,
15
+ max
16
+ };
17
+ };
18
+ const uint = (bits) => {
19
+ if (!Number.isInteger(bits) || bits < 1 || bits > 53) throw new Error("uint needs a bit width from 1 to 53");
20
+ return {
21
+ kind: "uint",
22
+ bits
23
+ };
24
+ };
25
+ export { every, int, uint, z3 };