lawspec 0.27.0 → 0.28.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/CHANGELOG.md +112 -1
- package/bin/lawspec.mjs +28 -8
- package/build.json +137 -119
- package/builtin-data-names.mjs +4 -4
- package/core.wasm +2 -2
- package/core_jsffi.js +5 -5
- package/examples/native-payments/elixir/lib/payments_domain.ex +1 -1
- package/examples/native-payments/erlang/src/payments_domain.erl +1 -1
- package/examples/rc1/bit-codec.lawspec +6 -6
- package/examples/rc1/native-payments.lawspec +6 -6
- package/examples/rc1/nesting/rrr.lawspec +2 -2
- package/examples/rc1/nesting/rru.lawspec +4 -4
- package/examples/rc1/nesting/rur.lawspec +4 -4
- package/examples/rc1/nesting/ruu.lawspec +5 -5
- package/examples/rc1/nesting/urr.lawspec +4 -4
- package/examples/rc1/nesting/uru.lawspec +5 -5
- package/examples/rc1/nesting/uur.lawspec +5 -5
- package/examples/rc1/nesting/uuu.lawspec +6 -6
- package/examples/rc1/recursive-records.lawspec +5 -5
- package/examples/rc1/refund-policy.lawspec +4 -0
- package/examples/specs/builtins.lawspec +2 -2
- package/examples/specs/collections.lawspec +8 -8
- package/examples/specs/composition.lawspec +10 -10
- package/examples/specs/contracts.lawspec +2 -2
- package/examples/specs/crypto.lawspec +2 -2
- package/examples/specs/flow_stack.lawspec +4 -4
- package/examples/specs/generation.lawspec +2 -2
- package/examples/specs/list_contracts.lawspec +3 -3
- package/examples/specs/lists.lawspec +6 -6
- package/examples/specs/matching.lawspec +8 -8
- package/examples/specs/payments.lawspec +5 -5
- package/examples/specs/records.lawspec +4 -4
- package/examples/specs/refinements.lawspec +4 -0
- package/examples/specs/resources.lawspec +5 -5
- package/examples/specs/sequences.lawspec +1 -1
- package/examples/specs/sum_refinements.lawspec +11 -11
- package/index.d.ts +154 -3
- package/package.json +1 -1
- package/proof.d.ts +57 -12
- package/proof.mjs +277 -13
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,116 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
## [0.28.0] - 2026-10-22
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- Laws about observed histories: `law n in history h is definition: the
|
|
14
|
+
complete history holds P` (closed: proved or refuted) or `the history so far
|
|
15
|
+
holds P` (open: proved, refuted, or the new status `pending` while what
|
|
16
|
+
comes next decides). A deadline is refuted as soon as an entry is observed
|
|
17
|
+
past it.
|
|
18
|
+
- Model laws with deadlines (`whenever P, Q within 24h`) in whole
|
|
19
|
+
microsecond ticks, only through the model's `wait` command; a
|
|
20
|
+
missed deadline is refuted with the run and the time waited. For models
|
|
21
|
+
the explicit search cannot finish, `lawspec prove` proves an invariant by
|
|
22
|
+
induction, or by an invariant Z3's Spacer proposes and plain queries
|
|
23
|
+
re-check, and refutes one with a bounded run the evaluator replays.
|
|
24
|
+
- Laws about a model's runs: `property` declares a claim in plain words
|
|
25
|
+
(`always`, `eventually`, `whenever P, Q`, `never P before Q`, `until`),
|
|
26
|
+
and `law n in model m [assuming [strong] fairness for c] is definition:
|
|
27
|
+
every run holds P end definition end law` (or `some run holds P`) checks it
|
|
28
|
+
over the model's reference by an in-house explicit-state search, shared by
|
|
29
|
+
the native and WASM compilers. A law is proved with the number of states
|
|
30
|
+
explored, refuted with the run that breaks it, or incomplete past the
|
|
31
|
+
search's bound; native conformance keeps its own evidence.
|
|
32
|
+
- `lawspec prove` quantifies `Rational` inputs exactly (never an irrational
|
|
33
|
+
witness), handles `Decimal`, and reasons about `Float32` and `Float64` with
|
|
34
|
+
IEEE equality: NaN differs from itself and the zeros are equal. A law true
|
|
35
|
+
for reals but not floats is refuted with a float the evaluator confirms.
|
|
36
|
+
- `lawspec prove` reasons about `Text`: joining, length, slices, decimal
|
|
37
|
+
text, ordering, `starts with`, `ends with`, `contains` and
|
|
38
|
+
`matches regex`, using UTF-32BE to preserve the complete Unicode scalar
|
|
39
|
+
domain through U+10FFFF despite Z3's smaller alphabet. List length and joining are
|
|
40
|
+
supported too, and the codec portfolio and unbounded laws of the
|
|
41
|
+
Chapter 6 reference models are proved.
|
|
42
|
+
- `lawspec prove` proves laws by induction. A law's harness says
|
|
43
|
+
`prove by induction on xs`, citing other laws with `using "|a|`; with no
|
|
44
|
+
setting, a law with one list-like input gets one try. Each case is its own
|
|
45
|
+
task with its own receipt, a law rests on the laws it cites, and a case
|
|
46
|
+
whose model the law survives reports that the induction hypothesis is too
|
|
47
|
+
weak. The harness can also choose how recursion is unfolded:
|
|
48
|
+
`prove by unfolding step by step [up to n times]`,
|
|
49
|
+
`prove by solver recursion`, or both in turn (the default). Unproved laws
|
|
50
|
+
over recursive definitions get a counterexample search, so obviously false
|
|
51
|
+
ones are refuted.
|
|
52
|
+
- `lawspec prove` handles laws over recursive definitions. Each task gives Z3
|
|
53
|
+
the definitions unfolded step by step (guarded axioms with fuel, as Why3
|
|
54
|
+
and Dafny do) and by solver recursion (`define-fun-rec`); the host tries
|
|
55
|
+
them in turn, and the evidence records which one proved the law and every
|
|
56
|
+
attempt.
|
|
57
|
+
- The laws about a function are checked together: completeness, overlap,
|
|
58
|
+
conflict and vacuity, on by default. A `laws for f are ... end laws` block
|
|
59
|
+
states claims (`complete over`, `without overlap`, `without conflict`) and
|
|
60
|
+
excuses checks with a reason (`partial`, `overlap allowed`,
|
|
61
|
+
`conflict allowed until`, `vacuity allowed for`), until a project version
|
|
62
|
+
or a UTC date-time. An excused failure is `exempted`, a new status weaker
|
|
63
|
+
than `assumed`, and keeps its counterexample; an expired exemption is
|
|
64
|
+
`refuted` and fails the build. The `exhaustive` layer decides finite
|
|
65
|
+
domains; `lawspec prove` sends the rest to Z3, and the evaluator confirms
|
|
66
|
+
every input Z3 gives. `lawspec.json` gains `projectVersion`.
|
|
67
|
+
- A new evidence status, `refuted`: a law a confirmed counterexample shows
|
|
68
|
+
false (the compiler's exhaustive check, or a Z3 model the reference
|
|
69
|
+
evaluator confirms). The build still fails with a `refuted` diagnostic, and
|
|
70
|
+
`lawspec evidence` lists the law under `REFUTED` and exits with status 1.
|
|
71
|
+
- Z3 proof tasks cover data (`lawspec-smtlib-v2`): enums, records,
|
|
72
|
+
alternatives, structural records, `Maybe`, `List` and `Either` become SMT
|
|
73
|
+
datatypes whose field refinements are part of their well-formedness. The
|
|
74
|
+
refund policy and order lifecycle laws in `examples/rc1` are proved, and a
|
|
75
|
+
counterexample over data is read back and confirmed by the evaluator.
|
|
76
|
+
- `lawspec prove` validates counterexamples. When Z3 finds a law's negation
|
|
77
|
+
satisfiable, it gives values for the law's outer inputs, and the compiler
|
|
78
|
+
re-checks the law at them with its reference evaluator. A confirmed law is
|
|
79
|
+
`refuted` with its inputs, and `prove` exits with status 1. Unconfirmed
|
|
80
|
+
values are a `proof-translation` diagnostic, never a refutation.
|
|
81
|
+
- `lawspec-smtlib-v1` proof tasks are frozen byte for byte, checked against
|
|
82
|
+
a corpus of every current task. The compiler can name a later encoding,
|
|
83
|
+
`lawspec-smtlib-v2`, for tasks that need new features.
|
|
84
|
+
- A definition may rely on an ability operation's refined result. The
|
|
85
|
+
generated code checks each such result where the definition performs the
|
|
86
|
+
operation, and stops the definition if a handler broke the type.
|
|
87
|
+
`lawspec evidence` reports each check as `runtime-checked`.
|
|
88
|
+
### Changed
|
|
89
|
+
|
|
90
|
+
- **Breaking:** `Maybe`'s values are now `Present x` and `Absent`. They were
|
|
91
|
+
`Just x` and `Nothing`. The type is still `Maybe a`. The old names are not
|
|
92
|
+
aliases: a source that uses them is refused, and the error names the new
|
|
93
|
+
constructor. Generated code follows the new names wherever LawSpec's
|
|
94
|
+
constructors appear: data tags (`Maybe::Present`, `Maybe::Absent`), the
|
|
95
|
+
Python, JavaScript, TypeScript and JVM `Present` and `Absent` classes, the
|
|
96
|
+
Go `LawSpecPresent` and `LawSpecAbsent` helpers, the C# `Maybe.Absent`
|
|
97
|
+
helper, the typed Java `Maybe.present`, `absent` and `isPresent`, the
|
|
98
|
+
Erlang and Elixir `present` and `absent` atoms, rendered values, the
|
|
99
|
+
editor grammar and the npm names. Native mappings are unchanged: Rust,
|
|
100
|
+
Swift, Scala, F# and Gleam keep their options, and Haskell keeps `Maybe`.
|
|
101
|
+
|
|
102
|
+
### Fixed
|
|
103
|
+
|
|
104
|
+
- Proof execution discards imported settlement answers, checks the complete
|
|
105
|
+
solver protocol for law-set and model tasks, and records model solver
|
|
106
|
+
identities and raw output. An unavailable model solver stays explicit.
|
|
107
|
+
- Model induction keeps an unencodable command obligation incomplete rather
|
|
108
|
+
than proving only the remaining steps. Reachability counts obey the search
|
|
109
|
+
bound, and unfinished history searches cannot refute a law. Open history
|
|
110
|
+
deadlines stay pending, late responses fail, and backwards times are refused.
|
|
111
|
+
- Go harness statistics belong to each test run, so a law's boundary tests no
|
|
112
|
+
longer reset its property test's counts while they run in parallel. Python,
|
|
113
|
+
JavaScript, Rust, Haskell and Java (with Kotlin, Scala, Groovy and Clojure)
|
|
114
|
+
keep statistics per run too.
|
|
115
|
+
- The workflows example's `|an all group's checks run at the same time|` law
|
|
116
|
+
checks that the two slow checks overlapped in time, on every target,
|
|
117
|
+
instead of timing the call against 550 ms, which failed on a loaded machine.
|
|
118
|
+
|
|
9
119
|
## [0.27.0] - 2026-10-21
|
|
10
120
|
|
|
11
121
|
### Added
|
|
@@ -1805,7 +1915,8 @@ A maintenance release. The language, generated code and API are unchanged from
|
|
|
1805
1915
|
machine-sized bindings reject an architecture mismatch. Rust adapters take
|
|
1806
1916
|
owned values.
|
|
1807
1917
|
|
|
1808
|
-
[Unreleased]: https://github.com/brain-fuel/lawspec/compare/v0.
|
|
1918
|
+
[Unreleased]: https://github.com/brain-fuel/lawspec/compare/v0.28.0...HEAD
|
|
1919
|
+
[0.28.0]: https://github.com/brain-fuel/lawspec/compare/v0.27.0...v0.28.0
|
|
1809
1920
|
[0.27.0]: https://github.com/brain-fuel/lawspec/compare/v0.26.0...v0.27.0
|
|
1810
1921
|
[0.26.0]: https://github.com/brain-fuel/lawspec/compare/v0.25.0...v0.26.0
|
|
1811
1922
|
[0.25.0]: https://github.com/brain-fuel/lawspec/compare/v0.24.0...v0.25.0
|
package/bin/lawspec.mjs
CHANGED
|
@@ -26,7 +26,7 @@ import {
|
|
|
26
26
|
safePath,
|
|
27
27
|
collectSources,
|
|
28
28
|
} from "../files.mjs";
|
|
29
|
-
const VERSION = "0.
|
|
29
|
+
const VERSION = "0.28.0";
|
|
30
30
|
const args = process.argv.slice(2);
|
|
31
31
|
const verb = args.shift();
|
|
32
32
|
const options = {};
|
|
@@ -75,6 +75,13 @@ function testCommand(target, root) {
|
|
|
75
75
|
command = `npm exec -- tsc -p tsconfig.json && node --test ${shellQuote("dist/" + testDir)}/*.test.js`;
|
|
76
76
|
return `(cd ${shellQuote(root)} && ${command})`;
|
|
77
77
|
}
|
|
78
|
+
// A refuted law fails the command, but evidence still lists it: the
|
|
79
|
+
// diagnostics then only say which laws are refuted.
|
|
80
|
+
function refutedOnly(result) {
|
|
81
|
+
return result.diagnostics?.length && result.diagnostics.every((d) => d.code === "refuted") && result.evidence
|
|
82
|
+
? { ...result, refuted: result.diagnostics, diagnostics: [] } : result;
|
|
83
|
+
}
|
|
84
|
+
|
|
78
85
|
function diagnostics(result) {
|
|
79
86
|
if (result.diagnostics?.length)
|
|
80
87
|
throw Object.assign(
|
|
@@ -864,6 +871,10 @@ async function main() {
|
|
|
864
871
|
...(await packageInput(config, configRoot)),
|
|
865
872
|
generation: config.generation,
|
|
866
873
|
machineBits: options.machineBits ?? config.machineBits ?? 64,
|
|
874
|
+
// What a law-set exemption's until is compared with: the project's
|
|
875
|
+
// version and the current UTC time.
|
|
876
|
+
...(typeof config.projectVersion === "string" ? { projectVersion: config.projectVersion } : {}),
|
|
877
|
+
now: new Date().toISOString(),
|
|
867
878
|
};
|
|
868
879
|
const compiler = await createCompiler();
|
|
869
880
|
if (verb === "prove") {
|
|
@@ -875,11 +886,13 @@ async function main() {
|
|
|
875
886
|
.filter(([name]) => options[name] !== undefined).map(([name,key]) => [key,Number(options[name])])),
|
|
876
887
|
}));
|
|
877
888
|
output(options.json ? result : result.solverEvidence.length
|
|
878
|
-
? result.solverEvidence.map(row => `${row.declaration}: ${row.status} (${row.outcome}). ${row.reason}`).join("\n")
|
|
889
|
+
? result.solverEvidence.map(row => `${row.declaration}${row.kind === "analysis" ? ` ${row.stage}` : ""}: ${row.status} (${row.outcome}). ${row.reason}`).join("\n")
|
|
879
890
|
: (input.verification?.layers.includes("proof")
|
|
880
891
|
? "No source law obligations are available. No solver was invoked."
|
|
881
892
|
: "No proof layer selected. Intrinsic definition checks passed; no solver was invoked."));
|
|
882
|
-
|
|
893
|
+
// A refuted law is a definite failure; anything else not proved is incomplete.
|
|
894
|
+
if (result.solverEvidence.some(row => row.status === "refuted")) process.exitCode = 1;
|
|
895
|
+
else if (result.solverEvidence.some(row => !["proved", "exempted"].includes(row.status))) process.exitCode = 2;
|
|
883
896
|
return;
|
|
884
897
|
}
|
|
885
898
|
// Each obligation reports how it is discharged, strongest first.
|
|
@@ -891,11 +904,17 @@ async function main() {
|
|
|
891
904
|
["runtime-checked", "RUNTIME CHECKED"],
|
|
892
905
|
["default-handler", "DEFAULT HANDLER"],
|
|
893
906
|
["assumed", "ASSUMED / EXTERNAL"],
|
|
907
|
+
// A law-set check a laws-for block excuses, with its reason and expiry.
|
|
908
|
+
["exempted", "EXEMPTED"],
|
|
909
|
+
// A law a confirmed counterexample shows false; the build fails.
|
|
910
|
+
["refuted", "REFUTED"],
|
|
894
911
|
// The harness plane: a law it marks as known to fail, a law whose last
|
|
895
912
|
// run was flaky, and a law whose tests it skips.
|
|
896
913
|
["known-failing", "KNOWN FAILING"],
|
|
897
914
|
["flaky", "FLAKY"],
|
|
898
915
|
["skipped", "SKIPPED"],
|
|
916
|
+
// A law about an open history that the entries so far do not decide.
|
|
917
|
+
["pending", "PENDING"],
|
|
899
918
|
["planned", "PLANNED"],
|
|
900
919
|
["not-verified", "NOT VERIFIED"],
|
|
901
920
|
["incomplete", "INCOMPLETE"],
|
|
@@ -904,9 +923,9 @@ async function main() {
|
|
|
904
923
|
const evidenceSummary = (evidence) => {
|
|
905
924
|
if (!evidence.length) return "";
|
|
906
925
|
const count = (status) => evidence.filter((item) => item.status === status).length;
|
|
907
|
-
//
|
|
908
|
-
//
|
|
909
|
-
const harnessFrom = statuses.findIndex(([status]) => status === "
|
|
926
|
+
// Exempted, refuted and the harness statuses (after assumed) are counted only when
|
|
927
|
+
// some obligation has them.
|
|
928
|
+
const harnessFrom = statuses.findIndex(([status]) => status === "exempted");
|
|
910
929
|
const shown = statuses.filter(([status], i) => i < harnessFrom || count(status));
|
|
911
930
|
return ` Evidence: ${shown.map(([status, label]) => `${count(status)} ${label.toLowerCase()}`).join(", ")}.`;
|
|
912
931
|
};
|
|
@@ -937,8 +956,9 @@ async function main() {
|
|
|
937
956
|
const named = await readAttestation(config);
|
|
938
957
|
const { runs, attestations, outcomes } = await lastRuns();
|
|
939
958
|
const recorded = named && typeof named.run?.id === "string" ? outcomes.get(named.run.id) : undefined;
|
|
940
|
-
const result = diagnostics(await compiler.check({ ...input,
|
|
941
|
-
...(named ? { attestation: named, ...(recorded ? { attestedOutcomes: recorded } : {}) } : {}) }));
|
|
959
|
+
const result = diagnostics(refutedOnly(await compiler.check({ ...input,
|
|
960
|
+
...(named ? { attestation: named, ...(recorded ? { attestedOutcomes: recorded } : {}) } : {}) })));
|
|
961
|
+
if (result.refuted) process.exitCode = 1;
|
|
942
962
|
let evidence = attachNativeEvidence(result.evidence,await readNativeObservations({compiler,input,selected,roots,
|
|
943
963
|
configRoot,build:await buildDigest(),evidence:result.evidence,attestation:named}));
|
|
944
964
|
const environments = named ? [result.attestation] : [];
|