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/LANGUAGE.md
DELETED
|
@@ -1,646 +0,0 @@
|
|
|
1
|
-
# LawSpec language and compiler boundary (0.14)
|
|
2
|
-
|
|
3
|
-
LawSpec describes portable laws, concrete examples, and adapter contracts. The
|
|
4
|
-
compiler is written in Haskell. Rust is an output backend alongside Java, Python,
|
|
5
|
-
JavaScript, TypeScript, Go, Haskell, and Kotlin.
|
|
6
|
-
|
|
7
|
-
## Lists and algebraic containers
|
|
8
|
-
|
|
9
|
-
`List a` is an ordered, finite sequence of values of one type. Lists nest and
|
|
10
|
-
retain duplicates. Literals use brackets; their element type comes from the
|
|
11
|
-
surrounding signature, quantifier, or annotation. An unconstrained empty list
|
|
12
|
-
needs an annotation such as `([] :: List Int8)`.
|
|
13
|
-
|
|
14
|
-
```lawspec
|
|
15
|
-
unit guide.lists
|
|
16
|
-
|
|
17
|
-
reverse :: List Int32 -> List Int32
|
|
18
|
-
|
|
19
|
-
law `reverse preserves length` is
|
|
20
|
-
definition is
|
|
21
|
-
`for all` (xs :: List Int32) .
|
|
22
|
-
prelude.length (reverse xs) = prelude.length xs
|
|
23
|
-
end
|
|
24
|
-
example `duplicates count separately` is
|
|
25
|
-
xs = [3, 1, 3]
|
|
26
|
-
expect prelude.length xs = 3
|
|
27
|
-
expect reverse xs = [3, 1, 3]
|
|
28
|
-
end
|
|
29
|
-
end
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
`prelude.length` returns an exact integer. List equality compares corresponding
|
|
33
|
-
values in order and requires equal lengths. It preserves scalar equality rules:
|
|
34
|
-
NaN still differs from itself, signed zeros compare equal, and Symbols compare
|
|
35
|
-
by identity. Generic list equality requires `Eq a`.
|
|
36
|
-
|
|
37
|
-
`Maybe a` has constructors `Nothing` and `Just value`. `Either a b` has
|
|
38
|
-
constructors `Left value` and `Right value`. These are algebraic sums, separate
|
|
39
|
-
from the interoperability types `Nullable a` and `Optional a`.
|
|
40
|
-
|
|
41
|
-
```lawspec
|
|
42
|
-
unit guide.presence
|
|
43
|
-
|
|
44
|
-
echo :: Maybe (Either Int8 Bool) -> Maybe (Either Int8 Bool)
|
|
45
|
-
|
|
46
|
-
law `preserve every alternative` is
|
|
47
|
-
definition is `for all` (x :: Maybe (Either Int8 Bool)) . echo x = x end
|
|
48
|
-
example `absent` is x = Nothing expect echo x = Nothing end
|
|
49
|
-
example `left integer` is x = Just (Left 127) expect echo x = Just (Left 127) end
|
|
50
|
-
example `right boolean` is x = Just (Right false) expect echo x = Just (Right false) end
|
|
51
|
-
end
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
For `Maybe (Maybe Bool)`, `Nothing`, `Just Nothing`, and `Just (Just false)`
|
|
55
|
-
remain distinct. Nesting a constructor application as an argument generally
|
|
56
|
-
requires parentheses, as in `Just (Left 127)`.
|
|
57
|
-
|
|
58
|
-
The [collections example](examples/specs/collections.lawspec) combines reverse
|
|
59
|
-
involution, sorting idempotence, sortedness, length, and permutation preservation.
|
|
60
|
-
`sorted` and `permutation` in that example are adapters supplied by the user;
|
|
61
|
-
they are not built-in helpers. Sortedness and length alone cannot establish that
|
|
62
|
-
a sorting adapter retained the original elements.
|
|
63
|
-
|
|
64
|
-
## Products, sums, and pattern matching
|
|
65
|
-
|
|
66
|
-
A `type` declaration names its constructors and each constructor's fields. One
|
|
67
|
-
constructor describes a product; multiple constructors describe a sum. Type
|
|
68
|
-
parameters are declared explicitly with `:: Type`.
|
|
69
|
-
|
|
70
|
-
```lawspec
|
|
71
|
-
unit guide.trees
|
|
72
|
-
|
|
73
|
-
type Pair (a :: Type) (b :: Type) is
|
|
74
|
-
Pair
|
|
75
|
-
first :: a
|
|
76
|
-
second :: b
|
|
77
|
-
end
|
|
78
|
-
|
|
79
|
-
type Tree (a :: Type) is
|
|
80
|
-
Leaf value :: a
|
|
81
|
-
Branch children :: List (Tree a)
|
|
82
|
-
end
|
|
83
|
-
|
|
84
|
-
definition rebuild (tree :: Tree a) :: Tree a is
|
|
85
|
-
match tree with
|
|
86
|
-
| Leaf value -> Leaf value
|
|
87
|
-
| Branch children -> Branch children
|
|
88
|
-
end
|
|
89
|
-
end
|
|
90
|
-
|
|
91
|
-
law `preserve the constructor and its fields` is
|
|
92
|
-
definition is `for all` (tree :: Tree Int8) . rebuild tree = tree end
|
|
93
|
-
example `nested branches` is
|
|
94
|
-
tree = Branch [Leaf 127, Branch [], Leaf -128]
|
|
95
|
-
expect rebuild tree = Branch [Leaf 127, Branch [], Leaf -128]
|
|
96
|
-
end
|
|
97
|
-
end
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
Constructors receive fields in declaration order. A match evaluates its
|
|
101
|
-
scrutinee once; each branch binds that constructor's fields in the same order.
|
|
102
|
-
Bindings are scoped to the branch. Matching must be exhaustive and cannot repeat
|
|
103
|
-
a constructor. Lists match with `Nil` and `Cons head tail`; Maybe and Either use
|
|
104
|
-
their constructors above. Recursive declarations must be strictly positive.
|
|
105
|
-
Constructors may refine natural indices; see [indexed families](#natural-indexed-families).
|
|
106
|
-
GADT result signatures that refine type arguments are not supported.
|
|
107
|
-
|
|
108
|
-
Equality is structural and type-directed, including named fields and nested
|
|
109
|
-
containers. Native public declarations retain their names and type parameters;
|
|
110
|
-
schemas and checked codecs support them at runtime. They are not replacements
|
|
111
|
-
for the public data types. See the target guides for native representations:
|
|
112
|
-
[Java](JAVA.md), [Python](PYTHON.md), [JavaScript/TypeScript](WEB.md),
|
|
113
|
-
[Go](GO.md), [Haskell](HASKELL.md), [Kotlin](KOTLIN.md), and [Rust](RUST.md).
|
|
114
|
-
In Haskell, `Text` remains `Data.Text.Text`, while `List Char` becomes the linked
|
|
115
|
-
list `[Char]`. These are distinct LawSpec types even when they contain the same
|
|
116
|
-
characters.
|
|
117
|
-
|
|
118
|
-
Generators compose the target framework's generators and shrinkers. Recursive
|
|
119
|
-
values have a structural size budget; each constructor reserves enough budget
|
|
120
|
-
for its fields before distributing the remainder. Boundaries include empty and
|
|
121
|
-
singleton lists and constructor-specific values. Small finite domains are
|
|
122
|
-
enumerated. An empty type cannot supply a generated argument, but containers
|
|
123
|
-
such as `List Empty` and `Maybe Empty` can still be inhabited. An empty or
|
|
124
|
-
unreachable input domain never makes a property pass vacuously.
|
|
125
|
-
|
|
126
|
-
Whole-value refinements can inspect products and sums using exhaustive matches.
|
|
127
|
-
List element refinements, Maybe/Either payload refinements, and refined arguments
|
|
128
|
-
of recursive and nonrecursive named type constructors are supported; see
|
|
129
|
-
[refinements](REFINEMENTS.md#named-data-payloads). Direct refinements on named
|
|
130
|
-
constructor fields use checked constructor contracts. Recursive payload predicates
|
|
131
|
-
follow stored type arguments and preserve outer dependent inputs.
|
|
132
|
-
|
|
133
|
-
## Natural-indexed families
|
|
134
|
-
|
|
135
|
-
A data declaration may take `Natural` parameters. Each constructor states how it
|
|
136
|
-
determines them with `where <index> = <expression>`:
|
|
137
|
-
|
|
138
|
-
```lawspec
|
|
139
|
-
type Vec (n :: Natural) (a :: Type) is
|
|
140
|
-
| VNil where n = 0
|
|
141
|
-
| VCons head :: a tail :: Vec m a where n = m + 1
|
|
142
|
-
end
|
|
143
|
-
|
|
144
|
-
type Tree (n :: Natural) (a :: Type) is
|
|
145
|
-
| Tip where n = 0
|
|
146
|
-
| Bin left :: Tree l a value :: a right :: Tree r a where n = l + r + 1
|
|
147
|
-
end
|
|
148
|
-
|
|
149
|
-
append :: (xs :: Vec n Int8) -> (ys :: Vec m Int8) -> (r :: Vec (n + m) Int8)
|
|
150
|
-
zip :: (xs :: Vec n Int8) -> (ys :: Vec n Bool) -> (r :: Vec n Bool)
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
Index expressions are sums of natural literals and index variables. A variable
|
|
154
|
-
such as `m` is bound by the field whose type mentions it, and every index needs
|
|
155
|
-
exactly one equation in every constructor. `Natural` is also an ordinary value
|
|
156
|
-
type: an unbounded integer that is at least zero.
|
|
157
|
-
|
|
158
|
-
Indices are evidence, not a second type system. The compiler elaborates a family
|
|
159
|
-
before inference into three ordinary declarations:
|
|
160
|
-
|
|
161
|
-
- erased data `Vec a` with the same constructors, which is the native
|
|
162
|
-
representation on every target;
|
|
163
|
-
- a checked structural measure for each index, named `<index>Of<Type>` (here
|
|
164
|
-
`nOfVec` and `nOfTree`), recomputed from the constructor equations;
|
|
165
|
-
- a refinement, so `Vec e a` in any signature or quantifier means
|
|
166
|
-
`(v :: Vec a where nOfVec v == e)`.
|
|
167
|
-
|
|
168
|
-
`append` above is therefore an adapter contract: its result must have length
|
|
169
|
-
`nOfVec xs + nOfVec ys`, and a native implementation that drops an element
|
|
170
|
-
fails with the postcondition. An index variable that is otherwise unbound, like
|
|
171
|
-
`n` and `m` in `append`, is implicit. It is determined by the first binder whose
|
|
172
|
-
family type mentions it alone, and later occurrences read that binder's measure.
|
|
173
|
-
Implicit indices must not first appear inside an expression, and a result cannot
|
|
174
|
-
introduce one.
|
|
175
|
-
|
|
176
|
-
Generation follows the index. For a free index, as in `append`, values come from
|
|
177
|
-
the erased type and the index is their measure. For a fixed index (`Vec 3 Int8`)
|
|
178
|
-
or a shared one (`zip`'s `ys`), the target is solved backwards through the
|
|
179
|
-
constructor equations: `VCons` for `n = 3` needs a tail with index 2, and `Bin`
|
|
180
|
-
splits `n - 1` between its subtrees. Samples are constructed, not filtered, and
|
|
181
|
-
shrinking stays within the index on every target. The same planning applies to
|
|
182
|
-
any user-written measure over declared data whose branches are a constant plus
|
|
183
|
-
the same measure of that branch's fields.
|
|
184
|
-
|
|
185
|
-
### Proved indices and evidence
|
|
186
|
-
|
|
187
|
-
Checked definitions may return indexed families. The compiler proves their
|
|
188
|
-
result indices statically, so they need no runtime postcondition:
|
|
189
|
-
|
|
190
|
-
```lawspec
|
|
191
|
-
definition concatV (xs :: Vec n Int8) (ys :: Vec m Int8) :: Vec (n + m) Int8 is
|
|
192
|
-
match xs with
|
|
193
|
-
| VNil -> ys
|
|
194
|
-
| VCons h t -> VCons h (concatV t ys)
|
|
195
|
-
end
|
|
196
|
-
end
|
|
197
|
-
```
|
|
198
|
-
|
|
199
|
-
The proof uses exact linear arithmetic over the measures. A measure applied to a
|
|
200
|
-
known constructor unfolds to that constructor's equation, so `nOfVec (VCons h t)`
|
|
201
|
-
is `nOfVec t + 1`. Within a match branch, the scrutinee's constructor is known.
|
|
202
|
-
Calls of checked definitions are pure, so equal calls have equal results. A
|
|
203
|
-
recursive call contributes its own signature as the induction hypothesis, and
|
|
204
|
-
natural measures are non-negative. A definition whose result index does not
|
|
205
|
-
follow fails with `definition result refinement could not be proved`.
|
|
206
|
-
|
|
207
|
-
Every contract obligation is recorded with how it is discharged. Definition
|
|
208
|
-
postconditions are `proved`, and generated code omits their runtime checks.
|
|
209
|
-
Definition preconditions guard native callers, and adapter contracts cover
|
|
210
|
-
native code that LawSpec cannot inspect, so both are `runtime-checked`.
|
|
211
|
-
`lawspec check` summarizes the evidence, and the API reports each obligation in
|
|
212
|
-
the `evidence` field. A proved definition is a natural reference model for a
|
|
213
|
-
native adapter, as in `append xs ys = concatV xs ys` in the
|
|
214
|
-
[indexed example](examples/specs/indexed_families.lawspec).
|
|
215
|
-
|
|
216
|
-
## Domain modeling
|
|
217
|
-
|
|
218
|
-
### Wrappers and constrained primitives
|
|
219
|
-
|
|
220
|
-
A `wrapper` gives a primitive or container a domain meaning. It declares a
|
|
221
|
-
distinct nominal type with one field, `value`, and an optional constraint:
|
|
222
|
-
|
|
223
|
-
```lawspec
|
|
224
|
-
wrapper UnitQuantity is Int32 where value >= 1 && value <= 1000 end
|
|
225
|
-
wrapper OrderId is Text where prelude.length value > 0 end
|
|
226
|
-
wrapper NonEmptyList (a :: Type) is List a where prelude.length value > 0 end
|
|
227
|
-
```
|
|
228
|
-
|
|
229
|
-
`UnitQuantity` is not interchangeable with `Int32` or with another wrapper over
|
|
230
|
-
`Int32`. Its constructor, `UnitQuantity 5`, checks the constraint, so an invalid
|
|
231
|
-
value cannot be constructed in an example, produced by a generator, or decoded
|
|
232
|
-
from native code. `valueOfUnitQuantity` unwraps it. A wrapper elaborates to a
|
|
233
|
-
single-constructor product with a refined field and a checked definition, and
|
|
234
|
-
its native representation is that product on every target. The constraint is
|
|
235
|
-
reported as a `construction` obligation in the evidence.
|
|
236
|
-
|
|
237
|
-
### Workflows and state distinctions
|
|
238
|
-
|
|
239
|
-
A workflow names a pipeline of adapter steps between distinct state types:
|
|
240
|
-
|
|
241
|
-
```lawspec
|
|
242
|
-
type UnvalidatedOrder is UnvalidatedOrder id :: Text quantity :: Int32 end
|
|
243
|
-
type ValidatedOrder is ValidatedOrder id :: OrderId quantity :: UnitQuantity end
|
|
244
|
-
type PricedOrder is PricedOrder id :: OrderId quantity :: UnitQuantity total :: Int64 end
|
|
245
|
-
|
|
246
|
-
workflow placeOrder :: UnvalidatedOrder -> Either OrderError PricedOrder is
|
|
247
|
-
validateOrder :: UnvalidatedOrder -> Either OrderError ValidatedOrder
|
|
248
|
-
priceOrder :: ValidatedOrder -> Either OrderError PricedOrder
|
|
249
|
-
end
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
Each step is an ordinary adapter declaration with one input. The compiler checks
|
|
253
|
-
that every step accepts the state the previous step produces, that fallible steps
|
|
254
|
-
(those returning `Either E T`) share one error type, and that the workflow's
|
|
255
|
-
declared result matches: `Either E T` if any step can fail, otherwise `T`. It then
|
|
256
|
-
adds the law `placeOrder composes its steps`: the native workflow must equal the
|
|
257
|
-
railway composition of the native steps, where the first `Left` is the result. A
|
|
258
|
-
step declared again with the same type is shared between workflows.
|
|
259
|
-
|
|
260
|
-
Because each state is its own type, a `ValidatedOrder` can only hold checked
|
|
261
|
-
values, and a step that needs one cannot be given raw input. See the
|
|
262
|
-
[domain modeling example](examples/specs/domain_modeling.lawspec).
|
|
263
|
-
|
|
264
|
-
## Imports and packages
|
|
265
|
-
|
|
266
|
-
### Importing units
|
|
267
|
-
|
|
268
|
-
A unit may import other units after its `unit` line:
|
|
269
|
-
|
|
270
|
-
```lawspec
|
|
271
|
-
unit shop.orders
|
|
272
|
-
import shop.domain as domain (Money, Cents, `commutative`)
|
|
273
|
-
|
|
274
|
-
type Currency is | Usd | Gbp end
|
|
275
|
-
settlement :: Currency -> domain.Currency
|
|
276
|
-
|
|
277
|
-
law `dollars settle in dollars` is
|
|
278
|
-
definition is
|
|
279
|
-
settlement Usd = domain.Usd
|
|
280
|
-
end
|
|
281
|
-
end
|
|
282
|
-
```
|
|
283
|
-
|
|
284
|
-
`import U` makes every declaration of `U` available qualified by an alias, which
|
|
285
|
-
defaults to the unit's last name segment (`import shop.domain` gives `domain`);
|
|
286
|
-
`as` names another alias. A parenthesized list also makes the listed names
|
|
287
|
-
available unqualified. Listing a data type or wrapper brings its constructors and
|
|
288
|
-
its generated functions (`valueOf<Name>`, indexed-family measures) with it; list
|
|
289
|
-
a law by its quoted name. Qualified names are written without spaces around the
|
|
290
|
-
dot (`domain.Usd`); write `f . g` with spaces to compose a function whose name is
|
|
291
|
-
also an alias.
|
|
292
|
-
|
|
293
|
-
What can be imported:
|
|
294
|
-
|
|
295
|
-
- data types, wrappers and indexed families, with their constructors;
|
|
296
|
-
- refinements;
|
|
297
|
-
- checked definitions;
|
|
298
|
-
- generic laws, that is laws with parameters, which the importer applies to its
|
|
299
|
-
own adapters (`` `commutative` total ``).
|
|
300
|
-
|
|
301
|
-
Adapter signatures and laws without parameters belong to their unit: they are the
|
|
302
|
-
unit's own contract with its native code and are tested there. Referring to
|
|
303
|
-
another unit's adapter is an error, as is importing a declaration that uses one.
|
|
304
|
-
|
|
305
|
-
Names are scoped to their unit. Two units may both declare `Currency`, `Usd` or a
|
|
306
|
-
definition `size`; `domain.Usd` and the local `Usd` are different constructors.
|
|
307
|
-
Targets with a single data namespace qualify the colliding native names by unit
|
|
308
|
-
(`ShopDomainCurrency`, `ShopOrdersCurrency`). An unqualified name that is both
|
|
309
|
-
listed in an import and declared locally is an error, as is one listed from two
|
|
310
|
-
units. Imports are not re-exported: a unit uses what it imports itself.
|
|
311
|
-
|
|
312
|
-
Imports are resolved before type checking. A data type stays with the unit that
|
|
313
|
-
declares it, so values of `domain.Money` are the same values in every importing
|
|
314
|
-
unit. Imported refinements, checked definitions and generic laws are copied into
|
|
315
|
-
the importing unit, together with everything they use, under names derived from
|
|
316
|
-
their unit (`domain.centsOf` is emitted as `shopDomainCentsOf`). Core and all
|
|
317
|
-
eight targets therefore need nothing new. Import cycles, unknown units and
|
|
318
|
-
missing names are reported at the import.
|
|
319
|
-
|
|
320
|
-
### Packages
|
|
321
|
-
|
|
322
|
-
A package is a named, versioned directory of units, described by
|
|
323
|
-
`lawspec-package.json`:
|
|
324
|
-
|
|
325
|
-
```json
|
|
326
|
-
{
|
|
327
|
-
"name": "shop.domain",
|
|
328
|
-
"version": "1.2.0",
|
|
329
|
-
"sources": ["src"],
|
|
330
|
-
"dependencies": {}
|
|
331
|
-
}
|
|
332
|
-
```
|
|
333
|
-
|
|
334
|
-
Every unit of a package is named after it: `shop.domain` or `shop.domain.<name>`.
|
|
335
|
-
A project, or another package, declares the packages it depends on with version
|
|
336
|
-
ranges, and lists the package directories to load:
|
|
337
|
-
|
|
338
|
-
```json
|
|
339
|
-
{
|
|
340
|
-
"version": 1,
|
|
341
|
-
"sources": ["orders.lawspec"],
|
|
342
|
-
"dependencies": {"shop.domain": "^1.0.0"},
|
|
343
|
-
"packages": ["../shop-domain"],
|
|
344
|
-
"targets": [{"language": "java", "root": "java"}]
|
|
345
|
-
}
|
|
346
|
-
```
|
|
347
|
-
|
|
348
|
-
A unit may import the units of its own package (or project) and of the packages
|
|
349
|
-
it depends on directly. Versions are `MAJOR.MINOR.PATCH` with an optional
|
|
350
|
-
prerelease. Ranges combine `1.2.3` (exactly), `^1.2.3`, `~1.2.3`, `>=`, `>`,
|
|
351
|
-
`<=`, `<` and `*`, with npm's meaning. Resolution is exact: one version of each
|
|
352
|
-
package is supplied, every range must accept it, a package that nothing requires
|
|
353
|
-
is rejected, and package dependency cycles are rejected. Project units may not
|
|
354
|
-
use a dependency's namespace.
|
|
355
|
-
|
|
356
|
-
A package publishes a behavioral contract. Its types, refinements, definitions
|
|
357
|
-
and generic laws are a library, and its adapter signatures and concrete laws are
|
|
358
|
-
obligations: a project that depends on the package implements those adapters in
|
|
359
|
-
its own native code and is tested against the package's laws, with the same
|
|
360
|
-
user-owned adapter files as for its own units. `lawspec package` checks a
|
|
361
|
-
package on its own and summarizes its units, laws and data types. A package
|
|
362
|
-
directory can be distributed any way that delivers the directory, for example
|
|
363
|
-
as an npm package. See the [package example](examples/packages).
|
|
364
|
-
|
|
365
|
-
## Total definitions
|
|
366
|
-
|
|
367
|
-
A unit can supply an implementation as a checked total definition:
|
|
368
|
-
|
|
369
|
-
```lawspec
|
|
370
|
-
definition increment (x :: Int8) :: BigInt
|
|
371
|
-
requires Integer Int8
|
|
372
|
-
is
|
|
373
|
-
x + 1
|
|
374
|
-
end
|
|
375
|
-
```
|
|
376
|
-
|
|
377
|
-
Parameters and the result have explicit types. The optional `requires` clause
|
|
378
|
-
uses the same `Eq`, `Integer`, `Ordered`, and `Bounded` capabilities as laws.
|
|
379
|
-
Requirements are checked even when the definition is unused. Bodies must have
|
|
380
|
-
exhaustive matches, proven structural descent for recursive calls, and guards
|
|
381
|
-
for operations that could otherwise fail. Calls may use other checked
|
|
382
|
-
definitions; external adapters cannot establish a definition's totality.
|
|
383
|
-
|
|
384
|
-
For exact arithmetic, the totality checker can combine linear bounds and Boolean
|
|
385
|
-
guards. For example, `x >= 0 && 1 / (x + 1) > 0` is safe for integer `x`: the
|
|
386
|
-
right side runs only when its denominator is positive. Proof arithmetic uses
|
|
387
|
-
arbitrary exact fractions, preserves strict boundaries, and has a bounded work
|
|
388
|
-
budget. An unproved obligation is rejected; IEEE expressions never acquire
|
|
389
|
-
rational identities such as `x - x = 0` from this checker.
|
|
390
|
-
|
|
391
|
-
Primitive integer ranges are available to the checker automatically, including
|
|
392
|
-
the selected machine width and BigUInt's nonnegative domain. Integer comparisons
|
|
393
|
-
retain integrality: for Int8 `x`, `x < 127 && prelude.Int8 (x + 1) > x` safely
|
|
394
|
-
narrows only on the guarded branch. The unguarded conversion is rejected because
|
|
395
|
-
`127 + 1` is outside Int8. Range bounds alone do not prove that a Rational or
|
|
396
|
-
Decimal input has no fractional part.
|
|
397
|
-
Pattern matching retains the primitive ranges of extracted fields within that
|
|
398
|
-
branch. For example, an Int8 list head still makes `head + 129` strictly positive;
|
|
399
|
-
that fact cannot be reused for an Int64 field in another constructor branch.
|
|
400
|
-
|
|
401
|
-
Definitions produce reusable generated source with checked native entry points
|
|
402
|
-
on all eight targets. They do not produce user-owned adapter stubs. Integer
|
|
403
|
-
arithmetic preserves the mathematical result; the example above returns `128`
|
|
404
|
-
for the largest Int8 input. See [the total-function example](examples/specs/total_functions.lawspec)
|
|
405
|
-
for recursive list counting, structural equality, and explicit expected values.
|
|
406
|
-
|
|
407
|
-
Definitions can quantify type variables implicitly through their signatures:
|
|
408
|
-
|
|
409
|
-
```lawspec
|
|
410
|
-
definition same (x :: a) (y :: a) :: Bool requires Eq a is x == y end
|
|
411
|
-
definition count (xs :: List a) :: BigInt is
|
|
412
|
-
match xs with
|
|
413
|
-
| Nil -> 0
|
|
414
|
-
| Cons head tail -> 1 + count tail
|
|
415
|
-
end
|
|
416
|
-
end
|
|
417
|
-
```
|
|
418
|
-
|
|
419
|
-
Each template is checked for typing, capabilities, termination, and definedness,
|
|
420
|
-
including unused templates. Calls specialize it to concrete argument and result
|
|
421
|
-
types before Core elaboration. Different calls can use different types; recursive
|
|
422
|
-
self-calls must retain the same types. Ambiguous calls require an annotation,
|
|
423
|
-
such as `count ([] :: List Int8)` to specify an empty list's element type.
|
|
424
|
-
Unused templates emit no instances.
|
|
425
|
-
Checked definitions may also appear in refinement predicates and adapter
|
|
426
|
-
preconditions or postconditions. Their closed call graphs contain only other
|
|
427
|
-
checked definitions; adapter calls remain forbidden in predicates. The compiler
|
|
428
|
-
uses the same concrete Core definitions to check example domains and plan finite
|
|
429
|
-
cases and boundaries that generated tests use at runtime.
|
|
430
|
-
Definition parameters and results may carry refinements. The compiler proves
|
|
431
|
-
body definedness and result claims under ordered input preconditions, checks
|
|
432
|
-
callee preconditions, and preserves the contracts through specialization. Native
|
|
433
|
-
entry points enforce the same contracts. See [refined definitions](REFINEMENTS.md#refined-definitions).
|
|
434
|
-
|
|
435
|
-
## Source and declarations
|
|
436
|
-
|
|
437
|
-
A source has one named `unit`, its imports, function signatures, data
|
|
438
|
-
declarations, checked definitions, reusable refinements, and laws. Qualified unit names determine target module/package paths. Function
|
|
439
|
-
signatures are curried: `a -> b -> c` takes two inputs and returns `c`. Parentheses
|
|
440
|
-
group types and expressions. Comments start with `--` and run to the line end.
|
|
441
|
-
|
|
442
|
-
The following grammar summarizes the main forms; the parser and executable
|
|
443
|
-
compiler tests specify lexical details:
|
|
444
|
-
|
|
445
|
-
```text
|
|
446
|
-
source = "unit" qualified-name import* declaration*
|
|
447
|
-
import = "import" qualified-name ["as" name]
|
|
448
|
-
["(" (name | quoted-name) ("," (name | quoted-name))* ")"]
|
|
449
|
-
declaration = name "::" type | law | refinement | data-type | function
|
|
450
|
-
data-type = "type" name ("(" name "::" "Type" ")")*
|
|
451
|
-
"is" constructor* "end"
|
|
452
|
-
constructor = name (name "::" type)*
|
|
453
|
-
function = "definition" name parameter* "::" type requirements?
|
|
454
|
-
"is" expression "end"
|
|
455
|
-
type = type-atom ["->" type]
|
|
456
|
-
type-atom = primitive | type-variable | "(" type ")"
|
|
457
|
-
| ("Nullable" | "Optional" | "List" | "Maybe") type-atom
|
|
458
|
-
| "Either" type-atom type-atom
|
|
459
|
-
| data-type-name type-atom*
|
|
460
|
-
| refinement-name argument*
|
|
461
|
-
| "(" name "::" type ["where" expression] ")"
|
|
462
|
-
refinement = "refinement" name parameter* requirements?
|
|
463
|
-
"is" type "end"
|
|
464
|
-
parameter = "(" name "::" type ["where" expression] ")"
|
|
465
|
-
requirements = "requires" (capability type)+
|
|
466
|
-
capability = "Eq" | "Integer" | "Ordered" | "Bounded"
|
|
467
|
-
law = "law" quoted-name parameter* requirements? "is"
|
|
468
|
-
"definition" "is" proposition "end"
|
|
469
|
-
description? rationale? example* references? "end"
|
|
470
|
-
proposition = "`for all`" parameter+ "." proposition
|
|
471
|
-
| expression "=" expression
|
|
472
|
-
| expression "implies" proposition
|
|
473
|
-
| proposition "and" proposition
|
|
474
|
-
| quoted-name expression* | expression
|
|
475
|
-
expression = ... | "[" [expression ("," expression)*] "]"
|
|
476
|
-
| constructor-name expression*
|
|
477
|
-
| "match" expression "with"
|
|
478
|
-
("|" constructor-name name* "->" expression)+ "end"
|
|
479
|
-
example = "example" quoted-name "is" (name "=" literal)+
|
|
480
|
-
("expect" expression "=" literal)+ "end"
|
|
481
|
-
```
|
|
482
|
-
|
|
483
|
-
Law names use backticks. Text/metadata use double quotes with escapes. Named
|
|
484
|
-
refinement declarations state their type versus value parameter kinds, including
|
|
485
|
-
forward references; the compiler validates their arity and argument kinds.
|
|
486
|
-
Lowercase type names represent variables. `a :: Type` is a type parameter, not a
|
|
487
|
-
runtime value with a generator.
|
|
488
|
-
|
|
489
|
-
A generic law is specialized when invoked with concrete adapters. Its declared
|
|
490
|
-
capabilities must justify its operations; specialization resolves those
|
|
491
|
-
requirements for the actual types. `Integer` as a capability requires an integer
|
|
492
|
-
type. `Integer` in a concrete result signature denotes a representation-independent
|
|
493
|
-
mathematical integer. See [refinements and abstract integers](REFINEMENTS.md).
|
|
494
|
-
|
|
495
|
-
## Expressions and arithmetic
|
|
496
|
-
|
|
497
|
-
Application binds most tightly. The remaining precedence, highest first, is:
|
|
498
|
-
unary `!`/`-`, composition `.`, multiplication/division, addition/subtraction,
|
|
499
|
-
comparisons (`==`, `!=`, `<`, `<=`, `>`, `>=`), `&&`, then `||`.
|
|
500
|
-
Comparisons do not chain. Arithmetic associates left; composition associates
|
|
501
|
-
right. An adjacent numeric sign remains part of an argument: `f -42` applies `f`
|
|
502
|
-
to negative 42. Write `x - 42` for subtraction.
|
|
503
|
-
|
|
504
|
-
Assertion `=` differs from Boolean `==`. `implies` guards its following
|
|
505
|
-
proposition; `and` requires both assertions. Parentheses determine the scope of a
|
|
506
|
-
shared guard. Both Boolean operators and implications short-circuit.
|
|
507
|
-
|
|
508
|
-
Literals acquire types from declared context. Unconstrained integers have type
|
|
509
|
-
`Integer`; decimal tokens have type `Decimal`. An annotation such as
|
|
510
|
-
`(127 :: Int8)` specifies context. A declared float context can type a decimal
|
|
511
|
-
token directly, but an explicitly constructed exact Decimal is not implicitly
|
|
512
|
-
converted into a float.
|
|
513
|
-
|
|
514
|
-
Integer `+`, `-`, `*`, and negation produce exact `Integer` results. Decimal
|
|
515
|
-
dominates integer/Decimal combinations; Rational dominates exact combinations
|
|
516
|
-
involving Rational. Exact `/` returns Rational. `prelude.quot` truncates integer
|
|
517
|
-
quotients toward zero; `prelude.rem` is the associated remainder. Division by
|
|
518
|
-
zero fails when evaluated. Explicit numeric conversions use `prelude.Type`.
|
|
519
|
-
Exact/inexact mixing otherwise fails type checking. IEEE arithmetic widens float
|
|
520
|
-
or complex precision as required; equality treats NaN as unequal and signed
|
|
521
|
-
zero as equal. Decimal rounding is explicit, with a scale and ties-to-even rule.
|
|
522
|
-
|
|
523
|
-
Passing a computed exact result to a bounded adapter argument performs a checked
|
|
524
|
-
conversion. It never wraps, truncates a fraction, or silently changes precision.
|
|
525
|
-
Adapter results are validated against the declared domain before use. See the
|
|
526
|
-
[primitive reference](PRIMITIVES.md) for all domains and helpers.
|
|
527
|
-
|
|
528
|
-
## Refinements and executable contracts
|
|
529
|
-
|
|
530
|
-
Refinements are pure Boolean predicates over a value and preceding binders.
|
|
531
|
-
They cannot call user adapters. Dependent inputs are generated in order;
|
|
532
|
-
shrinking preserves their predicates. Bounds such as `y > Int8.max - x` are
|
|
533
|
-
computed with exact arithmetic and can drive a dependent generator. If a chosen
|
|
534
|
-
`x` has no possible `y`, generation retries earlier inputs. Search exhaustion
|
|
535
|
-
fails explicitly rather than passing a property with no valid cases.
|
|
536
|
-
|
|
537
|
-
Contracts check preconditions, evaluate an adapter once, validate the result,
|
|
538
|
-
and then check postconditions against that same result. Predicate errors are
|
|
539
|
-
contextual failures, not rejected samples. Small finite domains are enumerated;
|
|
540
|
-
other domains use target property frameworks. `machineBits: 32 | 64` controls
|
|
541
|
-
machine-integer domains independently of the compiler host architecture. Native
|
|
542
|
-
machine-sized adapter bindings additionally verify the executing architecture.
|
|
543
|
-
|
|
544
|
-
## Compiler stages and public API
|
|
545
|
-
|
|
546
|
-
The parser retains source ranges. Resolution and inference check names, kinds,
|
|
547
|
-
capabilities, contextual literals, and generic specializations. Elaboration
|
|
548
|
-
produces typed core expressions with resolved declaration/binder IDs, explicit
|
|
549
|
-
arithmetic evidence and conversions, plus an authoritative proposition tree.
|
|
550
|
-
Refinement declarations become predicates on quantifiers and contracts; targets
|
|
551
|
-
do not interpret refinement syntax.
|
|
552
|
-
|
|
553
|
-
An independent core validator checks scopes, kinds, operand/result types,
|
|
554
|
-
capability evidence, and conversions. A pure core evaluator supports deterministic
|
|
555
|
-
domain checks and reference tests. The testing planner computes finite cases,
|
|
556
|
-
boundaries, and dependent generator requirements. All eight emitters consume
|
|
557
|
-
that plan and the core, without importing source syntax or inference.
|
|
558
|
-
|
|
559
|
-
`check`/`expand` report semantic validity. `planGeneration` additionally reports
|
|
560
|
-
execution feasibility, including empty finite domains. Source syntax errors,
|
|
561
|
-
semantic errors, core invariant failures, and generation errors have distinct
|
|
562
|
-
diagnostic codes. Runtime failures identify the law/example or adapter contract.
|
|
563
|
-
Parsed expressions retain real source ranges; synthesized expressions identify
|
|
564
|
-
the declaration that caused their creation.
|
|
565
|
-
|
|
566
|
-
API schema v3 uses separately defined wire views, with lossless tagged scalar
|
|
567
|
-
values. It does not serialize internal AST constructors. See the
|
|
568
|
-
[API migration guide](API-MIGRATION.md).
|
|
569
|
-
|
|
570
|
-
## Roadmap
|
|
571
|
-
|
|
572
|
-
0.11 elaborates natural-indexed families to erased data, measures and
|
|
573
|
-
refinements. The Core type model distinguishes type arguments from index
|
|
574
|
-
arguments, but that representation is not a claim that arbitrary dependent
|
|
575
|
-
programs are accepted. External type bindings and custom generator bindings
|
|
576
|
-
(0.10) configure native representations alongside the typed testing plan and do
|
|
577
|
-
not change source-language typing or equality; see
|
|
578
|
-
[the binding reference](NATIVE-BINDINGS.md).
|
|
579
|
-
|
|
580
|
-
### 0.12 Proof-producing dependent layer (released)
|
|
581
|
-
|
|
582
|
-
- Index equalities in checked definitions are discharged statically. Adapter
|
|
583
|
-
results remain runtime-checked.
|
|
584
|
-
- Linear `Natural` arithmetic over measures is solved exactly, with unfolding
|
|
585
|
-
on known constructors and induction through recursive calls.
|
|
586
|
-
- Evidence is recorded for every contract obligation as `proved` or
|
|
587
|
-
`runtime-checked`, and reported by `lawspec check` and the API.
|
|
588
|
-
- Proved definition postconditions produce no runtime checks.
|
|
589
|
-
- Checked definitions may return indexed families. See
|
|
590
|
-
[proved indices](#proved-indices-and-evidence).
|
|
591
|
-
|
|
592
|
-
Still open, for evaluation in later releases: index equalities between sibling
|
|
593
|
-
fields (perfect trees whose subtrees share one index), non-linear indices, and
|
|
594
|
-
GADTs that refine type arguments.
|
|
595
|
-
|
|
596
|
-
### 0.13 Wlaschin-style domain modeling primitives (released)
|
|
597
|
-
|
|
598
|
-
- Semantic wrappers and constrained primitives: `wrapper` declarations with
|
|
599
|
-
checked constructors.
|
|
600
|
-
- Illegal states are unrepresentable: wrapper and field constraints are checked
|
|
601
|
-
on construction, generation and native decoding, and reported as evidence.
|
|
602
|
-
- Explicit domain workflows and state distinctions: `workflow` declarations with
|
|
603
|
-
checked step types and a generated railway composition law.
|
|
604
|
-
- See [domain modeling](#domain-modeling).
|
|
605
|
-
|
|
606
|
-
### 0.14 Cross-unit imports and packages (released)
|
|
607
|
-
|
|
608
|
-
- Reusable law, type and refinement libraries: `import` brings another unit's
|
|
609
|
-
types, refinements, checked definitions and generic laws into scope.
|
|
610
|
-
- Versioning and namespacing: packages have names, semantic versions and
|
|
611
|
-
dependency ranges, units live in their package's namespace, and constructor
|
|
612
|
-
names are scoped to their unit.
|
|
613
|
-
- Publishable behavioral contracts: a package's adapter signatures and laws are
|
|
614
|
-
implemented and tested by every project that depends on it.
|
|
615
|
-
- See [imports and packages](#imports-and-packages).
|
|
616
|
-
|
|
617
|
-
Still open: re-exports, and several versions of one package in one build.
|
|
618
|
-
|
|
619
|
-
### 0.15 Evidence/discharge model
|
|
620
|
-
|
|
621
|
-
Each obligation reports how it was discharged:
|
|
622
|
-
|
|
623
|
-
- `PROVED`: discharged statically, by 0.12 evidence or definition proofs.
|
|
624
|
-
- `EXHAUSTIVELY CHECKED`: every value of a finite domain was checked.
|
|
625
|
-
- `PROPERTY TESTED`: generated cases, examples and boundaries.
|
|
626
|
-
- `RUNTIME CHECKED`: adapter contracts and checked codecs at native boundaries.
|
|
627
|
-
- `ASSUMED / EXTERNAL`: native adapters and bindings taken on trust.
|
|
628
|
-
|
|
629
|
-
## Generated project formatting
|
|
630
|
-
|
|
631
|
-
`lawspec init --target java` creates a readable Maven scaffold; Kotlin init
|
|
632
|
-
likewise expands Gradle blocks with two-space indentation. `--minify` explicitly
|
|
633
|
-
selects compact scaffolds and configuration JSON. `generate` and `examples`
|
|
634
|
-
accept the same flag for generated source. The mode is per invocation and does
|
|
635
|
-
not become a project default. Init preserves existing build files, and generation
|
|
636
|
-
preserves user-owned adapters regardless of formatting mode.
|
|
637
|
-
|
|
638
|
-
Generated runtime support and checked definitions belong in source directories;
|
|
639
|
-
framework-specific property helpers belong in test directories. Both follow
|
|
640
|
-
custom layout settings. Python uses PEP 8: four-space indentation, 79-column
|
|
641
|
-
code, and 72-column prose. Other targets follow Google language guidance where
|
|
642
|
-
applicable, with standard Rust formatting. Formatting is deterministic in the
|
|
643
|
-
native and WASM compilers; generation does not download or invoke a formatter.
|
|
644
|
-
|
|
645
|
-
See [the release notes](RELEASE-0.10.md) for compatibility and scope, and the target
|
|
646
|
-
guides for formatting verification and native representation details.
|