@milkenjoyer/toolchain 0.12.0 → 0.14.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 +115 -6
- package/dist/arithmetic.d.mts +45 -0
- package/dist/arithmetic.mjs +25 -0
- package/dist/formal.mjs +369 -273
- package/dist/guard.d.mts +2 -2
- package/dist/guard.mjs +1 -46
- package/dist/knip.mjs +2 -1
- package/dist/manifest-xQwgnYI1.mjs +53 -0
- package/dist/specs-file-NsQF4V7X.mjs +135 -0
- package/dist/standard.d.mts +2 -0
- package/dist/standard.mjs +398 -0
- package/package.json +10 -2
- package/src/formal/arithmetic.ts +190 -0
- package/src/formal/checks.ts +19 -1
- package/src/formal/critical.ts +48 -0
- package/src/formal/proof-run.ts +77 -0
- package/src/formal/proofs.ts +2 -36
- package/src/formal/prover.ts +291 -0
- package/src/formal/specs-file.ts +119 -0
- package/src/formal/specs.ts +3 -87
- package/src/formal/tla.ts +36 -17
- package/src/formal/z3.ts +321 -0
- package/src/formal.ts +1 -1
- package/src/standard/agents.ts +44 -0
- package/src/standard/checks.ts +19 -0
- package/src/standard/config.ts +110 -0
- package/src/standard/formal.ts +93 -0
- package/src/standard/manifest.ts +102 -0
- package/src/standard/plugin-skills.ts +88 -0
- package/src/standard/repo.ts +69 -0
- package/src/standard/toolchain.ts +90 -0
- package/src/standard.ts +71 -0
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
|
|
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
|
-
|
|
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,109 @@ 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.
|
|
252
|
+
|
|
253
|
+
## Standard check
|
|
254
|
+
|
|
255
|
+
Run `vp exec standard` from a Git repository. The command accepts no arguments. It checks tracked files that still exist.
|
|
256
|
+
|
|
257
|
+
Findings go to stderr as `<file>: <rule>: <message>`, sorted by file and rule order. Failure ends with `standard: N findings` and exit code 1. Success prints `standard: N rules, no findings` and exits 0. Extra arguments print `usage: standard` and exit 2.
|
|
258
|
+
|
|
259
|
+
- `toolchain-pin` requires an exact toolchain dependency or an exact catalog entry.
|
|
260
|
+
- `lint-package` rejects repo-owned lint packages.
|
|
261
|
+
- `lint-fmt` requires the shared lint and fmt imports through the root Vite config.
|
|
262
|
+
- `tsconfig-base` requires the shared base in the root extends chain.
|
|
263
|
+
- `node-version` requires the toolchain's Node version.
|
|
264
|
+
- `renovate-preset` requires the shared Renovate preset URL.
|
|
265
|
+
- `exact-versions` rejects dependency ranges in tracked manifests.
|
|
266
|
+
- `specs` requires valid specs metadata, a spec entry and coverage of critical files.
|
|
267
|
+
- `ready-formal` requires a ready workflow step running `vp exec formal`. A step or job with `if: false` or `continue-on-error` does not count.
|
|
268
|
+
- `task-agents` requires a Task agents section with one line pointing to `agent-kit:task-agents`.
|
|
269
|
+
- `skill-names` rejects repo skills that share plugin skill names.
|
|
270
|
+
|
|
271
|
+
New rules register in `src/standard/checks.ts`.
|
|
@@ -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 };
|