@milkenjoyer/toolchain 0.11.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.
Files changed (45) hide show
  1. package/README.md +190 -17
  2. package/dist/arithmetic.d.mts +45 -0
  3. package/dist/arithmetic.mjs +25 -0
  4. package/dist/conformance.d.mts +18 -0
  5. package/dist/conformance.mjs +31 -0
  6. package/dist/effect-plugin.mjs +1 -1
  7. package/dist/exceptions-Dybl9xpc.mjs +11 -0
  8. package/dist/exceptions.mjs +1 -1
  9. package/dist/foldkit-plugin.mjs +1 -1
  10. package/dist/formal.d.mts +131 -3
  11. package/dist/formal.mjs +1006 -146
  12. package/dist/guard.mjs +2 -2
  13. package/dist/knip.mjs +2 -1
  14. package/dist/{lint-JSnPsGO1.mjs → lint-IhmtnBbx.mjs} +3 -3
  15. package/dist/lint.mjs +1 -1
  16. package/dist/plugin.mjs +1 -1
  17. package/dist/proof.mjs +1 -1
  18. package/dist/trace-file-KuPRWgwt.mjs +17 -0
  19. package/dist/verdict.d.mts +1 -1
  20. package/dist/verdict.mjs +1 -1
  21. package/dist/{verification-p2rSx5lc.d.mts → verification-FgQFU1YN.d.mts} +1 -1
  22. package/dist/verification.d.mts +1 -1
  23. package/dist/verification.mjs +1 -1
  24. package/package.json +12 -3
  25. package/src/formal/arithmetic.ts +190 -0
  26. package/src/formal/cfg.ts +58 -1
  27. package/src/formal/checks.ts +57 -52
  28. package/src/formal/coverage.ts +79 -0
  29. package/src/formal/gate.ts +74 -0
  30. package/src/formal/git.ts +38 -0
  31. package/src/formal/proof-run.ts +77 -0
  32. package/src/formal/proofs.ts +226 -0
  33. package/src/formal/prover.ts +291 -0
  34. package/src/formal/semantics.ts +110 -0
  35. package/src/formal/specs.ts +103 -31
  36. package/src/formal/tla.ts +60 -19
  37. package/src/formal/trace-file.ts +35 -0
  38. package/src/formal/traces.ts +293 -0
  39. package/src/formal/violations.ts +76 -0
  40. package/src/formal/z3.ts +321 -0
  41. package/src/formal.ts +10 -3
  42. package/dist/exceptions-Bq-9MxoR.mjs +0 -3
  43. package/dist/{effect-plugin-kYxB-5LJ.mjs → effect-plugin-BXUx9PPu.mjs} +1 -1
  44. package/dist/{plugin-BoBRGtGf.mjs → plugin-CwxhPtui.mjs} +1 -1
  45. package/dist/{verification-6s2chr4X.mjs → verification-oAc1Q6I9.mjs} +1 -1
package/README.md CHANGED
@@ -46,33 +46,206 @@ 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 TLA+ spec in the repository against the standard in agent-kit#276. Run it from anywhere in the repository with no arguments. It reads `specs.json` at the repository root and the tracked `.tla` and `.cfg` files.
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
- `specs.json` maps each spec's path to its entry. Unknown keys fail. Kani entries (`.rs`) decode with the same schema and are left to the repository's own guard.
53
+ ### `specs.json`
54
+
55
+ The root `specs.json` is decoded strictly, so an unknown key fails.
54
56
 
55
57
  ```json
56
58
  {
57
- "apps/indexer/formal/IndexerPass.tla": {
58
- "synced": "<40-hex commit>",
59
- "covers": ["apps/indexer/src/pass.ts"],
60
- "mode": "gate",
61
- "timeoutSeconds": 60
59
+ "critical": ["apps/indexer/src/pass.ts"],
60
+ "specs": {
61
+ "apps/indexer/formal/IndexerPass.tla": {
62
+ "synced": "<40-hex commit>",
63
+ "covers": ["apps/indexer/src/pass.ts"],
64
+ "mode": "gate",
65
+ "timeoutSeconds": 120,
66
+ "witnesses": ["NoCommitLands"],
67
+ "breaks": [
68
+ {
69
+ "violates": "TypeOK",
70
+ "find": "cursorSlot' = c.upTo",
71
+ "replace": "cursorSlot' = -1"
72
+ },
73
+ {
74
+ "violates": "NoDuplicate",
75
+ "find": "applied \\o c.batch",
76
+ "replace": "applied \\o c.batch \\o c.batch"
77
+ }
78
+ ],
79
+ "traces": {
80
+ "seed": 7,
81
+ "depth": 100,
82
+ "count": 500,
83
+ "steer": { "Crash": 8 },
84
+ "conformance": "apps/indexer/formal/indexer-pass.conformance.test.ts"
85
+ }
86
+ },
87
+ "apps/house/formal/Rounds.tla": {
88
+ "synced": "<40-hex commit>",
89
+ "covers": ["apps/house/src/rounds.ts"],
90
+ "mode": "library"
91
+ }
92
+ },
93
+ "kani": {
94
+ "apps/house/core/src/legs.rs": {
95
+ "synced": "<40-hex commit>",
96
+ "covers": ["apps/house/core/src/legs.rs"],
97
+ "mode": "manual",
98
+ "timeoutSeconds": 300
99
+ }
62
100
  }
63
101
  }
64
102
  ```
