lawspec 0.20.0 → 0.20.1

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
@@ -1,33 +1,51 @@
1
1
  # Changelog
2
2
 
3
- ## Unreleased
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.20.1] - 2026-10-06
10
+
11
+ ### Added
12
+
13
+ - The repository follows canon's canonical format. `canon.yaml`,
14
+ `canonical_refs.yaml` (every work the docs and code cite, and the
15
+ requirements the tests verify), `canonical_decisions.yaml` (the design
16
+ decisions, each cited as `ref:KEY`) and `canonical_exemptions.yaml` sit at
17
+ the root, and `canonical_vetting/` holds every comment, page, decision and
18
+ reference as pending until the owner vets it in 0.20.2.
19
+ - `make canon` and `lawspec-dev canon` run canon over the repository, and the
20
+ complete check runs it as its `canon` step. Set `CANON_HOME` to a canon
21
+ checkout built with `stack build`; without one the step is skipped with a
22
+ message.
23
+ - Documentation pages cite sources and decisions as `ref:KEY`, rendered as
24
+ links on the site.
25
+
26
+ ### Changed
27
+
28
+ - `CHANGELOG.md` follows Keep a Changelog 1.0.0: dated releases, changes
29
+ grouped as Added, Changed, Removed and Fixed, and comparison links.
30
+ - Every documentation page begins with front matter naming its id, kind and
31
+ title; `docs/nav.json` no longer repeats page titles.
32
+ - Documentation fences include files with `include=` instead of `file=`,
33
+ which is left to canon's tangled blocks.
34
+ - The contributing and release guides move to `docs/how-to/contribute.md` and
35
+ `docs/how-to/release.md`, and appear on the site.
36
+ - `lawspec-dev bump` and `version --check` cover `canon.yaml`.
37
+ - The npm package's `README.md` and `CHANGELOG.md` are copied from the
38
+ repository root when the package is packed, instead of being kept twice in
39
+ git. The package's contents are unchanged.
40
+
41
+ ## [0.20.0] - 2026-10-05
42
+
43
+ ### Added
4
44
 
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
45
  - `lawspec.json` can bind an `async` adapter to native code returning the
23
46
  target's task: a coroutine, `Promise`, `CompletableFuture`, `suspend fun`,
24
47
  `LawSpecTask`, Rust future or `IO` action. The bridge stays asynchronous
25
48
  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
49
  - `SizedStack n a` and `SizedQueue n a` are stacks and queues indexed by their
32
50
  size: `prelude.sizedPop`, `sizedTop`, `sizedDequeue` and `sizedFront` take a
33
51
  non-empty one by type.
@@ -38,13 +56,7 @@
38
56
  names each branch's type.
39
57
  - `if c then a else b` in laws and checked definitions. Only the selected
40
58
  branch is evaluated, and the totality audit checks each branch knowing which
41
- way the condition went. `prelude.select` now means the same.
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.
59
+ way the condition went.
48
60
  - A unit can re-export names it imports with an `export` line after its
49
61
  imports (`export Band, rates.rateOf`), so a package can offer one facade
50
62
  unit. Re-exported names are the original declarations, not copies.
@@ -54,33 +66,78 @@
54
66
  version after the package name (`shop.tax.v2x0x0.api`), so their types and
55
67
  native names stay apart. A mismatch between two versions' types names both
56
68
  versions. A package supplied in one version is unchanged.
69
+ - New channel frames `take`, `state`, `moved` and `moved-ack`, for moving a
70
+ channel end between nodes.
71
+
72
+ ### Changed
73
+
74
+ - `lawspec package` lists only the package's own units, not those of the
75
+ packages it depends on.
76
+ - An `all` group with an asynchronous step runs its steps at the same time,
77
+ on each target's own concurrency, so it takes as long as its slowest step.
78
+ Results and accumulated errors keep the order of declaration, and every
79
+ step finishes before the group fails. Groups of synchronous steps still run
80
+ in turn.
81
+ - A channel end that already talks across the network now moves when it is
82
+ sent to another node, instead of being relayed. The old node hands the
83
+ end's state over (sequence numbers, unacknowledged values, values received
84
+ but not yet used), forwards anything still in flight, and the peer is told
85
+ the new address, so the old node can stop once the receive returns. Ends
86
+ can move on again, and a peer that does not answer the move is still
87
+ reached through the old node. Local ends are relayed as before.
88
+ - A match may leave out constructors that the value's index rules out: taking
89
+ the head of a `Vec (n + 1) a` needs no `VNil` branch. The compiler proves
90
+ each one impossible, and names a constructor the index allows.
91
+ - `prelude.select` now means the same as `if c then a else b`.
92
+ - The totality audit bounds products: `x * x` for an `Int16` `x` fits `Int64`,
93
+ and factors with known bounds give their product's bounds.
94
+ - Scenarios may close cycles between processes: LawSpec accepts channels that
95
+ form a cycle when no process can wait for another in a cycle, and names the
96
+ waits when one could. Scenarios with mailboxes or `or else` keep the tree
97
+ rule.
57
98
 
58
- ## 0.19.1
99
+ ### Fixed
100
+
101
+ - A node's channel ends stop resending once the node closes (Python, Go,
102
+ Haskell).
103
+ - A Rust unit with native bindings keeps its generated remote, session, actor
104
+ and mailbox code.
105
+
106
+ ## [0.19.1] - 2026-10-05
107
+
108
+ ### Added
59
109
 
60
110
  - A handle's Kotlin type binding can give the native class's type
61
111
  `arguments` (`["kotlin.Int"]`), so generated Kotlin names the handle's type
62
112
  in full instead of `kotlin.Any`.
113
+
114
+ ### Changed
115
+
63
116
  - A Haskell method binding on a handle with no type binding names the handle
64
117
  and the `lawspec.json` entry to add.
118
+
119
+ ### Fixed
120
+
65
121
  - The sessions example's adapters are asynchronous, so the JavaScript and
66
122
  TypeScript ones await each receive instead of using `receiveNow`.
67
123
 
68
- ## 0.19.0
124
+ ## [0.19.0] - 2026-10-04
69
125
 
70
- ### Stateful models
126
+ ### Added
71
127
 
72
- - A `model` pairs a system's commands with a reference: a model state and a
73
- checked definition per command. LawSpec generates runs of commands from the
74
- model, runs them against the adapters, and checks every result, abstracted
75
- state and invariant. See [models](docs/reference/language/models.md).
128
+ - Stateful models: a `model` pairs a system's commands with a reference, a
129
+ model state and a checked definition per command. LawSpec generates runs of
130
+ commands from the model, runs them against the adapters, and checks every
131
+ result, abstracted state and invariant. See
132
+ [models](docs/reference/language/models.md).
76
133
  - **Linear** models thread a flow-typed state, and each command's typestate
77
134
  comes from its flow signature, so runs never take a step the types forbid.
78
135
  **Shared** models share one handle; `when` preconditions come from the
79
136
  model state.
80
- - Generation and shrinking are portable: a SplitMix64 generator over type
81
- descriptors gives the same runs and the same shrinks on every target for
82
- the same seed. A failing run is shrunk by dropping commands and shrinking
83
- arguments.
137
+ - Portable generation and shrinking for models: a SplitMix64 generator over
138
+ type descriptors gives the same runs and the same shrinks on every target
139
+ for the same seed. A failing run is shrunk by dropping commands and
140
+ shrinking arguments.
84
141
  - Shared models also run in parallel: a short prefix, then a branch per
85
142
  thread, run at the same time with random yields, repeated, and each history
86
143
  must be linearizable. Sets and maps are checked key by key.
@@ -91,9 +148,6 @@
91
148
  - `handle Name` declares a type only adapters create. With native bindings,
92
149
  a handle can be a target's own class, such as a concurrent queue, and
93
150
  commands can call its methods and constructors directly.
94
-
95
- ### Protocols, scenarios and typed channels
96
-
97
151
  - A `protocol` lists what one end of a channel sends and receives. A
98
152
  `scenario` runs a shared model's commands from processes (`par ... with ...
99
153
  end`) that talk over channels (`send`, `receive`, `expect`). LawSpec proves
@@ -104,9 +158,6 @@
104
158
  implementation code: a type per step, so an out-of-order send does not
105
159
  compile. A used end fails if used again (in Rust, it does not compile).
106
160
  `spawn` and `par` run processes on the target's own concurrency.
107
-
108
- ### Actors and supervision
109
-
110
161
  - An `actor` owns a state and handles one message at a time. Handlers are
111
162
  plain functions from the state to a reply and the next state. Actors are
112
163
  checked like shared models, with injected crashes, and generated as typed
@@ -120,9 +171,6 @@
120
171
  - Failures are affine in scenarios: a receive from a failed process fails,
121
172
  or runs its `or else`, instead of blocking. One run in three crashes a
122
173
  process. Typed channel ends raise `PeerFailed` when the other end gives up.
123
-
124
- ### Mailboxes
125
-
126
174
  - `mailbox jobs of Job` declares a typed queue with many senders and one
127
175
  receiver. Every target generates `JobsMailbox`, which can also be served on
128
176
  a node and sent to from others.
@@ -130,9 +178,6 @@
130
178
  every message sent must be received, and senders join the receiver in the
131
179
  deadlock-freedom tree. A receive whose senders have all failed fails, or
132
180
  runs its `or else`.
133
-
134
- ### Distribution
135
-
136
181
  - Nodes talk over a transport: in memory (with loss, duplication, delay and
137
182
  partitions, for testing), TCP or HTTP. Actors can be served and called
138
183
  across nodes, protocols can listen and dial, and checked definitions can be
@@ -146,125 +191,126 @@
146
191
  - A channel end sent to another node keeps working there: the sending node
147
192
  relays the conversation. Every protocol can `listen` and `dial`.
148
193
  - One scenario run in three sends every channel over a faulty network.
194
+ - `lawspec evidence` lists models, consistency, restarts and supervision as
195
+ property-tested, and each scenario as proved deadlock-free and race-free.
149
196
 
150
- ### Generation
197
+ ### Changed
151
198
 
152
199
  - A refinement's constant integer bounds narrow generation on every target,
153
200
  so `(amount :: Int32 where amount >= 1 && amount <= 1000)` is drawn from
154
201
  `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
