lawspec 0.8.0 → 0.10.0

package/PRIMITIVES.md

@@ -1,4 +1,4 @@
-# LawSpec scalar reference (0.8.0)
+# LawSpec scalar reference (0.10.0)
 
 A scalar has a declared domain, checked literals, equality, property inputs, and
 boundary fixtures. General collections, objects, pointers, and type-only constructs

package/PYTHON.md

@@ -0,0 +1,152 @@
+# Python backend
+
+Python output follows [PEP 8](https://peps.python.org/pep-0008/): four-space
+indentation, a 79-column code target, 72-column prose comments/docstrings, and
+two blank lines between top-level definitions. Explicit `--minify` permits
+compact layout while preserving Python indentation and semantics.
+`tools/python-formatting-integration.mjs` checks generated runtime, adapter,
+definition, and test files with pycodestyle 2.14.0 at both machine widths. It
+also compares readable and compact syntax trees, including literal contents.
+
+Use Python 3.13 or later. Generated tests use Hypothesis; generated data classes,
+scalar operations, and schema validation do not depend on a test framework.
+
+## Native structural values
+
+| LawSpec type | Adapter representation |
+| --- | --- |
+| `List a` | `list[A]` |
+| `Maybe a` | `lawspec_schema.Maybe[A]`, with `Nothing` and `Just` variants |
+| `Either a b` | `lawspec_schema.Either[A, B]`, with `Left` and `Right` variants |
+| User-defined products and sums | Named generic dataclasses in `lawspec_data` |
+| `Nullable a`, `Optional a` | Tagged `lawspec_runtime.Presence` values |
+
+`Nothing()` differs from `Just(Nothing())`. `Left(value)` differs from
+`Right(value)`. These algebraic variants are separate from the interoperability
+states represented by `Nullable`, `Optional`, `Null`, and `Undefined`.
+
+For example, this declaration:
+
+```lawspec
+type Tree (a :: Type) is
+  Leaf value :: a
+  Branch children :: List (Tree a)
+end
+```
+
+produces a generic `Tree` base and `TreeLeaf` and `TreeBranch` dataclasses. A
+product has one variant: `Pair` with constructor `Pair` produces `PairPair`.
+When names conflict across units or between types and variants, the compiler
+plans distinct names using their Core identities. Use the emitted declarations
+and adapter annotations as the authoritative names.
+
+Native pattern matching works on the generated variants:
+
+```python
+import lawspec_data as data
+
+
+def count_leaves(tree: data.Tree[int]) -> int:
+    match tree:
+        case data.TreeLeaf():
+            return 1
+        case data.TreeBranch(children=children):
+            return sum(count_leaves(child) for child in children)
+    raise TypeError("unknown Tree variant")
+```
+
+Classes are frozen and use slots. Container payloads are copied when crossing
+adapter boundaries, so modifying a native list does not change another use of
+the logical test input. An abstract base cannot be directly constructed; empty
+types acquire no artificial variant.
+
+LawSpec equality uses schema-directed comparisons, including IEEE NaN and
+signed-zero rules and Symbol identity. Generated dataclasses do not derive
+Python field equality, whose container shortcuts can change those rules.
+
+## Checked boundaries
+
+Generated calls validate input values, convert them to native classes, call the
+adapter, and validate its result. A field extracted from a native product can
+be returned directly from an adapter with the corresponding LawSpec result
+type. The same representation is used for nested and standalone containers.
+
+Diagnostics identify constructor fields and list indices. Checks distinguish
+Bool from integers, enforce primitive ranges under the selected `machineBits`,
+reject invalid scalar text, and preserve raw code units, code points, and bytes.
+Preconditions and postconditions operate on validated logical values.
+
+## Total definitions
+
+Checked total definitions emit reusable Python functions separately from adapters:
+
+```lawspec
+unit example.total
+
+definition increment (x :: Int8) :: BigInt is x + 1 end
+```
+
+```python
+from lawspec_definitions.example import total
+
+symbols = {}
+assert total.increment(symbols, 127) == 128
+```
+
+The first argument is the Symbol fixture context shared within an example.
+Public signatures preserve native container and variant annotations; checked
+conversion enforces element types, ranges, machine profiles, and nested presence
+states at runtime. Errors include the resolved definition name. Source functions
+and implementation bodies have no Hypothesis or pytest dependency.
+
+`lawspec_definition_bodies.py` holds checked logical implementations. Public
+modules under `lawspec_definitions/` provide native entry points grouped by unit.
+Both belong in source directories and are generated-owned. Properties invoke
+those checked bodies directly; definitions do not create adapter stubs. Unit
+modules cannot shadow support modules or another unit's package. Native function
+names such as `str` do not shadow built-ins used by generated validation.
+
+Definition bodies and Python properties share typed expression rendering. Match
+inputs are evaluated once, branches remain lazy, guards short-circuit, and exact
+Decimal arithmetic is independent of Python's ambient rounding context.
+Definitions must pass structural termination and definedness checks. Generic
+definitions specialize to concrete uses. Refined signatures become checked
+contracts, and refinement predicates may call checked definitions.
+
+`tools/python-definitions-integration.mjs` checks standalone source calls,
+properties, incorrect adapters, both machine profiles, custom layouts, compact
+execution, and regeneration protection. The bundled Python corpus passes PEP 8 checks at 79 code columns and 72 prose
+columns. The style audit includes the standalone total-definition fixture.
+
+## Generation and layouts
+
+Hypothesis composes tuples, alternatives, lists, and dependent strategies.
+Recursive generation reserves each field's minimum node budget before sharing
+the remainder. List length and element budgets vary together. Shrinking remains
+native to Hypothesis and preserves the schema and structural size bound.
+Small finite domains are enumerated; empty domains do not pass vacuously.
+
+`lawspec_data.py` and `lawspec_schema.py` belong in the configured source
+directory. `lawspec_data_strategies.py` belongs in the test directory. Configure
+Python's import paths for those directories when using a custom layout.
+Adapters remain user-owned. Unit names cannot shadow generated support modules.
+
+
+Internal checked Core definition contracts now run at native and logical entry
+points. Emission proves the obligations first; argument validation precedes
+ordered preconditions, and result validation precedes postconditions. Contract
+binders map explicitly to body inputs and the checked result. Refined source
+signatures now produce these contracts through template proof and specialization.
+
+`tools/portable-definition-contract-integration.mjs` exercises Python, JavaScript
+and strict TypeScript with both machine profiles and layouts, without property
+frameworks. It also verifies that deliberately corrupted results are rejected.
+The fixture in `test/DefinitionContractFixture.hs` is shared with the JVM checks.
+
+## Checking Python style
+
+Set `LAWSPEC_CORE` to the native compiler, `LAWSPEC_PYTHON` to Python 3.13 or
+later, and `LAWSPEC_PYCODESTYLE` to the `pycodestyle.py` source from version
+2.14.0. Then run `node tools/python-formatting-integration.mjs`. The checker is
+a development dependency; generating and executing runtime code does not
+require it. Optional positional arguments select individual specification files.

package/README.md

@@ -2,10 +2,23 @@
 
 **State the law once. Check it everywhere.**
 
-LawSpec 0.8 compiles reusable laws into native property tests, executable examples,
+LawSpec 0.10 compiles reusable laws into native property tests, executable examples,
 and implementation adapters. The compiler is Haskell, distributed as prebuilt
 WebAssembly with a Node CLI and an asynchronous, typed JavaScript API.
 
+## Structural data and total definitions in 0.9.0
+
+LawSpec 0.9 adds `List`, algebraic `Maybe` and `Either`, named
+parameterized products and sums, and checked total definitions on all eight
+backends. See the [language reference](LANGUAGE.md),
+[collections](examples/specs/collections.lawspec),
+[data types](examples/specs/data_types.lawspec), and
+[total functions](examples/specs/total_functions.lawspec).
+
+Generated code is readable by default; `--minify` explicitly selects compact
+output. Python follows PEP 8. See the [0.9 release notes](RELEASE-0.9.md)
+and [API migration guide](API-MIGRATION.md).
+
 ## Rust and the typed front end in 0.8.0
 
 Rust joins Java, Python, JavaScript, TypeScript, Go, Haskell, and Kotlin. All
@@ -23,12 +36,27 @@ Compiler API consumers should read the [schema v3 migration guide](API-MIGRATION
 Scalar values use tagged, lossless encodings; generated runtime placement is
 separate from artifact ownership. Java 25+ and Python 3.13+ baselines are unchanged.
 
+## Native domain bindings in 0.10
+
+LawSpec 0.10 adds configuration for existing application products and sums,
+function bindings, checked conversion hooks, and native property-generator
+factories on all eight targets. Generators retain their framework's shrinkers;
+explicit examples, boundaries, and finite-domain checks remain independent.
+See the [native-binding reference and acceptance status](NATIVE-BINDINGS.md),
+the [release notes](RELEASE-0.10.md), and
+[schema 4 migration notes](API-MIGRATION.md#schema-4-native-bindings).
+Existing specifications without bindings retain their behavior.
+
 ## Install and try it
 
+LawSpec has its own [syntax-highlighting grammar and VS Code extension](editors/vscode/README.md)
+for keywords, types, refinements, literals, and law names. GitHub needs upstream Linguist
+support to use it; GitHub currently uses the Haskell fallback.
+
 Install [LawSpec from npm](https://www.npmjs.com/package/lawspec):
 
 ```sh
-npm install --save-dev lawspec@0.8.0
+npm install --save-dev lawspec@0.10.0
 npx lawspec --version
 ```
 
@@ -42,8 +70,8 @@ local dependencies so LawSpec can create its `package.json` and test script:
 ```sh
 mkdir lawspec-example
 cd lawspec-example
-npm exec --package=lawspec@0.8.0 -- lawspec init --target javascript
-npm install --save-dev lawspec@0.8.0
+npm exec --package=lawspec@0.10.0 -- lawspec init --target javascript
+npm install --save-dev lawspec@0.10.0
 npx lawspec check
 npx lawspec explain 'example.atoi_codec::itoa and then atoi yields a'
 npx lawspec doctor
@@ -179,11 +207,13 @@ Reusable laws can declare typed unary function parameters and `requires Eq a`, n
 [parameterized refinements and executable contracts](REFINEMENTS.md).
 Definitions support law application, function application/composition, universal
 quantification, `implies`, Boolean predicates, scalar literals, and equality.
-Function signatures and quantified inputs support the [scalar catalog](PRIMITIVES.md),
-including mixed and multiple inputs. Generic variables are supported in reusable
-laws. Scalar types can also be intermediate or compared results. Functions are synchronous and support curried signatures with any positive
-number of scalar arguments. Text literals are double-quoted, with escapes such as `\"`, `\\`,
-`\n`, and `\t`; examples must bind each input to a literal of its declared type.
+Function signatures and quantified inputs support the [scalar catalog](PRIMITIVES.md)
+and [structural types](LANGUAGE.md), including mixed and multiple inputs.
+Generic variables are supported in reusable laws. Scalar and structural values
+can also be intermediate or compared results. Functions are synchronous and
+support curried signatures with any positive number of arguments. Text literals
+are double-quoted, with escapes such as `\"`, `\\`, `\n`, and `\t`; examples must
+bind each input to a concrete value of its declared type.
 Text values contain Unicode scalar values; surrogate code points are rejected.
 
 Examples refer to the expanded input names, including names inherited from the
@@ -193,9 +223,10 @@ produce literal braces. Law blocks use this order:
 definition, optional description, optional rationale, examples, optional references.
 `--` starts a line comment. Names that cannot be emitted portably are diagnosed.
 
-General collections, external law packages, cross-unit imports beyond the
-prelude, async functions, direct existing-symbol binding and browser hosting are
-outside this release.
+Collections beyond `List`, external law packages, cross-unit imports beyond the
+prelude, async functions and browser hosting remain outside the language.
+Direct existing-symbol bindings are part of LawSpec 0.10 described
+above; the published 0.9 release uses implementation adapters.
 
 ## Algebra and currying (0.6)
 
@@ -250,7 +281,7 @@ reusable laws accept these curried functions, their partial applications, and
 scalar parameters. Quantified test inputs remain scalar.
 
 The prelude defines the following laws. Every row has an executable example in
-[algebra.lawspec](https://github.com/brain-fuel/lawspec/blob/v0.8.0/examples/specs/algebra.lawspec), including both sides of every
+[algebra.lawspec](https://github.com/brain-fuel/lawspec/blob/v0.10.0/examples/specs/algebra.lawspec), including both sides of every
 combined law. `f` and `g` are binary operations, `inverse` is unary, and `e` and
 `zero` are scalar parameters. All these laws require equality of the element type.
 
@@ -318,7 +349,7 @@ their entire consequence. Every conjunct is type-checked and emitted. As with
 existing assertions, the first failure stops that individual test. `and` is now
 a reserved word.
 
-[Currying examples](https://github.com/brain-fuel/lawspec/blob/v0.8.0/examples/specs/currying.lawspec) demonstrate a four-argument
+[Currying examples](https://github.com/brain-fuel/lawspec/blob/v0.10.0/examples/specs/currying.lawspec) demonstrate a four-argument
 function partially applied twice, a formatter with four heterogeneous arguments,
 and composition after partial application. Each example states its exact outputs.
 Run `node npm/bin/lawspec.mjs examples` after rebuilding to inspect all nine units
@@ -370,7 +401,7 @@ law `valid ports round trip` is
 end
 ```
 
-The [complete port example](https://github.com/brain-fuel/lawspec/blob/v0.8.0/examples/specs/parse_port.lawspec)
+The [complete port example](https://github.com/brain-fuel/lawspec/blob/v0.10.0/examples/specs/parse_port.lawspec)
 defines valid ports as 1–65535, and covers both endpoints, ordinary ports, zero,
 negative values, and 65536. All explicit `expect` assertions run regardless of
 the law's condition. A false condition skips only the consequence: invalid ports
@@ -388,7 +419,7 @@ The prelude includes `satisfies predicate` (the predicate holds for every input)
 and `left inverse when predicate parse render` (the guarded round trip above).
 These reusable laws preserve the condition and its lexical bindings when expanded.
 `equivalent` can also compare two predicates, since `Bool` supports equality.
-The [Boolean flags example](https://github.com/brain-fuel/lawspec/blob/v0.8.0/examples/specs/boolean_flags.lawspec)
+The [Boolean flags example](https://github.com/brain-fuel/lawspec/blob/v0.10.0/examples/specs/boolean_flags.lawspec)
 checks that flipping twice restores both `false` and `true`; all targets generate
 Boolean property inputs and explicit tests for both Boolean boundary values. Java caps Boolean-only JetCheck runs at the number of
 possible input combinations (up to 100), avoiding generator exhaustion.
@@ -467,7 +498,7 @@ This expands to `for all (x :: Int32) . render (x) = referenceRender (x)`.
 The example inherits the input name `x` from the prelude. Both functions are
 user-owned adapter functions; either may delegate to your existing code.
 
-[The complete example](https://github.com/brain-fuel/lawspec/blob/v0.8.0/examples/specs/equivalent.lawspec) compares decimal
+[The complete example](https://github.com/brain-fuel/lawspec/blob/v0.10.0/examples/specs/equivalent.lawspec) compares decimal
 renderers and two implementations that clamp negative integers to zero. For
 JavaScript, their adapters can be:
 
@@ -504,7 +535,7 @@ law `normalizers agree` is
 end
 ```
 
-The [slug example](https://github.com/brain-fuel/lawspec/blob/v0.8.0/examples/specs/slug.lawspec)
+The [slug example](https://github.com/brain-fuel/lawspec/blob/v0.10.0/examples/specs/slug.lawspec)
 compares two implementations of ASCII-space replacement. It includes empty,
 Unicode and escaped text. Each target uses its native string generator:
 JetCheck `Generator.stringsOf(Generator.asciiPrintableChars())`, Hypothesis `st.text()`, fast-check `fc.string()`,
@@ -531,7 +562,7 @@ law `canonicalization reaches a fixed point` is
 end
 ```
 
-The [canonical URL example](https://github.com/brain-fuel/lawspec/blob/v0.8.0/examples/specs/canonical_url.lawspec)
+The [canonical URL example](https://github.com/brain-fuel/lawspec/blob/v0.10.0/examples/specs/canonical_url.lawspec)
 uses removal of **all trailing slashes** as a small fixed-point demonstration,
 not a complete URL canonicalization algorithm. For JavaScript:
 
@@ -540,13 +571,31 @@ export const canonicalize = value => value.replace(/\/+$/, "");
 ```
 
 Removing just one trailing slash fails the supplied repeated-slash example.
-The [mixed-input example](https://github.com/brain-fuel/lawspec/blob/v0.8.0/examples/specs/mixed_inputs.lawspec)
+The [mixed-input example](https://github.com/brain-fuel/lawspec/blob/v0.10.0/examples/specs/mixed_inputs.lawspec)
 shows `Text` and `Int32` in the same quantified property and executable example.
-The JavaScript API represents input bindings and expected values as `number | string | boolean`.
-Each example includes `expectations: { actual: Expr; expected: number | string | boolean }[]`.
+The JavaScript API represents example bindings as typed records whose values use
+`DataValue`: lossless tagged scalar payloads or structural constructors. Expected results are
+typed expressions inside `Assertion` trees, not untyped JavaScript primitives.
+See the [API migration guide](API-MIGRATION.md) for their wire representation.
 
 ## Generate all example artifacts
 
+To use native domain bindings, export the runnable payment
+example (omit `--target` to export all eight languages):
+
+```sh
+lawspec examples --example payments --target rust --output native_payments
+cd native_payments/rust
+# Install the dependencies listed in README.md, then:
+lawspec check
+lawspec generate
+cargo test
+```
+
+These projects include application-owned types, native generators, binding
+configuration, and build files. Re-exporting preserves edits and leaves the
+compiler's generation manifest separate from the example export manifest.
+
 ```sh
 npx lawspec examples
 # Or select a target and a relative output directory:
@@ -605,7 +654,7 @@ by the JS shim.
 ## Build and verify
 
 For contributors working from a repository checkout, build a local archive with
-`npm pack ./npm` and install it with `npm install --save-dev ./lawspec-0.8.0.tgz`.
+`npm pack ./npm` and install it with `npm install --save-dev ./lawspec-0.10.0.tgz`.
 The package payload lives in `npm/`.
 
 ```sh
@@ -644,6 +693,20 @@ unchanged. Arguments select individual targets. `LAWSPEC_PYTHON=3.14` selects th
 additional Python reference environment. CI also exercises Node 22/24/26 and packs
 and installs the npm archive. Registry publication is a separate release action.
 
+The native-binding acceptance command uses the installed npm archive, public CLI,
+and the selected target's normal test command:
+
+```sh
+node tools/native-example-integration.mjs rust
+LAWSPEC_MACHINE_BITS=32 LAWSPEC_MINIFY=1 node tools/native-example-integration.mjs rust
+```
+
+Replace `rust` with any supported target. It exports the payment project, verifies
+correct behavior, rejects an incorrect fee, and checks regeneration. Per-command
+logs live in `.artifacts/native-example-integration/`. See the
+[acceptance reference](NATIVE-BINDINGS.md) for dependency overrides and remaining
+verification gates.
+
 
 Refinement predicates can depend on earlier inputs. Generated tests backtrack from
 impossible prefixes, preserve the domain during shrinking, and validate function