65
103
 
66
- `mode` is `gate` or `manual`. `timeoutSeconds` defaults to 60 and allows up to 1800. The command also decodes `witnesses` (operator names), `breaks` (`{ violates, find, replace, file? }`), `traces` (`{ seed, depth, count }`) and `conformance` (a test file, set together with `traces`). It doesn't run them yet; agent-kit#278 adds that.
67
-
68
- The checks:
69
-
70
- - `specs`: every tracked `.tla` has an entry, every `.tla` entry names a tracked file, every gate spec `X.tla` has `X.cfg`, every config beside a spec pairs with a module (`X.cfg` or `X.<variant>.cfg`) and parses, and `specs.json` decodes.
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
+ - `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
+ - `mode` is `gate`, `manual` or `library`.
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.
108
+ - A `library` module has no config and no witnesses, breaks or traces. Other specs extend it.
109
+ - Any other config, such as `X.fast.cfg`, fails. Give a variant its own module that `EXTENDS X`.
110
+ - `timeoutSeconds` defaults to 60 and allows up to 1800. It bounds each TLC run and the conformance run.
111
+ - `witnesses` lists operators that must be violated: a state or behavior the spec claims to reach.
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
+ - `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` and `arithmetic`.
115
+ - `proofs` and `arithmetic` are optional. See [Arithmetic proofs](#arithmetic-proofs).
116
+
117
+ ### Checks
118
+
119
+ The checks run in this order:
120
+
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.
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.
71
124
  - `sany`: SANY parses every `.tla` with no error and no warning.
72
- - `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`. A clause such as `v = v` or a quantified clause about `v` doesn't count.
73
- - `deadlock`: no config sets `CHECK_DEADLOCK FALSE`. Give a bounded spec an explicit finished step instead. The command never passes `-deadlock`.
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`.
126
+ - `deadlock`: no config sets `CHECK_DEADLOCK FALSE`. Give a bounded spec an explicit finished step instead.
127
+ - `fairness`: every `WF_` and `SF_` uses `vars` as its subscript.
74
128
  - `constants`: no two integer constants in one config share a value.
75
129
  - `format`: every `.tla` matches `formatter.Main`'s output byte for byte. The finding prints the command that rewrites the file.