202
 
158
- ### Evidence
203
+ ### Removed
159
204
 
160
- - `lawspec evidence` lists models, consistency, restarts and supervision as
161
- property-tested, and each scenario as proved deadlock-free and race-free.
205
+ - Generated Python property tests no longer have a per-example deadline, since
206
+ adapters may wait on networks or timers.
162
207
 
163
- ## 0.18.0
208
+ ## [0.18.0] - 2026-10-03
164
209
 
165
- ### Railway combinators
210
+ ### Added
166
211
 
167
- - `>>=`, `<$>`, `<!>`, `<|>`, `??`, `>=>`, `|>` and `<*>`, and the prelude
168
- names `bind`, `then`, `map`, `mapError`, `orElse`, `fallback`, `fromEither`,
169
- `andThen`, `pipe`, `both`, `ensure`, `isLeft` and `isRight`, sequence, map
170
- and recover `Either` values in laws and checked definitions on every target.
171
- See [expressions](docs/reference/language/expressions-and-arithmetic.md).
212
+ - Railway combinators: `>>=`, `<$>`, `<!>`, `<|>`, `??`, `>=>`, `|>` and
213
+ `<*>`, and the prelude names `bind`, `then`, `map`, `mapError`, `orElse`,
214
+ `fallback`, `fromEither`, `andThen`, `pipe`, `both`, `ensure`, `isLeft` and
215
+ `isRight`, sequence, map and recover `Either` values in laws and checked
216
+ definitions on every target. See
217
+ [expressions](docs/reference/language/expressions-and-arithmetic.md).
172
218
  - `Pair` joins the built-in collections unit, and `prelude.select` chooses
173
219
  between two values.
174
-
175
- ### Generated workflows
176
-
177
- - LawSpec now generates each `workflow` on every target from its stages:
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
220
+ - LawSpec generates each `workflow` on every target from its stages: steps,
221
+ `then`, `map`, `mapError`, `tap`, `ensure`, `orElse`, `fallback`, and `all`
222
+ groups whose results `combine` joins. With `accumulate`, an `all` group
223
+ reports every failing step's error. See
181
224
  [workflows](docs/reference/language/workflows.md).
182
- - Steps may fail with different error types. A declared error type takes them
183
- through `mapError`; with `Either _ T`, LawSpec generates an error type named
184
- after the workflow, with a constructor per failing step
225
+ - Workflow steps may fail with different error types. A declared error type
226
+ takes them through `mapError`; with `Either _ T`, LawSpec generates an error
227
+ type named after the workflow, with a constructor per failing step
185
228
  (`PlaceOrderValidateOrderFailed`).
186
229
  - Generated laws check that each workflow composes its stages, succeeds when
187
230
  every stage does, stops when a step fails, and recovers with each handler.
188
- - **Migration:** hand-written workflow adapters are no longer called. Remove
189
- them, and move any behaviour they had into the steps.
190
-
191
- ### Policies
192
-
193
- - A step can run under `retry` (immediate, fixed, linear, exponential,
194
- fibonacci or custom, with optional jitter and a `when` predicate),
195
- `timeout`, `rateLimit` (token bucket, leaky bucket, fixed or sliding
196
- window; wait or reject), `circuitBreaker`, `bulkhead`, `cache`,
197
- `compensate` and `hedge`. A policy failure becomes a constructor of a
198
- generated error type, or the value a declared error type names with `else`.
199
- - Workflows run under a workflow runtime: a real or virtual clock, a SplitMix64
200
- random source identical on every target, a trace, and the state of
201
- limiters, breakers, bulkheads and caches. Callers create one to give a
202
- workflow its own state or a virtual clock; otherwise a shared runtime is used.
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
231
+ - Step policies: `retry` (immediate, fixed, linear, exponential, fibonacci or
232
+ custom, with optional jitter and a `when` predicate), `timeout`,
233
+ `rateLimit` (token bucket, leaky bucket, fixed or sliding window; wait or
234
+ reject), `circuitBreaker`, `bulkhead`, `cache`, `compensate` and `hedge`. A
235
+ policy failure becomes a constructor of a generated error type, or the value
236
+ a declared error type names with `else`.
237
+ - A workflow runtime: a real or virtual clock, a SplitMix64 random source
238
+ identical on every target, a trace, and the state of limiters, breakers,
239
+ bulkheads and caches. Callers create one to give a workflow its own state or
240
+ a virtual clock; otherwise a shared runtime is used.
241
+ - The built-in unit `lawspec.resilience` defines the rate limits, breaker and
242
+ bulkhead once, as checked definitions, so they behave the same on every
243
+ target. A new `resilience` acceptance suite checks each target's runtime
244
+ against them.
245
+ - `Duration`, a whole number of microseconds, exact on every target, with
213
246
  literals (`250ms`, `2s`, `5min`), arithmetic, comparisons and native types
214
247
  (`timedelta`, `time.Duration`, `java.time.Duration`,
215
248
  `kotlin.time.Duration`, `std::time::Duration`). See
216
249
  [durations](docs/reference/language/durations.md).
250
+ - Kotlin workflows can call `suspend` adapters. The Kotlin scaffold depends on
251
+ `kotlinx-coroutines-core`, and `lawspec doctor` reports it missing.
252
+
253
+ ### Changed
254
+
255
+ - **Migration:** hand-written workflow adapters are no longer called. Remove
256
+ them, and move any behaviour they had into the steps.
257
+ - Generated tests run workflows on a virtual clock with stateful policies,
258
+ timeouts and hedges off; retries still apply.
217
259
  - The totality audit proves more: products and quotients are atoms, quotients
218
260
  are bounded, calls satisfy their definitions' postconditions, and unwrapped
219
261
  wrapper values satisfy their constraints.
262
+ - On JavaScript and TypeScript, a checked definition that calls an `async`
263
+ adapter, directly or through another definition, is itself `async`.
264
+
265
+ ### Removed
220
266
 
221
- ### Other changes
267
+ - Python property tests have no per-example deadline, since adapters may do
268
+ real work.
269
+
270
+ ### Fixed
222
271
 
223
272
  - A definition or adapter named with a target keyword is emitted with a
224
273
  leading underscore on that target (`class` is `_class` in Python); such names
225
274
  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
275
  - Python: a synchronous definition called from inside a running event loop
231
276
  (from an `async` adapter) awaits its asynchronous steps on a thread of its
232
277
  own instead of failing.
233
- - Python property tests have no per-example deadline, since adapters may do
234
- real work.
235
278
 
236
- ## 0.17.5
279
+ ## [0.17.5] - 2026-10-02
237
280
 
238
- ### `lawspec test` confirms that each law's tests ran
281
+ ### Changed
239
282
 
240
- - A test filter that matches nothing makes Go, Rust, Node, Kotest and hspec
283
+ - Results and runner reports of `lawspec test` live in `.lawspec/results` and
284
+ `.lawspec/reports`, each with its own `.gitignore`.
285
+
286
+ ### Fixed
287
+
288
+ - A test filter that matches nothing made Go, Rust, Node, Kotest and hspec
241
289
  report success without running anything. `lawspec test` now reads each
242
290
  runner's own report (pytest and Node JUnit XML, `go test -json`, the
243
291
  Surefire and Gradle reports, and Rust's and hspec's per-test output) and
244
292
  records a law as passing only if at least one of its tests ran and was not
245
293
  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
294
 
249
- ## 0.17.4
295
+ ## [0.17.4] - 2026-10-02
250
296
 
251
- ### `lawspec test`
297
+ ### Added
252
298
 
