lawspec 0.14.0 → 0.15.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 +501 -0
- package/README.md +60 -728
- package/api.mjs +1 -1
- package/bin/lawspec.mjs +46 -6
- package/build.json +18 -18
- package/core.wasm +0 -0
- package/doctor.mjs +1 -0
- package/examples-command.mjs +1 -0
- package/files.mjs +1 -0
- package/index.d.ts +18 -1
- package/launcher.mjs +26 -16
- package/native-examples.mjs +1 -0
- package/package.json +33 -6
- package/read-only-hpack.mjs +1 -0
- package/scalars.mjs +1 -0
- package/templates.mjs +112 -219
- package/API-MIGRATION.md +0 -320
- package/GO.md +0 -144
- package/HASKELL.md +0 -172
- package/JAVA.md +0 -113
- package/KOTLIN.md +0 -219
- package/LANGUAGE.md +0 -646
- package/NATIVE-BINDINGS.md +0 -1051
- package/PRIMITIVES.md +0 -150
- package/PYTHON.md +0 -152
- package/REFINEMENTS.md +0 -449
- package/RELEASE-0.10.md +0 -60
- package/RELEASE-0.11.md +0 -62
- package/RELEASE-0.12.md +0 -47
- package/RELEASE-0.13.md +0 -97
- package/RELEASE-0.14.md +0 -52
- package/RELEASE-0.9.md +0 -61
- package/RUST.md +0 -211
- package/WEB.md +0 -144
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,501 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.15.1
|
|
4
|
+
|
|
5
|
+
A maintenance release. The language and generated code are unchanged.
|
|
6
|
+
|
|
7
|
+
- **Documentation** moves into a [Diátaxis](https://diataxis.fr) site in
|
|
8
|
+
`docs/`: tutorials, how-to guides, reference and explanation. It replaces the
|
|
9
|
+
README's version-history sections, the per-target guides, `LANGUAGE.md`,
|
|
10
|
+
`NATIVE-BINDINGS.md`, `PRIMITIVES.md`, `REFINEMENTS.md`, `API-MIGRATION.md`
|
|
11
|
+
and the separate release notes, which this changelog now collects.
|
|
12
|
+
- **Lessons.** Eight tutorials build a coffee shop's ordering system, in Java,
|
|
13
|
+
Python and JavaScript tracks. Each lesson's specification is editable and
|
|
14
|
+
compiles in the browser, and the JavaScript tests run in the page. The lesson
|
|
15
|
+
implementations are a new acceptance suite, `lessons`, with a mutant per
|
|
16
|
+
lesson on each of the three targets.
|
|
17
|
+
- **The site** is static and built with `make docs`: `make docs-serve` previews
|
|
18
|
+
it and `make docs-deploy` deploys it to Cloudflare Pages. It runs the npm
|
|
19
|
+
package's `core.wasm` through a browser launcher with a minimal WASI shim,
|
|
20
|
+
and highlights LawSpec and every target language, in the editor too. Every
|
|
21
|
+
example is an editable sandbox: **Check** shows each law's evidence, and
|
|
22
|
+
lessons' **▶ Run** runs the generated JavaScript or TypeScript tests against
|
|
23
|
+
an editable implementation in an isolated frame, reporting each law's
|
|
24
|
+
examples, boundary cases and generated cases. Generated tests are read-only.
|
|
25
|
+
The `lessons` acceptance suite also covers TypeScript.
|
|
26
|
+
- **Evidence.** A law whose equation compares two Boolean expressions now shows
|
|
27
|
+
its claim as written (`isWeekend d == (d == 0 || d == 6)`), not as the
|
|
28
|
+
equivalence the prover uses.
|
|
29
|
+
- **Generated JavaScript.** Every JavaScript file in the repository is generated
|
|
30
|
+
from `templates/` by `lawspec-dev generate`, with the version, targets,
|
|
31
|
+
scaffolds and test commands filled in from the Haskell sources. The
|
|
32
|
+
compiler's own facts are no longer copied by hand into the npm CLI.
|
|
33
|
+
- **Development.** 121 unmaintained integration scripts, most of which needed
|
|
34
|
+
manual setup and no longer ran, are removed; the acceptance suites and the
|
|
35
|
+
Hspec tests cover what they did. The TypeScript API type check becomes an npm
|
|
36
|
+
test. The Makefile covers every task (`make` lists them), `lawspec-dev bump`
|
|
37
|
+
sets the version everywhere, and `RELEASING.md` documents the release.
|
|
38
|
+
- The npm package ships `README.md`, `CHANGELOG.md` and `LICENSE`; the
|
|
39
|
+
documentation is online.
|
|
40
|
+
|
|
41
|
+
## 0.15.0
|
|
42
|
+
|
|
43
|
+
### Evidence and discharge
|
|
44
|
+
|
|
45
|
+
Every obligation of a program reports how it is discharged, strongest first:
|
|
46
|
+
|
|
47
|
+
- `proved`: statically. Definition postconditions and indices, as since 0.12,
|
|
48
|
+
and now laws that call only checked definitions.
|
|
49
|
+
- `exhaustively-checked`: every input of a finite domain, by the compiler for
|
|
50
|
+
laws over checked definitions and otherwise by the generated tests. A law with
|
|
51
|
+
no inputs is a single case.
|
|
52
|
+
- `property-tested`: generated cases, boundary cases and examples.
|
|
53
|
+
- `runtime-checked`: adapter contracts, definition preconditions, constructor
|
|
54
|
+
constraints and native type bindings, at every native boundary.
|
|
55
|
+
- `assumed`: adapters, native functions, custom generators and codec hooks,
|
|
56
|
+
taken on trust. Each adapter reports how many laws call it, or that none does.
|
|
57
|
+
|
|
58
|
+
`lawspec check` summarizes the obligations by status, and the new
|
|
59
|
+
`lawspec evidence` lists each with its claim and reason (`--json` for the API
|
|
60
|
+
records, and a unit or `unit::declaration` filter). See
|
|
61
|
+
[evidence and discharge](docs/reference/language/evidence-and-discharge.md).
|
|
62
|
+
|
|
63
|
+
### Laws proved and refuted by the compiler
|
|
64
|
+
|
|
65
|
+
A law over checked definitions is attempted as a proof by the same exact linear
|
|
66
|
+
arithmetic that proves definition results, from its input refinements, with
|
|
67
|
+
definitions that have no preconditions unfolded into the claim. When it is not
|
|
68
|
+
proved and its domain is finite, the compiler evaluates every input; a
|
|
69
|
+
counterexample is a compile error with code `refuted`, such as
|
|
70
|
+
`law always positive is false for x = -128`. Specifications that compiled
|
|
71
|
+
before may therefore be rejected if a law over definitions is false.
|
|
72
|
+
|
|
73
|
+
The prover also handles constant factors on integer expressions (`x * 2`),
|
|
74
|
+
which it previously treated as non-linear, so more definition results are
|
|
75
|
+
proved.
|
|
76
|
+
|
|
77
|
+
### API
|
|
78
|
+
|
|
79
|
+
`evidence` items have the five statuses above and new stages: `law`,
|
|
80
|
+
`adapter`, and, with native bindings, `binding`, `codec`, `generator` and
|
|
81
|
+
`native-function`. `claim` is `null` for obligations without one. The
|
|
82
|
+
TypeScript API declares `ObligationEvidence` and `DischargeStatus`. See
|
|
83
|
+
[API migration](docs/explanation/api-migration.md#evidence-and-discharge-0150).
|
|
84
|
+
|
|
85
|
+
## 0.14.0
|
|
86
|
+
|
|
87
|
+
### Imports
|
|
88
|
+
|
|
89
|
+
```lawspec fragment
|
|
90
|
+
unit shop.orders
|
|
91
|
+
import shop.domain as domain (Money, Cents, `commutative`)
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
A unit imports other units by name. Every declaration of an imported unit is
|
|
95
|
+
available through the alias (`domain.Usd`, `domain.centsOf`), and listed names
|
|
96
|
+
also unqualified. Types, wrappers, indexed families, refinements, checked
|
|
97
|
+
definitions and generic laws can be imported. Adapters and concrete laws stay
|
|
98
|
+
with their unit. Import cycles, unknown units and missing or ambiguous names are
|
|
99
|
+
reported at the import, with the reason: an adapter, a constructor listed
|
|
100
|
+
without its type, or a law without parameters.
|
|
101
|
+
|
|
102
|
+
Names are scoped to their unit, so units compiled together no longer need
|
|
103
|
+
distinct constructor names. Targets with one data namespace (Python,
|
|
104
|
+
JavaScript, TypeScript, Go and Haskell) name colliding types after their unit,
|
|
105
|
+
`ShopDomainCurrency` and `ShopOrdersCurrency`, and their constructors
|
|
106
|
+
`ShopDomainCurrencyUsd`. Java, Kotlin and Rust qualify only the type. Earlier
|
|
107
|
+
versions qualified only the colliding names, for example
|
|
108
|
+
`ShopDomainTypeCurrencyUsd` next to `CurrencyEur`.
|
|
109
|
+
|
|
110
|
+
Imports are resolved before type checking, like indexed families and domain
|
|
111
|
+
models, so Core and the eight backends are unchanged.
|
|
112
|
+
|
|
113
|
+
### Packages
|
|
114
|
+
|
|
115
|
+
A `lawspec-package.json` names a package, its version, its source directories
|
|
116
|
+
and the version ranges of its dependencies. Package units are named after the
|
|
117
|
+
package, a unit imports only from its own package and direct dependencies, and
|
|
118
|
+
every range must accept the supplied version. A project lists `dependencies` and
|
|
119
|
+
the `packages` directories in `lawspec.json`. A package's adapters and laws are a
|
|
120
|
+
published contract: dependent projects implement and test them as their own.
|
|
121
|
+
`lawspec package` checks a package and summarizes it. See
|
|
122
|
+
[imports and packages](docs/reference/language/imports-and-packages.md).
|
|
123
|
+
|
|
124
|
+
The compiler API accepts `dependencies`, `packages` and `package`, and reports
|
|
125
|
+
the resolved packages (see
|
|
126
|
+
[API migration](docs/explanation/api-migration.md#imports-and-packages-0140)).
|
|
127
|
+
|
|
128
|
+
### Other changes
|
|
129
|
+
|
|
130
|
+
- Rust: a law without quantified inputs no longer emits an untyped empty case
|
|
131
|
+
vector, which did not compile.
|
|
132
|
+
- The VS Code grammar highlights `import` and `as`.
|
|
133
|
+
- A new acceptance suite, `packages`, runs the
|
|
134
|
+
[package example](examples/packages) on all eight targets in both machine
|
|
135
|
+
profiles and rejects five adapter mutants plus the bare stubs. `lawspec-dev ci`
|
|
136
|
+
includes it.
|
|
137
|
+
|
|
138
|
+
## 0.13.2
|
|
139
|
+
|
|
140
|
+
A maintenance release. The language, generated code and API are unchanged.
|
|
141
|
+
|
|
142
|
+
- The repository has no hosted CI. `stack run lawspec-dev -- ci` runs the
|
|
143
|
+
complete check locally: compiler, npm, parity, package and editor checks, then
|
|
144
|
+
for each target the dependency bootstrap, every acceptance suite in both
|
|
145
|
+
machine profiles, and the installed native-binding example. It logs each step to
|
|
146
|
+
`.artifacts/ci/` and exits non-zero on any failure. `--target`, `--core`,
|
|
147
|
+
`--fail-fast`, `--rust-toolchains` and `--rust-targets` select what to run.
|
|
148
|
+
`make ci` is equivalent.
|
|
149
|
+
- The JavaScript acceptance runners and fixture modules replaced by
|
|
150
|
+
`lawspec-acceptance` are removed.
|
|
151
|
+
- The package smoke test's per-command timeout is ten minutes: exporting every
|
|
152
|
+
bundled example had exceeded the former two-minute limit on slower machines.
|
|
153
|
+
- The integration bootstrap restores missing scaffold files in existing projects.
|
|
154
|
+
|
|
155
|
+
## 0.13.1
|
|
156
|
+
|
|
157
|
+
A maintenance release. The language, generated code and API are unchanged from
|
|
158
|
+
0.13.0.
|
|
159
|
+
|
|
160
|
+
- Repository checks move from JavaScript to Haskell. `lawspec-dev boundaries` and
|
|
161
|
+
`lawspec-dev integrity` replace `tools/check-boundaries.mjs` and
|
|
162
|
+
`tools/build-integrity.mjs`. The integrity check now also rejects staged npm
|
|
163
|
+
copies of documentation and examples that differ from their sources.
|
|
164
|
+
- `lawspec-acceptance` runs the bundled-example acceptance suites
|
|
165
|
+
(`integration`, `algebra`, `scalar`, `refinement`, `indexed`, `domain`) in
|
|
166
|
+
process. Adapters and mutants are real files under `acceptance/`, and a
|
|
167
|
+
mutant that only breaks the build now fails the suite. This exposed a
|
|
168
|
+
TypeScript scalar mutant that previously counted as rejected because it
|
|
169
|
+
failed type-checking; it now exercises the laws.
|
|
170
|
+
- Build-file scaffolds are defined once in Haskell (`LawSpec.Scaffold`) and
|
|
171
|
+
checked against the npm templates byte for byte.
|
|
172
|
+
- Compiler API contract tests formerly in `npm/test` run in hspec against the
|
|
173
|
+
same JSON boundary that `core.wasm` exports. A new npm test checks that
|
|
174
|
+
generation never rewrites build files and that regeneration is a no-op on
|
|
175
|
+
every target.
|
|
176
|
+
|
|
177
|
+
## 0.13.0
|
|
178
|
+
|
|
179
|
+
### Wrappers and constrained primitives
|
|
180
|
+
|
|
181
|
+
```lawspec fragment
|
|
182
|
+
wrapper UnitQuantity is Int32 where value >= 1 && value <= 1000 end
|
|
183
|
+
wrapper NonEmptyList (a :: Type) is List a where prelude.length value > 0 end
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
A wrapper declares a distinct nominal type with one field, `value`, and an
|
|
187
|
+
optional constraint. Its constructor checks the constraint, so an invalid value
|
|
188
|
+
cannot be constructed in an example (the compiler rejects `UnitQuantity 0`),
|
|
189
|
+
produced by a generator, or decoded from native code. `valueOf<Name>` unwraps a
|
|
190
|
+
value. Wrappers may take type parameters. They elaborate to a single-constructor
|
|
191
|
+
product with a refined field, so all eight targets represent them natively with
|
|
192
|
+
no new runtime machinery.
|
|
193
|
+
|
|
194
|
+
### Workflows and state distinctions
|
|
195
|
+
|
|
196
|
+
```lawspec fragment
|
|
197
|
+
workflow placeOrder :: UnvalidatedOrder -> Either OrderError PricedOrder is
|
|
198
|
+
validateOrder :: UnvalidatedOrder -> Either OrderError ValidatedOrder
|
|
199
|
+
priceOrder :: ValidatedOrder -> Either OrderError PricedOrder
|
|
200
|
+
end
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
A workflow declares its steps as adapters and checks the pipeline: each step
|
|
204
|
+
must accept the previous step's state, and fallible steps must share an error
|
|
205
|
+
type. The workflow's result must match `Either E T` when any step can fail, or
|
|
206
|
+
`T` otherwise. The compiler adds the law `placeOrder composes its steps`: the
|
|
207
|
+
native workflow must equal the railway composition of the native steps.
|
|
208
|
+
Diagnostics name the step and the mismatched types, with the workflow's source
|
|
209
|
+
location. See [domain modeling](docs/reference/language/domain-modeling.md).
|
|
210
|
+
|
|
211
|
+
### Evidence
|
|
212
|
+
|
|
213
|
+
Constructor field constraints, including wrapper constraints, appear in the
|
|
214
|
+
evidence as `construction` obligations with status `runtime-checked`, next to
|
|
215
|
+
the contract obligations introduced in 0.12. The TypeScript API declares these
|
|
216
|
+
records as `ObligationEvidence`; the 0.12 typing was not published.
|
|
217
|
+
|
|
218
|
+
### Examples and acceptance
|
|
219
|
+
|
|
220
|
+
`examples/specs/domain_modeling.lawspec` combines wrappers, a parameterized
|
|
221
|
+
`NonEmptyList`, order states and the workflow. It runs on all eight targets in
|
|
222
|
+
both machine profiles. Correct adapters pass; mutants that break a wrapper
|
|
223
|
+
invariant, the railway composition, or a non-empty list operation fail.
|
|
224
|
+
|
|
225
|
+
### Compatibility
|
|
226
|
+
|
|
227
|
+
`wrapper` and `workflow` begin new declarations. Specifications that do not use
|
|
228
|
+
them compile as in 0.12. API schemas 3 and 4 are unchanged, apart from the
|
|
229
|
+
additive `construction` stage in `evidence`.
|
|
230
|
+
|
|
231
|
+
## 0.12.0
|
|
232
|
+
|
|
233
|
+
### Proved indices
|
|
234
|
+
|
|
235
|
+
Checked definitions may return natural-indexed families, and the compiler
|
|
236
|
+
proves their result indices statically:
|
|
237
|
+
|
|
238
|
+
```lawspec fragment
|
|
239
|
+
definition concatV (xs :: Vec n Int8) (ys :: Vec m Int8) :: Vec (n + m) Int8 is
|
|
240
|
+
match xs with
|
|
241
|
+
| VNil -> ys
|
|
242
|
+
| VCons h t -> VCons h (concatV t ys)
|
|
243
|
+
end
|
|
244
|
+
end
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
The totality prover now treats calls of checked definitions as pure linear
|
|
248
|
+
atoms, so equal calls have equal results. A single-argument definition that
|
|
249
|
+
matches on its argument unfolds on a known constructor, so `nOfVec (VCons h t)`
|
|
250
|
+
is `nOfVec t + 1`. Natural measures are non-negative. Together with the existing
|
|
251
|
+
match facts and the induction hypothesis from recursive calls, this proves
|
|
252
|
+
definitions such as `concatV`, and tree flattening through nested calls. It
|
|
253
|
+
rejects definitions whose result indices do not follow, including an unchanged
|
|
254
|
+
length, a dropped element, an extra element and a wrong recursive argument.
|
|
255
|
+
See [proved indices](docs/reference/language/indexed-families.md#proved-indices).
|
|
256
|
+
|
|
257
|
+
### Evidence
|
|
258
|
+
|
|
259
|
+
Every contract obligation is recorded as `proved` or `runtime-checked`.
|
|
260
|
+
Definition postconditions are proved, and generated code on all eight targets no
|
|
261
|
+
longer re-checks them at runtime. Definition preconditions, which guard native
|
|
262
|
+
callers, and adapter contracts remain runtime-checked. `lawspec check` prints a
|
|
263
|
+
summary, and API responses include an additive `evidence` array; see
|
|
264
|
+
[API migration](docs/explanation/api-migration.md#evidence-0120).
|
|
265
|
+
|
|
266
|
+
The indexed example now includes proved definitions `concatV` and `flattenV`,
|
|
267
|
+
used as reference models for the native `append` and `flatten` adapters. The
|
|
268
|
+
eight-target acceptance runner executes them in both machine profiles and still
|
|
269
|
+
rejects every index-breaking adapter mutant.
|
|
270
|
+
|
|
271
|
+
### Compatibility
|
|
272
|
+
|
|
273
|
+
Specifications that compiled with 0.11 compile unchanged. Generated definition
|
|
274
|
+
code omits postcondition checks that are now proved, which changes generated
|
|
275
|
+
output but not behavior. API schemas 3 and 4 are unchanged apart from the
|
|
276
|
+
additive `evidence` field. Index equalities between sibling fields, non-linear
|
|
277
|
+
indices and type-refining GADTs remain open; see the
|
|
278
|
+
[current limits](docs/reference/language/index.md#current-limits).
|
|
279
|
+
|
|
280
|
+
## 0.11.0
|
|
281
|
+
|
|
282
|
+
### Natural-indexed families
|
|
283
|
+
|
|
284
|
+
Data declarations may take `Natural` parameters, and each constructor states
|
|
285
|
+
its index equation:
|
|
286
|
+
|
|
287
|
+
```lawspec fragment
|
|
288
|
+
type Vec (n :: Natural) (a :: Type) is
|
|
289
|
+
| VNil where n = 0
|
|
290
|
+
| VCons head :: a tail :: Vec m a where n = m + 1
|
|
291
|
+
end
|
|
292
|
+
|
|
293
|
+
append :: (xs :: Vec n Int8) -> (ys :: Vec m Int8) -> (r :: Vec (n + m) Int8)
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
A family elaborates before inference into ordinary erased data, a checked
|
|
297
|
+
structural measure per index (`nOfVec`), and a refinement relating the measure
|
|
298
|
+
to the index. Core and all eight emitters are unchanged. Native code works with
|
|
299
|
+
the erased type, and every index claim is evidence checked at test time: a
|
|
300
|
+
dependent result such as `Vec (n + m) Int8` is an adapter postcondition.
|
|
301
|
+
|
|
302
|
+
An index variable that is otherwise unbound is implicit. The first binder whose
|
|
303
|
+
family type mentions it determines it, and later occurrences read that binder's
|
|
304
|
+
measure. Index expressions are sums of natural literals and index variables.
|
|
305
|
+
`Natural` is also available as a value type. Diagnostics use the `indexed` code.
|
|
306
|
+
See [indexed families](docs/reference/language/indexed-families.md).
|
|
307
|
+
|
|
308
|
+
### Index-directed generation
|
|
309
|
+
|
|
310
|
+
A quantifier constrained by a linear structural measure, including a fixed index
|
|
311
|
+
(`Vec 3 Int8`) or a shared one (`zip`'s second argument), is generated by solving
|
|
312
|
+
the constructor equations backwards instead of filtering. Multi-field equations
|
|
313
|
+
such as `Bin … where n = l + r + 1` split the remaining index across fields.
|
|
314
|
+
Python, JavaScript, TypeScript, Java, Kotlin, Go, Haskell and Rust construct these
|
|
315
|
+
values natively, and framework shrinking stays within the index. The same
|
|
316
|
+
planning applies to user-written linear measures over declared data.
|
|
317
|
+
|
|
318
|
+
`examples/specs/indexed_families.lawspec` runs on all eight targets. Correct
|
|
319
|
+
adapters pass free, fixed and shared index laws; mutants that add, drop or lose
|
|
320
|
+
elements fail their dependent contracts.
|
|
321
|
+
|
|
322
|
+
### Tower-polymorphic Integer results restored
|
|
323
|
+
|
|
324
|
+
0.9 had narrowed Kotlin and Haskell adapters whose result is the abstract
|
|
325
|
+
`Integer` to `BigInteger` and `Integer`. They again return `Number` (Kotlin) and
|
|
326
|
+
`LS.IntegerValue` (Haskell), as in 0.8 and as Java always did. `Integer` is the top
|
|
327
|
+
of the integral tower: an implementation may return any integral native value,
|
|
328
|
+
and the result bridge rejects non-integral values and checks the logical domain.
|
|
329
|
+
Adapters written against 0.9 or 0.10 stubs that return `BigInteger` or `Integer`
|
|
330
|
+
still compile, because both are integral.
|
|
331
|
+
|
|
332
|
+
This regression had kept the Kotlin and Haskell target checks failing since
|
|
333
|
+
0.9. Those checks, and the scalar mutation fixtures, now pass with the documented
|
|
334
|
+
typed Symbol, Decimal, Utf16Text and Optional representations.
|
|
335
|
+
|
|
336
|
+
### Compatibility
|
|
337
|
+
|
|
338
|
+
Specifications without indexed families generate the same code as 0.10, apart
|
|
339
|
+
from the Integer result signatures above. API schemas 3 and 4 are unchanged.
|
|
340
|
+
GADTs that refine type arguments, non-linear indices and index equalities between
|
|
341
|
+
sibling fields remain future work.
|
|
342
|
+
|
|
343
|
+
## 0.10.0
|
|
344
|
+
|
|
345
|
+
### Existing application models
|
|
346
|
+
|
|
347
|
+
Native bindings connect LawSpec products and sums to existing application types
|
|
348
|
+
on Java, Python, JavaScript, TypeScript, Go, Haskell, Kotlin and Rust. Configure
|
|
349
|
+
constructor and field mappings, bind adapter declarations to existing functions,
|
|
350
|
+
or supply paired conversion hooks for representations requiring custom code.
|
|
351
|
+
Bindings resolve against typed declaration identities; they do not change the
|
|
352
|
+
meaning of arithmetic, equality, definitions or refinements. See
|
|
353
|
+
[Bind native types and functions](docs/how-to/bind-native-types.md).
|
|
354
|
+
|
|
355
|
+
Checked bridges compose through generic and recursive types and the built-in
|
|
356
|
+
containers. They preserve exact numeric values, Symbol identity and distinct
|
|
357
|
+
absence states. Invalid native inputs, results, generator samples and shrink
|
|
358
|
+
candidates fail with context.
|
|
359
|
+
|
|
360
|
+
### Native generators
|
|
361
|
+
|
|
362
|
+
Factories return their framework's generator: JetCheck, Hypothesis, fast-check,
|
|
363
|
+
Rapid, Hedgehog, Kotest or Proptest. Generic factories receive child generators.
|
|
364
|
+
Composition retains native shrinking. Explicit examples, deterministic boundaries
|
|
365
|
+
and finite-domain enumeration still run when the factory's distribution excludes
|
|
366
|
+
those values.
|
|
367
|
+
|
|
368
|
+
A factory can ignore an uninhabited parameter, as in `Phantom Empty`. Requesting a
|
|
369
|
+
value from that parameter fails generation; it cannot turn a property into a
|
|
370
|
+
vacuous success. Finite inhabited containers such as `List Empty` still enumerate.
|
|
371
|
+
|
|
372
|
+
Optional `stub: true` generator bindings create user-owned implementation files.
|
|
373
|
+
Regeneration preserves edits and reports changed factory signatures for review.
|
|
374
|
+
|
|
375
|
+
### API and migration
|
|
376
|
+
|
|
377
|
+
Native binding requests negotiate schema 4. Schema 3 remains supported for
|
|
378
|
+
specifications without bindings. Structured native references and strict
|
|
379
|
+
configuration validation prevent older compilers from silently ignoring mappings.
|
|
380
|
+
Go additionally supports explicit import aliases; Rust binds tests to the
|
|
381
|
+
application library's type identities.
|
|
382
|
+
|
|
383
|
+
Existing adapter files cannot be overwritten by adopting a binding. Move their
|
|
384
|
+
implementations into the application module and save the old adapters before
|
|
385
|
+
generation. Generated source bridges, test helpers and user-owned application
|
|
386
|
+
files retain separate placement and ownership. See the
|
|
387
|
+
[migration guide](docs/explanation/api-migration.md#native-bindings-schema-4-0100) and
|
|
388
|
+
[adopting bindings](docs/how-to/bind-native-types.md#adopt-bindings-in-an-existing-project).
|
|
389
|
+
|
|
390
|
+
### Runnable payment projects
|
|
391
|
+
|
|
392
|
+
`lawspec examples --example payments` exports a project for every target; use
|
|
393
|
+
`--target rust` or another language to select one. Each project includes an
|
|
394
|
+
application model, native generator, configuration, build files and instructions.
|
|
395
|
+
The shared specification checks exact fees, currency preservation, sum payloads,
|
|
396
|
+
ordered archives, duplicates and absence. Re-exporting preserves application
|
|
397
|
+
edits and the separate compiler generation manifest.
|
|
398
|
+
|
|
399
|
+
Both 32-bit and 64-bit logical machine profiles and readable/compact output are
|
|
400
|
+
covered by the acceptance matrices. Java 25+, Python 3.13+ and the other published
|
|
401
|
+
toolchain baselines remain unchanged. Python output follows PEP 8.
|
|
402
|
+
|
|
403
|
+
## 0.9.0
|
|
404
|
+
|
|
405
|
+
This release adds structural data and checked total definitions across Java,
|
|
406
|
+
Python, JavaScript, TypeScript, Go, Haskell, Kotlin and Rust.
|
|
407
|
+
|
|
408
|
+
### Language
|
|
409
|
+
|
|
410
|
+
- `List a` supports nested contextual literals, structural equality, exact
|
|
411
|
+
length, deterministic boundaries, and native framework generation/shrinking.
|
|
412
|
+
- Algebraic `Maybe a` and `Either a b` provide `Nothing`/`Just` and `Left`/`Right`.
|
|
413
|
+
They remain distinct from interoperability `Nullable` and `Optional` values.
|
|
414
|
+
- Named parameterized products and sums have constructors and ordered fields.
|
|
415
|
+
Generated native types and typed adapters preserve their structure.
|
|
416
|
+
- Total definitions support exhaustive matching and checked structural recursion.
|
|
417
|
+
The compiler rejects partial matches and recursion it cannot establish as
|
|
418
|
+
terminating. Generic definitions specialize to their concrete uses.
|
|
419
|
+
- Refined definition signatures become executable native contracts. Scoped
|
|
420
|
+
payload predicates preserve type-parameter roles through recursive and mutual
|
|
421
|
+
data declarations, including predicates that depend on preceding inputs.
|
|
422
|
+
|
|
423
|
+
Existing scalar semantics remain intact: exact arithmetic does not wrap,
|
|
424
|
+
conversions to bounded adapter parameters are checked, floating equality follows
|
|
425
|
+
IEEE rules, and Symbol equality uses identity.
|
|
426
|
+
|
|
427
|
+
### Generated output
|
|
428
|
+
|
|
429
|
+
Readable code is the default for runtimes, declarations, definitions, adapters,
|
|
430
|
+
tests, and scaffolds. Explicit `--minify` selects compact output for `init`,
|
|
431
|
+
`generate`, and `examples`; the compiler API accepts `minify: true`.
|
|
432
|
+
|
|
433
|
+
Output follows Google language-specific guidance where applicable, PEP 8 for
|
|
434
|
+
Python, standard Go and Rust formatting, and an 80-column Haskell layout.
|
|
435
|
+
Formatting is deterministic in both native and WASM compilation and requires
|
|
436
|
+
no formatter download. Compact output preserves required layout, literal
|
|
437
|
+
contents, and semantics. Changing formatting mode does not overwrite edited
|
|
438
|
+
adapters or create false adapter-signature updates.
|
|
439
|
+
|
|
440
|
+
### API and compatibility
|
|
441
|
+
|
|
442
|
+
API schema 3 adds named data declarations, structural values, checked definitions,
|
|
443
|
+
construction/matching expressions, and scoped payload predicates. Existing scalar
|
|
444
|
+
wire encodings are unchanged. Exhaustive expression visitors must handle the
|
|
445
|
+
new variants; see [API migration](docs/explanation/api-migration.md#structural-data-and-definitions-090).
|
|
446
|
+
|
|
447
|
+
Java 25+, Python 3.13+, Node 22+, and Rust 1.85+ baselines remain unchanged.
|
|
448
|
+
Machine-width profiles, custom source/test directories, generation manifests,
|
|
449
|
+
and user ownership of adapters/build files remain supported. Framework-specific
|
|
450
|
+
strategies stay separate from reusable runtime source.
|
|
451
|
+
|
|
452
|
+
### Examples and release acceptance
|
|
453
|
+
|
|
454
|
+
Bundled examples cover reverse involution, sorting idempotence/sortedness/length/
|
|
455
|
+
permutation, nested presence, products/sums, exhaustive matches, total functions,
|
|
456
|
+
and recursive payload refinements. Release acceptance includes compiler and
|
|
457
|
+
native/WASM checks, native execution on all eight targets, deliberately incorrect
|
|
458
|
+
adapters, independent formatting/syntax checks, regeneration protection, and
|
|
459
|
+
installation of the packed npm artifact.
|
|
460
|
+
|
|
461
|
+
## 0.8.0
|
|
462
|
+
|
|
463
|
+
Rust support and a shared typed compiler boundary are the focus of this release.
|
|
464
|
+
The compiler remains implemented in Haskell and ships as prebuilt WebAssembly.
|
|
465
|
+
|
|
466
|
+
### Changes
|
|
467
|
+
|
|
468
|
+
- Rust 2024, with Rust 1.85 as the minimum toolchain, Cargo scaffolding, Proptest
|
|
469
|
+
generation/shrinking, the complete scalar catalog, refinements, and contracts.
|
|
470
|
+
- An independent numeric Rust runtime with owned native bridges, exact arithmetic,
|
|
471
|
+
checked conversions, direct IEEE rounding, raw text, Symbol identity, and
|
|
472
|
+
distinct nested absence states. Proptest support is emitted separately.
|
|
473
|
+
- A typed core and proposition tree shared by all eight emitters. Resolved IDs,
|
|
474
|
+
parsed source ranges, contextual literals, arithmetic evidence, and conversions
|
|
475
|
+
survive elaboration. Emitters no longer import source syntax or inference.
|
|
476
|
+
- An independent core validator and evaluator. Testing plans distinguish semantic
|
|
477
|
+
validity from execution feasibility and preserve dependent refinement domains.
|
|
478
|
+
- API schema v3 with explicit wire views and unchanged lossless scalar encodings.
|
|
479
|
+
Explicit schema-v2 requests receive a migration diagnostic.
|
|
480
|
+
- Rust module wiring, custom layouts, Cargo preflight, adapter preservation,
|
|
481
|
+
generation manifests, bundled examples, and installed-package coverage.
|
|
482
|
+
- Exact algebra and numeric currying examples. Logical `Integer` replaces their
|
|
483
|
+
former modular Int32 contracts. Examples cover Int32 overflow, large products,
|
|
484
|
+
Int32-minimum negation, and values beyond machine/safe-number bounds; deliberately
|
|
485
|
+
wrapping adapters are rejected on every target.
|
|
486
|
+
|
|
487
|
+
See [Rust](docs/how-to/targets/rust.md), [the language reference](docs/reference/language/index.md),
|
|
488
|
+
[primitives](docs/reference/primitives.md), [refinements](docs/reference/refinements.md), and
|
|
489
|
+
[API migration](docs/explanation/api-migration.md#schema-2-to-schema-3-080).
|
|
490
|
+
|
|
491
|
+
### Compatibility and scope
|
|
492
|
+
|
|
493
|
+
Java 25+, Python 3.13+, and Node 22+ baselines remain unchanged. Existing LawSpec
|
|
494
|
+
source remains compatible. API clients must migrate to schema v3. All nonempty
|
|
495
|
+
plans emit scalar runtime source; existing Haskell projects need direct `text`
|
|
496
|
+
and `bytestring` dependencies in the component compiling that source. Build
|
|
497
|
+
files and implementation adapters remain user-owned.
|
|
498
|
+
|
|
499
|
+
Machine-sized domains use an explicit 32/64-bit profile. Native machine-sized
|
|
500
|
+
bindings reject an architecture mismatch. Rust adapters take owned values;
|
|
501
|
+
borrowing/lifetimes do not become LawSpec language constructs.
|