lawspec 0.20.1 → 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 CHANGED
@@ -6,6 +6,300 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
7
  ## [Unreleased]
8
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
+
9
303
  ## [0.20.1] - 2026-10-06
10
304
 
11
305
  ### Added
@@ -15,7 +309,7 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
15
309
  requirements the tests verify), `canonical_decisions.yaml` (the design
16
310
  decisions, each cited as `ref:KEY`) and `canonical_exemptions.yaml` sit at
17
311
  the root, and `canonical_vetting/` holds every comment, page, decision and
18
- reference as pending until the owner vets it in 0.20.2.
312
+ reference as pending with owner review deferred until after the 0.21 refactor.
19
313
  - `make canon` and `lawspec-dev canon` run canon over the repository, and the
20
314
  complete check runs it as its `canon` step. Set `CANON_HOME` to a canon
21
315
  checkout built with `stack build`; without one the step is skipped with a
@@ -923,7 +1217,8 @@ A maintenance release. The language, generated code and API are unchanged from
923
1217
  machine-sized bindings reject an architecture mismatch. Rust adapters take
924
1218
  owned values.
925
1219
 
926
- [Unreleased]: https://github.com/brain-fuel/lawspec/compare/v0.20.1...HEAD
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
927
1222
  [0.20.1]: https://github.com/brain-fuel/lawspec/compare/v0.20.0...v0.20.1
928
1223
  [0.20.0]: https://github.com/brain-fuel/lawspec/compare/v0.19.1...v0.20.0
929
1224
  [0.19.1]: https://github.com/brain-fuel/lawspec/compare/v0.19.0...v0.19.1
package/README.md CHANGED
@@ -30,7 +30,7 @@ Node 22+ and the selected target's build tools are required. No Haskell
30
30
  toolchain is needed. The reference platforms are macOS and Linux.
31
31
 
32
32
  ```sh
33
- npm install --save-dev lawspec@0.20.1
33
+ npm install --save-dev lawspec@0.21.0
34
34
  npx lawspec --version
35
35
  ```
36
36
 
@@ -40,8 +40,8 @@ LawSpec can create `package.json` and its test script:
40
40
  ```sh
41
41
  mkdir lawspec-example
42
42
  cd lawspec-example
43
- npm exec --package=lawspec@0.20.1 -- lawspec init --target javascript
44
- npm install --save-dev lawspec@0.20.1
43
+ npm exec --package=lawspec@0.21.0 -- lawspec init --target javascript
44
+ npm install --save-dev lawspec@0.21.0
45
45
  npx lawspec check
46
46
  npx lawspec explain 'example.atoi_codec::itoa and then atoi yields a'
47
47
  npx lawspec doctor