253
- - Runs the generated tests of only the laws whose results may have changed
254
- since their last passing run, through each target's own runner, and records
255
- the laws that pass. A law runs again when the law changes, or anything it
256
- depends on: the types and definitions it reaches, its unit's generated
257
- tests, the LawSpec version, the target's settings, the project's build and
258
- lock files, the toolchain, and, for a law that calls adapters, any file in
259
- the project LawSpec did not generate. `--fresh` runs every law. See
299
+ - `lawspec test` runs the generated tests of only the laws whose results may
300
+ have changed since their last passing run, through each target's own runner,
301
+ and records the laws that pass. A law runs again when the law changes, or
302
+ anything it depends on: the types and definitions it reaches, its unit's
303
+ generated tests, the LawSpec version, the target's settings, the project's
304
+ build and lock files, the toolchain, and, for a law that calls adapters, any
305
+ file in the project LawSpec did not generate. `--fresh` runs every law. See
260
306
  [`lawspec test`](docs/reference/cli.md#test).
261
- - Every run uses one random seed for all property tests, printed in the
262
- summary and recorded with each pass; `--seed` fixes it.
307
+ - Every `lawspec test` run uses one random seed for all property tests,
308
+ printed in the summary and recorded with each pass; `--seed` fixes it.
263
309
  - `planGeneration` responses list each law's generated test file, its
264
310
  position in the unit, its dependency key and whether it calls adapters
265
311
  (`tests`).
266
312
 
267
- ### Changes to generated tests
313
+ ### Changed
268
314
 
269
315
  - Property tests read their seed from `LAWSPEC_SEED` on every target, so a
270
316
  failing run can be repeated exactly.
@@ -272,63 +318,70 @@
272
318
  their example and boundary tests, so each law's tests can be selected by
273
319
  name.
274
320
 
275
- ## 0.17.3
276
-
277
- ### Incremental front end
321
+ ## [0.17.3] - 2026-10-02
278
322
 
279
- - Each law's expansion and type checking, and its elaboration to Core, are
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
323
+ ### Added
289
324
 
290
325
  - `lawspec check`, `evidence`, `explain` and `generate` keep the compiler's
291
326
  work in `.lawspec/cache` and reuse it across runs. Results are identical to
292
327
  an uncached run. With every bundled example in one project, a repeated
293
328
  `lawspec check` takes 4.7 seconds instead of 8.4, and generating Python
294
329
  tests through the API 9.2 instead of 18.2 (natively, a third of the time).
295
- - One folder per compiler build, with its own `.gitignore`; damaged entries
296
- are recomputed. `--no-cache` or `"cache": false` turns it off. See
297
- [the compiler cache](docs/reference/cli.md#the-compiler-cache).
330
+ - The cache keeps one folder per compiler build, with its own `.gitignore`;
331
+ damaged entries are recomputed. `--no-cache` or `"cache": false` turns it
332
+ off. See [the compiler cache](docs/reference/cli.md#the-compiler-cache).
298
333
  - API requests may name a `cacheDirectory` to share work the same way.
299
334
 
300
- ## 0.17.2
335
+ ### Changed
301
336
 
302
- ### Dependency-tracked incremental compilation
337
+ - Each law's expansion and type checking, and its elaboration to Core, are
338
+ keyed by exactly their inputs: the law, the laws it invokes, its unit's
339
+ signatures and the program's data types. Editing a definition's body, or
340
+ another unit's laws, no longer re-checks a law.
341
+ - Unit validation and totality checks are keyed by the unit.
342
+ - Evidence discharge shares the test planner's work, and builds the type
343
+ registry once per program rather than once per law.
344
+
345
+ ## [0.17.2] - 2026-10-02
346
+
347
+ ### Added
303
348
 
304
349
  - The compiler builds a dependency graph of each program. Its nodes are data
305
350
  types and declarations (with their contracts and checked definitions), and
306
351
  each node has a Merkle digest (SHA-256) of its content and of everything it
307
352
  references, with recursive groups digested together.
353
+
354
+ ### Changed
355
+
308
356
  - A law is planned again only when it, or a type or definition it can reach,
309
357
  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 (emitters name types across
311
- the whole program), or when a checked definition is added, removed or
312
- renamed. Editing one definition's body no longer replans and re-emits the
313
- whole program, and reverting an edit reuses the earlier results.
358
+ laws' plans changes, when a data type changes, or when a checked definition
359
+ is added, removed or renamed. Editing one definition's body no longer
360
+ replans and re-emits the whole program, and reverting an edit reuses the
361
+ earlier results.
314
362
  - Each law is planned from only the types and definitions it reaches, which
315
363
  cuts planning time for the bundled examples by two thirds. Evidence
316
364
  discharge plans laws the same way, so `lawspec evidence` reports the boundary
317
365
  cases the generated tests use.
318
-
319
- ### Changes to generated tests
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.
366
+ - Boundary search for constrained data takes its depth, and its scalar
367
+ boundary seeds, from the types the law reaches rather than the whole
368
+ program, so adding an unrelated type no longer changes a law's tests.
325
369
  Regenerating can change the boundary cases of laws over indexed families and
326
370
  constrained data; among the bundled examples, `indexed_arithmetic`,
327
371
  `domain_modeling` and the shop package's domain unit gain or lose cases.
328
372
 
329
- ## 0.17.1
373
+ ## [0.17.1] - 2026-10-01
330
374
 
331
- ### Faster compilation
375
+ ### Added
376
+
377
+ - `lawspec-dev ci` records passing results by content. Acceptance suites key
378
+ each run by the generated project and everything else its tests read, so a
379
+ compiler change that leaves a target's output unchanged skips that target's
380
+ native tests. Core steps key by the repository files they read.
381
+ - `lawspec-dev ci --fresh` (`make ci-fresh`) runs every step, and releases use
382
+ it. See [contributing](docs/how-to/contribute.md#checks).
383
+
384
+ ### Changed
332
385
 
333
386
  - The compiler reuses work for whatever did not change. A compiler instance
334
387
  (one `createCompiler()`, one wasm instance or one process) compiles,
@@ -339,144 +392,130 @@
339
392
  - `lawspec examples` and other multi-target runs compile once instead of once
340
393
  per target: generating every bundled example for all eight targets takes
341
394
  about 105 seconds instead of about 270.
342
- - A single compile is faster too: kind lookups use a map instead of scanning
343
- every type in the program, boundary candidates are deduplicated in
344
- `n log n`, and long failure messages are split by bisection. Compiling all
345
- bundled examples together takes a quarter less time.
346
-
347
- ### Incremental local checks
395
+ - A single compile is faster: kind lookups use a map instead of scanning every
396
+ type in the program, boundary candidates are deduplicated in `n log n`, and
397
+ long failure messages are split by bisection. Compiling all bundled examples
398
+ together takes a quarter less time.
399
+
400
+ ## [0.17.0] - 2026-10-01
401
+
402
+ ### Added
403
+
404
+ - Built-in collections `Set a`, `KeyVal k v`, `Queue a`, `Stack a` and
405
+ `Deque a`, with `Entry k v` and `Ordering`. Operations are total prelude
406
+ functions, such as `prelude.setOf`, `prelude.lookup`, `prelude.push` and
407
+ `prelude.popBack`, and `prelude.compare` orders two keyed values. A unit
408
+ that declares a type of the same name keeps its own. See
409
+ [collections](docs/reference/language/collections.md).
410
+ - The `Keyed` capability, needed by Set elements and KeyVal keys: a total
411
+ order shared by every target. Exact numbers order by value, text by code
412
+ point, lists element by element and data by constructor, then fields.
413
+ Floats, complex numbers and symbols are not keyed.
414
+ - Collection adapters use each target's own collections: `frozenset` and
415
+ `dict` in Python, `Set` and `Map` in JavaScript, sorted slices in Go,
416
+ `java.util.Set` and `Map` in Java and Kotlin, `BTreeSet` and `BTreeMap` in
417
+ Rust, and `Data.Set` and `Data.Map` in Haskell. Python and JavaScript use
418
+ sorted tuples or arrays where elements are structured. Codecs sort,
419
+ deduplicate and keep the last value for a repeated key.
420
+ - `async price :: Text -> Int32` declares an asynchronous adapter. It returns
421
+ a coroutine in Python, a `Promise` in JavaScript and TypeScript, a
422
+ `CompletableFuture` in Java, a `suspend fun` in Kotlin, a goroutine-backed
423
+ `lawspec.Task` in Go, an `IO` action in Haskell and a `Future` in Rust. The
424
+ generated tests await each call where it is made, and check contracts on the
425
+ awaited result. See
426
+ [asynchronous functions](docs/reference/language/async-functions.md).
427
+ - `examples/specs/collections.lawspec` covers the new collections.
428
+
429
+ ### Changed
348
430
 
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
431
  - Generated Haskell projects depend on `containers`. Rust and Haskell
377
432
  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
433
  - A numeric literal passed to a generic function takes the type its other
394
434
  arguments fix: `prelude.insert 1 s` with `s :: Set Int32` needs no
395
435
  annotation.
396
436
  - Generated schemas no longer revalidate a whole value on each construction,
397
437
  match or checked-definition call; values are checked at the adapter
398
438
  boundary. Large recursive values test much faster.
399
- - The list example is now `examples/specs/lists.lawspec`;
400
- `collections.lawspec` covers the new collections.
401
-
402
- ## 0.16.0
403
-
404
- ### GADTs
405
-
406
- A constructor can fix a type parameter: `| Number value :: BigInt where a =
407
- BigInt` builds only `Expr BigInt`. Matching refines the parameter in each
408
- branch, so `definition eval (e :: Expr a) :: a` type-checks. A constructor that
409
- cannot build a type is no value of it: matches need no branch for it, and
410
- decoding rejects it. Definitions may call themselves at other instances
411
- (polymorphic recursion), up to 64 instances each. Existentials determined by
412
- the type (`where a = Pair b c`) are supported, and so are existentials only a
413
- field mentions: each such value carries its type as a trailing `witness` field,
414
- and generated values draw it from `Bool` and `Int32`. Native types use each
415
- target's own GADT form where it has one: sealed interfaces of records in Java,
416
- Kotlin data classes, Haskell GADT syntax, TypeScript conditional unions and
417
- `Expr[int]` in Python. See [GADTs](docs/reference/language/gadts.md).
418
-
419
- ### Index arithmetic and shared indices
420
-
439
+ - The list example is now `examples/specs/lists.lawspec`.
440
+
441
+ ## [0.16.0] - 2026-10-01
442
+
443
+ ### Added
444
+
445
+ - GADTs: a constructor can fix a type parameter, so `| Number value :: BigInt
446
+ where a = BigInt` builds only `Expr BigInt`. Matching refines the parameter
447
+ in each branch, so `definition eval (e :: Expr a) :: a` type-checks. A
448
+ constructor that cannot build a type is no value of it: matches need no
449
+ branch for it, and decoding rejects it. See
450
+ [GADTs](docs/reference/language/gadts.md).
451
+ - Definitions may call themselves at other instances (polymorphic recursion),
452
+ up to 64 instances each.
453
+ - Existentials determined by the type (`where a = Pair b c`), and existentials
454
+ only a field mentions: each such value carries its type as a trailing
455
+ `witness` field, and generated values draw it from `Bool` and `Int32`.
456
+ - Native GADT types use each target's own form where it has one: sealed
457
+ interfaces of records in Java, Kotlin data classes, Haskell GADT syntax,
458
+ TypeScript conditional unions and `Expr[int]` in Python.
421
459
  - Index expressions accept `+ - * div mod ^`. Subtraction never truncates:
422
460
  `n = m - 1` requires `m >= 1`, as a runtime-checked constructor constraint.
461
+ See [indexed families](docs/reference/language/indexed-families.md).
423
462
  - A variable bound by several fields makes their indices equal, so
424
463
  `Node left :: Perfect m right :: Perfect m` declares perfect trees.
425
464
  - An implicit index may first appear as `v + k` or `k * v`:
426
465
  `dropFirst :: (xs :: Row (k + 1)) -> (r :: Rest k)`.
466
+ - Flow types: `pop :: Stack (n + 1) / Stack n -> Int8` declares a flow
467
+ parameter, which the call takes from one type to another. In laws, `~s`
468
+ passes a state and rebinds it to the state the call leaves, and `e1; e2`
469
+ sequences: `(push x ~s; pop ~s) = x`. Each clause is checked left to right,
470
+ so a pop the stack cannot take is a compile error that suggests a bound. A
471
+ definition updates its flow parameter with `~s := e`. Each flow function
472
+ returns a generated product (`PopFlow` with `result` and `state`), indexed by
473
+ the state it leaves, so adapters' output states are runtime checked. See
474
+ [flow types](docs/reference/language/flow-types.md).
475
+ - New acceptance suites `gadt` and `flow`, and `indexed` gains
476
+ `examples/specs/indexed_arithmetic.lawspec`, with mutants for every target.
477
+ - The [roadmap](docs/explanation/roadmap.md) records 0.12 to 0.19.
478
+
479
+ ### Changed
480
+
427
481
  - Products and powers are uninterpreted atoms in the prover, so `r * c` and
428
482
  `c * r` agree. A definition's non-linear result index that cannot be proved
429
483
  is checked on each result and reported as `runtime-checked`; a linear one is
430
484
  still an error.
431
485
  - Generation solves any equation backwards over the indices each constructor
432
- can reach, in all seven runtimes. This fixes `n = m + m`, which used to build
433
- children of the wrong size, and builds balanced trees even without a fixed
434
- index.
486
+ can reach, in all seven runtimes, and builds balanced trees even without a
487
+ fixed index.
488
+ - A type variable that only a field mentions is now an existential, not an
489
+ error.
490
+ - Rust property tests run on a thread with a 64 MiB stack, for deep generated
491
+ values.
435
492
 
436
- See [indexed families](docs/reference/language/indexed-families.md).
493
+ ### Fixed
437
494
 
438
- ### Flow types
495
+ - Generation for `n = m + m` used to build children of the wrong size.
439
496
 
440
- `pop :: Stack (n + 1) / Stack n -> Int8` declares a flow parameter: the call
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).
497
+ ## [0.15.2] - 2026-09-30
449
498
 
450
- ### Other changes
499
+ ### Changed
451
500
 
452
- - A type variable that only a field mentions is now an existential, not an
453
- error.
454
- - Rust property tests run on a thread with a 64 MiB stack, for deep generated
455
- values.
456
- - New acceptance suites `gadt` and `flow`, and `indexed` gains
457
- `examples/specs/indexed_arithmetic.lawspec`, with mutants for every target.
458
- - The [roadmap](docs/explanation/roadmap.md) records 0.12 to 0.19.
501
+ - Generated data types are the types you would write by hand, so adapters no
502
+ longer cast. A product (a type with one constructor) is named after its type
503
+ and read directly; a sum (several constructors) is a closed family that the
504
+ language's own pattern matching checks for exhaustiveness. Laws, tests,
505
+ evidence and codec checks are unchanged, but the generated types adapters
506
+ compile against change:
459
507
 
460
- ## 0.15.2
461
-
462
- Generated data types are the types you would write by hand, so adapters no
463
- longer cast. A product (a type with one constructor) is named after its type
464
- and read directly; a sum (several constructors) is a closed family that the
465
- language's own pattern matching checks for exhaustiveness. Laws, tests,
466
- evidence and codec checks are unchanged, but the generated types adapters
467
- compile against change:
468
-
469
- | Target | Before | After |
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` |
508
+ | Target | Before | After |
509
+ | --- | --- | --- |
510
+ | Java | `var d = (Drink.DrinkCase) value0; d.shots` | `value0.shots()` (a `record`) |
511
+ | Java | `new Size.LargeCase()`, `x instanceof Size.LargeCase` | `new Size.Large()`, `case Size.Large large ->` (sealed interface of records) |
512
+ | Kotlin | `(value0 as Drink.DrinkCase).shots` | `value0.shots` (a `data class`) |
513
+ | Kotlin | `Size.SmallCase()`, `is Size.LargeCase` | `Size.Small` (a `data object`), `is Size.Large` |
514
+ | Go | `value0.(DrinkDrink).Shots`, `DrinkDrink{...}` | `value0.Shots`, `Drink{...}` (a plain struct) |
515
+ | Rust | `let Drink::Drink { shots, .. } = value0;` | `value0.shots` (a `struct` with public fields) |
516
+ | Python | `data.DrinkDrink(...)` | `data.Drink(...)` |
517
+ | JavaScript, TypeScript | `new data.DrinkDrink(...)` | `new data.Drink(...)`; TypeScript's `Drink` is the class |
518
+ | Haskell | `Data.DrinkDrink size shots` | `Data.Drink size shots` |
480
519
 
481
520
  - A case is named after its constructor. When that name equals the type's name
482
521
  or clashes with another case, Java and Kotlin keep a `Case` suffix.
@@ -488,21 +527,20 @@ compile against change:
488
527
  - Sums in Go, Rust, Python, JavaScript, TypeScript and Haskell keep their
489
528
  names (`SizeSmall`, `Size::Small`).
490
529
 
491
- ## 0.15.1
530
+ ## [0.15.1] - 2026-09-30
492
531
 
493
532
  A maintenance release. The language and generated code are unchanged.
494
533
 
495
- - **Documentation** moves into a [Diátaxis](https://diataxis.fr) site in
496
- `docs/`: tutorials, how-to guides, reference and explanation. It replaces the
497
- README's version-history sections, the per-target guides, `LANGUAGE.md`,
498
- `NATIVE-BINDINGS.md`, `PRIMITIVES.md`, `REFINEMENTS.md`, `API-MIGRATION.md`
499
- and the separate release notes, which this changelog now collects.
500
- - **Lessons.** Eight tutorials build a coffee shop's ordering system, in Java,
534
+ ### Added
535
+
536
+ - Documentation in a [Diátaxis](https://diataxis.fr) site in `docs/`:
537
+ tutorials, how-to guides, reference and explanation.
538
+ - Eight tutorial lessons build a coffee shop's ordering system, in Java,
501
539
  Python and JavaScript tracks. Each lesson's specification is editable and
502
540
  compiles in the browser, and the JavaScript tests run in the page. The lesson
503
541
  implementations are a new acceptance suite, `lessons`, with a mutant per
504
- lesson on each of the three targets.
505
- - **The site** is static and built with `make docs`: `make docs-serve` previews
542
+ lesson on each of the three targets; the suite also covers TypeScript.
543
+ - The site is static and built with `make docs`: `make docs-serve` previews
506
544
  it and `make docs-deploy` deploys it to Cloudflare Pages. It runs the npm
507
545
  package's `core.wasm` through a browser launcher with a minimal WASI shim,
508
546
  and highlights LawSpec and every target language, in the editor too. Every
@@ -510,480 +548,403 @@ A maintenance release. The language and generated code are unchanged.
510
548
  lessons' **▶ Run** runs the generated JavaScript or TypeScript tests against
511
549
  an editable implementation in an isolated frame, reporting each law's
512
550
  examples, boundary cases and generated cases. Generated tests are read-only.
513
- The `lessons` acceptance suite also covers TypeScript.
514
- - **Evidence.** A law whose equation compares two Boolean expressions now shows
515
- its claim as written (`isWeekend d == (d == 0 || d == 6)`), not as the
516
- equivalence the prover uses.
517
- - **Generated JavaScript.** Every JavaScript file in the repository is generated
518
- from `templates/` by `lawspec-dev generate`, with the version, targets,
519
- scaffolds and test commands filled in from the Haskell sources. The
520
- compiler's own facts are no longer copied by hand into the npm CLI.
521
- - **Development.** 121 unmaintained integration scripts, most of which needed
522
- manual setup and no longer ran, are removed; the acceptance suites and the
523
- Hspec tests cover what they did. The TypeScript API type check becomes an npm
524
- test. The Makefile covers every task (`make` lists them), `lawspec-dev bump`
525
- sets the version everywhere, and `RELEASING.md` documents the release.
526
- - The npm package ships `README.md`, `CHANGELOG.md` and `LICENSE`; the
527
- documentation is online.
528
-
529
- ## 0.15.0
530
-
531
- ### Evidence and discharge
532
-
533
- Every obligation of a program reports how it is discharged, strongest first:
534
-
535
- - `proved`: statically. Definition postconditions and indices, as since 0.12,
536
- and now laws that call only checked definitions.
537
- - `exhaustively-checked`: every input of a finite domain, by the compiler for
538
- laws over checked definitions and otherwise by the generated tests. A law with
539
- no inputs is a single case.
540
- - `property-tested`: generated cases, boundary cases and examples.
541
- - `runtime-checked`: adapter contracts, definition preconditions, constructor
542
- constraints and native type bindings, at every native boundary.
543
- - `assumed`: adapters, native functions, custom generators and codec hooks,
544
- taken on trust. Each adapter reports how many laws call it, or that none does.
545
-
546
- `lawspec check` summarizes the obligations by status, and the new
547
- `lawspec evidence` lists each with its claim and reason (`--json` for the API
548
- records, and a unit or `unit::declaration` filter). See
549
- [evidence and discharge](docs/reference/language/evidence-and-discharge.md).
550
-
551
- ### Laws proved and refuted by the compiler
552
-
553
- A law over checked definitions is attempted as a proof by the same exact linear
554
- arithmetic that proves definition results, from its input refinements, with
555
- definitions that have no preconditions unfolded into the claim. When it is not
556
- proved and its domain is finite, the compiler evaluates every input; a
557
- counterexample is a compile error with code `refuted`, such as
558
- `law always positive is false for x = -128`. Specifications that compiled
559
- before may therefore be rejected if a law over definitions is false.
560
-
561
- The prover also handles constant factors on integer expressions (`x * 2`),
562
- which it previously treated as non-linear, so more definition results are
563
- proved.
564
-
565
- ### API
566
-
567
- `evidence` items have the five statuses above and new stages: `law`,
568
- `adapter`, and, with native bindings, `binding`, `codec`, `generator` and
569
- `native-function`. `claim` is `null` for obligations without one. The
570
- TypeScript API declares `ObligationEvidence` and `DischargeStatus`. See
571
- [API migration](docs/explanation/api-migration.md#evidence-and-discharge-0150).
572
-
573
- ## 0.14.0
574
-
575
- ### Imports
576
-
577
- ```lawspec fragment
578
- unit shop.orders
579
- import shop.domain as domain (Money, Cents, `commutative`)
580
- ```
581
-
582
- A unit imports other units by name. Every declaration of an imported unit is
583
- available through the alias (`domain.Usd`, `domain.centsOf`), and listed names
584
- also unqualified. Types, wrappers, indexed families, refinements, checked
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 are
587
- reported at the import, with the reason: an adapter, a constructor listed
588
- without its type, or a law without parameters.
589
-
590
- Names are scoped to their unit, so units compiled together no longer need
591
- distinct constructor names. Targets with one data namespace (Python,
592
- JavaScript, TypeScript, Go and Haskell) name colliding types after their unit,
593
- `ShopDomainCurrency` and `ShopOrdersCurrency`, and their constructors
594
- `ShopDomainCurrencyUsd`. Java, Kotlin and Rust qualify only the type. Earlier
595
- versions qualified only the colliding names, for example
596
- `ShopDomainTypeCurrencyUsd` next to `CurrencyEur`.
597
-
598
- Imports are resolved before type checking, like indexed families and domain
599
- models, so Core and the eight backends are unchanged.
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.
551
+ - The Makefile covers every task (`make` lists them), `lawspec-dev bump`
552
+ sets the version everywhere, and the [release guide](docs/how-to/release.md)
553
+ documents the release.
554
+ - The npm package ships `README.md`, `CHANGELOG.md` and `LICENSE`.
555
+
556
+ ### Changed
557
+
558
+ - The documentation site replaces the README's version-history sections, the
559
+ per-target guides, `LANGUAGE.md`, `NATIVE-BINDINGS.md`, `PRIMITIVES.md`,
560
+ `REFINEMENTS.md`, `API-MIGRATION.md` and the separate release notes, which
561
+ this changelog now collects.
562
+ - A law whose equation compares two Boolean expressions shows its claim as
563
+ written (`isWeekend d == (d == 0 || d == 6)`), not as the equivalence the
564
+ prover uses.
565
+ - Every JavaScript file in the repository is generated from `templates/` by
566
+ `lawspec-dev generate`, with the version, targets, scaffolds and test
567
+ commands filled in from the Haskell sources.
568
+ - The TypeScript API type check is an npm test.
569
+
570
+ ### Removed
571
+
572
+ - 121 unmaintained integration scripts; the acceptance suites and the Hspec
573
+ tests cover what they did.
574
+
575
+ ## [0.15.0] - 2026-09-30
576
+
577
+ ### Added
578
+
579
+ - Every obligation of a program reports how it is discharged, strongest first:
580
+ - `proved`: statically. Definition postconditions and indices, as since 0.12,
581
+ and now laws that call only checked definitions.
582
+ - `exhaustively-checked`: every input of a finite domain, by the compiler for
583
+ laws over checked definitions and otherwise by the generated tests. A law
584
+ with no inputs is a single case.
585
+ - `property-tested`: generated cases, boundary cases and examples.
586
+ - `runtime-checked`: adapter contracts, definition preconditions,
587
+ constructor constraints and native type bindings, at every native boundary.
588
+ - `assumed`: adapters, native functions, custom generators and codec hooks,
589
+ taken on trust. Each adapter reports how many laws call it, or that none
590
+ does.
591
+ - `lawspec check` summarizes the obligations by status, and the new
592
+ `lawspec evidence` lists each with its claim and reason (`--json` for the API
593
+ records, and a unit or `unit::declaration` filter). See
594
+ [evidence and discharge](docs/reference/language/evidence-and-discharge.md).
595
+ - A law over checked definitions is attempted as a proof by exact linear
596
+ arithmetic, from its input refinements, with definitions that have no
597
+ preconditions unfolded into the claim. When it is not proved and its domain
598
+ is finite, the compiler evaluates every input; a counterexample is a compile
599
+ error with code `refuted`, such as `law always positive is false for x =
600
+ -128`.
601
+ - The prover handles constant factors on integer expressions (`x * 2`), so
602
+ more definition results are proved.
603
+ - API `evidence` items have the five statuses above and new stages: `law`,
604
+ `adapter`, and, with native bindings, `binding`, `codec`, `generator` and
605
+ `native-function`. The TypeScript API declares `ObligationEvidence` and
606
+ `DischargeStatus`. See
607
+ [API migration](docs/explanation/api-migration.md#evidence-and-discharge-0150).
608
+
609
+ ### Changed
610
+
611
+ - Specifications that compiled before may be rejected if a law over
612
+ definitions is false.
613
+ - `claim` is `null` for obligations without one.
614
+
615
+ ## [0.14.0] - 2026-09-29
616
+
617
+ ### Added
618
+
619
+ - A unit imports other units by name: ``import shop.domain as domain (Money,
620
+ Cents, `commutative`)``. Every declaration of an imported unit is available
621
+ through the alias (`domain.Usd`, `domain.centsOf`), and listed names also
622
+ unqualified. Types, wrappers, indexed families, refinements, checked
623
+ definitions and generic laws can be imported. Adapters and concrete laws stay
624
+ with their unit. Import cycles, unknown units and missing or ambiguous names
625
+ are reported at the import, with the reason: an adapter, a constructor listed
626
+ without its type, or a law without parameters.
627
+ - A `lawspec-package.json` names a package, its version, its source
628
+ directories and the version ranges of its dependencies. Package units are
629
+ named after the package, a unit imports only from its own package and direct
630
+ dependencies, and every range must accept the supplied version. A project
631
+ lists `dependencies` and the `packages` directories in `lawspec.json`. A
632
+ package's adapters and laws are a published contract: dependent projects
633
+ implement and test them as their own. `lawspec package` checks a package and
634
+ summarizes it. See
635
+ [imports and packages](docs/reference/language/imports-and-packages.md).
636
+ - The compiler API accepts `dependencies`, `packages` and `package`, and
637
+ reports the resolved packages (see
638
+ [API migration](docs/explanation/api-migration.md#imports-and-packages-0140)).
620
639
  - The VS Code grammar highlights `import` and `as`.
621
640
  - A new acceptance suite, `packages`, runs the
622
641
  [package example](examples/packages) on all eight targets in both machine
623
- profiles and rejects five adapter mutants plus the bare stubs. `lawspec-dev ci`
624
- includes it.
642
+ profiles and rejects five adapter mutants plus the bare stubs.
643
+ `lawspec-dev ci` includes it.
644
+
645
+ ### Changed
646
+
647
+ - Names are scoped to their unit, so units compiled together no longer need
648
+ distinct constructor names. Targets with one data namespace (Python,
649
+ JavaScript, TypeScript, Go and Haskell) name colliding types after their
650
+ unit, `ShopDomainCurrency` and `ShopOrdersCurrency`, and their constructors
651
+ `ShopDomainCurrencyUsd`. Java, Kotlin and Rust qualify only the type.
652
+ Earlier versions qualified only the colliding names, for example
653
+ `ShopDomainTypeCurrencyUsd` next to `CurrencyEur`.
654
+
655
+ ### Fixed
625
656
 
626
- ## 0.13.2
657
+ - Rust: a law without quantified inputs no longer emits an untyped empty case
658
+ vector, which did not compile.
659
+
660
+ ## [0.13.2] - 2026-09-29
627
661
 
628
662
  A maintenance release. The language, generated code and API are unchanged.
629
663
 
630
- - The repository has no hosted CI. `stack run lawspec-dev -- ci` runs the
631
- complete check locally: compiler, npm, parity, package and editor checks, then
632
- for each target the dependency bootstrap, every acceptance suite in both
633
- machine profiles, and the installed native-binding example. It logs each step to
664
+ ### Added
665
+
666
+ - `stack run lawspec-dev -- ci` (or `make ci`) runs the complete check
667
+ locally: compiler, npm, parity, package and editor checks, then for each
668
+ target the dependency bootstrap, every acceptance suite in both machine
669
+ profiles, and the installed native-binding example. It logs each step to
634
670
  `.artifacts/ci/` and exits non-zero on any failure. `--target`, `--core`,
635
671
  `--fail-fast`, `--rust-toolchains` and `--rust-targets` select what to run.
636
- `make ci` is equivalent.
672
+
673
+ ### Changed
674
+
675
+ - The repository has no hosted CI.
676
+ - The package smoke test's per-command timeout is ten minutes.
677
+
678
+ ### Removed
679
+
637
680
  - The JavaScript acceptance runners and fixture modules replaced by
638
- `lawspec-acceptance` are removed.
639
- - The package smoke test's per-command timeout is ten minutes: exporting every
640
- bundled example had exceeded the former two-minute limit on slower machines.
641
- - The integration bootstrap restores missing scaffold files in existing projects.
681
+ `lawspec-acceptance`.
682
+
683
+ ### Fixed
642
684
 
643
- ## 0.13.1
685
+ - Exporting every bundled example exceeded the package smoke test's former
686
+ two-minute limit on slower machines.
687
+ - The integration bootstrap restores missing scaffold files in existing
688
+ projects.
689
+
690
+ ## [0.13.1] - 2026-09-29
644
691
 
645
692
  A maintenance release. The language, generated code and API are unchanged from
646
693
  0.13.0.
647
694
 
648
- - Repository checks move from JavaScript to Haskell. `lawspec-dev boundaries` and
649
- `lawspec-dev integrity` replace `tools/check-boundaries.mjs` and
650
- `tools/build-integrity.mjs`. The integrity check now also rejects staged npm
695
+ ### Added
696
+
697
+ - A new npm test checks that generation never rewrites build files and that
698
+ regeneration is a no-op on every target.
699
+
700
+ ### Changed
701
+
702
+ - Repository checks move from JavaScript to Haskell. `lawspec-dev boundaries`
703
+ and `lawspec-dev integrity` replace `tools/check-boundaries.mjs` and
704
+ `tools/build-integrity.mjs`. The integrity check also rejects staged npm
651
705
  copies of documentation and examples that differ from their sources.
652
706
  - `lawspec-acceptance` runs the bundled-example acceptance suites
653
707
  (`integration`, `algebra`, `scalar`, `refinement`, `indexed`, `domain`) in
654
708
  process. Adapters and mutants are real files under `acceptance/`, and a
655
- mutant that only breaks the build now fails the suite. This exposed a
656
- TypeScript scalar mutant that previously counted as rejected because it
657
- failed type-checking; it now exercises the laws.
709
+ mutant that only breaks the build now fails the suite.
658
710
  - Build-file scaffolds are defined once in Haskell (`LawSpec.Scaffold`) and
659
711
  checked against the npm templates byte for byte.
660
712
  - Compiler API contract tests formerly in `npm/test` run in hspec against the
661
- same JSON boundary that `core.wasm` exports. A new npm test checks that
662
- generation never rewrites build files and that regeneration is a no-op on
663
- every target.
664
-
665
- ## 0.13.0
666
-
667
- ### Wrappers and constrained primitives
668
-
669
- ```lawspec fragment
670
- wrapper UnitQuantity is Int32 where value >= 1 && value <= 1000 end
671
- wrapper NonEmptyList (a :: Type) is List a where prelude.length value > 0 end
672
- ```
673
-
674
- A wrapper declares a distinct nominal type with one field, `value`, and an
675
- optional constraint. Its constructor checks the constraint, so an invalid value
676
- cannot be constructed in an example (the compiler rejects `UnitQuantity 0`),
677
- produced by a generator, or decoded from native code. `valueOf<Name>` unwraps a
678
- value. Wrappers may take type parameters. They elaborate to a single-constructor
679
- product with a refined field, so all eight targets represent them natively with
680
- no new runtime machinery.
681
-
682
- ### Workflows and state distinctions
683
-
684
- ```lawspec fragment
685
- workflow placeOrder :: UnvalidatedOrder -> Either OrderError PricedOrder is
686
- validateOrder :: UnvalidatedOrder -> Either OrderError ValidatedOrder
687
- priceOrder :: ValidatedOrder -> Either OrderError PricedOrder
688
- end
689
- ```
690
-
691
- A workflow declares its steps as adapters and checks the pipeline: each step
692
- must accept the previous step's state, and fallible steps must share an error
693
- type. The workflow's result must match `Either E T` when any step can fail, or
694
- `T` otherwise. The compiler adds the law `placeOrder composes its steps`: the
695
- native workflow must equal the railway composition of the native steps.
696
- Diagnostics name the step and the mismatched types, with the workflow's source
697
- location. See [domain modeling](docs/reference/language/domain-modeling.md).
698
-
699
- ### Evidence
700
-
701
- Constructor field constraints, including wrapper constraints, appear in the
702
- evidence as `construction` obligations with status `runtime-checked`, next to
703
- the contract obligations introduced in 0.12. The TypeScript API declares these
704
- records as `ObligationEvidence`; the 0.12 typing was not published.
705
-
706
- ### Examples and acceptance
707
-
708
- `examples/specs/domain_modeling.lawspec` combines wrappers, a parameterized
709
- `NonEmptyList`, order states and the workflow. It runs on all eight targets in
710
- both machine profiles. Correct adapters pass; mutants that break a wrapper
711
- invariant, the railway composition, or a non-empty list operation fail.
712
-
713
- ### Compatibility
714
-
715
- `wrapper` and `workflow` begin new declarations. Specifications that do not use
716
- them compile as in 0.12. API schemas 3 and 4 are unchanged, apart from the
717
- additive `construction` stage in `evidence`.
718
-
719
- ## 0.12.0
720
-
721
- ### Proved indices
722
-
723
- Checked definitions may return natural-indexed families, and the compiler
724
- proves their result indices statically:
725
-
726
- ```lawspec fragment
727
- definition concatV (xs :: Vec n Int8) (ys :: Vec m Int8) :: Vec (n + m) Int8 is
728
- match xs with
729
- | VNil -> ys
730
- | VCons h t -> VCons h (concatV t ys)
731
- end
732
- end
733
- ```
734
-
735
- The totality prover now treats calls of checked definitions as pure linear
736
- atoms, so equal calls have equal results. A single-argument definition that
737
- matches on its argument unfolds on a known constructor, so `nOfVec (VCons h t)`
738
- is `nOfVec t + 1`. Natural measures are non-negative. Together with the existing
739
- match facts and the induction hypothesis from recursive calls, this proves
740
- definitions such as `concatV`, and tree flattening through nested calls. It
741
- rejects definitions whose result indices do not follow, including an unchanged
742
- length, a dropped element, an extra element and a wrong recursive argument.
743
- See [proved indices](docs/reference/language/indexed-families.md#proved-indices).
744
-
745
- ### Evidence
746
-
747
- Every contract obligation is recorded as `proved` or `runtime-checked`.
748
- Definition postconditions are proved, and generated code on all eight targets no
749
- longer re-checks them at runtime. Definition preconditions, which guard native
750
- callers, and adapter contracts remain runtime-checked. `lawspec check` prints a
751
- summary, and API responses include an additive `evidence` array; see
752
- [API migration](docs/explanation/api-migration.md#evidence-0120).
753
-
754
- The indexed example now includes proved definitions `concatV` and `flattenV`,
755
- used as reference models for the native `append` and `flatten` adapters. The
756
- eight-target acceptance runner executes them in both machine profiles and still
757
- rejects every index-breaking adapter mutant.
758
-
759
- ### Compatibility
760
-
761
- Specifications that compiled with 0.11 compile unchanged. Generated definition
762
- code omits postcondition checks that are now proved, which changes generated
763
- output but not behavior. API schemas 3 and 4 are unchanged apart from the
764
- additive `evidence` field. Index equalities between sibling fields, non-linear
765
- indices and type-refining GADTs remain open; see the
766
- [current limits](docs/reference/language/index.md#current-limits).
767
-
768
- ## 0.11.0
769
-
770
- ### Natural-indexed families
771
-
772
- Data declarations may take `Natural` parameters, and each constructor states
773
- its index equation:
774
-
775
- ```lawspec fragment
776
- type Vec (n :: Natural) (a :: Type) is
777
- | VNil where n = 0
778
- | VCons head :: a tail :: Vec m a where n = m + 1
779
- end
780
-
781
- append :: (xs :: Vec n Int8) -> (ys :: Vec m Int8) -> (r :: Vec (n + m) Int8)
782
- ```
783
-
784
- A family elaborates before inference into ordinary erased data, a checked
785
- structural measure per index (`nOfVec`), and a refinement relating the measure
786
- to the index. Core and all eight emitters are unchanged. Native code works with
787
- the erased type, and every index claim is evidence checked at test time: a
788
- dependent result such as `Vec (n + m) Int8` is an adapter postcondition.
789
-
790
- An index variable that is otherwise unbound is implicit. The first binder whose
791
- family type mentions it determines it, and later occurrences read that binder's
792
- measure. Index expressions are sums of natural literals and index variables.
793
- `Natural` is also available as a value type. Diagnostics use the `indexed` code.
794
- See [indexed families](docs/reference/language/indexed-families.md).
795
-
796
- ### Index-directed generation
797
-
798
- A quantifier constrained by a linear structural measure, including a fixed index
799
- (`Vec 3 Int8`) or a shared one (`zip`'s second argument), is generated by solving
800
- the constructor equations backwards instead of filtering. Multi-field equations
801
- such as `Bin … where n = l + r + 1` split the remaining index across fields.
802
- Python, JavaScript, TypeScript, Java, Kotlin, Go, Haskell and Rust construct these
803
- values natively, and framework shrinking stays within the index. The same
804
- planning applies to user-written linear measures over declared data.
805
-
806
- `examples/specs/indexed_families.lawspec` runs on all eight targets. Correct
807
- adapters pass free, fixed and shared index laws; mutants that add, drop or lose
808
- elements fail their dependent contracts.
809
-
810
- ### Tower-polymorphic Integer results restored
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.
713
+ same JSON boundary that `core.wasm` exports.
714
+
715
+ ### Fixed
716
+
717
+ - A TypeScript scalar mutant counted as rejected because it failed
718
+ type-checking; it now exercises the laws.
719
+
720
+ ## [0.13.0] - 2026-09-29
721
+
722
+ ### Added
723
+
724
+ - `wrapper UnitQuantity is Int32 where value >= 1 && value <= 1000 end`
725
+ declares a distinct nominal type with one field, `value`, and an optional
726
+ constraint. Its constructor checks the constraint, so an invalid value
727
+ cannot be constructed in an example (the compiler rejects `UnitQuantity 0`),
728
+ produced by a generator, or decoded from native code. `valueOf<Name>`
729
+ unwraps a value. Wrappers may take type parameters (`wrapper NonEmptyList (a
730
+ :: Type) is List a where prelude.length value > 0 end`), and all eight
731
+ targets represent them natively.
732
+ - A `workflow` declares its steps as adapters and checks the pipeline: each
733
+ step must accept the previous step's state, and fallible steps must share an
734
+ error type. The workflow's result must match `Either E T` when any step can
735
+ fail, or `T` otherwise. The compiler adds the law `placeOrder composes its
736
+ steps`: the native workflow must equal the railway composition of the native
737
+ steps. Diagnostics name the step and the mismatched types, with the
738
+ workflow's source location. See
739
+ [domain modeling](docs/reference/language/domain-modeling.md).
740
+ - Constructor field constraints, including wrapper constraints, appear in the
741
+ evidence as `construction` obligations with status `runtime-checked`. The
742
+ TypeScript API declares these records as `ObligationEvidence`.
743
+ - `examples/specs/domain_modeling.lawspec` combines wrappers, a parameterized
744
+ `NonEmptyList`, order states and the workflow. It runs on all eight targets
745
+ in both machine profiles, with mutants for wrapper invariants, the railway
746
+ composition and non-empty list operations.
747
+
748
+ ### Changed
749
+
750
+ - `wrapper` and `workflow` begin new declarations. Specifications that do not
751
+ use them compile as in 0.12. API schemas 3 and 4 are unchanged, apart from
752
+ the additive `construction` stage in `evidence`.
753
+
754
+ ## [0.12.0] - 2026-09-29
755
+
756
+ ### Added
757
+
758
+ - Checked definitions may return natural-indexed families, and the compiler
759
+ proves their result indices statically, as in `definition concatV (xs :: Vec
760
+ n Int8) (ys :: Vec m Int8) :: Vec (n + m) Int8`. See
761
+ [proved indices](docs/reference/language/indexed-families.md#proved-indices).
762
+ - Every contract obligation is recorded as `proved` or `runtime-checked`.
763
+ `lawspec check` prints a summary, and API responses include an additive
764
+ `evidence` array; see
765
+ [API migration](docs/explanation/api-migration.md#evidence-0120).
766
+ - The indexed example includes proved definitions `concatV` and `flattenV`,
767
+ used as reference models for the native `append` and `flatten` adapters.
768
+
769
+ ### Changed
770
+
771
+ - The totality prover treats calls of checked definitions as pure linear
772
+ atoms, so equal calls have equal results. A single-argument definition that
773
+ matches on its argument unfolds on a known constructor, so `nOfVec (VCons h
774
+ t)` is `nOfVec t + 1`. Natural measures are non-negative. The prover rejects
775
+ definitions whose result indices do not follow.
776
+ - Definition postconditions are proved, and generated code on all eight
777
+ targets no longer re-checks them at runtime. This changes generated output
778
+ but not behavior. Definition preconditions and adapter contracts remain
779
+ runtime-checked.
780
+ - Specifications that compiled with 0.11 compile unchanged. API schemas 3 and
781
+ 4 are unchanged apart from the additive `evidence` field. See the
782
+ [current limits](docs/reference/language/index.md#current-limits).
783
+
784
+ ## [0.11.0] - 2026-09-29
785
+
786
+ ### Added
787
+
788
+ - Data declarations may take `Natural` parameters, and each constructor states
789
+ its index equation (`type Vec (n :: Natural) (a :: Type) is | VNil where n =
790
+ 0 | VCons head :: a tail :: Vec m a where n = m + 1 end`). Native code works
791
+ with the erased type, and every index claim is evidence checked at test
792
+ time: a dependent result such as `Vec (n + m) Int8` is an adapter
793
+ postcondition. An otherwise unbound index variable is implicit. Index
794
+ expressions are sums of natural literals and index variables. `Natural` is
795
+ also available as a value type. Diagnostics use the `indexed` code. See
796
+ [indexed families](docs/reference/language/indexed-families.md).
797
+ - A quantifier constrained by a linear structural measure, including a fixed
798
+ index (`Vec 3 Int8`) or a shared one, is generated by solving the
799
+ constructor equations backwards instead of filtering, natively on all eight
800
+ targets, and framework shrinking stays within the index. The same applies to
801
+ user-written linear measures over declared data.
802
+ - `examples/specs/indexed_families.lawspec` runs on all eight targets.
803
+
804
+ ### Fixed
805
+
806
+ - Kotlin and Haskell adapters whose result is the abstract `Integer` again
807
+ return `Number` (Kotlin) and `LS.IntegerValue` (Haskell), as in 0.8 and as
808
+ Java always did; 0.9 had narrowed them to `BigInteger` and `Integer`.
809
+ Adapters written against 0.9 or 0.10 stubs still compile.
810
+ - The Kotlin and Haskell target checks and the scalar mutation fixtures, which
811
+ had failed since 0.9, pass again.
812
+
813
+ ## [0.10.0] - 2026-09-29
814
+
815
+ ### Added
816
+
817
+ - Native bindings connect LawSpec products and sums to existing application
818
+ types on Java, Python, JavaScript, TypeScript, Go, Haskell, Kotlin and Rust:
819
+ constructor and field mappings, adapter declarations bound to existing
820
+ functions, or paired conversion hooks. See
821
+ [Bind native types and functions](docs/how-to/bind-native-types.md).
822
+ - Checked bridges compose through generic and recursive types and the
823
+ built-in containers. They preserve exact numeric values, Symbol identity and
824
+ distinct absence states. Invalid native inputs, results, generator samples
825
+ and shrink candidates fail with context.
826
+ - Native generator factories return their framework's generator: JetCheck,
827
+ Hypothesis, fast-check, Rapid, Hedgehog, Kotest or Proptest. Generic
828
+ factories receive child generators, and composition keeps native shrinking.
829
+ Explicit examples, boundaries and finite-domain enumeration still run.
830
+ - A factory can ignore an uninhabited parameter, as in `Phantom Empty`;
831
+ requesting a value from it fails generation instead of passing vacuously.
832
+ - Optional `stub: true` generator bindings create user-owned implementation
833
+ files. Regeneration preserves edits and reports changed factory signatures.
834
+ - API schema 4 for native binding requests. Go supports explicit import
835
+ aliases; Rust binds tests to the application library's type identities.
836
+ - `lawspec examples --example payments` exports a runnable project for every
837
+ target (`--target` selects one), with an application model, native
838
+ generator, configuration, build files and instructions. Re-exporting
839
+ preserves application edits.
840
+
841
+ ### Changed
842
+
843
+ - Schema 3 remains supported for specifications without bindings. Strict
844
+ configuration validation prevents older compilers from silently ignoring
845
+ mappings.
846
+ - Adopting a binding never overwrites existing adapter files: move their
847
+ implementations into the application module first. See the
848
+ [migration guide](docs/explanation/api-migration.md#native-bindings-schema-4-0100) and
849
+ [adopting bindings](docs/how-to/bind-native-types.md#adopt-bindings-in-an-existing-project).
850
+ - Python output follows PEP 8.
851
+
852
+ ## [0.9.0] - 2026-09-28
853
+
854
+ ### Added
855
+
856
+ - `List a` with nested contextual literals, structural equality, exact
857
+ length, deterministic boundaries, and native framework generation and
858
+ shrinking.
859
+ - Algebraic `Maybe a` and `Either a b`, with `Nothing`/`Just` and
860
+ `Left`/`Right`, distinct from interoperability `Nullable` and `Optional`.
861
+ - Named parameterized products and sums with constructors and ordered fields,
862
+ preserved by generated native types and typed adapters.
863
+ - Total definitions with exhaustive matching and checked structural recursion.
905
864
  The compiler rejects partial matches and recursion it cannot establish as
906
865
  terminating. Generic definitions specialize to their concrete uses.
907
866
  - Refined definition signatures become executable native contracts. Scoped
908
- payload predicates preserve type-parameter roles through recursive and mutual
909
- data declarations, including predicates that depend on preceding inputs.
910
-
911
- Existing scalar semantics remain intact: exact arithmetic does not wrap,
912
- conversions to bounded adapter parameters are checked, floating equality follows
913
- IEEE rules, and Symbol equality uses identity.
914
-
915
- ### Generated output
916
-
917
- Readable code is the default for runtimes, declarations, definitions, adapters,
918
- tests, and scaffolds. Explicit `--minify` selects compact output for `init`,
919
- `generate`, and `examples`; the compiler API accepts `minify: true`.
920
-
921
- Output follows Google language-specific guidance where applicable, PEP 8 for
922
- Python, standard Go and Rust formatting, and an 80-column Haskell layout.
923
- Formatting is deterministic in both native and WASM compilation and requires
924
- no formatter download. Compact output preserves required layout, literal
925
- contents, and semantics. Changing formatting mode does not overwrite edited
926
- adapters or create false adapter-signature updates.
927
-
928
- ### API and compatibility
929
-
930
- API schema 3 adds named data declarations, structural values, checked definitions,
931
- construction/matching expressions, and scoped payload predicates. Existing scalar
932
- wire encodings are unchanged. Exhaustive expression visitors must handle the
933
- new variants; see [API migration](docs/explanation/api-migration.md#structural-data-and-definitions-090).
934
-
935
- Java 25+, Python 3.13+, Node 22+, and Rust 1.85+ baselines remain unchanged.
936
- Machine-width profiles, custom source/test directories, generation manifests,
937
- and user ownership of adapters/build files remain supported. Framework-specific
938
- strategies stay separate from reusable runtime source.
939
-
940
- ### Examples and release acceptance
941
-
942
- Bundled examples cover reverse involution, sorting idempotence/sortedness/length/
943
- permutation, nested presence, products/sums, exhaustive matches, total functions,
944
- and recursive payload refinements. Release acceptance includes compiler and
945
- native/WASM checks, native execution on all eight targets, deliberately incorrect
946
- adapters, independent formatting/syntax checks, regeneration protection, and
947
- installation of the packed npm artifact.
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.
867
+ payload predicates preserve type-parameter roles through recursive and
868
+ mutual data declarations, including predicates that depend on preceding
869
+ inputs.
870
+ - `--minify` selects compact output for `init`, `generate` and `examples`; the
871
+ compiler API accepts `minify: true`.
872
+ - API schema 3 adds named data declarations, structural values, checked
873
+ definitions, construction and matching expressions, and scoped payload
874
+ predicates. Exhaustive expression visitors must handle the new variants; see
875
+ [API migration](docs/explanation/api-migration.md#structural-data-and-definitions-090).
876
+ - Bundled examples for reverse involution, sorting, nested presence, products
877
+ and sums, exhaustive matches, total functions and recursive payload
878
+ refinements.
879
+
880
+ ### Changed
881
+
882
+ - Readable code is the default for runtimes, declarations, definitions,
883
+ adapters, tests and scaffolds. Output follows Google language-specific
884
+ guidance where applicable, PEP 8 for Python, standard Go and Rust
885
+ formatting, and an 80-column Haskell layout. Formatting is deterministic in
886
+ native and WASM compilation and needs no formatter download. Changing the
887
+ formatting mode does not overwrite edited adapters or create false
888
+ adapter-signature updates.
889
+
890
+ ## [0.8.0] - 2026-09-25
891
+
892
+ ### Added
893
+
894
+ - Rust 2024, with Rust 1.85 as the minimum toolchain, Cargo scaffolding,
895
+ Proptest generation and shrinking, the complete scalar catalog, refinements
896
+ and contracts. See [Rust](docs/how-to/targets/rust.md).
897
+ - An independent numeric Rust runtime with owned native bridges, exact
898
+ arithmetic, checked conversions, direct IEEE rounding, raw text, Symbol
899
+ identity and distinct nested absence states.
900
+ - A typed core and proposition tree shared by all eight emitters.
901
+ - An independent core validator and evaluator. Testing plans distinguish
902
+ semantic validity from execution feasibility and preserve dependent
903
+ refinement domains.
904
+ - API schema v3 with explicit wire views and unchanged lossless scalar
905
+ encodings. See
906
+ [API migration](docs/explanation/api-migration.md#schema-2-to-schema-3-080).
968
907
  - Rust module wiring, custom layouts, Cargo preflight, adapter preservation,
969
- generation manifests, bundled examples, and installed-package coverage.
970
- - Exact algebra and numeric currying examples. Logical `Integer` replaces their
971
- former modular Int32 contracts. Examples cover Int32 overflow, large products,
972
- Int32-minimum negation, and values beyond machine/safe-number bounds; deliberately
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).
908
+ generation manifests, bundled examples and installed-package coverage.
909
+ - Exact algebra and numeric currying examples, covering Int32 overflow, large
910
+ products, Int32-minimum negation, and values beyond machine and safe-number
911
+ bounds.
978
912
 
979
- ### Compatibility and scope
913
+ ### Changed
980
914
 
981
- Java 25+, Python 3.13+, and Node 22+ baselines remain unchanged. Existing LawSpec
982
- source remains compatible. API clients must migrate to schema v3. All nonempty
983
- plans emit scalar runtime source; existing Haskell projects need direct `text`
984
- and `bytestring` dependencies in the component compiling that source. Build
985
- files and implementation adapters remain user-owned.
986
-
987
- Machine-sized domains use an explicit 32/64-bit profile. Native machine-sized
988
- bindings reject an architecture mismatch. Rust adapters take owned values;
989
- borrowing/lifetimes do not become LawSpec language constructs.
915
+ - API clients must migrate to schema v3; explicit schema-v2 requests receive a
916
+ migration diagnostic.
917
+ - Logical `Integer` replaces the examples' former modular Int32 contracts;
918
+ wrapping adapters are rejected on every target.
919
+ - All nonempty plans emit scalar runtime source; existing Haskell projects
920
+ need direct `text` and `bytestring` dependencies in the component compiling
921
+ that source.
922
+ - Machine-sized domains use an explicit 32/64-bit profile, and native
923
+ machine-sized bindings reject an architecture mismatch. Rust adapters take
924
+ owned values.
925
+
926
+ [Unreleased]: https://github.com/brain-fuel/lawspec/compare/v0.20.1...HEAD
927
+ [0.20.1]: https://github.com/brain-fuel/lawspec/compare/v0.20.0...v0.20.1
928
+ [0.20.0]: https://github.com/brain-fuel/lawspec/compare/v0.19.1...v0.20.0
929
+ [0.19.1]: https://github.com/brain-fuel/lawspec/compare/v0.19.0...v0.19.1
930
+ [0.19.0]: https://github.com/brain-fuel/lawspec/compare/v0.18.0...v0.19.0
931
+ [0.18.0]: https://github.com/brain-fuel/lawspec/compare/v0.17.5...v0.18.0
932
+ [0.17.5]: https://github.com/brain-fuel/lawspec/compare/v0.17.4...v0.17.5
933
+ [0.17.4]: https://github.com/brain-fuel/lawspec/compare/v0.17.3...v0.17.4
934
+ [0.17.3]: https://github.com/brain-fuel/lawspec/compare/v0.17.2...v0.17.3
935
+ [0.17.2]: https://github.com/brain-fuel/lawspec/compare/v0.17.1...v0.17.2
936
+ [0.17.1]: https://github.com/brain-fuel/lawspec/compare/v0.17.0...v0.17.1
937
+ [0.17.0]: https://github.com/brain-fuel/lawspec/compare/v0.16.0...v0.17.0
938
+ [0.16.0]: https://github.com/brain-fuel/lawspec/compare/v0.15.2...v0.16.0
939
+ [0.15.2]: https://github.com/brain-fuel/lawspec/compare/v0.15.1...v0.15.2
940
+ [0.15.1]: https://github.com/brain-fuel/lawspec/compare/v0.15.0...v0.15.1
941
+ [0.15.0]: https://github.com/brain-fuel/lawspec/compare/v0.14.0...v0.15.0
942
+ [0.14.0]: https://github.com/brain-fuel/lawspec/compare/v0.13.2...v0.14.0
943
+ [0.13.2]: https://github.com/brain-fuel/lawspec/compare/v0.13.1...v0.13.2
944
+ [0.13.1]: https://github.com/brain-fuel/lawspec/compare/v0.13.0...v0.13.1
945
+ [0.13.0]: https://github.com/brain-fuel/lawspec/compare/v0.12.0...v0.13.0
946
+ [0.12.0]: https://github.com/brain-fuel/lawspec/compare/v0.11.0...v0.12.0
947
+ [0.11.0]: https://github.com/brain-fuel/lawspec/compare/v0.10.0...v0.11.0
948
+ [0.10.0]: https://github.com/brain-fuel/lawspec/compare/v0.9.0...v0.10.0
949
+ [0.9.0]: https://github.com/brain-fuel/lawspec/compare/4bf7fe5...v0.9.0
950
+ [0.8.0]: https://github.com/brain-fuel/lawspec/compare/v0.7.0...4bf7fe5