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.
Files changed (40) hide show
  1. package/CHANGELOG.md +112 -1
  2. package/bin/lawspec.mjs +28 -8
  3. package/build.json +137 -119
  4. package/builtin-data-names.mjs +4 -4
  5. package/core.wasm +2 -2
  6. package/core_jsffi.js +5 -5
  7. package/examples/native-payments/elixir/lib/payments_domain.ex +1 -1
  8. package/examples/native-payments/erlang/src/payments_domain.erl +1 -1
  9. package/examples/rc1/bit-codec.lawspec +6 -6
  10. package/examples/rc1/native-payments.lawspec +6 -6
  11. package/examples/rc1/nesting/rrr.lawspec +2 -2
  12. package/examples/rc1/nesting/rru.lawspec +4 -4
  13. package/examples/rc1/nesting/rur.lawspec +4 -4
  14. package/examples/rc1/nesting/ruu.lawspec +5 -5
  15. package/examples/rc1/nesting/urr.lawspec +4 -4
  16. package/examples/rc1/nesting/uru.lawspec +5 -5
  17. package/examples/rc1/nesting/uur.lawspec +5 -5
  18. package/examples/rc1/nesting/uuu.lawspec +6 -6
  19. package/examples/rc1/recursive-records.lawspec +5 -5
  20. package/examples/rc1/refund-policy.lawspec +4 -0
  21. package/examples/specs/builtins.lawspec +2 -2
  22. package/examples/specs/collections.lawspec +8 -8
  23. package/examples/specs/composition.lawspec +10 -10
  24. package/examples/specs/contracts.lawspec +2 -2
  25. package/examples/specs/crypto.lawspec +2 -2
  26. package/examples/specs/flow_stack.lawspec +4 -4
  27. package/examples/specs/generation.lawspec +2 -2
  28. package/examples/specs/list_contracts.lawspec +3 -3
  29. package/examples/specs/lists.lawspec +6 -6
  30. package/examples/specs/matching.lawspec +8 -8
  31. package/examples/specs/payments.lawspec +5 -5
  32. package/examples/specs/records.lawspec +4 -4
  33. package/examples/specs/refinements.lawspec +4 -0
  34. package/examples/specs/resources.lawspec +5 -5
  35. package/examples/specs/sequences.lawspec +1 -1
  36. package/examples/specs/sum_refinements.lawspec +11 -11
  37. package/index.d.ts +154 -3
  38. package/package.json +1 -1
  39. package/proof.d.ts +57 -12
  40. 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.27.0...HEAD
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.27.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
- if (result.solverEvidence.some(row => row.status !== "proved")) process.exitCode = 2;
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
- // The harness statuses (after assumed) are counted only when a harness
908
- // gives some.
909
- const harnessFrom = statuses.findIndex(([status]) => status === "known-failing");
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] : [];