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/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.