76
- - `tlc`: TLC runs each gate spec's `X.cfg` within its `timeoutSeconds`. Any TLC warning or error fails the run, and so do a nonzero exit, a missing success message and a zero distinct-state count. Manual specs don't run.
130
+ - `tlc`: TLC runs each gate spec's `X.cfg` once, with `-coverage` and `-lncheck final`, within its `timeoutSeconds`. Any TLC warning or error fails the run, and so do a nonzero exit, a missing success message, a zero distinct-state count and a missing or unreadable coverage report.
131
+ - `coverage`: the gate run enables every action, and every expression under the init predicate and the enabled actions runs at least once. The finding quotes the source that never runs.
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.
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.
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.
136
+
137
+ When a gate run fails, its spec's `coverage`, `witnesses`, `breaks` and `traces` don't run; the `tlc` finding already fails the command.
138
+
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.
140
+
141
+ ### Traces
142
+
143
+ For a gate spec with `traces`, the command runs TLC in simulation mode with `-simulate num=<count> -depth <depth> -seed <seed> -workers 1`. Each behavior is serialized with `IOUtils!Serialize` and `TLCExt!Trace`, once per behavior. The actions are the ones TLC reports in the gate's coverage, including quantified actions with arguments. The init and next operators come from `INIT` and `NEXT`, or from a `SPECIFICATION` that conjoins one named init predicate with one `[][Next]_vars`.
144
+
145
+ `TLCExt!Trace` drops each step whose state equals the one before it, such as a no-op retry, so a serialized behavior can hold fewer states than `TLCGet("level")`. The generated wrapper adds a counter that every action increments, so no step is dropped. The command then requires exactly `count` behaviors of exactly `depth` states, known actions with the right number of arguments, and exactly the spec's variables.
146
+
147
+ The conformance test replays the traces through `replayTraces`, which registers one test per trace. For each trace it calls your function once to start the real code, then drives that code one step at a time:
148
+
149
+ ```ts
150
+ import { replayTraces } from "@milkenjoyer/toolchain/conformance";
151
+
152
+ replayTraces("indexer pass", async (trace) => {
153
+ const pass = await startPass(trace.constants);
154
+ return {
155
+ step: (step) => pass.apply(step.action, step.args),
156
+ observe: () => ({ cursorSlot: pass.cursor(), applied: pass.applied() }),
157
+ };
158
+ });
159
+ ```
160
+
161
+ `step` runs each model step after the init state through the code. After the init state and after every step, `replayTraces` calls `observe` and compares what it returns with the model state on those variables. `observe` must return at least one of the spec's variables and nothing else, and every value must equal the model's.
162
+
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.
164
+
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.
77
250
 
78
- Each passing TLC run prints its distinct-state count. The command exits 0 when nothing is found. It prints each finding to stderr as `<file>: <check>: <message>` and exits 1. It also exits 1 when it can't run, for example without Java 17 or with a bad jar.
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 };
@@ -0,0 +1,18 @@
1
+ import * as Schema from "effect/Schema";
2
+ declare const Trace: Schema.Struct<{
3
+ readonly index: Schema.Int;
4
+ readonly constants: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
5
+ readonly steps: Schema.NonEmptyArray<Schema.Struct<{
6
+ readonly action: Schema.NonEmptyString;
7
+ readonly args: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
8
+ readonly state: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
9
+ }>>;
10
+ }>;
11
+ type Trace = typeof Trace.Type;
12
+ type Step = Trace["steps"][number];
13
+ export type Replay = {
14
+ readonly step: (step: Step) => void | Promise<void>;
15
+ readonly observe: () => Readonly<Record<string, unknown>> | Promise<Readonly<Record<string, unknown>>>;
16
+ };
17
+ export declare const replayTraces: (name: string, start: (trace: Trace) => Replay | Promise<Replay>) => void;
18
+ export type { Trace };
@@ -0,0 +1,31 @@
1
+ import { n as readTraces, r as receiptPath, t as FORMAL_TRACES } from "./trace-file-KuPRWgwt.mjs";
2
+ import { readFileSync, writeFileSync } from "node:fs";
3
+ import * as Config from "effect/Config";
4
+ import * as Effect from "effect/Effect";
5
+ import { afterAll, expect, test } from "vite-plus/test";
6
+ // src/conformance.ts
7
+ const replayTraces = (name, start) => {
8
+ const file = Effect.runSync(Config.String(FORMAL_TRACES).pipe(Config.withDefault("")));
9
+ if (file === "") {
10
+ test.skip(`${name}: run vp exec formal to replay traces`, () => {});
11
+ return;
12
+ }
13
+ const traces = readTraces(readFileSync(file, "utf8"));
14
+ let passed = 0;
15
+ for (const trace of traces) test(`${name} #${trace.index}`, async () => {
16
+ const replay = await start(trace);
17
+ for (const [index, step] of trace.steps.entries()) {
18
+ if (index > 0) await replay.step(step);
19
+ const observed = await replay.observe();
20
+ const keys = Object.keys(observed);
21
+ expect(keys, `step ${index} observes no model variable`).not.toEqual([]);
22
+ expect(keys.filter((key) => !Object.hasOwn(step.state, key)), `step ${index} observes variables the model doesn't have`).toEqual([]);
23
+ expect(observed, `step ${index} (${step.action}) differs from the model`).toEqual(Object.fromEntries(keys.map((key) => [key, step.state[key]])));
24
+ }
25
+ passed++;
26
+ });
27
+ afterAll(() => {
28
+ writeFileSync(receiptPath(file), String(passed));
29
+ });
30
+ };
31
+ export { replayTraces };
@@ -1 +1 @@
1
- export { t as default } from "./effect-plugin-kYxB-5LJ.mjs";
1
+ export { t as default } from "./effect-plugin-BXUx9PPu.mjs";
@@ -0,0 +1,11 @@
1
+ // src/exceptions.ts
2
+ const exceptions = [{
3
+ files: ["packages/toolchain/src/conformance.ts"],
4
+ rules: [
5
+ "eslint/no-restricted-imports",
6
+ "vitest/no-disabled-tests",
7
+ "vitest/no-conditional-tests"
8
+ ],
9
+ issue: "https://github.com/birbprophet/agent-kit/issues/278"
10
+ }];
11
+ export { exceptions as t };
@@ -1 +1 @@
1
- export { t as exceptions } from "./exceptions-Bq-9MxoR.mjs";
1
+ export { t as exceptions } from "./exceptions-Dybl9xpc.mjs";
@@ -1,8 +1,8 @@
1
1
  import * as Arr from "effect/Array";
