lawspec 0.15.0 → 0.15.2

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/RELEASE-0.13.md DELETED
@@ -1,97 +0,0 @@
1
- # LawSpec 0.13
2
-
3
- ## 0.13.2
4
-
5
- A maintenance release. The language, generated code and API are unchanged.
6
-
7
- - The repository has no hosted CI. `stack run lawspec-dev -- ci` runs the
8
- complete check locally: compiler, npm, parity, package and editor checks, then
9
- for each target the dependency bootstrap, every acceptance suite in both
10
- machine profiles, and the installed native-binding example. It logs each step to
11
- `.artifacts/ci/` and exits non-zero on any failure. `--target`, `--core`,
12
- `--fail-fast`, `--rust-toolchains` and `--rust-targets` select what to run.
13
- `make ci` is equivalent.
14
- - The JavaScript acceptance runners and fixture modules replaced by
15
- `lawspec-acceptance` are removed.
16
- - The package smoke test's per-command timeout is ten minutes: exporting every
17
- bundled example had exceeded the former two-minute limit on slower machines.
18
- - The integration bootstrap restores missing scaffold files in existing projects.
19
-
20
- ## 0.13.1
21
-
22
- A maintenance release. The language, generated code and API are unchanged from
23
- 0.13.0.
24
-
25
- - Repository checks move from JavaScript to Haskell. `lawspec-dev boundaries` and
26
- `lawspec-dev integrity` replace `tools/check-boundaries.mjs` and
27
- `tools/build-integrity.mjs`. The integrity check now also rejects staged npm
28
- copies of documentation and examples that differ from their sources.
29
- - `lawspec-acceptance` runs the bundled-example acceptance suites
30
- (`integration`, `algebra`, `scalar`, `refinement`, `indexed`, `domain`) in
31
- process. Adapters and mutants are real files under `acceptance/`, and a
32
- mutant that only breaks the build now fails the suite. This exposed a
33
- TypeScript scalar mutant that previously counted as rejected because it
34
- failed type-checking; it now exercises the laws. The JavaScript runners
35
- continue to run alongside it in CI.
36
- - Build-file scaffolds are defined once in Haskell (`LawSpec.Scaffold`) and
37
- checked against the npm templates byte for byte.
38
- - Compiler API contract tests formerly in `npm/test` run in hspec against the
39
- same JSON boundary that `core.wasm` exports. A new npm test checks that
40
- generation never rewrites build files and that regeneration is a no-op on
41
- every target.
42
-
43
- ## 0.13.0
44
-
45
- ### Wrappers and constrained primitives
46
-
47
- ```lawspec
48
- wrapper UnitQuantity is Int32 where value >= 1 && value <= 1000 end
49
- wrapper NonEmptyList (a :: Type) is List a where prelude.length value > 0 end
50
- ```
51
-
52
- A wrapper declares a distinct nominal type with one field, `value`, and an
53
- optional constraint. Its constructor checks the constraint, so an invalid value
54
- cannot be constructed in an example (the compiler rejects `UnitQuantity 0`),
55
- produced by a generator, or decoded from native code. `valueOf<Name>` unwraps a
56
- value. Wrappers may take type parameters. They elaborate to a single-constructor
57
- product with a refined field, so all eight targets represent them natively with
58
- no new runtime machinery.
59
-
60
- ### Workflows and state distinctions
61
-
62
- ```lawspec
63
- workflow placeOrder :: UnvalidatedOrder -> Either OrderError PricedOrder is
64
- validateOrder :: UnvalidatedOrder -> Either OrderError ValidatedOrder
65
- priceOrder :: ValidatedOrder -> Either OrderError PricedOrder
66
- end
67
- ```
68
-
69
- A workflow declares its steps as adapters and checks the pipeline: each step
70
- must accept the previous step's state, and fallible steps must share an error
71
- type. The workflow's result must match `Either E T` when any step can fail, or
72
- `T` otherwise. The compiler adds the law `placeOrder composes its steps`: the
73
- native workflow must equal the railway composition of the native steps.
74
- Diagnostics name the step and the mismatched types, with the workflow's source
75
- location.
76
-
77
- ### Evidence
78
-
79
- Constructor field constraints, including wrapper constraints, appear in the
80
- evidence as `construction` obligations with status `runtime-checked`, next to
81
- the contract obligations introduced in 0.12. The TypeScript API declares these
82
- records as `ObligationEvidence`; the 0.12 typing was not published.
83
-
84
- ### Examples and acceptance
85
-
86
- `examples/specs/domain_modeling.lawspec` combines wrappers, a parameterized
87
- `NonEmptyList`, order states and the workflow. `tools/domain-integration.mjs`
88
- runs it on all eight targets in both machine profiles. Correct adapters pass;
89
- mutants that break a wrapper invariant, the railway composition, or a non-empty
90
- list operation fail. The example runners now share
91
- `tools/example-acceptance.mjs`.
92
-
93
- ### Compatibility
94
-
95
- `wrapper` and `workflow` begin new declarations. Specifications that do not use
96
- them compile as in 0.12. API schemas 3 and 4 are unchanged, apart from the
97
- additive `construction` stage in `evidence`.
package/RELEASE-0.14.md DELETED
@@ -1,52 +0,0 @@
1
- # LawSpec 0.14
2
-
3
- ## 0.14.0
4
-
5
- ### Imports
6
-
7
- ```lawspec
8
- unit shop.orders
9
- import shop.domain as domain (Money, Cents, `commutative`)
10
- ```
11
-
12
- A unit imports other units by name. Every declaration of an imported unit is
13
- available through the alias (`domain.Usd`, `domain.centsOf`), and listed names
14
- also unqualified. Types, wrappers, indexed families, refinements, checked
15
- definitions and generic laws can be imported. Adapters and concrete laws stay
16
- with their unit. Import cycles, unknown units and missing or ambiguous names are
17
- reported at the import, with the reason: an adapter, a constructor listed
18
- without its type, or a law without parameters.
19
-
20
- Names are scoped to their unit, so units compiled together no longer need
21
- distinct constructor names. Targets with one data namespace (Python,
22
- JavaScript, TypeScript, Go and Haskell) name colliding types after their unit,
23
- `ShopDomainCurrency` and `ShopOrdersCurrency`, and their constructors
24
- `ShopDomainCurrencyUsd`. Java, Kotlin and Rust qualify only the type. Earlier
25
- versions qualified only the colliding names, for example
26
- `ShopDomainTypeCurrencyUsd` next to `CurrencyEur`.
27
-
28
- Imports are resolved before type checking, like indexed families and domain
29
- models, so Core and the eight backends are unchanged.
30
-
31
- ### Packages
32
-
33
- A `lawspec-package.json` names a package, its version, its source directories
34
- and the version ranges of its dependencies. Package units are named after the
35
- package, a unit imports only from its own package and direct dependencies, and
36
- every range must accept the supplied version. A project lists `dependencies` and
37
- the `packages` directories in `lawspec.json`. A package's adapters and laws are a
38
- published contract: dependent projects implement and test them as their own.
39
- `lawspec package` checks a package and summarizes it.
40
-
41
- The compiler API accepts `dependencies`, `packages` and `package`, and reports
42
- the resolved packages (see [API migration](API-MIGRATION.md#imports-and-packages-014)).
43
-
44
- ### Other changes
45
-
46
- - Rust: a law without quantified inputs no longer emits an untyped empty case
47
- vector, which did not compile.
48
- - The VS Code grammar highlights `import` and `as`.
49
- - A new acceptance suite, `packages`, runs the
50
- [package example](examples/packages) on all eight targets in both machine
51
- profiles and rejects five adapter mutants plus the bare stubs. `lawspec-dev ci`
52
- includes it.
package/RELEASE-0.15.md DELETED
@@ -1,44 +0,0 @@
1
- # LawSpec 0.15
2
-
3
- ## 0.15.0
4
-
5
- ### Evidence and discharge
6
-
7
- Every obligation of a program reports how it is discharged, strongest first:
8
-
9
- - `proved`: statically. Definition postconditions and indices, as since 0.12,
10
- and now laws that call only checked definitions.
11
- - `exhaustively-checked`: every input of a finite domain, by the compiler for
12
- laws over checked definitions and otherwise by the generated tests. A law with
13
- no inputs is a single case.
14
- - `property-tested`: generated cases, boundary cases and examples.
15
- - `runtime-checked`: adapter contracts, definition preconditions, constructor
16
- constraints and native type bindings, at every native boundary.
17
- - `assumed`: adapters, native functions, custom generators and codec hooks,
18
- taken on trust. Each adapter reports how many laws call it, or that none does.
19
-
20
- `lawspec check` summarizes the obligations by status, and the new
21
- `lawspec evidence` lists each with its claim and reason (`--json` for the API
22
- records, and a unit or `unit::declaration` filter).
23
-
24
- ### Laws proved and refuted by the compiler
25
-
26
- A law over checked definitions is attempted as a proof by the same exact linear
27
- arithmetic that proves definition results, from its input refinements, with
28
- definitions that have no preconditions unfolded into the claim. When it is not
29
- proved and its domain is finite, the compiler evaluates every input; a
30
- counterexample is a compile error with code `refuted`, such as
31
- `law always positive is false for x = -128`. Specifications that compiled
32
- before may therefore be rejected if a law over definitions is false.
33
-
34
- The prover also handles constant factors on integer expressions (`x * 2`),
35
- which it previously treated as non-linear, so more definition results are
36
- proved.
37
-
38
- ### API
39
-
40
- `evidence` items have the five statuses above and new stages: `law`,
41
- `adapter`, and, with native bindings, `binding`, `codec`, `generator` and
42
- `native-function`. `claim` is `null` for obligations without one. The
43
- TypeScript API declares `ObligationEvidence` and `DischargeStatus`. See
44
- [API migration](API-MIGRATION.md#evidence-and-discharge-015).
package/RELEASE-0.9.md DELETED
@@ -1,61 +0,0 @@
1
- # LawSpec 0.9.0
2
-
3
- This release adds structural data and checked total definitions across Java,
4
- Python, JavaScript, TypeScript, Go, Haskell, Kotlin, and Rust.
5
-
6
- ## Language
7
-
8
- - `List a` supports nested contextual literals, structural equality, exact
9
- length, deterministic boundaries, and native framework generation/shrinking.
10
- - Algebraic `Maybe a` and `Either a b` provide `Nothing`/`Just` and `Left`/`Right`.
11
- They remain distinct from interoperability `Nullable` and `Optional` values.
12
- - Named parameterized products and sums have constructors and ordered fields.
13
- Generated native types and typed adapters preserve their structure.
14
- - Total definitions support exhaustive matching and checked structural recursion.
15
- The compiler rejects partial matches and recursion it cannot establish as
16
- terminating. Generic definitions specialize to their concrete uses.
17
- - Refined definition signatures become executable native contracts. Scoped
18
- payload predicates preserve type-parameter roles through recursive and mutual
19
- data declarations, including predicates that depend on preceding inputs.
20
-
21
- Existing scalar semantics remain intact: exact arithmetic does not wrap,
22
- conversions to bounded adapter parameters are checked, floating equality follows
23
- IEEE rules, and Symbol equality uses identity.
24
-
25
- ## Generated output
26
-
27
- Readable code is the default for runtimes, declarations, definitions, adapters,
28
- tests, and scaffolds. Explicit `--minify` selects compact output for `init`,
29
- `generate`, and `examples`; the compiler API accepts `minify: true`.
30
-
31
- Output follows Google language-specific guidance where applicable, PEP 8 for
32
- Python, standard Go and Rust formatting, and an 80-column Haskell layout.
33
- Formatting is deterministic in both native and WASM compilation and requires
34
- no formatter download. Compact output preserves required layout, literal
35
- contents, and semantics. Changing formatting mode does not overwrite edited
36
- adapters or create false adapter-signature updates.
37
-
38
- ## API and compatibility
39
-
40
- API schema 3 adds named data declarations, structural values, checked definitions,
41
- construction/matching expressions, and scoped payload predicates. Existing scalar
42
- wire encodings are unchanged. Exhaustive expression visitors must handle the
43
- new variants; see [API migration](API-MIGRATION.md).
44
-
45
- Java 25+, Python 3.13+, Node 22+, and Rust 1.85+ baselines remain unchanged.
46
- Machine-width profiles, custom source/test directories, generation manifests,
47
- and user ownership of adapters/build files remain supported. Framework-specific
48
- strategies stay separate from reusable runtime source.
49
-
50
- GADTs, indexed families, and general dependent types remain future work. See
51
- [the language reference](LANGUAGE.md) and the target guides for native type
52
- representations and framework-specific refinement/shrinking limits.
53
-
54
- ## Examples and release acceptance
55
-
56
- Bundled examples cover reverse involution, sorting idempotence/sortedness/length/
57
- permutation, nested presence, products/sums, exhaustive matches, total functions,
58
- and recursive payload refinements. Release acceptance includes compiler and
59
- native/WASM checks, native execution on all eight targets, deliberately incorrect
60
- adapters, independent formatting/syntax checks, regeneration protection, and
61
- installation of the packed npm artifact. Publication is a separate step.
package/RUST.md DELETED
@@ -1,211 +0,0 @@
1
- # Rust backend
2
-
3
- Rust is the first backend built on LawSpec's typed core and testing plan. The
4
- compiler remains implemented in Haskell. Rust generation does not parse source
5
- expressions, infer their types, or expand refinement declarations.
6
-
7
- ## Project setup
8
-
9
- Use Rust 1.85 or later, edition 2024, and Cargo. The generated project pins
10
- Proptest 1.11.0, num-bigint 0.4.8, num-rational 0.4.2, num-complex 0.4.6, and
11
- num-traits 0.2.19.
12
-
13
- ```sh
14
- lawspec init --target rust
15
- lawspec doctor
16
- lawspec generate
17
- cargo test
18
- cargo test --release
19
- ```
20
-
21
- Adapters are user-owned files under `src/`. LawSpec maintains
22
- `lawspec_runtime.rs`, module declarations in `lawspec_modules.rs`, and tests
23
- under `tests/`. The scaffolded `src/lib.rs` includes the generated declarations;
24
- an existing library can include those declarations explicitly. Generation
25
- preserves edited adapters and reports required signature updates.
26
-
27
- The numeric runtime has no Proptest dependency. Framework support lives in a
28
- separate generated file, `tests/support/lawspec_strategies.rs`.
29
-
30
- ## Total definitions (0.9)
31
-
32
- Unit-level definitions supply executable implementations alongside laws:
33
-
34
- ```lawspec
35
- unit example.total
36
-
37
- definition size (xs :: List Int8) :: BigInt is
38
- match xs with
39
- | Nil -> 0
40
- | Cons head tail -> 1 + size tail
41
- end
42
- end
43
- ```
44
-
45
- The compiler checks types, exhaustive matching, structural termination, and
46
- potentially failing operations before emission. Definitions may call other
47
- checked definitions, including forward references; they cannot call adapters.
48
- Generic definitions specialize to concrete uses. Refinement predicates may call
49
- checked definitions. Refined definition signatures become checked native contracts.
50
-
51
- Rust emits their implementations into the generated source file
52
- `lawspec_definitions.rs`. They are not user-owned adapter stubs. Typed native
53
- entry points are grouped by unit, for example:
54
-
55
- ```rust
56
- let mut context = lawspec_runtime::Context::default();
57
- let count = lawspec_definitions::example_total::size(&mut context, vec![1, 2, 3])?;
58
- ```
59
-
60
- These entry points return `lawspec_runtime::Result<T>` and check native values
61
- at the boundary. Share the context when Symbol fixture identities must match.
62
- Native machine-sized bindings check the architecture, including fields in
63
- unselected data variants. The implementation has no Proptest dependency and can
64
- be used by the application library. Generated properties invoke the same checked
65
- implementation; remaining external declarations still receive adapter stubs.
66
-
67
- `tools/rust-definitions-integration.mjs` verifies both machine profiles, custom
68
- source/test roots, native calls, readable and compact source, exact `rustfmt`
69
- layout, incorrect adapters, and regeneration ownership.
70
-
71
- ## Formatting (0.9)
72
-
73
- Rust source uses four-space indentation and structured line wrapping. Request
74
- compact layout explicitly with `lawspec generate --minify`, or `minify: true`
75
- in the compiler API. The mode is not saved in project configuration. Formatting
76
- switches preserve user-owned adapters and their canonical interface references.
77
-
78
- `tools/rust-formatting-integration.mjs` compares all Rust artifacts generated
79
- from the bundled examples and the total-definition fixture against rustfmt,
80
- under both machine profiles. Formatting is implemented in the compiler; generated
81
- projects do not need rustfmt to run. The bundled WASM uses the same layout.
82
-
83
- ## Owned adapter values
84
-
85
- Arguments and results are owned Rust values. LawSpec does not add borrowing,
86
- lifetimes, or pointer operations to its language. Tests clone values where an
87
- expression needs to use an input more than once.
88
-
89
- | LawSpec domain | Rust adapter representation |
90
- | --- | --- |
91
- | `Bool` | `bool` |
92
- | Fixed signed/unsigned integers | `i8`…`i64`, `u8`…`u64` |
93
- | `IntSize`, `UIntSize`, `UIntPtr` | `isize`, `usize`, `usize` |
94
- | `BigInt`, `BigUInt` | `BigInt`, `BigUint` |
95
- | `Integer` input | `BigInt` |
96
- | `Integer` result | `Integer`, with lossless `From` implementations |
97
- | `Decimal`, `Rational` | Generated `Decimal`, `BigRational` |
98
- | `Float32`, `Float64` | `f32`, `f64` |
99
- | `Complex64`, `Complex128` | `Complex32`, `Complex64` from num-complex |
100
- | `Char`, `Text` | `char`, `String` |
101
- | `CodePoint`, `CodePointText` | Generated checked wrappers |
102
- | `CodeUnit16`, `Utf16Text`, `Bytes` | `u16`, generated UTF-16 wrapper, `Vec<u8>` |
103
- | `Symbol` | Generated identity type; cloning preserves identity |
104
- | `Unit`, `Null`, `Undefined` | `()`, distinct generated absence types |
105
- | `Nullable a`, `Optional a` | Distinct generated enums, including nested presence |
106
- | `List a` | `Vec<A>` |
107
- | `Maybe a` | `Option<A>` |
108
- | `Either a b` | Generated `Either<A, B>` |
109
- | User-defined products and sums | Named generic enums in `lawspec_data` |
110
-
111
- Names such as `Integer` and `Decimal` above are exported by the generated
112
- `lawspec_runtime` module. Machine-sized native bindings check the requested
113
- `machineBits` against the executing architecture.
114
-
115
- For a declaration such as `successor :: Int8 -> Integer`, an implementation can
116
- return a wider native integer through the logical result wrapper:
117
-
118
- ```rust
119
- use crate::lawspec_runtime as ls;
120
-
121
- pub fn successor(value: i8) -> ls::Integer {
122
- (i16::from(value) + 1).into()
123
- }
124
- ```
125
-
126
- Exact arithmetic in laws uses arbitrary precision. Passing its result to an
127
- `i8` adapter parameter performs a checked conversion. A fractional or
128
- out-of-range value fails with the adapter's context.
129
-
130
- `Decimal` stores an arbitrary integer coefficient and exponent. Decimal
131
- arithmetic is exact; explicit rounding uses the requested scale and ties to
132
- even. Exact-to-float conversion rounds directly to the requested IEEE precision,
133
- including subnormal and halfway cases.
134
-
135
- ## Native data declarations
136
-
137
- User-defined data emits reusable `lawspec_data.rs` and `lawspec_schema.rs` in the
138
- source directory. Adapters receive native enum values with named, typed fields.
139
- A product uses an enum with one record variant. Parameterized fields retain
140
- Rust generic types; recursive fields use `Box` where an inline cycle requires
141
- indirection, while `Vec` already supplies it. Mutually recursive declarations
142
- are resolved together. When two units use the same type name, generated names
143
- are qualified by their unit identities.
144
-
145
- The runtime's `FromValue` and `IntoValue` traits provide conversion bridges.
146
- Generated calls validate the complete logical value before conversion and the
147
- native result before checking postconditions. This preserves raw UTF-16 units,
148
- bytes, nested presence, and primitive range checks inside custom fields.
149
- Machine-width checks also apply to machine integers inside custom data.
150
-
151
- Generated enums derive `Clone` and `Debug`. LawSpec equality remains a runtime
152
- operation: it compares fields structurally, retains IEEE NaN and signed-zero
153
- rules, and compares Symbols by identity. It does not replace these rules with a
154
- derived Rust `Eq` implementation.
155
-
156
- Unused or exclusively recursive type parameters use a `PhantomData` marker.
157
- Types with no constructors remain uninhabited; they do not acquire a synthetic
158
- variant. Generated schemas and conversion support have no Proptest dependency.
159
- The test support composes native Proptest strategies for recursive values and
160
- shrinking, with deterministic boundary cases and finite-domain enumeration.
161
- The structural budget counts each scalar, container, and constructor as one
162
- node. Generation reserves every product field's minimum before distributing
163
- remaining nodes. List length and element budgets vary together, so a deep
164
- singleton remains reachable and lists have no hidden four-element limit.
165
- Native shrinking preserves the schema and the structural budget.
166
-
167
- ## Refinements and generation
168
-
169
- Small finite domains are enumerated. Larger domains use native Proptest
170
- strategies. Integer bounds over earlier inputs become dependent strategies;
171
- when a prefix has no possible continuation, generation retries the prefix.
172
- Shrinking recomputes those dependent bounds and retains only valid tuples.
173
- Refinement evaluation errors fail the test rather than being counted as rejected
174
- samples. Generation limits prevent an empty or unreachable domain from passing
175
- vacuously.
176
-
177
- Contracts check preconditions, evaluate the adapter once, validate its native
178
- result, and then check postconditions on that result.
179
-
180
- ## Custom layouts
181
-
182
- `sourceDir` and `testDir` move generated sources and imports together. Set Cargo's
183
- `[lib] path` to the library entry point under the selected source directory. For
184
- test directories other than `tests`, register generated test files using Cargo
185
- `[[test]]` entries. Doctor checks the selected Cargo package, edition, resolved
186
- dependencies, library directory, and custom test registration.
187
-
188
- Internal typed Core definitions with attached contracts are proved before Rust
189
- emission. Generated source checks preconditions after argument validation and
190
- postconditions after result validation, without property-framework dependencies.
191
- Checks sequence through Result, preserving ordered predicates and contextual
192
- failures. Native wrappers share logical enforcement. Readable contract bodies
193
- match rustfmt exactly.
194
- The shared native fixture passes both machine profiles and formatting modes,
195
- including exact division, narrowing, nested calls, direct logical entry checks,
196
- and rejection of corrupted results. Refined source definition signatures now
197
- produce these contracts through template proof and specialization.
198
-
199
- ## Constructor field contracts
200
-
201
- Rust checks constructor predicates at logical definition and native adapter
202
- boundaries. Generated proptest strategies validate complete candidates, retain
203
- native shrinking, and share each case's Symbol context with witness literals and
204
- assertions. Only false predicates trigger retries; evaluation errors fail the
205
- property. `maxAttempts` bounds local and global rejection, and exhaustion does
206
- not prove an empty domain.
207
-
208
- Validated witnesses seed nested payloads. Builtin lists and presence/sum
209
- containers retain native structural shrinking; sampled named witnesses can
210
- still produce larger counterexamples than native branches. Recursive named
211
- refined payloads remain outside the currently supported contract fragment.
package/WEB.md DELETED
@@ -1,144 +0,0 @@
1
- # JavaScript and TypeScript backends
2
-
3
- LawSpec emits ES modules. JavaScript uses `.mjs`; TypeScript uses `.ts` with `.js`
4
- import paths for NodeNext compilation. Generated data and numeric support belong
5
- in source directories and do not depend on fast-check. Generated properties use
6
- fast-check's native generators and shrinkers.
7
-
8
- ## Native structural values
9
-
10
- `List a` uses `Array<A>`. `Maybe a` and `Either a b` use named classes and, in
11
- TypeScript, generic unions from `lawspec_data`. User products and sums likewise
12
- have named native variant classes. TypeScript retains payload types and nominal
13
- variant identity, including recursive fields and phantom parameters.
14
-
15
- `Nullable a` and `Optional a` use tagged `data.Presence<A>` values, preserving
16
- nested states separately from algebraic `Maybe`. Runtime checks enforce the
17
- presence kind and payload domain. Scalar and structural presence values both use
18
- the schema bridge when crossing native adapter boundaries.
19
-
20
- Checked conversions copy containers, reject sparse arrays and invalid fields,
21
- validate numeric ranges and machine profiles, and preserve raw text and bytes.
22
- LawSpec equality follows the schema: NaN differs from itself, signed zeros compare
23
- equal, and Symbols compare by identity. Ordinary JavaScript object equality is
24
- not a replacement for structural LawSpec equality.
25
-
26
- ## Total definitions
27
-
28
- Checked definitions produce reusable source functions:
29
-
30
- ```lawspec
31
- unit example.total
32
-
33
- definition increment (x :: Int8) :: BigInt is x + 1 end
34
- ```
35
-
36
- ```javascript
37
- import {increment} from './lawspec_definitions/example/total.mjs';
38
-
39
- const symbols = new Map();
40
- const result = increment(symbols, 127); // 128n
41
- ```
42
-
43
- The TypeScript entry point has `symbols: Map<string, symbol>`, `value0: number`,
44
- and a `bigint` result. Native signatures preserve lists, products, sums, and
45
- nested presence payloads. Runtime validation also rejects invalid number ranges,
46
- fractional primitive inputs, and malformed values from JavaScript callers.
47
- Failures identify the resolved definition.
48
-
49
- The first argument shares Symbol fixture identity across calls within an example.
50
- Equal descriptions in separate contexts do not create equal Symbols. Exact
51
- integers use bigint; exact Decimal and Rational operations use the scalar runtime
52
- without passing through Number arithmetic.
53
-
54
- Public modules live under `lawspec_definitions/`, grouped by unit. Checked logical
55
- bodies live in `lawspec_definition_bodies`. Both are generated-owned source.
56
- Properties call the implementations directly; a definition never becomes an
57
- adapter stub. Ordinary adapters remain user-owned. Support-module collisions and
58
- bindings that shadow generated global access are rejected before output.
59
-
60
- Definitions and properties share typed Core expression rendering. Match inputs
61
- are evaluated once, only the selected branch runs, and Boolean guards
62
- short-circuit. Totality validation checks structural descent and potentially
63
- failing operations. Generic definitions specialize to concrete uses. Refined signatures become
64
- checked contracts, and refinement predicates may call checked definitions.
65
-
66
- ## Formatting and verification
67
-
68
- Definition output uses two-space blocks, four-space continuations, single-quoted
69
- strings, and an 80-column layout. String tokens preserve escaped and raw payloads
70
- in readable and compact modes. Compact mode removes optional document breaks.
71
- The public `--minify` path covers runtime, declaration, definition, adapter, and
72
- test artifacts. `tools/web-formatting-integration.mjs` checks the full bundled
73
- corpus for formatting rules and readable/compact syntax-tree equivalence. It
74
- records Prettier differences separately: Prettier's continuation layout is not
75
- the Google four-space continuation rule used here.
76
-
77
- `tools/web-definitions-integration.mjs` checks both targets and machine profiles,
78
- strict TypeScript entry points and rejected assignments, source-only execution,
79
- recursive properties, incorrect adapters, compact output, custom directories,
80
- and regeneration protection. The implementation modules pass strict TypeScript
81
- without `any` or `@ts-nocheck`. Existing schema and numeric runtime TypeScript
82
- files still use `@ts-nocheck`; their public data declarations and definition
83
- entry points are checked separately.
84
-
85
- ## Runtime source formatting
86
-
87
- The checked-in JavaScript scalar runtime, schema runtime, and fast-check helpers
88
- use two-space indentation, single quotes, and an 80-column target, formatted with
89
- Prettier 3.6.2. `node tools/format-web-runtimes.mjs` checks these sources;
90
- `--write` formats them. Set `LAWSPEC_PRETTIER` to the formatter's `index.mjs` when
91
- it is not in `.artifacts/formatter-deps/prettier/`. This development tool never
92
- runs in generated projects or during compiler requests.
93
-
94
- Run `python3 tools/embed-runtimes.py` after runtime edits, then use `--check` to
95
- verify that native/WASM source embedding is current. Both JavaScript and
96
- TypeScript receive the reviewed runtime source, with the existing typed-schema
97
- constructor annotation and module-extension adjustments for TypeScript.
98
-
99
-
100
- Internal checked Core definition contracts now run at native and logical entry
101
- points. Emission proves the obligations first; argument validation precedes
102
- ordered preconditions, and result validation precedes postconditions. Contract
103
- binders map explicitly to body inputs and the checked result. Refined source
104
- signatures now produce these contracts through template proof and specialization.
105
-
106
- `tools/portable-definition-contract-integration.mjs` exercises Python, JavaScript
107
- and strict TypeScript with both machine profiles and layouts, without property
108
- frameworks. It also verifies that deliberately corrupted results are rejected.
109
- The fixture in `test/DefinitionContractFixture.hs` is shared with the JVM checks.
110
-
111
-
112
- ## Generated source style checks
113
-
114
- JavaScript and TypeScript emitters use two-space blocks and four-space
115
- continuations. The latter follows the [Google JavaScript line-wrapping guide](https://google.github.io/styleguide/jsguide.html#s4.5-line-wrapping).
116
- Binary operators remain on the preceding line when an expression wraps.
117
- Generated adapter error messages and tagged scalar values use the shared
118
- single-quoted JavaScript literal renderer.
119
-
120
- `tools/web-formatting-integration.mjs` independently parses both output modes
121
- with TypeScript, compares their syntax trees and literal contents, and checks
122
- quote choice, binary-operator breaks, continuation and statement-block indentation,
123
- the 80-column limit, tabs, and trailing
124
- whitespace. Module imports/re-exports and indivisible source excerpts on their
125
- own comment line are explicit column exceptions. Ordinary prose and code remain
126
- subject to the limit. Long scalar string values use escaped concatenated chunks;
127
- property names remain single tokens. It runs
128
- both machine profiles for the bundled examples and total-definition fixture.
129
- Set `LAWSPEC_CORE` to the native compiler; optional `LAWSPEC_TYPESCRIPT` and
130
- `LAWSPEC_PRETTIER` paths select the cached development tools. Prettier must be
131
- version 3.6.2. Positional arguments select specification files.
132
-
133
- Prettier differences are saved for inspection, not treated as an exact Google
134
- style oracle: its continuation indentation differs from Google's. These checks
135
- are partial style evidence. Additional indentation cases (such as switch bodies
136
- and type declarations) and Kotlin formatter acceptance remain tracked in the 0.9 plan; passing this script alone does not
137
- establish complete style conformance.
138
-
139
- The development-only runtime formatter (`tools/format-web-runtimes.mjs`) applies
140
- Prettier layout and then syntax-tree-directed continuation indentation. It verifies
141
- that JavaScript tokens remain unchanged, retains relative callback block indentation,
142
- and rejects adjustments inside multiline template literals. It is idempotent and
143
- checks the resulting 80-column limit. Reviewed runtime source is embedded at build
144
- time; generated projects never download or invoke these development tools.