lawspec 0.20.0 → 0.21.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 +982 -726
- package/README.md +4 -4
- package/bin/lawspec.mjs +260 -32
- package/build.json +362 -170
- package/core.wasm +0 -0
- package/core_jsffi.js +2 -2
- package/examples/specs/abilities.lawspec +103 -0
- package/examples/specs/ability_imports.lawspec +107 -0
- package/examples/specs/builtins.lawspec +121 -0
- package/examples/specs/crypto.lawspec +51 -0
- package/examples/specs/distribution.lawspec +29 -0
- package/examples/specs/failures.lawspec +96 -0
- package/examples/specs/handler_bindings.lawspec +65 -0
- package/examples/specs/harness.lawspec +75 -0
- package/examples/specs/harness_testing.lawspec +45 -0
- package/examples/specs/matchers.lawspec +112 -0
- package/examples/specs/resources.lawspec +116 -0
- package/examples/specs/scheduling_order.lawspec +18 -0
- package/examples/specs/scheduling_overlap.lawspec +14 -0
- package/examples/specs/tables.lawspec +64 -0
- package/index.d.ts +2 -0
- package/package.json +2 -1
- package/templates.mjs +14 -14
- package/test-command.mjs +165 -30
package/CHANGELOG.md
CHANGED
|
@@ -1,33 +1,345 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
All notable changes to LawSpec are documented in this file. The format is based
|
|
4
|
+
on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and LawSpec adheres
|
|
5
|
+
to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
|
+
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
## [0.21.0] - 2026-10-07
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- Existing features are abilities. `async f ::` is `f :: ... uses Async`
|
|
14
|
+
(both spellings mean the same declaration); workflow policies are handler
|
|
15
|
+
transformers over `Async`, `Clock` and `Fail`; a protocol is `Session P`,
|
|
16
|
+
a mailbox `Mailbox T`, an actor a `Process` with a `State` handler, a
|
|
17
|
+
supervisor a `Fail` handler that restarts, a model a stateful spec
|
|
18
|
+
handler checked through `abstract`, a scenario a program under a
|
|
19
|
+
`Scheduler` handler, and distribution the `Network` ability whose
|
|
20
|
+
transports are handlers. The syntax is unchanged; `lawspec check --json`
|
|
21
|
+
lists each unit's `abilityRows`, and the new page "Existing features as
|
|
22
|
+
abilities" shows each mapping.
|
|
23
|
+
- The network is secure by default on every target: each node has an
|
|
24
|
+
ML-DSA-65 identity, the first frame between two nodes waits for a signed
|
|
25
|
+
ML-KEM-768 handshake, and frames cross sealed with AES-256-GCM. The record
|
|
26
|
+
format is the same on every target, and each checks the same handshake
|
|
27
|
+
vector. `nativeBindings.network` in `lawspec.json` binds a node identity
|
|
28
|
+
and trusted peers (written to `lawspec-network.conf`). An in-memory
|
|
29
|
+
transport without the handshake exists for tests only; no setting turns
|
|
30
|
+
security off. A program that makes nodes imports `lawspec.network`, which
|
|
31
|
+
writes the secure handler's module beside the runtime; programs without
|
|
32
|
+
it, or without `lawspec.crypto`, no longer depend on any crypto library,
|
|
33
|
+
and `lawspec init` scaffolds projects without them. Scenarios' network
|
|
34
|
+
runs use the in-memory transport made for tests. (Rust and Haskell call
|
|
35
|
+
`lawspec_network::install()` / `LawSpecNetwork.install` before making
|
|
36
|
+
nodes; the generated tests do.)
|
|
37
|
+
- Temporal propositions: `eventually within 2 s, P`, `always within 500 ms,
|
|
38
|
+
P` and `never within d, P`, over the `Clock`; under `using virtual clock`
|
|
39
|
+
they are deterministic and checked at compile time.
|
|
40
|
+
- Performance budgets: `expect f x takes at most 5 ms`, or `e takes at most
|
|
41
|
+
d` as a law's claim, timed on the real clock, with the new evidence status
|
|
42
|
+
`measured`.
|
|
43
|
+
- Typed mailboxes have `receive_within` / `receiveWithin`: the next message,
|
|
44
|
+
or nothing when none arrives in time.
|
|
45
|
+
- The `Async` default handler also starts tasks, waits for them and runs
|
|
46
|
+
several side by side; workflows' `all` groups run through it.
|
|
47
|
+
- Built-in abilities. `import lawspec.time`, `lawspec.randomness`,
|
|
48
|
+
`lawspec.crypto`, `lawspec.host`, `lawspec.logging` or `lawspec.concurrent`
|
|
49
|
+
adds the unit and its abilities: `Clock`; `Random` and `SecureRandom`;
|
|
50
|
+
`Hash`, `KeyExchange`, `Signature` and `Aead`; `FileSystem`, `Environment`
|
|
51
|
+
and `Ports`; `Log` and `Trace`; `Async`. Each has laws, and a default
|
|
52
|
+
handler on every target, generated into the unit's module and reported in
|
|
53
|
+
evidence with the new status `default-handler` (`DEFAULT HANDLER`).
|
|
54
|
+
`handlers` in `lawspec.json` binds another, and the ability's laws then
|
|
55
|
+
check it.
|
|
56
|
+
- `Instant`, microseconds since 1970: `t + d`, `t - d`, `b - a` (a
|
|
57
|
+
`Duration`) and comparisons, saturating rather than failing. `Clock` has
|
|
58
|
+
`now` and `sleep`, and its laws say time does not go back and sleeping
|
|
59
|
+
lets the time pass. `using virtual clock` runs a law under a clock that
|
|
60
|
+
moves only when told to; `advance d` lets `d` pass.
|
|
61
|
+
- `Random` is reproducible: the same seed gives the same draws on all eight
|
|
62
|
+
targets. `using seeded random n` starts it at `n`; the default handler
|
|
63
|
+
starts at the run's seed. `SecureRandom` is the operating system's
|
|
64
|
+
generator. They are separate abilities: seeded random where SecureRandom
|
|
65
|
+
is needed is a compile error, SecureRandom has no spec handlers, and the
|
|
66
|
+
native interfaces differ, so the typed targets reject the mix too.
|
|
67
|
+
- Cryptography is post-quantum by default: ML-KEM-768 (FIPS 203) key
|
|
68
|
+
exchange, ML-DSA-65 (FIPS 204) signatures, SHA3-256 and SHAKE256 (FIPS
|
|
69
|
+
202), and AES-256-GCM authenticated encryption, with SLH-DSA-SHAKE-128f
|
|
70
|
+
(FIPS 205) as an alternative Signature handler. Keys, ciphertexts and
|
|
71
|
+
signatures are opaque values whose bytes are the standards' encodings.
|
|
72
|
+
Their laws: decapsulating gives the encapsulated secret, a signature
|
|
73
|
+
verifies exactly for its message and its signer's key, and unsealing fails
|
|
74
|
+
for another key or other associated data.
|
|
75
|
+
- A program that imports `lawspec.crypto` gets a test of the default
|
|
76
|
+
handlers against NIST's ACVP and CAVP vectors, on every target.
|
|
77
|
+
- New acceptance suites `builtins` and `crypto`, on all eight targets, with
|
|
78
|
+
mutants: a clock that goes back, a seeded Random used as SecureRandom (a
|
|
79
|
+
compile error in the typed targets), a log written twice, a signature
|
|
80
|
+
handler that verifies a tampered message, and a key exchange that returns
|
|
81
|
+
another secret.
|
|
82
|
+
- Abilities. `ability Gateway is authorize :: Card -> Payment ... laws ... end`
|
|
83
|
+
names a dependency's operations and the laws every handler of it keeps.
|
|
84
|
+
`uses Gateway, Clock` after a signature says what it uses; a native adapter
|
|
85
|
+
gets one handler per ability before its arguments. A checked definition may
|
|
86
|
+
use abilities, and its ability row is inferred; a definition that lists its
|
|
87
|
+
abilities must list at least those.
|
|
88
|
+
- Handlers. `handler fakeGateway for Gateway is authorize c is ... end ... end`
|
|
89
|
+
is a spec handler; each clause is a checked definition. `with state s :: S
|
|
90
|
+
start e` keeps a state, updated with `~s := e;`. Each ability's native
|
|
91
|
+
production handler is written by hand (`GatewayHandler`), or bound under
|
|
92
|
+
`handlers` in `lawspec.json`.
|
|
93
|
+
- A law holds for every lawful handler. `using h` names a handler only when
|
|
94
|
+
it is part of the claim; otherwise the law runs under each lawful handler in
|
|
95
|
+
turn, one law per choice. `using recording Gateway` records calls, which a
|
|
96
|
+
law counts with `calls of capture` and `calls of capture with (cents)`.
|
|
97
|
+
- Each ability law is one obligation per handler. For a spec handler without
|
|
98
|
+
state the compiler proves it, or checks every case of a finite domain, so a
|
|
99
|
+
handler that breaks it is a compile error; native handlers are
|
|
100
|
+
property-tested.
|
|
101
|
+
- `fails with E` is short for `uses Fail E`. `raise e` aborts with a failure,
|
|
102
|
+
and `prelude.attempt e` in a law gives `Right` of the value or `Left` of the
|
|
103
|
+
failure.
|
|
104
|
+
- Core has `Perform`, `Handle` and `Calls`. Every target passes handlers in
|
|
105
|
+
the context it gives every definition (evidence passing), and generates a
|
|
106
|
+
native interface per ability: a Python `Protocol`, a TypeScript interface, a
|
|
107
|
+
Go interface, a Java or Kotlin interface, a Rust trait, a Haskell record of
|
|
108
|
+
`IO` operations; with spec handler and recording classes beside it.
|
|
109
|
+
- Abilities cross units. `import` brings a unit's abilities and handlers;
|
|
110
|
+
imported definitions may use abilities, and the declaring unit keeps the
|
|
111
|
+
native interface, production handler and recording.
|
|
112
|
+
- Effects in order: `a; b` and `let x = e in body` in definitions and laws.
|
|
113
|
+
An operation that gives `Unit` is called for its effect.
|
|
114
|
+
- `handle e with h end` installs a spec handler around part of a definition,
|
|
115
|
+
which then does not use its ability. A handler's clauses may use other
|
|
116
|
+
abilities; a law under that handler gets handlers for them too.
|
|
117
|
+
- A parameterized ability may be used at several types in one unit (`Store
|
|
118
|
+
Int32`, `Store Text`), each with its own interface (`StoreInt32`).
|
|
119
|
+
- An operation's type may be refined; every handler owes its result's
|
|
120
|
+
refinement as a law.
|
|
121
|
+
- Native adapters fail with the runtime's `Fail` on every target (`raise
|
|
122
|
+
ls.Fail(v)`, `throw new ls.Fail(v)`, `panic(LawSpecFail{Value: v})`,
|
|
123
|
+
`LawSpecRuntime.Fail`, `ls::fail`, `LS.Fail`), and `failures` in
|
|
124
|
+
`lawspec.json` maps the application's own exceptions to failure
|
|
125
|
+
constructors.
|
|
126
|
+
- The compiler runs spec handlers with state over a finite domain, so a law
|
|
127
|
+
they break is a compile error.
|
|
128
|
+
- `lawspec explain` shows a law's handlers and the ability rows of what it
|
|
129
|
+
calls.
|
|
130
|
+
- A bound production handler speaks the bound native types: through the
|
|
131
|
+
handler schema in Python and JavaScript, and an `<Ability>Bound` wrapper in
|
|
132
|
+
the typed targets. A bound adapter gets its handlers too.
|
|
133
|
+
- New acceptance suite `abilities`, with mutants: an adapter that calls its
|
|
134
|
+
dependency twice, native handlers that break an ability law or a refined
|
|
135
|
+
result, and an adapter that fails with the wrong failure. It now covers two
|
|
136
|
+
units. New suite `handlerbindings`: bound handlers, bound types and mapped
|
|
137
|
+
exceptions on all eight targets.
|
|
138
|
+
- Matchers: typed predicates that read like sentences. `xs has same items
|
|
139
|
+
as ys`, `xs contains x` (an item, or text inside text), `xs contains all of
|
|
140
|
+
ys`, `xs is subset of ys`, `x is within 0.001 of y`, `t starts with "a"`,
|
|
141
|
+
`t ends with "z"`, `t matches regex "[a-z]+"` and `v matches Shipped _ _`.
|
|
142
|
+
The list matchers are checked definitions of a built-in unit,
|
|
143
|
+
`lawspec.matchers`.
|
|
144
|
+
- `Regex` and `regex "..."`. Every regex literal is checked at compile time
|
|
145
|
+
against a portable dialect, the part of RE2 and ECMAScript that means the
|
|
146
|
+
same in both, and matches a whole text. Each runtime has its own matcher, so
|
|
147
|
+
no target needs a regex library.
|
|
148
|
+
- Typed failures in laws: `expect charge o fails with Declined _`, with
|
|
149
|
+
`message contains "..."` for a failure's message field. `expect e` takes
|
|
150
|
+
any `Bool`.
|
|
151
|
+
- Tables: `table (a, b, expected) is row 1, 2, 3 ... expect f a b = expected
|
|
152
|
+
end`. Each row is its own example.
|
|
153
|
+
- Examples fenced with `example` in a law's description are examples of the
|
|
154
|
+
law, named after the description.
|
|
155
|
+
- Recorded values: `expect f x = recorded "name"` compares with
|
|
156
|
+
`recorded/<unit>/<name>`, by the portable rendering every target shares. A
|
|
157
|
+
missing or changed recording fails; `lawspec test --update-recorded`
|
|
158
|
+
records again.
|
|
159
|
+
- Resources: `resource Database is acquire ... release ... reset ... end`,
|
|
160
|
+
taken by a law with `law ... for db :: Database is`. Each case acquires
|
|
161
|
+
them first and releases them after, even when it fails. Built in:
|
|
162
|
+
`TemporaryDirectory`, `TemporaryFile`, `FreePort` and `SavedEnvironment`.
|
|
163
|
+
- A failing comparison names where a list or data value first differs, with
|
|
164
|
+
both values in the portable rendering.
|
|
165
|
+
- New acceptance suites `matchers`, `failures`, `tables` and `resources`, with
|
|
166
|
+
mutants: a reordered list that fails `=` but passes `has same items as`, a
|
|
167
|
+
resource never released, a failure of the wrong constructor, and a stale
|
|
168
|
+
recording.
|
|
169
|
+
- Harness units: `harness shop.testing for shop is ... end`, in its own file
|
|
170
|
+
or after a unit's members, says how a unit's laws are tested and can never
|
|
171
|
+
change what they mean. It may not declare laws, definitions, abilities,
|
|
172
|
+
handlers or types, refers only to its unit's laws, handlers and resources,
|
|
173
|
+
and its expressions call checked definitions only.
|
|
174
|
+
- Strategies: `strategy orders :: Order is frequency 9 small, 1 bulk end`,
|
|
175
|
+
with `any`, `one of`, `such that p at most n discards` and `bind x :: T
|
|
176
|
+
from g in g'`, used with `for law \`x\` use orders for o`. A strategy's
|
|
177
|
+
type must be the input's, and every value it draws is checked against the
|
|
178
|
+
input's refinements.
|
|
179
|
+
- `test with fakeGateway, native` narrows the lawful handlers a law runs
|
|
180
|
+
against; a variant it leaves out stays an obligation, reported skipped.
|
|
181
|
+
- Adequacy: `cover 10% "label" when p` (an unmet cover fails the run),
|
|
182
|
+
`classify p as "label"`, `label e` and `target maximize e`, with
|
|
183
|
+
statistics printed and kept by `lawspec test`.
|
|
184
|
+
- Run metadata per unit, group (`for laws`) or law: `tags`, `skip`,
|
|
185
|
+
`known failing` (a known-failing law that passes fails the run), `timeout`,
|
|
186
|
+
`repeat`, `retry flaky`, `order random` and `parallel`.
|
|
187
|
+
- `share R per group | unit | run`, only for a resource that declares
|
|
188
|
+
`reset`; `benchmark \`name\` is e end`, measured and never asserted.
|
|
189
|
+
- All eight targets, through each one's property-testing library.
|
|
190
|
+
- Evidence has three harness statuses, `known-failing`, `flaky` and `skipped`.
|
|
191
|
+
`lawspec evidence` shows a `HARNESS` section after the obligations: each
|
|
192
|
+
law's harness and its last run's adequacy.
|
|
193
|
+
- `lawspec test --tag a --exclude-tag b` selects laws by harness tags;
|
|
194
|
+
`--report junit=path` writes one JUnit report merged across targets;
|
|
195
|
+
`--coverage` measures coverage with coverage.py, c8, `go test -cover`,
|
|
196
|
+
JaCoCo, Kover, cargo-llvm-cov or hpc, and says how to install a missing one.
|
|
197
|
+
A failing law is kept with its seed in `.lawspec/failures` and replayed
|
|
198
|
+
first; Hypothesis and proptest keep their counterexamples there too.
|
|
199
|
+
- New acceptance suite `harness`, with mutants, among them spec mutants (an
|
|
200
|
+
acceptance suite may now edit its specs): an unmet cover, a strategy drawing
|
|
201
|
+
outside the input's refinement, a harness declaring a law, sharing a
|
|
202
|
+
resource without `reset`, and a known-failing law that passes.
|
|
203
|
+
- A shared resource is shared at run time: `share R per group | unit | run`
|
|
204
|
+
acquires R once per scope, resets it before every later case, lets one case
|
|
205
|
+
hold it at a time, and releases it when the test process ends, on all eight
|
|
206
|
+
targets. The `resources` suite shares a pool that may be opened only once
|
|
207
|
+
per process, with mutants for a pool never drained and for a harness that
|
|
208
|
+
does not share it.
|
|
209
|
+
- `expect ... fails with` checks native adapters' failures too: synchronous
|
|
210
|
+
and async adapters raise the runtime's `Fail` on every target, and a
|
|
211
|
+
constructor mapped from an application's exception under `failures` in
|
|
212
|
+
`lawspec.json` matches with its message.
|
|
213
|
+
- A benchmark may call what uses abilities; it runs under their production
|
|
214
|
+
handlers. `lawspec test --benchmarks` runs the harness's benchmarks after the
|
|
215
|
+
laws.
|
|
216
|
+
- A strategy's type may be an inline refinement, `strategy small :: (o ::
|
|
217
|
+
Order where itemsOf o <= 3) is ... end`, whose values are kept like `such
|
|
218
|
+
that`. Harness expressions and strategies may name a unit's imports through
|
|
219
|
+
their aliases.
|
|
220
|
+
- `target maximize` steers on every target: where the property library has
|
|
221
|
+
no targeted search, LawSpec climbs after the property, moving the
|
|
222
|
+
best-scoring case's integers while the score rises.
|
|
223
|
+
- LawSpec owns a unit's scheduling through a small harness driver in each
|
|
224
|
+
runtime; the test framework hosts and reports. `order random` is seeded by
|
|
225
|
+
the run's seed, printed, and replayable on all eight targets; `parallel`
|
|
226
|
+
runs a unit's tests at the same time on all eight (Python on a thread pool
|
|
227
|
+
when pytest-xdist is absent, Java through a generated
|
|
228
|
+
`junit-platform.properties`, Haskell on the threaded runtime), and each
|
|
229
|
+
runtime records the parallelism it achieved, which `lawspec test` prints.
|
|
230
|
+
The test manifest carries whether a law's unit is parallel, and its
|
|
231
|
+
benchmarks.
|
|
232
|
+
- `resource T is concurrent`: a resource cases cannot interfere through. A
|
|
233
|
+
harness may share a resource under `parallel` only if it is concurrent.
|
|
234
|
+
- New acceptance suite `scheduling`: on every target, the same seed gives
|
|
235
|
+
the same order, other seeds other orders, and a `parallel` unit's laws
|
|
236
|
+
overlap.
|
|
237
|
+
|
|
238
|
+
### Changed
|
|
239
|
+
|
|
240
|
+
- Workflow time is the `Clock` ability's: a law that installs a clock (such
|
|
241
|
+
as `using virtual clock`) runs its workflows on it. On a virtual clock,
|
|
242
|
+
timeouts and hedges count virtual time, so generated workflow tests now
|
|
243
|
+
run with them on, deterministically; before, they were off because they
|
|
244
|
+
used real time.
|
|
245
|
+
- Channel-end `take` tokens are 32 bytes from the operating system's secure
|
|
246
|
+
generator on every target (Haskell's were clock-based).
|
|
247
|
+
- Remote definitions are named by a SHA3-256 content hash that names its
|
|
248
|
+
algorithm: `sha3-256:` then 64 hexadecimal digits.
|
|
249
|
+
- A generated project that imports `lawspec.crypto` or `lawspec.network`
|
|
250
|
+
depends on the default handlers' libraries (in Haskell and Rust,
|
|
251
|
+
`lawspec.randomness` does too, for its secure generator):
|
|
252
|
+
`cryptography` (Python), `@noble/post-quantum` (JavaScript, TypeScript),
|
|
253
|
+
`circl` and Go 1.25 (Go), Bouncy Castle (Java, Kotlin), `crypton`, `mlkem`
|
|
254
|
+
and `mldsa` (Haskell), and RustCrypto's `ml-kem`, `ml-dsa`, `slh-dsa`,
|
|
255
|
+
`sha3`, `shake` and `aes-gcm` (Rust).
|
|
256
|
+
- In Go, a program's ability that shares a name with another unit's (such
|
|
257
|
+
as a built-in `Log`) is named after its unit (`ExampleShopLog`), since
|
|
258
|
+
every Go package holds every ability.
|
|
259
|
+
- A Haskell project depends on `directory`. A Go test file imports rapid only
|
|
260
|
+
when a law draws its inputs with it.
|
|
261
|
+
- Generated tests are named after law labels on every target
|
|
262
|
+
(`test_charges_once__property`, `TestChargesOnce_Property`,
|
|
263
|
+
`lawChargesOnce_property`, `law_charges_once`), unique within a unit. The
|
|
264
|
+
test manifest carries each law's name, tags, skip and known failing.
|
|
265
|
+
- On Java and Kotlin, an ability or handler whose class would be named like
|
|
266
|
+
the class holding its unit's abilities is a compile error that says what to
|
|
267
|
+
rename.
|
|
268
|
+
- The failure database keeps a failing case's inputs in LawSpec's wire
|
|
269
|
+
encoding (`.lawspec/failures/<target>/inputs`), on every target, and the
|
|
270
|
+
law's tests replay them before any new case.
|
|
271
|
+
- Built-in resources acquire and release through `lawspec.host`'s
|
|
272
|
+
abilities, under their production handlers: `FileSystem` gains
|
|
273
|
+
`temporaryDirectory` and `temporaryFile`, `Environment` gains
|
|
274
|
+
`environmentSnapshot` and `restoreEnvironment`, and `FreePort` uses
|
|
275
|
+
`freePort`. A program that names a built-in resource gets `lawspec.host`.
|
|
276
|
+
|
|
277
|
+
### Fixed
|
|
278
|
+
|
|
279
|
+
- Java ability interfaces no longer end a wrapped parameter list with a
|
|
280
|
+
comma; a Rust handler parameter that is a keyword is a raw identifier; a
|
|
281
|
+
Rust ability operation's result is checked against its type.
|
|
282
|
+
- A law that hands a resource it takes to a definition that releases it,
|
|
283
|
+
through any chain of checked definitions or spec handler clauses, is now
|
|
284
|
+
an error, like a law that calls the release itself. The check is a
|
|
285
|
+
conservative data-flow analysis over the whole program.
|
|
286
|
+
- `any` in a strategy of a refined type aims at the refinement, as a law
|
|
287
|
+
input's generator does: the refinement's constant integer bounds narrow
|
|
288
|
+
the range it draws from, instead of drawing the whole type and discarding
|
|
289
|
+
what the refinement rejects.
|
|
290
|
+
- A size-indexed collection input (`SizedStack 3 Int8`, `SizedQueue n a`)
|
|
291
|
+
is generated from its size, as a user family's index directs generation,
|
|
292
|
+
instead of drawing a collection of any size and filtering for the size.
|
|
293
|
+
The family's measure is recognised under the name an importing unit calls
|
|
294
|
+
it by. Python's Hypothesis no longer fails the `collections` suite now and
|
|
295
|
+
then with the `filter_too_much` health check.
|
|
296
|
+
- Generating a program with many data types no longer takes time quadratic
|
|
297
|
+
in their number: each target's native data names count clashes once, and
|
|
298
|
+
each codec and native type maker builds its type registry and names once
|
|
299
|
+
per unit rather than once per adapter argument. Generating every bundled
|
|
300
|
+
example is about three times faster for Haskell and twice for Go and
|
|
301
|
+
Kotlin, with byte-identical output.
|
|
302
|
+
|
|
303
|
+
## [0.20.1] - 2026-10-06
|
|
304
|
+
|
|
305
|
+
### Added
|
|
306
|
+
|
|
307
|
+
- The repository follows canon's canonical format. `canon.yaml`,
|
|
308
|
+
`canonical_refs.yaml` (every work the docs and code cite, and the
|
|
309
|
+
requirements the tests verify), `canonical_decisions.yaml` (the design
|
|
310
|
+
decisions, each cited as `ref:KEY`) and `canonical_exemptions.yaml` sit at
|
|
311
|
+
the root, and `canonical_vetting/` holds every comment, page, decision and
|
|
312
|
+
reference as pending with owner review deferred until after the 0.21 refactor.
|
|
313
|
+
- `make canon` and `lawspec-dev canon` run canon over the repository, and the
|
|
314
|
+
complete check runs it as its `canon` step. Set `CANON_HOME` to a canon
|
|
315
|
+
checkout built with `stack build`; without one the step is skipped with a
|
|
316
|
+
message.
|
|
317
|
+
- Documentation pages cite sources and decisions as `ref:KEY`, rendered as
|
|
318
|
+
links on the site.
|
|
319
|
+
|
|
320
|
+
### Changed
|
|
321
|
+
|
|
322
|
+
- `CHANGELOG.md` follows Keep a Changelog 1.0.0: dated releases, changes
|
|
323
|
+
grouped as Added, Changed, Removed and Fixed, and comparison links.
|
|
324
|
+
- Every documentation page begins with front matter naming its id, kind and
|
|
325
|
+
title; `docs/nav.json` no longer repeats page titles.
|
|
326
|
+
- Documentation fences include files with `include=` instead of `file=`,
|
|
327
|
+
which is left to canon's tangled blocks.
|
|
328
|
+
- The contributing and release guides move to `docs/how-to/contribute.md` and
|
|
329
|
+
`docs/how-to/release.md`, and appear on the site.
|
|
330
|
+
- `lawspec-dev bump` and `version --check` cover `canon.yaml`.
|
|
331
|
+
- The npm package's `README.md` and `CHANGELOG.md` are copied from the
|
|
332
|
+
repository root when the package is packed, instead of being kept twice in
|
|
333
|
+
git. The package's contents are unchanged.
|
|
334
|
+
|
|
335
|
+
## [0.20.0] - 2026-10-05
|
|
336
|
+
|
|
337
|
+
### Added
|
|
4
338
|
|
|
5
|
-
## 0.20.0
|
|
6
|
-
|
|
7
|
-
- An `all` group with an asynchronous step runs its steps at the same time,
|
|
8
|
-
on each target's own concurrency, so it takes as long as its slowest step.
|
|
9
|
-
Results and accumulated errors keep the order of declaration, and every
|
|
10
|
-
step finishes before the group fails. Groups of synchronous steps still run
|
|
11
|
-
in turn.
|
|
12
|
-
- A channel end that already talks across the network now moves when it is
|
|
13
|
-
sent to another node, instead of being relayed. The old node hands the
|
|
14
|
-
end's state over (sequence numbers, unacknowledged values, values received
|
|
15
|
-
but not yet used), forwards anything still in flight, and the peer is told
|
|
16
|
-
the new address, so the old node can stop once the receive returns. Ends
|
|
17
|
-
can move on again, and a peer that does not answer the move is still
|
|
18
|
-
reached through the old node. Local ends are relayed as before. New frames:
|
|
19
|
-
`take`, `state`, `moved` and `moved-ack`.
|
|
20
|
-
- A node's channel ends stop resending once the node closes (Python, Go,
|
|
21
|
-
Haskell).
|
|
22
339
|
- `lawspec.json` can bind an `async` adapter to native code returning the
|
|
23
340
|
target's task: a coroutine, `Promise`, `CompletableFuture`, `suspend fun`,
|
|
24
341
|
`LawSpecTask`, Rust future or `IO` action. The bridge stays asynchronous
|
|
25
342
|
and converts the result once the task completes.
|
|
26
|
-
- A Rust unit with native bindings keeps its generated remote, session, actor
|
|
27
|
-
and mailbox code.
|
|
28
|
-
- A match may leave out constructors that the value's index rules out: taking
|
|
29
|
-
the head of a `Vec (n + 1) a` needs no `VNil` branch. The compiler proves
|
|
30
|
-
each one impossible, and names a constructor the index allows.
|
|
31
343
|
- `SizedStack n a` and `SizedQueue n a` are stacks and queues indexed by their
|
|
32
344
|
size: `prelude.sizedPop`, `sizedTop`, `sizedDequeue` and `sizedFront` take a
|
|
33
345
|
non-empty one by type.
|
|
@@ -38,13 +350,7 @@
|
|
|
38
350
|
names each branch's type.
|
|
39
351
|
- `if c then a else b` in laws and checked definitions. Only the selected
|
|
40
352
|
branch is evaluated, and the totality audit checks each branch knowing which
|
|
41
|
-
way the condition went.
|
|
42
|
-
- The totality audit bounds products: `x * x` for an `Int16` `x` fits `Int64`,
|
|
43
|
-
and factors with known bounds give their product's bounds.
|
|
44
|
-
- Scenarios may close cycles between processes: LawSpec accepts channels that
|
|
45
|
-
form a cycle when no process can wait for another in a cycle, and names the
|
|
46
|
-
waits when one could. Scenarios with mailboxes or `or else` keep the tree
|
|
47
|
-
rule.
|
|
353
|
+
way the condition went.
|
|
48
354
|
- A unit can re-export names it imports with an `export` line after its
|
|
49
355
|
imports (`export Band, rates.rateOf`), so a package can offer one facade
|
|
50
356
|
unit. Re-exported names are the original declarations, not copies.
|
|
@@ -54,33 +360,78 @@
|
|
|
54
360
|
version after the package name (`shop.tax.v2x0x0.api`), so their types and
|
|
55
361
|
native names stay apart. A mismatch between two versions' types names both
|
|
56
362
|
versions. A package supplied in one version is unchanged.
|
|
363
|
+
- New channel frames `take`, `state`, `moved` and `moved-ack`, for moving a
|
|
364
|
+
channel end between nodes.
|
|
365
|
+
|
|
366
|
+
### Changed
|
|
367
|
+
|
|
368
|
+
- `lawspec package` lists only the package's own units, not those of the
|
|
369
|
+
packages it depends on.
|
|
370
|
+
- An `all` group with an asynchronous step runs its steps at the same time,
|
|
371
|
+
on each target's own concurrency, so it takes as long as its slowest step.
|
|
372
|
+
Results and accumulated errors keep the order of declaration, and every
|
|
373
|
+
step finishes before the group fails. Groups of synchronous steps still run
|
|
374
|
+
in turn.
|
|
375
|
+
- A channel end that already talks across the network now moves when it is
|
|
376
|
+
sent to another node, instead of being relayed. The old node hands the
|
|
377
|
+
end's state over (sequence numbers, unacknowledged values, values received
|
|
378
|
+
but not yet used), forwards anything still in flight, and the peer is told
|
|
379
|
+
the new address, so the old node can stop once the receive returns. Ends
|
|
380
|
+
can move on again, and a peer that does not answer the move is still
|
|
381
|
+
reached through the old node. Local ends are relayed as before.
|
|
382
|
+
- A match may leave out constructors that the value's index rules out: taking
|
|
383
|
+
the head of a `Vec (n + 1) a` needs no `VNil` branch. The compiler proves
|
|
384
|
+
each one impossible, and names a constructor the index allows.
|
|
385
|
+
- `prelude.select` now means the same as `if c then a else b`.
|
|
386
|
+
- The totality audit bounds products: `x * x` for an `Int16` `x` fits `Int64`,
|
|
387
|
+
and factors with known bounds give their product's bounds.
|
|
388
|
+
- Scenarios may close cycles between processes: LawSpec accepts channels that
|
|
389
|
+
form a cycle when no process can wait for another in a cycle, and names the
|
|
390
|
+
waits when one could. Scenarios with mailboxes or `or else` keep the tree
|
|
391
|
+
rule.
|
|
57
392
|
|
|
58
|
-
|
|
393
|
+
### Fixed
|
|
394
|
+
|
|
395
|
+
- A node's channel ends stop resending once the node closes (Python, Go,
|
|
396
|
+
Haskell).
|
|
397
|
+
- A Rust unit with native bindings keeps its generated remote, session, actor
|
|
398
|
+
and mailbox code.
|
|
399
|
+
|
|
400
|
+
## [0.19.1] - 2026-10-05
|
|
401
|
+
|
|
402
|
+
### Added
|
|
59
403
|
|
|
60
404
|
- A handle's Kotlin type binding can give the native class's type
|
|
61
405
|
`arguments` (`["kotlin.Int"]`), so generated Kotlin names the handle's type
|
|
62
406
|
in full instead of `kotlin.Any`.
|
|
407
|
+
|
|
408
|
+
### Changed
|
|
409
|
+
|
|
63
410
|
- A Haskell method binding on a handle with no type binding names the handle
|
|
64
411
|
and the `lawspec.json` entry to add.
|
|
412
|
+
|
|
413
|
+
### Fixed
|
|
414
|
+
|
|
65
415
|
- The sessions example's adapters are asynchronous, so the JavaScript and
|
|
66
416
|
TypeScript ones await each receive instead of using `receiveNow`.
|
|
67
417
|
|
|
68
|
-
## 0.19.0
|
|
418
|
+
## [0.19.0] - 2026-10-04
|
|
69
419
|
|
|
70
|
-
###
|
|
420
|
+
### Added
|
|
71
421
|
|
|
72
|
-
-
|
|
73
|
-
checked definition per command. LawSpec generates runs of
|
|
74
|
-
model, runs them against the adapters, and checks every
|
|
75
|
-
state and invariant. See
|
|
422
|
+
- Stateful models: a `model` pairs a system's commands with a reference, a
|
|
423
|
+
model state and a checked definition per command. LawSpec generates runs of
|
|
424
|
+
commands from the model, runs them against the adapters, and checks every
|
|
425
|
+
result, abstracted state and invariant. See
|
|
426
|
+
[models](docs/reference/language/models.md).
|
|
76
427
|
- **Linear** models thread a flow-typed state, and each command's typestate
|
|
77
428
|
comes from its flow signature, so runs never take a step the types forbid.
|
|
78
429
|
**Shared** models share one handle; `when` preconditions come from the
|
|
79
430
|
model state.
|
|
80
|
-
-
|
|
81
|
-
descriptors gives the same runs and the same shrinks on every target
|
|
82
|
-
the same seed. A failing run is shrunk by dropping commands and
|
|
83
|
-
arguments.
|
|
431
|
+
- Portable generation and shrinking for models: a SplitMix64 generator over
|
|
432
|
+
type descriptors gives the same runs and the same shrinks on every target
|
|
433
|
+
for the same seed. A failing run is shrunk by dropping commands and
|
|
434
|
+
shrinking arguments.
|
|
84
435
|
- Shared models also run in parallel: a short prefix, then a branch per
|
|
85
436
|
thread, run at the same time with random yields, repeated, and each history
|
|
86
437
|
must be linearizable. Sets and maps are checked key by key.
|
|
@@ -91,9 +442,6 @@
|
|
|
91
442
|
- `handle Name` declares a type only adapters create. With native bindings,
|
|
92
443
|
a handle can be a target's own class, such as a concurrent queue, and
|
|
93
444
|
commands can call its methods and constructors directly.
|
|
94
|
-
|
|
95
|
-
### Protocols, scenarios and typed channels
|
|
96
|
-
|
|
97
445
|
- A `protocol` lists what one end of a channel sends and receives. A
|
|
98
446
|
`scenario` runs a shared model's commands from processes (`par ... with ...
|
|
99
447
|
end`) that talk over channels (`send`, `receive`, `expect`). LawSpec proves
|
|
@@ -104,9 +452,6 @@
|
|
|
104
452
|
implementation code: a type per step, so an out-of-order send does not
|
|
105
453
|
compile. A used end fails if used again (in Rust, it does not compile).
|
|
106
454
|
`spawn` and `par` run processes on the target's own concurrency.
|
|
107
|
-
|
|
108
|
-
### Actors and supervision
|
|
109
|
-
|
|
110
455
|
- An `actor` owns a state and handles one message at a time. Handlers are
|
|
111
456
|
plain functions from the state to a reply and the next state. Actors are
|
|
112
457
|
checked like shared models, with injected crashes, and generated as typed
|
|
@@ -120,9 +465,6 @@
|
|
|
120
465
|
- Failures are affine in scenarios: a receive from a failed process fails,
|
|
121
466
|
or runs its `or else`, instead of blocking. One run in three crashes a
|
|
122
467
|
process. Typed channel ends raise `PeerFailed` when the other end gives up.
|
|
123
|
-
|
|
124
|
-
### Mailboxes
|
|
125
|
-
|
|
126
468
|
- `mailbox jobs of Job` declares a typed queue with many senders and one
|
|
127
469
|
receiver. Every target generates `JobsMailbox`, which can also be served on
|
|
128
470
|
a node and sent to from others.
|
|
@@ -130,9 +472,6 @@
|
|
|
130
472
|
every message sent must be received, and senders join the receiver in the
|
|
131
473
|
deadlock-freedom tree. A receive whose senders have all failed fails, or
|
|
132
474
|
runs its `or else`.
|
|
133
|
-
|
|
134
|
-
### Distribution
|
|
135
|
-
|
|
136
475
|
- Nodes talk over a transport: in memory (with loss, duplication, delay and
|
|
137
476
|
partitions, for testing), TCP or HTTP. Actors can be served and called
|
|
138
477
|
across nodes, protocols can listen and dial, and checked definitions can be
|
|
@@ -146,125 +485,126 @@
|
|
|
146
485
|
- A channel end sent to another node keeps working there: the sending node
|
|
147
486
|
relays the conversation. Every protocol can `listen` and `dial`.
|
|
148
487
|
- One scenario run in three sends every channel over a faulty network.
|
|
488
|
+
- `lawspec evidence` lists models, consistency, restarts and supervision as
|
|
489
|
+
property-tested, and each scenario as proved deadlock-free and race-free.
|
|
149
490
|
|
|
150
|
-
###
|
|
491
|
+
### Changed
|
|
151
492
|
|
|
152
493
|
- A refinement's constant integer bounds narrow generation on every target,
|
|
153
494
|
so `(amount :: Int32 where amount >= 1 && amount <= 1000)` is drawn from
|
|
154
495
|
`1..1000` instead of being filtered out of every `Int32`.
|
|
155
|
-
- Generated Python property tests no longer have a per-example deadline, since
|
|
156
|
-
adapters may wait on networks or timers.
|
|
157
496
|
|
|
158
|
-
###
|
|
497
|
+
### Removed
|
|
159
498
|
|
|
160
|
-
-
|
|
161
|
-
|
|
499
|
+
- Generated Python property tests no longer have a per-example deadline, since
|
|
500
|
+
adapters may wait on networks or timers.
|
|
162
501
|
|
|
163
|
-
## 0.18.0
|
|
502
|
+
## [0.18.0] - 2026-10-03
|
|
164
503
|
|
|
165
|
-
###
|
|
504
|
+
### Added
|
|
166
505
|
|
|
167
|
-
- `>>=`, `<$>`, `<!>`, `<|>`, `??`, `>=>`, `|>` and
|
|
168
|
-
names `bind`, `then`, `map`, `mapError`, `orElse`,
|
|
169
|
-
`andThen`, `pipe`, `both`, `ensure`, `isLeft` and
|
|
170
|
-
and recover `Either` values in laws and checked
|
|
171
|
-
|
|
506
|
+
- Railway combinators: `>>=`, `<$>`, `<!>`, `<|>`, `??`, `>=>`, `|>` and
|
|
507
|
+
`<*>`, and the prelude names `bind`, `then`, `map`, `mapError`, `orElse`,
|
|
508
|
+
`fallback`, `fromEither`, `andThen`, `pipe`, `both`, `ensure`, `isLeft` and
|
|
509
|
+
`isRight`, sequence, map and recover `Either` values in laws and checked
|
|
510
|
+
definitions on every target. See
|
|
511
|
+
[expressions](docs/reference/language/expressions-and-arithmetic.md).
|
|
172
512
|
- `Pair` joins the built-in collections unit, and `prelude.select` chooses
|
|
173
513
|
between two values.
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
steps, `then`, `map`, `mapError`, `tap`, `ensure`, `orElse`, `fallback`, and
|
|
179
|
-
`all` groups whose results `combine` joins. With `accumulate`, an `all`
|
|
180
|
-
group reports every failing step's error. See
|
|
514
|
+
- LawSpec generates each `workflow` on every target from its stages: steps,
|
|
515
|
+
`then`, `map`, `mapError`, `tap`, `ensure`, `orElse`, `fallback`, and `all`
|
|
516
|
+
groups whose results `combine` joins. With `accumulate`, an `all` group
|
|
517
|
+
reports every failing step's error. See
|
|
181
518
|
[workflows](docs/reference/language/workflows.md).
|
|
182
|
-
-
|
|
183
|
-
through `mapError`; with `Either _ T`, LawSpec generates an error
|
|
184
|
-
after the workflow, with a constructor per failing step
|
|
519
|
+
- Workflow steps may fail with different error types. A declared error type
|
|
520
|
+
takes them through `mapError`; with `Either _ T`, LawSpec generates an error
|
|
521
|
+
type named after the workflow, with a constructor per failing step
|
|
185
522
|
(`PlaceOrderValidateOrderFailed`).
|
|
186
523
|
- Generated laws check that each workflow composes its stages, succeeds when
|
|
187
524
|
every stage does, stops when a step fails, and recovers with each handler.
|
|
188
|
-
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
- The rate limits, breaker and bulkhead are written once, as checked
|
|
204
|
-
definitions of a built-in unit, `lawspec.resilience`, so they behave the same
|
|
205
|
-
on every target. A new resilience acceptance suite checks each target's
|
|
206
|
-
runtime against them.
|
|
207
|
-
- Generated tests run workflows on a virtual clock with stateful policies,
|
|
208
|
-
timeouts and hedges off; retries still apply.
|
|
209
|
-
|
|
210
|
-
### Durations
|
|
211
|
-
|
|
212
|
-
- `Duration` is a whole number of microseconds, exact on every target, with
|
|
525
|
+
- Step policies: `retry` (immediate, fixed, linear, exponential, fibonacci or
|
|
526
|
+
custom, with optional jitter and a `when` predicate), `timeout`,
|
|
527
|
+
`rateLimit` (token bucket, leaky bucket, fixed or sliding window; wait or
|
|
528
|
+
reject), `circuitBreaker`, `bulkhead`, `cache`, `compensate` and `hedge`. A
|
|
529
|
+
policy failure becomes a constructor of a generated error type, or the value
|
|
530
|
+
a declared error type names with `else`.
|
|
531
|
+
- A workflow runtime: a real or virtual clock, a SplitMix64 random source
|
|
532
|
+
identical on every target, a trace, and the state of limiters, breakers,
|
|
533
|
+
bulkheads and caches. Callers create one to give a workflow its own state or
|
|
534
|
+
a virtual clock; otherwise a shared runtime is used.
|
|
535
|
+
- The built-in unit `lawspec.resilience` defines the rate limits, breaker and
|
|
536
|
+
bulkhead once, as checked definitions, so they behave the same on every
|
|
537
|
+
target. A new `resilience` acceptance suite checks each target's runtime
|
|
538
|
+
against them.
|
|
539
|
+
- `Duration`, a whole number of microseconds, exact on every target, with
|
|
213
540
|
literals (`250ms`, `2s`, `5min`), arithmetic, comparisons and native types
|
|
214
541
|
(`timedelta`, `time.Duration`, `java.time.Duration`,
|
|
215
542
|
`kotlin.time.Duration`, `std::time::Duration`). See
|
|
216
543
|
[durations](docs/reference/language/durations.md).
|
|
544
|
+
- Kotlin workflows can call `suspend` adapters. The Kotlin scaffold depends on
|
|
545
|
+
`kotlinx-coroutines-core`, and `lawspec doctor` reports it missing.
|
|
546
|
+
|
|
547
|
+
### Changed
|
|
548
|
+
|
|
549
|
+
- **Migration:** hand-written workflow adapters are no longer called. Remove
|
|
550
|
+
them, and move any behaviour they had into the steps.
|
|
551
|
+
- Generated tests run workflows on a virtual clock with stateful policies,
|
|
552
|
+
timeouts and hedges off; retries still apply.
|
|
217
553
|
- The totality audit proves more: products and quotients are atoms, quotients
|
|
218
554
|
are bounded, calls satisfy their definitions' postconditions, and unwrapped
|
|
219
555
|
wrapper values satisfy their constraints.
|
|
556
|
+
- On JavaScript and TypeScript, a checked definition that calls an `async`
|
|
557
|
+
adapter, directly or through another definition, is itself `async`.
|
|
558
|
+
|
|
559
|
+
### Removed
|
|
220
560
|
|
|
221
|
-
|
|
561
|
+
- Python property tests have no per-example deadline, since adapters may do
|
|
562
|
+
real work.
|
|
563
|
+
|
|
564
|
+
### Fixed
|
|
222
565
|
|
|
223
566
|
- A definition or adapter named with a target keyword is emitted with a
|
|
224
567
|
leading underscore on that target (`class` is `_class` in Python); such names
|
|
225
568
|
were rejected or broke the build before.
|
|
226
|
-
- On JavaScript and TypeScript, a checked definition that calls an `async`
|
|
227
|
-
adapter, directly or through another definition, is itself `async`.
|
|
228
|
-
- Kotlin workflows can call `suspend` adapters. The Kotlin scaffold depends on
|
|
229
|
-
`kotlinx-coroutines-core`, and `lawspec doctor` reports it missing.
|
|
230
569
|
- Python: a synchronous definition called from inside a running event loop
|
|
231
570
|
(from an `async` adapter) awaits its asynchronous steps on a thread of its
|
|
232
571
|
own instead of failing.
|
|
233
|
-
- Python property tests have no per-example deadline, since adapters may do
|
|
234
|
-
real work.
|
|
235
572
|
|
|
236
|
-
## 0.17.5
|
|
573
|
+
## [0.17.5] - 2026-10-02
|
|
237
574
|
|
|
238
|
-
###
|
|
575
|
+
### Changed
|
|
239
576
|
|
|
240
|
-
-
|
|
577
|
+
- Results and runner reports of `lawspec test` live in `.lawspec/results` and
|
|
578
|
+
`.lawspec/reports`, each with its own `.gitignore`.
|
|
579
|
+
|
|
580
|
+
### Fixed
|
|
581
|
+
|
|
582
|
+
- A test filter that matches nothing made Go, Rust, Node, Kotest and hspec
|
|
241
583
|
report success without running anything. `lawspec test` now reads each
|
|
242
584
|
runner's own report (pytest and Node JUnit XML, `go test -json`, the
|
|
243
585
|
Surefire and Gradle reports, and Rust's and hspec's per-test output) and
|
|
244
586
|
records a law as passing only if at least one of its tests ran and was not
|
|
245
587
|
skipped. A selected law with no executed test fails the run, naming the law.
|
|
246
|
-
- Results and runner reports live in `.lawspec/results` and `.lawspec/reports`,
|
|
247
|
-
each with its own `.gitignore`.
|
|
248
588
|
|
|
249
|
-
## 0.17.4
|
|
589
|
+
## [0.17.4] - 2026-10-02
|
|
250
590
|
|
|
251
|
-
###
|
|
591
|
+
### Added
|
|
252
592
|
|
|
253
|
-
-
|
|
254
|
-
since their last passing run, through each target's own runner,
|
|
255
|
-
the laws that pass. A law runs again when the law changes, or
|
|
256
|
-
depends on: the types and definitions it reaches, its unit's
|
|
257
|
-
tests, the LawSpec version, the target's settings, the project's
|
|
258
|
-
lock files, the toolchain, and, for a law that calls adapters, any
|
|
259
|
-
the project LawSpec did not generate. `--fresh` runs every law. See
|
|
593
|
+
- `lawspec test` runs the generated tests of only the laws whose results may
|
|
594
|
+
have changed since their last passing run, through each target's own runner,
|
|
595
|
+
and records the laws that pass. A law runs again when the law changes, or
|
|
596
|
+
anything it depends on: the types and definitions it reaches, its unit's
|
|
597
|
+
generated tests, the LawSpec version, the target's settings, the project's
|
|
598
|
+
build and lock files, the toolchain, and, for a law that calls adapters, any
|
|
599
|
+
file in the project LawSpec did not generate. `--fresh` runs every law. See
|
|
260
600
|
[`lawspec test`](docs/reference/cli.md#test).
|
|
261
|
-
- Every run uses one random seed for all property tests,
|
|
262
|
-
summary and recorded with each pass; `--seed` fixes it.
|
|
601
|
+
- Every `lawspec test` run uses one random seed for all property tests,
|
|
602
|
+
printed in the summary and recorded with each pass; `--seed` fixes it.
|
|
263
603
|
- `planGeneration` responses list each law's generated test file, its
|
|
264
604
|
position in the unit, its dependency key and whether it calls adapters
|
|
265
605
|
(`tests`).
|
|
266
606
|
|
|
267
|
-
###
|
|
607
|
+
### Changed
|
|
268
608
|
|
|
269
609
|
- Property tests read their seed from `LAWSPEC_SEED` on every target, so a
|
|
270
610
|
failing run can be repeated exactly.
|
|
@@ -272,63 +612,70 @@
|
|
|
272
612
|
their example and boundary tests, so each law's tests can be selected by
|
|
273
613
|
name.
|
|
274
614
|
|
|
275
|
-
## 0.17.3
|
|
276
|
-
|
|
277
|
-
### Incremental front end
|
|
615
|
+
## [0.17.3] - 2026-10-02
|
|
278
616
|
|
|
279
|
-
|
|
280
|
-
keyed by exactly their inputs: the law, the laws it invokes, its unit's
|
|
281
|
-
signatures and the program's data types. Editing a definition's body, or
|
|
282
|
-
another unit's laws, no longer re-checks a law; the dependency keys of
|
|
283
|
-
0.17.2 still replan the laws that reach the edit.
|
|
284
|
-
- Unit validation and totality checks are keyed by the unit.
|
|
285
|
-
- Evidence discharge shares the test planner's work, and builds the type
|
|
286
|
-
registry once per program rather than once per law.
|
|
287
|
-
|
|
288
|
-
### On-disk compiler cache
|
|
617
|
+
### Added
|
|
289
618
|
|
|
290
619
|
- `lawspec check`, `evidence`, `explain` and `generate` keep the compiler's
|
|
291
620
|
work in `.lawspec/cache` and reuse it across runs. Results are identical to
|
|
292
621
|
an uncached run. With every bundled example in one project, a repeated
|
|
293
622
|
`lawspec check` takes 4.7 seconds instead of 8.4, and generating Python
|
|
294
623
|
tests through the API 9.2 instead of 18.2 (natively, a third of the time).
|
|
295
|
-
-
|
|
296
|
-
are recomputed. `--no-cache` or `"cache": false` turns it
|
|
297
|
-
[the compiler cache](docs/reference/cli.md#the-compiler-cache).
|
|
624
|
+
- The cache keeps one folder per compiler build, with its own `.gitignore`;
|
|
625
|
+
damaged entries are recomputed. `--no-cache` or `"cache": false` turns it
|
|
626
|
+
off. See [the compiler cache](docs/reference/cli.md#the-compiler-cache).
|
|
298
627
|
- API requests may name a `cacheDirectory` to share work the same way.
|
|
299
628
|
|
|
300
|
-
|
|
629
|
+
### Changed
|
|
301
630
|
|
|
302
|
-
|
|
631
|
+
- Each law's expansion and type checking, and its elaboration to Core, are
|
|
632
|
+
keyed by exactly their inputs: the law, the laws it invokes, its unit's
|
|
633
|
+
signatures and the program's data types. Editing a definition's body, or
|
|
634
|
+
another unit's laws, no longer re-checks a law.
|
|
635
|
+
- Unit validation and totality checks are keyed by the unit.
|
|
636
|
+
- Evidence discharge shares the test planner's work, and builds the type
|
|
637
|
+
registry once per program rather than once per law.
|
|
638
|
+
|
|
639
|
+
## [0.17.2] - 2026-10-02
|
|
640
|
+
|
|
641
|
+
### Added
|
|
303
642
|
|
|
304
643
|
- The compiler builds a dependency graph of each program. Its nodes are data
|
|
305
644
|
types and declarations (with their contracts and checked definitions), and
|
|
306
645
|
each node has a Merkle digest (SHA-256) of its content and of everything it
|
|
307
646
|
references, with recursive groups digested together.
|
|
647
|
+
|
|
648
|
+
### Changed
|
|
649
|
+
|
|
308
650
|
- A law is planned again only when it, or a type or definition it can reach,
|
|
309
651
|
changes. A unit's files are emitted again only when the unit or one of its
|
|
310
|
-
laws' plans changes, when a data type changes
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
652
|
+
laws' plans changes, when a data type changes, or when a checked definition
|
|
653
|
+
is added, removed or renamed. Editing one definition's body no longer
|
|
654
|
+
replans and re-emits the whole program, and reverting an edit reuses the
|
|
655
|
+
earlier results.
|
|
314
656
|
- Each law is planned from only the types and definitions it reaches, which
|
|
315
657
|
cuts planning time for the bundled examples by two thirds. Evidence
|
|
316
658
|
discharge plans laws the same way, so `lawspec evidence` reports the boundary
|
|
317
659
|
cases the generated tests use.
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
- Boundary search for constrained data took its depth from the number of data
|
|
322
|
-
types in the whole program, and seeded scalar boundaries with literals from
|
|
323
|
-
every type's constructor predicates. Both now come from the types the law
|
|
324
|
-
reaches, so adding an unrelated type no longer changes a law's tests.
|
|
660
|
+
- Boundary search for constrained data takes its depth, and its scalar
|
|
661
|
+
boundary seeds, from the types the law reaches rather than the whole
|
|
662
|
+
program, so adding an unrelated type no longer changes a law's tests.
|
|
325
663
|
Regenerating can change the boundary cases of laws over indexed families and
|
|
326
664
|
constrained data; among the bundled examples, `indexed_arithmetic`,
|
|
327
665
|
`domain_modeling` and the shop package's domain unit gain or lose cases.
|
|
328
666
|
|
|
329
|
-
## 0.17.1
|
|
667
|
+
## [0.17.1] - 2026-10-01
|
|
330
668
|
|
|
331
|
-
###
|
|
669
|
+
### Added
|
|
670
|
+
|
|
671
|
+
- `lawspec-dev ci` records passing results by content. Acceptance suites key
|
|
672
|
+
each run by the generated project and everything else its tests read, so a
|
|
673
|
+
compiler change that leaves a target's output unchanged skips that target's
|
|
674
|
+
native tests. Core steps key by the repository files they read.
|
|
675
|
+
- `lawspec-dev ci --fresh` (`make ci-fresh`) runs every step, and releases use
|
|
676
|
+
it. See [contributing](docs/how-to/contribute.md#checks).
|
|
677
|
+
|
|
678
|
+
### Changed
|
|
332
679
|
|
|
333
680
|
- The compiler reuses work for whatever did not change. A compiler instance
|
|
334
681
|
(one `createCompiler()`, one wasm instance or one process) compiles,
|
|
@@ -339,144 +686,130 @@
|
|
|
339
686
|
- `lawspec examples` and other multi-target runs compile once instead of once
|
|
340
687
|
per target: generating every bundled example for all eight targets takes
|
|
341
688
|
about 105 seconds instead of about 270.
|
|
342
|
-
- A single compile is faster
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
689
|
+
- A single compile is faster: kind lookups use a map instead of scanning every
|
|
690
|
+
type in the program, boundary candidates are deduplicated in `n log n`, and
|
|
691
|
+
long failure messages are split by bisection. Compiling all bundled examples
|
|
692
|
+
together takes a quarter less time.
|
|
693
|
+
|
|
694
|
+
## [0.17.0] - 2026-10-01
|
|
695
|
+
|
|
696
|
+
### Added
|
|
697
|
+
|
|
698
|
+
- Built-in collections `Set a`, `KeyVal k v`, `Queue a`, `Stack a` and
|
|
699
|
+
`Deque a`, with `Entry k v` and `Ordering`. Operations are total prelude
|
|
700
|
+
functions, such as `prelude.setOf`, `prelude.lookup`, `prelude.push` and
|
|
701
|
+
`prelude.popBack`, and `prelude.compare` orders two keyed values. A unit
|
|
702
|
+
that declares a type of the same name keeps its own. See
|
|
703
|
+
[collections](docs/reference/language/collections.md).
|
|
704
|
+
- The `Keyed` capability, needed by Set elements and KeyVal keys: a total
|
|
705
|
+
order shared by every target. Exact numbers order by value, text by code
|
|
706
|
+
point, lists element by element and data by constructor, then fields.
|
|
707
|
+
Floats, complex numbers and symbols are not keyed.
|
|
708
|
+
- Collection adapters use each target's own collections: `frozenset` and
|
|
709
|
+
`dict` in Python, `Set` and `Map` in JavaScript, sorted slices in Go,
|
|
710
|
+
`java.util.Set` and `Map` in Java and Kotlin, `BTreeSet` and `BTreeMap` in
|
|
711
|
+
Rust, and `Data.Set` and `Data.Map` in Haskell. Python and JavaScript use
|
|
712
|
+
sorted tuples or arrays where elements are structured. Codecs sort,
|
|
713
|
+
deduplicate and keep the last value for a repeated key.
|
|
714
|
+
- `async price :: Text -> Int32` declares an asynchronous adapter. It returns
|
|
715
|
+
a coroutine in Python, a `Promise` in JavaScript and TypeScript, a
|
|
716
|
+
`CompletableFuture` in Java, a `suspend fun` in Kotlin, a goroutine-backed
|
|
717
|
+
`lawspec.Task` in Go, an `IO` action in Haskell and a `Future` in Rust. The
|
|
718
|
+
generated tests await each call where it is made, and check contracts on the
|
|
719
|
+
awaited result. See
|
|
720
|
+
[asynchronous functions](docs/reference/language/async-functions.md).
|
|
721
|
+
- `examples/specs/collections.lawspec` covers the new collections.
|
|
722
|
+
|
|
723
|
+
### Changed
|
|
348
724
|
|
|
349
|
-
- `lawspec-dev ci` records passing results by content. Acceptance suites key
|
|
350
|
-
each run by the generated project and everything else its tests read, so a
|
|
351
|
-
compiler change that leaves a target's output unchanged skips that target's
|
|
352
|
-
native tests. Core steps key by the repository files they read.
|
|
353
|
-
- `lawspec-dev ci --fresh` (`make ci-fresh`) runs every step, and releases use
|
|
354
|
-
it. See [CONTRIBUTING](CONTRIBUTING.md#checks).
|
|
355
|
-
|
|
356
|
-
## 0.17.0
|
|
357
|
-
|
|
358
|
-
### Collections
|
|
359
|
-
|
|
360
|
-
`Set a`, `KeyVal k v`, `Queue a`, `Stack a` and `Deque a` are built in, with
|
|
361
|
-
`Entry k v` and `Ordering`. Operations are total prelude functions, such as
|
|
362
|
-
`prelude.setOf`, `prelude.lookup`, `prelude.push` and `prelude.popBack`, and
|
|
363
|
-
`prelude.compare` orders two keyed values. A unit that declares a type of the
|
|
364
|
-
same name keeps its own.
|
|
365
|
-
|
|
366
|
-
- Set elements and KeyVal keys need the new `Keyed` capability: a total order
|
|
367
|
-
shared by every target. Exact numbers order by value, text by code point,
|
|
368
|
-
lists element by element and data by constructor, then fields. Floats,
|
|
369
|
-
complex numbers and symbols are not keyed.
|
|
370
|
-
- Adapters use each target's own collections: `frozenset` and `dict` in
|
|
371
|
-
Python, `Set` and `Map` in JavaScript, sorted slices in Go, `java.util.Set`
|
|
372
|
-
and `Map` in Java and Kotlin, `BTreeSet` and `BTreeMap` in Rust, and
|
|
373
|
-
`Data.Set` and `Data.Map` in Haskell. Python and JavaScript use sorted tuples
|
|
374
|
-
or arrays where elements are structured. Codecs sort, deduplicate and keep
|
|
375
|
-
the last value for a repeated key.
|
|
376
725
|
- Generated Haskell projects depend on `containers`. Rust and Haskell
|
|
377
726
|
generated data derive `Ord` when it is keyed.
|
|
378
|
-
|
|
379
|
-
See [collections](docs/reference/language/collections.md).
|
|
380
|
-
|
|
381
|
-
### Asynchronous functions
|
|
382
|
-
|
|
383
|
-
`async price :: Text -> Int32` declares an asynchronous adapter. It returns a
|
|
384
|
-
coroutine in Python, a `Promise` in JavaScript and TypeScript, a
|
|
385
|
-
`CompletableFuture` in Java, a `suspend fun` in Kotlin, a goroutine-backed
|
|
386
|
-
`lawspec.Task` in Go, an `IO` action in Haskell and a `Future` in Rust. The
|
|
387
|
-
generated tests await each call where it is made, and check contracts on the
|
|
388
|
-
awaited result. See
|
|
389
|
-
[asynchronous functions](docs/reference/language/async-functions.md).
|
|
390
|
-
|
|
391
|
-
### Other changes
|
|
392
|
-
|
|
393
727
|
- A numeric literal passed to a generic function takes the type its other
|
|
394
728
|
arguments fix: `prelude.insert 1 s` with `s :: Set Int32` needs no
|
|
395
729
|
annotation.
|
|
396
730
|
- Generated schemas no longer revalidate a whole value on each construction,
|
|
397
731
|
match or checked-definition call; values are checked at the adapter
|
|
398
732
|
boundary. Large recursive values test much faster.
|
|
399
|
-
- The list example is now `examples/specs/lists.lawspec
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
### Index arithmetic and shared indices
|
|
420
|
-
|
|
733
|
+
- The list example is now `examples/specs/lists.lawspec`.
|
|
734
|
+
|
|
735
|
+
## [0.16.0] - 2026-10-01
|
|
736
|
+
|
|
737
|
+
### Added
|
|
738
|
+
|
|
739
|
+
- GADTs: a constructor can fix a type parameter, so `| Number value :: BigInt
|
|
740
|
+
where a = BigInt` builds only `Expr BigInt`. Matching refines the parameter
|
|
741
|
+
in each branch, so `definition eval (e :: Expr a) :: a` type-checks. A
|
|
742
|
+
constructor that cannot build a type is no value of it: matches need no
|
|
743
|
+
branch for it, and decoding rejects it. See
|
|
744
|
+
[GADTs](docs/reference/language/gadts.md).
|
|
745
|
+
- Definitions may call themselves at other instances (polymorphic recursion),
|
|
746
|
+
up to 64 instances each.
|
|
747
|
+
- Existentials determined by the type (`where a = Pair b c`), and existentials
|
|
748
|
+
only a field mentions: each such value carries its type as a trailing
|
|
749
|
+
`witness` field, and generated values draw it from `Bool` and `Int32`.
|
|
750
|
+
- Native GADT types use each target's own form where it has one: sealed
|
|
751
|
+
interfaces of records in Java, Kotlin data classes, Haskell GADT syntax,
|
|
752
|
+
TypeScript conditional unions and `Expr[int]` in Python.
|
|
421
753
|
- Index expressions accept `+ - * div mod ^`. Subtraction never truncates:
|
|
422
754
|
`n = m - 1` requires `m >= 1`, as a runtime-checked constructor constraint.
|
|
755
|
+
See [indexed families](docs/reference/language/indexed-families.md).
|
|
423
756
|
- A variable bound by several fields makes their indices equal, so
|
|
424
757
|
`Node left :: Perfect m right :: Perfect m` declares perfect trees.
|
|
425
758
|
- An implicit index may first appear as `v + k` or `k * v`:
|
|
426
759
|
`dropFirst :: (xs :: Row (k + 1)) -> (r :: Rest k)`.
|
|
760
|
+
- Flow types: `pop :: Stack (n + 1) / Stack n -> Int8` declares a flow
|
|
761
|
+
parameter, which the call takes from one type to another. In laws, `~s`
|
|
762
|
+
passes a state and rebinds it to the state the call leaves, and `e1; e2`
|
|
763
|
+
sequences: `(push x ~s; pop ~s) = x`. Each clause is checked left to right,
|
|
764
|
+
so a pop the stack cannot take is a compile error that suggests a bound. A
|
|
765
|
+
definition updates its flow parameter with `~s := e`. Each flow function
|
|
766
|
+
returns a generated product (`PopFlow` with `result` and `state`), indexed by
|
|
767
|
+
the state it leaves, so adapters' output states are runtime checked. See
|
|
768
|
+
[flow types](docs/reference/language/flow-types.md).
|
|
769
|
+
- New acceptance suites `gadt` and `flow`, and `indexed` gains
|
|
770
|
+
`examples/specs/indexed_arithmetic.lawspec`, with mutants for every target.
|
|
771
|
+
- The [roadmap](docs/explanation/roadmap.md) records 0.12 to 0.19.
|
|
772
|
+
|
|
773
|
+
### Changed
|
|
774
|
+
|
|
427
775
|
- Products and powers are uninterpreted atoms in the prover, so `r * c` and
|
|
428
776
|
`c * r` agree. A definition's non-linear result index that cannot be proved
|
|
429
777
|
is checked on each result and reported as `runtime-checked`; a linear one is
|
|
430
778
|
still an error.
|
|
431
779
|
- Generation solves any equation backwards over the indices each constructor
|
|
432
|
-
can reach, in all seven runtimes
|
|
433
|
-
|
|
434
|
-
|
|
780
|
+
can reach, in all seven runtimes, and builds balanced trees even without a
|
|
781
|
+
fixed index.
|
|
782
|
+
- A type variable that only a field mentions is now an existential, not an
|
|
783
|
+
error.
|
|
784
|
+
- Rust property tests run on a thread with a 64 MiB stack, for deep generated
|
|
785
|
+
values.
|
|
435
786
|
|
|
436
|
-
|
|
787
|
+
### Fixed
|
|
437
788
|
|
|
438
|
-
|
|
789
|
+
- Generation for `n = m + m` used to build children of the wrong size.
|
|
439
790
|
|
|
440
|
-
|
|
441
|
-
takes the stack from one type to another. In laws, `~s` passes a state and
|
|
442
|
-
rebinds it to the state the call leaves, and `e1; e2` sequences:
|
|
443
|
-
`(push x ~s; pop ~s) = x`. Each clause is checked left to right, so a pop the
|
|
444
|
-
stack cannot take is a compile error that suggests a bound. A definition
|
|
445
|
-
updates its flow parameter with `~s := e`. Each flow function returns a
|
|
446
|
-
generated product (`PopFlow` with `result` and `state`), indexed by the state
|
|
447
|
-
it leaves, so adapters' output states are runtime checked. See
|
|
448
|
-
[flow types](docs/reference/language/flow-types.md).
|
|
791
|
+
## [0.15.2] - 2026-09-30
|
|
449
792
|
|
|
450
|
-
###
|
|
793
|
+
### Changed
|
|
451
794
|
|
|
452
|
-
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
- The [roadmap](docs/explanation/roadmap.md) records 0.12 to 0.19.
|
|
795
|
+
- Generated data types are the types you would write by hand, so adapters no
|
|
796
|
+
longer cast. A product (a type with one constructor) is named after its type
|
|
797
|
+
and read directly; a sum (several constructors) is a closed family that the
|
|
798
|
+
language's own pattern matching checks for exhaustiveness. Laws, tests,
|
|
799
|
+
evidence and codec checks are unchanged, but the generated types adapters
|
|
800
|
+
compile against change:
|
|
459
801
|
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
|
470
|
-
|
|
|
471
|
-
| Java | `var d = (Drink.DrinkCase) value0; d.shots` | `value0.shots()` (a `record`) |
|
|
472
|
-
| Java | `new Size.LargeCase()`, `x instanceof Size.LargeCase` | `new Size.Large()`, `case Size.Large large ->` (sealed interface of records) |
|
|
473
|
-
| Kotlin | `(value0 as Drink.DrinkCase).shots` | `value0.shots` (a `data class`) |
|
|
474
|
-
| Kotlin | `Size.SmallCase()`, `is Size.LargeCase` | `Size.Small` (a `data object`), `is Size.Large` |
|
|
475
|
-
| Go | `value0.(DrinkDrink).Shots`, `DrinkDrink{...}` | `value0.Shots`, `Drink{...}` (a plain struct) |
|
|
476
|
-
| Rust | `let Drink::Drink { shots, .. } = value0;` | `value0.shots` (a `struct` with public fields) |
|
|
477
|
-
| Python | `data.DrinkDrink(...)` | `data.Drink(...)` |
|
|
478
|
-
| JavaScript, TypeScript | `new data.DrinkDrink(...)` | `new data.Drink(...)`; TypeScript's `Drink` is the class |
|
|
479
|
-
| Haskell | `Data.DrinkDrink size shots` | `Data.Drink size shots` |
|
|
802
|
+
| Target | Before | After |
|
|
803
|
+
| --- | --- | --- |
|
|
804
|
+
| Java | `var d = (Drink.DrinkCase) value0; d.shots` | `value0.shots()` (a `record`) |
|
|
805
|
+
| Java | `new Size.LargeCase()`, `x instanceof Size.LargeCase` | `new Size.Large()`, `case Size.Large large ->` (sealed interface of records) |
|
|
806
|
+
| Kotlin | `(value0 as Drink.DrinkCase).shots` | `value0.shots` (a `data class`) |
|
|
807
|
+
| Kotlin | `Size.SmallCase()`, `is Size.LargeCase` | `Size.Small` (a `data object`), `is Size.Large` |
|
|
808
|
+
| Go | `value0.(DrinkDrink).Shots`, `DrinkDrink{...}` | `value0.Shots`, `Drink{...}` (a plain struct) |
|
|
809
|
+
| Rust | `let Drink::Drink { shots, .. } = value0;` | `value0.shots` (a `struct` with public fields) |
|
|
810
|
+
| Python | `data.DrinkDrink(...)` | `data.Drink(...)` |
|
|
811
|
+
| JavaScript, TypeScript | `new data.DrinkDrink(...)` | `new data.Drink(...)`; TypeScript's `Drink` is the class |
|
|
812
|
+
| Haskell | `Data.DrinkDrink size shots` | `Data.Drink size shots` |
|
|
480
813
|
|
|
481
814
|
- A case is named after its constructor. When that name equals the type's name
|
|
482
815
|
or clashes with another case, Java and Kotlin keep a `Case` suffix.
|
|
@@ -488,21 +821,20 @@ compile against change:
|
|
|
488
821
|
- Sums in Go, Rust, Python, JavaScript, TypeScript and Haskell keep their
|
|
489
822
|
names (`SizeSmall`, `Size::Small`).
|
|
490
823
|
|
|
491
|
-
## 0.15.1
|
|
824
|
+
## [0.15.1] - 2026-09-30
|
|
492
825
|
|
|
493
826
|
A maintenance release. The language and generated code are unchanged.
|
|
494
827
|
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
- **Lessons.** Eight tutorials build a coffee shop's ordering system, in Java,
|
|
828
|
+
### Added
|
|
829
|
+
|
|
830
|
+
- Documentation in a [Diátaxis](https://diataxis.fr) site in `docs/`:
|
|
831
|
+
tutorials, how-to guides, reference and explanation.
|
|
832
|
+
- Eight tutorial lessons build a coffee shop's ordering system, in Java,
|
|
501
833
|
Python and JavaScript tracks. Each lesson's specification is editable and
|
|
502
834
|
compiles in the browser, and the JavaScript tests run in the page. The lesson
|
|
503
835
|
implementations are a new acceptance suite, `lessons`, with a mutant per
|
|
504
|
-
lesson on each of the three targets.
|
|
505
|
-
-
|
|
836
|
+
lesson on each of the three targets; the suite also covers TypeScript.
|
|
837
|
+
- The site is static and built with `make docs`: `make docs-serve` previews
|
|
506
838
|
it and `make docs-deploy` deploys it to Cloudflare Pages. It runs the npm
|
|
507
839
|
package's `core.wasm` through a browser launcher with a minimal WASI shim,
|
|
508
840
|
and highlights LawSpec and every target language, in the editor too. Every
|
|
@@ -510,480 +842,404 @@ A maintenance release. The language and generated code are unchanged.
|
|
|
510
842
|
lessons' **▶ Run** runs the generated JavaScript or TypeScript tests against
|
|
511
843
|
an editable implementation in an isolated frame, reporting each law's
|
|
512
844
|
examples, boundary cases and generated cases. Generated tests are read-only.
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
`
|
|
568
|
-
`
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
definitions and generic laws can be imported. Adapters and concrete laws stay
|
|
586
|
-
with their unit. Import cycles, unknown units and missing or ambiguous names
|
|
587
|
-
reported at the import, with the reason: an adapter, a constructor listed
|
|
588
|
-
without its type, or a law without parameters.
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
`
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
### Packages
|
|
602
|
-
|
|
603
|
-
A `lawspec-package.json` names a package, its version, its source directories
|
|
604
|
-
and the version ranges of its dependencies. Package units are named after the
|
|
605
|
-
package, a unit imports only from its own package and direct dependencies, and
|
|
606
|
-
every range must accept the supplied version. A project lists `dependencies` and
|
|
607
|
-
the `packages` directories in `lawspec.json`. A package's adapters and laws are a
|
|
608
|
-
published contract: dependent projects implement and test them as their own.
|
|
609
|
-
`lawspec package` checks a package and summarizes it. See
|
|
610
|
-
[imports and packages](docs/reference/language/imports-and-packages.md).
|
|
611
|
-
|
|
612
|
-
The compiler API accepts `dependencies`, `packages` and `package`, and reports
|
|
613
|
-
the resolved packages (see
|
|
614
|
-
[API migration](docs/explanation/api-migration.md#imports-and-packages-0140)).
|
|
615
|
-
|
|
616
|
-
### Other changes
|
|
617
|
-
|
|
618
|
-
- Rust: a law without quantified inputs no longer emits an untyped empty case
|
|
619
|
-
vector, which did not compile.
|
|
845
|
+
- The Makefile covers every task (`make` lists them), `lawspec-dev bump`
|
|
846
|
+
sets the version everywhere, and the [release guide](docs/how-to/release.md)
|
|
847
|
+
documents the release.
|
|
848
|
+
- The npm package ships `README.md`, `CHANGELOG.md` and `LICENSE`.
|
|
849
|
+
|
|
850
|
+
### Changed
|
|
851
|
+
|
|
852
|
+
- The documentation site replaces the README's version-history sections, the
|
|
853
|
+
per-target guides, `LANGUAGE.md`, `NATIVE-BINDINGS.md`, `PRIMITIVES.md`,
|
|
854
|
+
`REFINEMENTS.md`, `API-MIGRATION.md` and the separate release notes, which
|
|
855
|
+
this changelog now collects.
|
|
856
|
+
- A law whose equation compares two Boolean expressions shows its claim as
|
|
857
|
+
written (`isWeekend d == (d == 0 || d == 6)`), not as the equivalence the
|
|
858
|
+
prover uses.
|
|
859
|
+
- Every JavaScript file in the repository is generated from `templates/` by
|
|
860
|
+
`lawspec-dev generate`, with the version, targets, scaffolds and test
|
|
861
|
+
commands filled in from the Haskell sources.
|
|
862
|
+
- The TypeScript API type check is an npm test.
|
|
863
|
+
|
|
864
|
+
### Removed
|
|
865
|
+
|
|
866
|
+
- 121 unmaintained integration scripts; the acceptance suites and the Hspec
|
|
867
|
+
tests cover what they did.
|
|
868
|
+
|
|
869
|
+
## [0.15.0] - 2026-09-30
|
|
870
|
+
|
|
871
|
+
### Added
|
|
872
|
+
|
|
873
|
+
- Every obligation of a program reports how it is discharged, strongest first:
|
|
874
|
+
- `proved`: statically. Definition postconditions and indices, as since 0.12,
|
|
875
|
+
and now laws that call only checked definitions.
|
|
876
|
+
- `exhaustively-checked`: every input of a finite domain, by the compiler for
|
|
877
|
+
laws over checked definitions and otherwise by the generated tests. A law
|
|
878
|
+
with no inputs is a single case.
|
|
879
|
+
- `property-tested`: generated cases, boundary cases and examples.
|
|
880
|
+
- `runtime-checked`: adapter contracts, definition preconditions,
|
|
881
|
+
constructor constraints and native type bindings, at every native boundary.
|
|
882
|
+
- `assumed`: adapters, native functions, custom generators and codec hooks,
|
|
883
|
+
taken on trust. Each adapter reports how many laws call it, or that none
|
|
884
|
+
does.
|
|
885
|
+
- `lawspec check` summarizes the obligations by status, and the new
|
|
886
|
+
`lawspec evidence` lists each with its claim and reason (`--json` for the API
|
|
887
|
+
records, and a unit or `unit::declaration` filter). See
|
|
888
|
+
[evidence and discharge](docs/reference/language/evidence-and-discharge.md).
|
|
889
|
+
- A law over checked definitions is attempted as a proof by exact linear
|
|
890
|
+
arithmetic, from its input refinements, with definitions that have no
|
|
891
|
+
preconditions unfolded into the claim. When it is not proved and its domain
|
|
892
|
+
is finite, the compiler evaluates every input; a counterexample is a compile
|
|
893
|
+
error with code `refuted`, such as `law always positive is false for x =
|
|
894
|
+
-128`.
|
|
895
|
+
- The prover handles constant factors on integer expressions (`x * 2`), so
|
|
896
|
+
more definition results are proved.
|
|
897
|
+
- API `evidence` items have the five statuses above and new stages: `law`,
|
|
898
|
+
`adapter`, and, with native bindings, `binding`, `codec`, `generator` and
|
|
899
|
+
`native-function`. The TypeScript API declares `ObligationEvidence` and
|
|
900
|
+
`DischargeStatus`. See
|
|
901
|
+
[API migration](docs/explanation/api-migration.md#evidence-and-discharge-0150).
|
|
902
|
+
|
|
903
|
+
### Changed
|
|
904
|
+
|
|
905
|
+
- Specifications that compiled before may be rejected if a law over
|
|
906
|
+
definitions is false.
|
|
907
|
+
- `claim` is `null` for obligations without one.
|
|
908
|
+
|
|
909
|
+
## [0.14.0] - 2026-09-29
|
|
910
|
+
|
|
911
|
+
### Added
|
|
912
|
+
|
|
913
|
+
- A unit imports other units by name: ``import shop.domain as domain (Money,
|
|
914
|
+
Cents, `commutative`)``. Every declaration of an imported unit is available
|
|
915
|
+
through the alias (`domain.Usd`, `domain.centsOf`), and listed names also
|
|
916
|
+
unqualified. Types, wrappers, indexed families, refinements, checked
|
|
917
|
+
definitions and generic laws can be imported. Adapters and concrete laws stay
|
|
918
|
+
with their unit. Import cycles, unknown units and missing or ambiguous names
|
|
919
|
+
are reported at the import, with the reason: an adapter, a constructor listed
|
|
920
|
+
without its type, or a law without parameters.
|
|
921
|
+
- A `lawspec-package.json` names a package, its version, its source
|
|
922
|
+
directories and the version ranges of its dependencies. Package units are
|
|
923
|
+
named after the package, a unit imports only from its own package and direct
|
|
924
|
+
dependencies, and every range must accept the supplied version. A project
|
|
925
|
+
lists `dependencies` and the `packages` directories in `lawspec.json`. A
|
|
926
|
+
package's adapters and laws are a published contract: dependent projects
|
|
927
|
+
implement and test them as their own. `lawspec package` checks a package and
|
|
928
|
+
summarizes it. See
|
|
929
|
+
[imports and packages](docs/reference/language/imports-and-packages.md).
|
|
930
|
+
- The compiler API accepts `dependencies`, `packages` and `package`, and
|
|
931
|
+
reports the resolved packages (see
|
|
932
|
+
[API migration](docs/explanation/api-migration.md#imports-and-packages-0140)).
|
|
620
933
|
- The VS Code grammar highlights `import` and `as`.
|
|
621
934
|
- A new acceptance suite, `packages`, runs the
|
|
622
935
|
[package example](examples/packages) on all eight targets in both machine
|
|
623
|
-
profiles and rejects five adapter mutants plus the bare stubs.
|
|
624
|
-
includes it.
|
|
936
|
+
profiles and rejects five adapter mutants plus the bare stubs.
|
|
937
|
+
`lawspec-dev ci` includes it.
|
|
938
|
+
|
|
939
|
+
### Changed
|
|
940
|
+
|
|
941
|
+
- Names are scoped to their unit, so units compiled together no longer need
|
|
942
|
+
distinct constructor names. Targets with one data namespace (Python,
|
|
943
|
+
JavaScript, TypeScript, Go and Haskell) name colliding types after their
|
|
944
|
+
unit, `ShopDomainCurrency` and `ShopOrdersCurrency`, and their constructors
|
|
945
|
+
`ShopDomainCurrencyUsd`. Java, Kotlin and Rust qualify only the type.
|
|
946
|
+
Earlier versions qualified only the colliding names, for example
|
|
947
|
+
`ShopDomainTypeCurrencyUsd` next to `CurrencyEur`.
|
|
948
|
+
|
|
949
|
+
### Fixed
|
|
625
950
|
|
|
626
|
-
|
|
951
|
+
- Rust: a law without quantified inputs no longer emits an untyped empty case
|
|
952
|
+
vector, which did not compile.
|
|
953
|
+
|
|
954
|
+
## [0.13.2] - 2026-09-29
|
|
627
955
|
|
|
628
956
|
A maintenance release. The language, generated code and API are unchanged.
|
|
629
957
|
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
958
|
+
### Added
|
|
959
|
+
|
|
960
|
+
- `stack run lawspec-dev -- ci` (or `make ci`) runs the complete check
|
|
961
|
+
locally: compiler, npm, parity, package and editor checks, then for each
|
|
962
|
+
target the dependency bootstrap, every acceptance suite in both machine
|
|
963
|
+
profiles, and the installed native-binding example. It logs each step to
|
|
634
964
|
`.artifacts/ci/` and exits non-zero on any failure. `--target`, `--core`,
|
|
635
965
|
`--fail-fast`, `--rust-toolchains` and `--rust-targets` select what to run.
|
|
636
|
-
|
|
966
|
+
|
|
967
|
+
### Changed
|
|
968
|
+
|
|
969
|
+
- The repository has no hosted CI.
|
|
970
|
+
- The package smoke test's per-command timeout is ten minutes.
|
|
971
|
+
|
|
972
|
+
### Removed
|
|
973
|
+
|
|
637
974
|
- The JavaScript acceptance runners and fixture modules replaced by
|
|
638
|
-
`lawspec-acceptance
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
- The integration bootstrap restores missing scaffold files in existing projects.
|
|
975
|
+
`lawspec-acceptance`.
|
|
976
|
+
|
|
977
|
+
### Fixed
|
|
642
978
|
|
|
643
|
-
|
|
979
|
+
- Exporting every bundled example exceeded the package smoke test's former
|
|
980
|
+
two-minute limit on slower machines.
|
|
981
|
+
- The integration bootstrap restores missing scaffold files in existing
|
|
982
|
+
projects.
|
|
983
|
+
|
|
984
|
+
## [0.13.1] - 2026-09-29
|
|
644
985
|
|
|
645
986
|
A maintenance release. The language, generated code and API are unchanged from
|
|
646
987
|
0.13.0.
|
|
647
988
|
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
989
|
+
### Added
|
|
990
|
+
|
|
991
|
+
- A new npm test checks that generation never rewrites build files and that
|
|
992
|
+
regeneration is a no-op on every target.
|
|
993
|
+
|
|
994
|
+
### Changed
|
|
995
|
+
|
|
996
|
+
- Repository checks move from JavaScript to Haskell. `lawspec-dev boundaries`
|
|
997
|
+
and `lawspec-dev integrity` replace `tools/check-boundaries.mjs` and
|
|
998
|
+
`tools/build-integrity.mjs`. The integrity check also rejects staged npm
|
|
651
999
|
copies of documentation and examples that differ from their sources.
|
|
652
1000
|
- `lawspec-acceptance` runs the bundled-example acceptance suites
|
|
653
1001
|
(`integration`, `algebra`, `scalar`, `refinement`, `indexed`, `domain`) in
|
|
654
1002
|
process. Adapters and mutants are real files under `acceptance/`, and a
|
|
655
|
-
mutant that only breaks the build now fails the suite.
|
|
656
|
-
TypeScript scalar mutant that previously counted as rejected because it
|
|
657
|
-
failed type-checking; it now exercises the laws.
|
|
1003
|
+
mutant that only breaks the build now fails the suite.
|
|
658
1004
|
- Build-file scaffolds are defined once in Haskell (`LawSpec.Scaffold`) and
|
|
659
1005
|
checked against the npm templates byte for byte.
|
|
660
1006
|
- Compiler API contract tests formerly in `npm/test` run in hspec against the
|
|
661
|
-
same JSON boundary that `core.wasm` exports.
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
0.9 had narrowed Kotlin and Haskell adapters whose result is the abstract
|
|
813
|
-
`Integer` to `BigInteger` and `Integer`. They again return `Number` (Kotlin) and
|
|
814
|
-
`LS.IntegerValue` (Haskell), as in 0.8 and as Java always did. `Integer` is the top
|
|
815
|
-
of the integral tower: an implementation may return any integral native value,
|
|
816
|
-
and the result bridge rejects non-integral values and checks the logical domain.
|
|
817
|
-
Adapters written against 0.9 or 0.10 stubs that return `BigInteger` or `Integer`
|
|
818
|
-
still compile, because both are integral.
|
|
819
|
-
|
|
820
|
-
This regression had kept the Kotlin and Haskell target checks failing since
|
|
821
|
-
0.9. Those checks, and the scalar mutation fixtures, now pass with the documented
|
|
822
|
-
typed Symbol, Decimal, Utf16Text and Optional representations.
|
|
823
|
-
|
|
824
|
-
### Compatibility
|
|
825
|
-
|
|
826
|
-
Specifications without indexed families generate the same code as 0.10, apart
|
|
827
|
-
from the Integer result signatures above. API schemas 3 and 4 are unchanged.
|
|
828
|
-
GADTs that refine type arguments, non-linear indices and index equalities between
|
|
829
|
-
sibling fields remain future work.
|
|
830
|
-
|
|
831
|
-
## 0.10.0
|
|
832
|
-
|
|
833
|
-
### Existing application models
|
|
834
|
-
|
|
835
|
-
Native bindings connect LawSpec products and sums to existing application types
|
|
836
|
-
on Java, Python, JavaScript, TypeScript, Go, Haskell, Kotlin and Rust. Configure
|
|
837
|
-
constructor and field mappings, bind adapter declarations to existing functions,
|
|
838
|
-
or supply paired conversion hooks for representations requiring custom code.
|
|
839
|
-
Bindings resolve against typed declaration identities; they do not change the
|
|
840
|
-
meaning of arithmetic, equality, definitions or refinements. See
|
|
841
|
-
[Bind native types and functions](docs/how-to/bind-native-types.md).
|
|
842
|
-
|
|
843
|
-
Checked bridges compose through generic and recursive types and the built-in
|
|
844
|
-
containers. They preserve exact numeric values, Symbol identity and distinct
|
|
845
|
-
absence states. Invalid native inputs, results, generator samples and shrink
|
|
846
|
-
candidates fail with context.
|
|
847
|
-
|
|
848
|
-
### Native generators
|
|
849
|
-
|
|
850
|
-
Factories return their framework's generator: JetCheck, Hypothesis, fast-check,
|
|
851
|
-
Rapid, Hedgehog, Kotest or Proptest. Generic factories receive child generators.
|
|
852
|
-
Composition retains native shrinking. Explicit examples, deterministic boundaries
|
|
853
|
-
and finite-domain enumeration still run when the factory's distribution excludes
|
|
854
|
-
those values.
|
|
855
|
-
|
|
856
|
-
A factory can ignore an uninhabited parameter, as in `Phantom Empty`. Requesting a
|
|
857
|
-
value from that parameter fails generation; it cannot turn a property into a
|
|
858
|
-
vacuous success. Finite inhabited containers such as `List Empty` still enumerate.
|
|
859
|
-
|
|
860
|
-
Optional `stub: true` generator bindings create user-owned implementation files.
|
|
861
|
-
Regeneration preserves edits and reports changed factory signatures for review.
|
|
862
|
-
|
|
863
|
-
### API and migration
|
|
864
|
-
|
|
865
|
-
Native binding requests negotiate schema 4. Schema 3 remains supported for
|
|
866
|
-
specifications without bindings. Structured native references and strict
|
|
867
|
-
configuration validation prevent older compilers from silently ignoring mappings.
|
|
868
|
-
Go additionally supports explicit import aliases; Rust binds tests to the
|
|
869
|
-
application library's type identities.
|
|
870
|
-
|
|
871
|
-
Existing adapter files cannot be overwritten by adopting a binding. Move their
|
|
872
|
-
implementations into the application module and save the old adapters before
|
|
873
|
-
generation. Generated source bridges, test helpers and user-owned application
|
|
874
|
-
files retain separate placement and ownership. See the
|
|
875
|
-
[migration guide](docs/explanation/api-migration.md#native-bindings-schema-4-0100) and
|
|
876
|
-
[adopting bindings](docs/how-to/bind-native-types.md#adopt-bindings-in-an-existing-project).
|
|
877
|
-
|
|
878
|
-
### Runnable payment projects
|
|
879
|
-
|
|
880
|
-
`lawspec examples --example payments` exports a project for every target; use
|
|
881
|
-
`--target rust` or another language to select one. Each project includes an
|
|
882
|
-
application model, native generator, configuration, build files and instructions.
|
|
883
|
-
The shared specification checks exact fees, currency preservation, sum payloads,
|
|
884
|
-
ordered archives, duplicates and absence. Re-exporting preserves application
|
|
885
|
-
edits and the separate compiler generation manifest.
|
|
886
|
-
|
|
887
|
-
Both 32-bit and 64-bit logical machine profiles and readable/compact output are
|
|
888
|
-
covered by the acceptance matrices. Java 25+, Python 3.13+ and the other published
|
|
889
|
-
toolchain baselines remain unchanged. Python output follows PEP 8.
|
|
890
|
-
|
|
891
|
-
## 0.9.0
|
|
892
|
-
|
|
893
|
-
This release adds structural data and checked total definitions across Java,
|
|
894
|
-
Python, JavaScript, TypeScript, Go, Haskell, Kotlin and Rust.
|
|
895
|
-
|
|
896
|
-
### Language
|
|
897
|
-
|
|
898
|
-
- `List a` supports nested contextual literals, structural equality, exact
|
|
899
|
-
length, deterministic boundaries, and native framework generation/shrinking.
|
|
900
|
-
- Algebraic `Maybe a` and `Either a b` provide `Nothing`/`Just` and `Left`/`Right`.
|
|
901
|
-
They remain distinct from interoperability `Nullable` and `Optional` values.
|
|
902
|
-
- Named parameterized products and sums have constructors and ordered fields.
|
|
903
|
-
Generated native types and typed adapters preserve their structure.
|
|
904
|
-
- Total definitions support exhaustive matching and checked structural recursion.
|
|
1007
|
+
same JSON boundary that `core.wasm` exports.
|
|
1008
|
+
|
|
1009
|
+
### Fixed
|
|
1010
|
+
|
|
1011
|
+
- A TypeScript scalar mutant counted as rejected because it failed
|
|
1012
|
+
type-checking; it now exercises the laws.
|
|
1013
|
+
|
|
1014
|
+
## [0.13.0] - 2026-09-29
|
|
1015
|
+
|
|
1016
|
+
### Added
|
|
1017
|
+
|
|
1018
|
+
- `wrapper UnitQuantity is Int32 where value >= 1 && value <= 1000 end`
|
|
1019
|
+
declares a distinct nominal type with one field, `value`, and an optional
|
|
1020
|
+
constraint. Its constructor checks the constraint, so an invalid value
|
|
1021
|
+
cannot be constructed in an example (the compiler rejects `UnitQuantity 0`),
|
|
1022
|
+
produced by a generator, or decoded from native code. `valueOf<Name>`
|
|
1023
|
+
unwraps a value. Wrappers may take type parameters (`wrapper NonEmptyList (a
|
|
1024
|
+
:: Type) is List a where prelude.length value > 0 end`), and all eight
|
|
1025
|
+
targets represent them natively.
|
|
1026
|
+
- A `workflow` declares its steps as adapters and checks the pipeline: each
|
|
1027
|
+
step must accept the previous step's state, and fallible steps must share an
|
|
1028
|
+
error type. The workflow's result must match `Either E T` when any step can
|
|
1029
|
+
fail, or `T` otherwise. The compiler adds the law `placeOrder composes its
|
|
1030
|
+
steps`: the native workflow must equal the railway composition of the native
|
|
1031
|
+
steps. Diagnostics name the step and the mismatched types, with the
|
|
1032
|
+
workflow's source location. See
|
|
1033
|
+
[domain modeling](docs/reference/language/domain-modeling.md).
|
|
1034
|
+
- Constructor field constraints, including wrapper constraints, appear in the
|
|
1035
|
+
evidence as `construction` obligations with status `runtime-checked`. The
|
|
1036
|
+
TypeScript API declares these records as `ObligationEvidence`.
|
|
1037
|
+
- `examples/specs/domain_modeling.lawspec` combines wrappers, a parameterized
|
|
1038
|
+
`NonEmptyList`, order states and the workflow. It runs on all eight targets
|
|
1039
|
+
in both machine profiles, with mutants for wrapper invariants, the railway
|
|
1040
|
+
composition and non-empty list operations.
|
|
1041
|
+
|
|
1042
|
+
### Changed
|
|
1043
|
+
|
|
1044
|
+
- `wrapper` and `workflow` begin new declarations. Specifications that do not
|
|
1045
|
+
use them compile as in 0.12. API schemas 3 and 4 are unchanged, apart from
|
|
1046
|
+
the additive `construction` stage in `evidence`.
|
|
1047
|
+
|
|
1048
|
+
## [0.12.0] - 2026-09-29
|
|
1049
|
+
|
|
1050
|
+
### Added
|
|
1051
|
+
|
|
1052
|
+
- Checked definitions may return natural-indexed families, and the compiler
|
|
1053
|
+
proves their result indices statically, as in `definition concatV (xs :: Vec
|
|
1054
|
+
n Int8) (ys :: Vec m Int8) :: Vec (n + m) Int8`. See
|
|
1055
|
+
[proved indices](docs/reference/language/indexed-families.md#proved-indices).
|
|
1056
|
+
- Every contract obligation is recorded as `proved` or `runtime-checked`.
|
|
1057
|
+
`lawspec check` prints a summary, and API responses include an additive
|
|
1058
|
+
`evidence` array; see
|
|
1059
|
+
[API migration](docs/explanation/api-migration.md#evidence-0120).
|
|
1060
|
+
- The indexed example includes proved definitions `concatV` and `flattenV`,
|
|
1061
|
+
used as reference models for the native `append` and `flatten` adapters.
|
|
1062
|
+
|
|
1063
|
+
### Changed
|
|
1064
|
+
|
|
1065
|
+
- The totality prover treats calls of checked definitions as pure linear
|
|
1066
|
+
atoms, so equal calls have equal results. A single-argument definition that
|
|
1067
|
+
matches on its argument unfolds on a known constructor, so `nOfVec (VCons h
|
|
1068
|
+
t)` is `nOfVec t + 1`. Natural measures are non-negative. The prover rejects
|
|
1069
|
+
definitions whose result indices do not follow.
|
|
1070
|
+
- Definition postconditions are proved, and generated code on all eight
|
|
1071
|
+
targets no longer re-checks them at runtime. This changes generated output
|
|
1072
|
+
but not behavior. Definition preconditions and adapter contracts remain
|
|
1073
|
+
runtime-checked.
|
|
1074
|
+
- Specifications that compiled with 0.11 compile unchanged. API schemas 3 and
|
|
1075
|
+
4 are unchanged apart from the additive `evidence` field. See the
|
|
1076
|
+
[current limits](docs/reference/language/index.md#current-limits).
|
|
1077
|
+
|
|
1078
|
+
## [0.11.0] - 2026-09-29
|
|
1079
|
+
|
|
1080
|
+
### Added
|
|
1081
|
+
|
|
1082
|
+
- Data declarations may take `Natural` parameters, and each constructor states
|
|
1083
|
+
its index equation (`type Vec (n :: Natural) (a :: Type) is | VNil where n =
|
|
1084
|
+
0 | VCons head :: a tail :: Vec m a where n = m + 1 end`). Native code works
|
|
1085
|
+
with the erased type, and every index claim is evidence checked at test
|
|
1086
|
+
time: a dependent result such as `Vec (n + m) Int8` is an adapter
|
|
1087
|
+
postcondition. An otherwise unbound index variable is implicit. Index
|
|
1088
|
+
expressions are sums of natural literals and index variables. `Natural` is
|
|
1089
|
+
also available as a value type. Diagnostics use the `indexed` code. See
|
|
1090
|
+
[indexed families](docs/reference/language/indexed-families.md).
|
|
1091
|
+
- A quantifier constrained by a linear structural measure, including a fixed
|
|
1092
|
+
index (`Vec 3 Int8`) or a shared one, is generated by solving the
|
|
1093
|
+
constructor equations backwards instead of filtering, natively on all eight
|
|
1094
|
+
targets, and framework shrinking stays within the index. The same applies to
|
|
1095
|
+
user-written linear measures over declared data.
|
|
1096
|
+
- `examples/specs/indexed_families.lawspec` runs on all eight targets.
|
|
1097
|
+
|
|
1098
|
+
### Fixed
|
|
1099
|
+
|
|
1100
|
+
- Kotlin and Haskell adapters whose result is the abstract `Integer` again
|
|
1101
|
+
return `Number` (Kotlin) and `LS.IntegerValue` (Haskell), as in 0.8 and as
|
|
1102
|
+
Java always did; 0.9 had narrowed them to `BigInteger` and `Integer`.
|
|
1103
|
+
Adapters written against 0.9 or 0.10 stubs still compile.
|
|
1104
|
+
- The Kotlin and Haskell target checks and the scalar mutation fixtures, which
|
|
1105
|
+
had failed since 0.9, pass again.
|
|
1106
|
+
|
|
1107
|
+
## [0.10.0] - 2026-09-29
|
|
1108
|
+
|
|
1109
|
+
### Added
|
|
1110
|
+
|
|
1111
|
+
- Native bindings connect LawSpec products and sums to existing application
|
|
1112
|
+
types on Java, Python, JavaScript, TypeScript, Go, Haskell, Kotlin and Rust:
|
|
1113
|
+
constructor and field mappings, adapter declarations bound to existing
|
|
1114
|
+
functions, or paired conversion hooks. See
|
|
1115
|
+
[Bind native types and functions](docs/how-to/bind-native-types.md).
|
|
1116
|
+
- Checked bridges compose through generic and recursive types and the
|
|
1117
|
+
built-in containers. They preserve exact numeric values, Symbol identity and
|
|
1118
|
+
distinct absence states. Invalid native inputs, results, generator samples
|
|
1119
|
+
and shrink candidates fail with context.
|
|
1120
|
+
- Native generator factories return their framework's generator: JetCheck,
|
|
1121
|
+
Hypothesis, fast-check, Rapid, Hedgehog, Kotest or Proptest. Generic
|
|
1122
|
+
factories receive child generators, and composition keeps native shrinking.
|
|
1123
|
+
Explicit examples, boundaries and finite-domain enumeration still run.
|
|
1124
|
+
- A factory can ignore an uninhabited parameter, as in `Phantom Empty`;
|
|
1125
|
+
requesting a value from it fails generation instead of passing vacuously.
|
|
1126
|
+
- Optional `stub: true` generator bindings create user-owned implementation
|
|
1127
|
+
files. Regeneration preserves edits and reports changed factory signatures.
|
|
1128
|
+
- API schema 4 for native binding requests. Go supports explicit import
|
|
1129
|
+
aliases; Rust binds tests to the application library's type identities.
|
|
1130
|
+
- `lawspec examples --example payments` exports a runnable project for every
|
|
1131
|
+
target (`--target` selects one), with an application model, native
|
|
1132
|
+
generator, configuration, build files and instructions. Re-exporting
|
|
1133
|
+
preserves application edits.
|
|
1134
|
+
|
|
1135
|
+
### Changed
|
|
1136
|
+
|
|
1137
|
+
- Schema 3 remains supported for specifications without bindings. Strict
|
|
1138
|
+
configuration validation prevents older compilers from silently ignoring
|
|
1139
|
+
mappings.
|
|
1140
|
+
- Adopting a binding never overwrites existing adapter files: move their
|
|
1141
|
+
implementations into the application module first. See the
|
|
1142
|
+
[migration guide](docs/explanation/api-migration.md#native-bindings-schema-4-0100) and
|
|
1143
|
+
[adopting bindings](docs/how-to/bind-native-types.md#adopt-bindings-in-an-existing-project).
|
|
1144
|
+
- Python output follows PEP 8.
|
|
1145
|
+
|
|
1146
|
+
## [0.9.0] - 2026-09-28
|
|
1147
|
+
|
|
1148
|
+
### Added
|
|
1149
|
+
|
|
1150
|
+
- `List a` with nested contextual literals, structural equality, exact
|
|
1151
|
+
length, deterministic boundaries, and native framework generation and
|
|
1152
|
+
shrinking.
|
|
1153
|
+
- Algebraic `Maybe a` and `Either a b`, with `Nothing`/`Just` and
|
|
1154
|
+
`Left`/`Right`, distinct from interoperability `Nullable` and `Optional`.
|
|
1155
|
+
- Named parameterized products and sums with constructors and ordered fields,
|
|
1156
|
+
preserved by generated native types and typed adapters.
|
|
1157
|
+
- Total definitions with exhaustive matching and checked structural recursion.
|
|
905
1158
|
The compiler rejects partial matches and recursion it cannot establish as
|
|
906
1159
|
terminating. Generic definitions specialize to their concrete uses.
|
|
907
1160
|
- Refined definition signatures become executable native contracts. Scoped
|
|
908
|
-
payload predicates preserve type-parameter roles through recursive and
|
|
909
|
-
data declarations, including predicates that depend on preceding
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
|
|
925
|
-
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
and
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
|
|
944
|
-
|
|
945
|
-
|
|
946
|
-
|
|
947
|
-
|
|
948
|
-
|
|
949
|
-
## 0.8.0
|
|
950
|
-
|
|
951
|
-
Rust support and a shared typed compiler boundary are the focus of this release.
|
|
952
|
-
The compiler remains implemented in Haskell and ships as prebuilt WebAssembly.
|
|
953
|
-
|
|
954
|
-
### Changes
|
|
955
|
-
|
|
956
|
-
- Rust 2024, with Rust 1.85 as the minimum toolchain, Cargo scaffolding, Proptest
|
|
957
|
-
generation/shrinking, the complete scalar catalog, refinements, and contracts.
|
|
958
|
-
- An independent numeric Rust runtime with owned native bridges, exact arithmetic,
|
|
959
|
-
checked conversions, direct IEEE rounding, raw text, Symbol identity, and
|
|
960
|
-
distinct nested absence states. Proptest support is emitted separately.
|
|
961
|
-
- A typed core and proposition tree shared by all eight emitters. Resolved IDs,
|
|
962
|
-
parsed source ranges, contextual literals, arithmetic evidence, and conversions
|
|
963
|
-
survive elaboration. Emitters no longer import source syntax or inference.
|
|
964
|
-
- An independent core validator and evaluator. Testing plans distinguish semantic
|
|
965
|
-
validity from execution feasibility and preserve dependent refinement domains.
|
|
966
|
-
- API schema v3 with explicit wire views and unchanged lossless scalar encodings.
|
|
967
|
-
Explicit schema-v2 requests receive a migration diagnostic.
|
|
1161
|
+
payload predicates preserve type-parameter roles through recursive and
|
|
1162
|
+
mutual data declarations, including predicates that depend on preceding
|
|
1163
|
+
inputs.
|
|
1164
|
+
- `--minify` selects compact output for `init`, `generate` and `examples`; the
|
|
1165
|
+
compiler API accepts `minify: true`.
|
|
1166
|
+
- API schema 3 adds named data declarations, structural values, checked
|
|
1167
|
+
definitions, construction and matching expressions, and scoped payload
|
|
1168
|
+
predicates. Exhaustive expression visitors must handle the new variants; see
|
|
1169
|
+
[API migration](docs/explanation/api-migration.md#structural-data-and-definitions-090).
|
|
1170
|
+
- Bundled examples for reverse involution, sorting, nested presence, products
|
|
1171
|
+
and sums, exhaustive matches, total functions and recursive payload
|
|
1172
|
+
refinements.
|
|
1173
|
+
|
|
1174
|
+
### Changed
|
|
1175
|
+
|
|
1176
|
+
- Readable code is the default for runtimes, declarations, definitions,
|
|
1177
|
+
adapters, tests and scaffolds. Output follows Google language-specific
|
|
1178
|
+
guidance where applicable, PEP 8 for Python, standard Go and Rust
|
|
1179
|
+
formatting, and an 80-column Haskell layout. Formatting is deterministic in
|
|
1180
|
+
native and WASM compilation and needs no formatter download. Changing the
|
|
1181
|
+
formatting mode does not overwrite edited adapters or create false
|
|
1182
|
+
adapter-signature updates.
|
|
1183
|
+
|
|
1184
|
+
## [0.8.0] - 2026-09-25
|
|
1185
|
+
|
|
1186
|
+
### Added
|
|
1187
|
+
|
|
1188
|
+
- Rust 2024, with Rust 1.85 as the minimum toolchain, Cargo scaffolding,
|
|
1189
|
+
Proptest generation and shrinking, the complete scalar catalog, refinements
|
|
1190
|
+
and contracts. See [Rust](docs/how-to/targets/rust.md).
|
|
1191
|
+
- An independent numeric Rust runtime with owned native bridges, exact
|
|
1192
|
+
arithmetic, checked conversions, direct IEEE rounding, raw text, Symbol
|
|
1193
|
+
identity and distinct nested absence states.
|
|
1194
|
+
- A typed core and proposition tree shared by all eight emitters.
|
|
1195
|
+
- An independent core validator and evaluator. Testing plans distinguish
|
|
1196
|
+
semantic validity from execution feasibility and preserve dependent
|
|
1197
|
+
refinement domains.
|
|
1198
|
+
- API schema v3 with explicit wire views and unchanged lossless scalar
|
|
1199
|
+
encodings. See
|
|
1200
|
+
[API migration](docs/explanation/api-migration.md#schema-2-to-schema-3-080).
|
|
968
1201
|
- Rust module wiring, custom layouts, Cargo preflight, adapter preservation,
|
|
969
|
-
generation manifests, bundled examples
|
|
970
|
-
- Exact algebra and numeric currying examples
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
wrapping adapters are rejected on every target.
|
|
974
|
-
|
|
975
|
-
See [Rust](docs/how-to/targets/rust.md), [the language reference](docs/reference/language/index.md),
|
|
976
|
-
[primitives](docs/reference/primitives.md), [refinements](docs/reference/refinements.md), and
|
|
977
|
-
[API migration](docs/explanation/api-migration.md#schema-2-to-schema-3-080).
|
|
1202
|
+
generation manifests, bundled examples and installed-package coverage.
|
|
1203
|
+
- Exact algebra and numeric currying examples, covering Int32 overflow, large
|
|
1204
|
+
products, Int32-minimum negation, and values beyond machine and safe-number
|
|
1205
|
+
bounds.
|
|
978
1206
|
|
|
979
|
-
###
|
|
1207
|
+
### Changed
|
|
980
1208
|
|
|
981
|
-
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
|
|
1209
|
+
- API clients must migrate to schema v3; explicit schema-v2 requests receive a
|
|
1210
|
+
migration diagnostic.
|
|
1211
|
+
- Logical `Integer` replaces the examples' former modular Int32 contracts;
|
|
1212
|
+
wrapping adapters are rejected on every target.
|
|
1213
|
+
- All nonempty plans emit scalar runtime source; existing Haskell projects
|
|
1214
|
+
need direct `text` and `bytestring` dependencies in the component compiling
|
|
1215
|
+
that source.
|
|
1216
|
+
- Machine-sized domains use an explicit 32/64-bit profile, and native
|
|
1217
|
+
machine-sized bindings reject an architecture mismatch. Rust adapters take
|
|
1218
|
+
owned values.
|
|
1219
|
+
|
|
1220
|
+
[Unreleased]: https://github.com/brain-fuel/lawspec/compare/v0.21.0...HEAD
|
|
1221
|
+
[0.21.0]: https://github.com/brain-fuel/lawspec/compare/v0.20.1...v0.21.0
|
|
1222
|
+
[0.20.1]: https://github.com/brain-fuel/lawspec/compare/v0.20.0...v0.20.1
|
|
1223
|
+
[0.20.0]: https://github.com/brain-fuel/lawspec/compare/v0.19.1...v0.20.0
|
|
1224
|
+
[0.19.1]: https://github.com/brain-fuel/lawspec/compare/v0.19.0...v0.19.1
|
|
1225
|
+
[0.19.0]: https://github.com/brain-fuel/lawspec/compare/v0.18.0...v0.19.0
|
|
1226
|
+
[0.18.0]: https://github.com/brain-fuel/lawspec/compare/v0.17.5...v0.18.0
|
|
1227
|
+
[0.17.5]: https://github.com/brain-fuel/lawspec/compare/v0.17.4...v0.17.5
|
|
1228
|
+
[0.17.4]: https://github.com/brain-fuel/lawspec/compare/v0.17.3...v0.17.4
|
|
1229
|
+
[0.17.3]: https://github.com/brain-fuel/lawspec/compare/v0.17.2...v0.17.3
|
|
1230
|
+
[0.17.2]: https://github.com/brain-fuel/lawspec/compare/v0.17.1...v0.17.2
|
|
1231
|
+
[0.17.1]: https://github.com/brain-fuel/lawspec/compare/v0.17.0...v0.17.1
|
|
1232
|
+
[0.17.0]: https://github.com/brain-fuel/lawspec/compare/v0.16.0...v0.17.0
|
|
1233
|
+
[0.16.0]: https://github.com/brain-fuel/lawspec/compare/v0.15.2...v0.16.0
|
|
1234
|
+
[0.15.2]: https://github.com/brain-fuel/lawspec/compare/v0.15.1...v0.15.2
|
|
1235
|
+
[0.15.1]: https://github.com/brain-fuel/lawspec/compare/v0.15.0...v0.15.1
|
|
1236
|
+
[0.15.0]: https://github.com/brain-fuel/lawspec/compare/v0.14.0...v0.15.0
|
|
1237
|
+
[0.14.0]: https://github.com/brain-fuel/lawspec/compare/v0.13.2...v0.14.0
|
|
1238
|
+
[0.13.2]: https://github.com/brain-fuel/lawspec/compare/v0.13.1...v0.13.2
|
|
1239
|
+
[0.13.1]: https://github.com/brain-fuel/lawspec/compare/v0.13.0...v0.13.1
|
|
1240
|
+
[0.13.0]: https://github.com/brain-fuel/lawspec/compare/v0.12.0...v0.13.0
|
|
1241
|
+
[0.12.0]: https://github.com/brain-fuel/lawspec/compare/v0.11.0...v0.12.0
|
|
1242
|
+
[0.11.0]: https://github.com/brain-fuel/lawspec/compare/v0.10.0...v0.11.0
|
|
1243
|
+
[0.10.0]: https://github.com/brain-fuel/lawspec/compare/v0.9.0...v0.10.0
|
|
1244
|
+
[0.9.0]: https://github.com/brain-fuel/lawspec/compare/4bf7fe5...v0.9.0
|
|
1245
|
+
[0.8.0]: https://github.com/brain-fuel/lawspec/compare/v0.7.0...4bf7fe5
|