2
2
  import * as R from "effect/Record";
3
3
  import * as Schema from "effect/Schema";
4
- import * as Effect from "effect/Effect";
5
4
  import { existsSync, readFileSync } from "node:fs";
5
+ import * as Effect from "effect/Effect";
6
6
  import { dirname, join } from "node:path";
7
7
  import upstream from "@foldkit/oxlint-plugin";
8
8
  // src/foldkit-plugin.ts
package/dist/formal.d.mts CHANGED
@@ -1,14 +1,88 @@
1
- import "effect/Schema";
1
+ import * as Schema from "effect/Schema";
2
2
  import * as Effect from "effect/Effect";
3
+ import * as Layer from "effect/Layer";
3
4
  import { ChildProcessSpawner } from "effect/process";
4
5
  import { FileSystem } from "effect/FileSystem";
5
6
  import * as Context from "effect/Context";
6
- import * as Layer from "effect/Layer";
7
7
  import { Path } from "effect/Path";
8
+ type CfgConstant = {
9
+ readonly _tag: "Value";
10
+ readonly name: string;
11
+ readonly value: string;
12
+ } | {
13
+ readonly _tag: "Substitution";
14
+ readonly name: string;
15
+ readonly by: string;
16
+ };
17
+ type Cfg = {
18
+ readonly constants: ReadonlyArray<CfgConstant>;
19
+ readonly sections: ReadonlyArray<{
20
+ readonly keyword: string;
21
+ readonly text: string;
22
+ }>;
23
+ readonly properties: ReadonlyArray<string>;
24
+ readonly invariants: ReadonlyArray<string>;
25
+ readonly checkDeadlock: ReadonlyArray<boolean>;
26
+ };
27
+ type Operator = {
28
+ readonly name: string;
29
+ readonly level: number;
30
+ readonly params: ReadonlyArray<{
31
+ readonly name: string;
32
+ readonly arity: number;
33
+ }>;
34
+ readonly module: string;
35
+ };
8
36
  type Semantics = {
37
+ readonly operators: ReadonlyMap<string, Operator>;
38
+ readonly fairness: ReadonlyArray<{
39
+ readonly kind: string;
40
+ readonly line: string;
41
+ readonly valid: boolean;
42
+ }>;
43
+ readonly specifications: ReadonlyMap<string, {
44
+ readonly init: string;
45
+ readonly next: string;
46
+ }>;
9
47
  readonly variables: ReadonlyArray<string>;
10
48
  readonly typeOK: ReadonlySet<string> | undefined;
11
49
  };
50
+ declare const Entry: Schema.Union<readonly [Schema.Struct<{
51
+ readonly synced: Schema.String;
52
+ readonly covers: Schema.NonEmptyArray<Schema.NonEmptyString>;
53
+ readonly timeoutSeconds: Schema.withDecodingDefaultKey<Schema.Int, never>;
54
+ readonly witnesses: Schema.NonEmptyArray<Schema.String>;
55
+ readonly breaks: Schema.withDecodingDefaultKey<Schema.$Array<Schema.Struct<{
56
+ readonly violates: Schema.String;
57
+ readonly find: Schema.NonEmptyString;
58
+ readonly replace: Schema.String;
59
+ readonly file: Schema.optionalKey<Schema.String>;
60
+ }>>, never>;
61
+ readonly mode: Schema.Literal<"gate">;
62
+ readonly traces: Schema.optionalKey<Schema.Struct<{
63
+ readonly seed: Schema.Int;
64
+ readonly depth: Schema.Int;
65
+ readonly count: Schema.Int;
66
+ readonly steer: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Int>>;
67
+ readonly conformance: Schema.String;
68
+ }>>;
69
+ }>, Schema.Struct<{
70
+ readonly synced: Schema.String;
71
+ readonly covers: Schema.NonEmptyArray<Schema.NonEmptyString>;
72
+ readonly timeoutSeconds: Schema.withDecodingDefaultKey<Schema.Int, never>;
73
+ readonly witnesses: Schema.NonEmptyArray<Schema.String>;
74
+ readonly breaks: Schema.withDecodingDefaultKey<Schema.$Array<Schema.Struct<{
75
+ readonly violates: Schema.String;
76
+ readonly find: Schema.NonEmptyString;
77
+ readonly replace: Schema.String;
78
+ readonly file: Schema.optionalKey<Schema.String>;
79
+ }>>, never>;
80
+ readonly mode: Schema.Literal<"manual">;
81
+ }>, Schema.Struct<{
82
+ readonly synced: Schema.String;
83
+ readonly covers: Schema.NonEmptyArray<Schema.NonEmptyString>;
84
+ readonly mode: Schema.Literal<"library">;
85
+ }>]>;
12
86
  type Analysis = {
13
87
  readonly _tag: "Parsed";
14
88
  readonly semantics: Semantics;
@@ -16,6 +90,18 @@ type Analysis = {
16
90
  readonly _tag: "Unparsed";
17
91
  readonly output: string;
18
92
  };
93
+ type Model = {
94
+ readonly root: string;
95
+ readonly path: string;
96
+ readonly entry: Exclude<typeof Entry.Type, {
97
+ readonly mode: "library";
98
+ }>;
99
+ readonly semantics: Semantics;
100
+ readonly config: {
101
+ readonly path: string;
102
+ readonly cfg: Cfg;
103
+ };
104
+ };
19
105
  declare const FormalError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
20
106
  readonly _tag: "FormalError";
21
107
  } & Readonly<A>;
@@ -36,6 +122,15 @@ type TlcRun = {
36
122
  readonly _tag: "TimedOut";
37
123
  };
38
124
  type TlcInput = {
125
+ readonly mode: {
126
+ readonly _tag: "Check";
127
+ readonly coverage: boolean;
128
+ } | {
129
+ readonly _tag: "Simulate";
130
+ readonly num: number;
131
+ readonly depth: number;
132
+ readonly seed: number;
133
+ };
39
134
  readonly spec: string;
40
135
  readonly config: string;
41
136
  readonly timeoutSeconds: number;
@@ -56,5 +151,38 @@ declare const Tla_base: Context.ServiceClass<Tla, "formal/Tla", {
56
151
  declare class Tla extends Tla_base {
57
152
  static readonly layer: Layer.Layer<Tla, FormalError, ChildProcessSpawner.ChildProcessSpawner | FileSystem | Path>;
58
153
  }
59
- export declare const formal: (root: string) => Effect.Effect<0 | 1, FormalError | import("effect/PlatformError").PlatformError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("effect/Scope").Scope | Tla>;
154
+ type Span = {
155
+ readonly module: string;
156
+ readonly line: number;
157
+ readonly col: number;
158
+ readonly endLine: number;
159
+ readonly endCol: number;
160
+ };
161
+ type Coverage = {
162
+ readonly actions: ReadonlyArray<{
163
+ readonly name: string;
164
+ readonly span: Span;
165
+ readonly generated: bigint;
166
+ }>;
167
+ readonly zeros: ReadonlyArray<{
168
+ readonly scope: string;
169
+ readonly span: Span;
170
+ }>;
171
+ };
172
+ type GateResult = {
173
+ readonly _tag: "Passed";
174
+ readonly states: string;
175
+ readonly seconds: number;
176
+ readonly coverage: Coverage;
177
+ } | {
178
+ readonly _tag: "Failed";
179
+ readonly message: string;
180
+ };
181
+ declare const Gate_base: Context.ServiceClass<Gate, "formal/Gate", {
182
+ run: (model: Model) => Effect.Effect<GateResult, FormalError, never>;
183
+ }>;
184
+ declare class Gate extends Gate_base {
185
+ static readonly layer: Layer.Layer<Gate, never, Tla>;
186
+ }
187
+ export declare const formal: (root: string) => Effect.Effect<0 | 1, FormalError | import("effect/PlatformError").PlatformError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | import("effect/FileSystem").FileSystem | Gate | import("effect/Path").Path | import("effect/Scope").Scope | Tla>;
60
188
  export {};