lawspec 0.8.0 → 0.9.0

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.9 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
@@ -28,7 +41,7 @@ separate from artifact ownership. Java 25+ and Python 3.13+ baselines are unchan
 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.9.0
 npx lawspec --version
 ```
 
@@ -42,8 +55,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.9.0 -- lawspec init --target javascript
+npm install --save-dev lawspec@0.9.0
 npx lawspec check
 npx lawspec explain 'example.atoi_codec::itoa and then atoi yields a'
 npx lawspec doctor
@@ -250,7 +263,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.9.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 +331,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.9.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 +383,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.9.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 +401,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.9.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 +480,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.9.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 +517,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.9.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 +544,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.9.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,7 +553,7 @@ 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.9.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 }[]`.
@@ -605,7 +618,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.9.0.tgz`.
 The package payload lives in `npm/`.
 
 ```sh

package/REFINEMENTS.md

@@ -1,4 +1,4 @@
-# Refinements and abstract integers (0.8.0)
+# Refinements and abstract integers (0.9.0)
 
 A refinement restricts a scalar domain with a pure Boolean expression. LawSpec
 checks concrete examples, generates satisfying input tuples, and checks adapter
@@ -82,7 +82,8 @@ refinement PositiveInt8 is (value :: Int8 where value > 0) end
 
 Aliases preserve their underlying native representation. They can be nested in
 `Nullable` and `Optional`; inner predicates are checked only for present values.
-Type parameters range over the supported scalar types, including presence types.
+Type parameters range over supported value types, including structural types.
+Their declared capabilities determine which operations are available.
 
 `requires Integer T` describes integer capabilities in a generic declaration.
 `Integer` entails `Eq` and `Ordered`. `Ordered` currently covers exact real numbers
@@ -108,7 +109,30 @@ Adapter calls are forbidden in refinements. Predicate errors such as division by
 zero are reported as failures when evaluated; they are not ordinary rejection of
 an input. Short-circuited branches are not evaluated by generation optimizations.
 
-Every refined function signature creates a standalone property. Calls from other
+In the 0.9 frontend, predicates can call checked total definitions, including
+generic definitions specialized to the predicate's concrete types:
+
+```lawspec
+definition nonempty (xs :: List a) :: Bool is
+  match xs with
+    | Nil -> false
+    | Cons head tail -> true
+  end
+end
+
+refinement Nonempty (T :: Type) is
+  (xs :: List T where nonempty xs)
+end
+```
+
+The same closed definitions evaluate example inputs, constant refinement
+arguments, finite domains, and boundaries, and run in generated predicate and
+contract checks on all eight targets. Calls to adapters cannot enter that closed
+environment. Definitions can also refine their own parameters and results.
+Their bodies must be proved total under the ordered input preconditions, and
+every result refinement must follow from the body.
+
+Every refined adapter signature creates a standalone property. Calls from other
 laws also check argument preconditions, invoke the adapter once, snapshot its
 result, and check postconditions. Calling a function outside its precondition is
 a test failure, not a discarded example. Ordinary `implies` guards retain their
@@ -156,3 +180,265 @@ Statically established empty executable domains and invalid examples are rejecte
 See [the bundled examples](examples/specs/refinements.lawspec) for overflow,
 abstract integer arguments/results, dependent bounds, optional refinements,
 floating classification, and raw-byte lengths.
+
+
+## Refined definitions
+
+```lawspec
+definition increment (x :: Int8 where x < 127)
+  :: (result :: Int8 where result > x)
+is
+  prelude.Int8 (x + 1)
+end
+```
+
+Arithmetic promotes before the explicit Int8 conversion. The compiler proves
+that the precondition makes the conversion safe and that the result exceeds x.
+Later parameters may depend on earlier parameters. Result binders must differ
+from argument names.
+
+Generic definitions retain their contracts through specialization. Templates,
+including unused ones, must pass type, capability, termination and definedness
+checks before concrete instances are emitted. Each closed call must satisfy its
+callee's preconditions. Contracts cannot depend cyclically on their definitions
+or call adapters. A claim the proof checker cannot establish is rejected.
+
+The reference evaluator and all eight native backends validate arguments, check
+preconditions in order, evaluate the body, validate its result, and check
+postconditions. An invalid native call fails before unsafe body arithmetic.
+Definitions are proved during compilation; adapter contracts instead generate
+standalone properties because their implementations are external.
+
+See [refined definitions](examples/specs/refined_definitions.lawspec) for generic
+reciprocals, checked narrowing and dependent bounds. Both the native compiler
+and packaged WASM build support these contracts.
+
+The native definition-contract harnesses accept `LAWSPEC_CONTRACT_SOURCE=1`.
+This compiles `test/fixtures/definition_contracts.lawspec` through the public
+frontend before emitting native code. All eight targets pass both machine
+profiles and readable/compact modes, including ordered predicate checks, exact
+division through a specialized generic helper, narrowing, direct logical calls,
+and postcondition rejection of deliberately corrupted results. The default mode
+retains the independently constructed Core fixture.
+
+## Sum payload refinements
+
+`Maybe (value :: Int8 where value > 0)` admits `Nothing` and positive `Just`
+payloads. `Either (value :: Int8 where value > 0) Bool` checks the positive bound
+only for `Left`; `Right` retains its Bool domain. Nested sums compose these
+checks, and payload predicates may refer to earlier quantified inputs.
+
+These refinements elaborate to exhaustive Core matches. Unselected branches are
+not evaluated, and generated binder names preserve outer dependencies. Finite
+domains retain distinct absence and variant states. Named data payload and constructor-field refinements are also supported. The bundled [sum refinement examples](examples/specs/sum_refinements.lawspec)
+pass native framework execution on all eight targets under both machine profiles
+and readable/compact layouts. The data integration harnesses include these laws
+with their existing structural and incorrect-adapter checks.
+
+
+## List payload refinements
+
+`List (value :: Int8 where value > 0)` constrains every element and admits the
+empty list. Lists compose with other Lists, Maybe, and Either. An element
+predicate can refer to an earlier quantified input, for example:
+
+```lawspec
+law `elements exceed the earlier bound` is
+  definition is `for all` (floor :: Int8)
+    (xs :: List (value :: Int8 where value > floor)) .
+    prelude.length xs >= 0
+  end
+end
+```
+
+These domains elaborate to a typed, scoped Core `AllElements` predicate. It
+checks elements in order, stops at the first false result, and returns true for
+an empty list. Its binder is fresh with respect to outer dependencies. There is
+no new user-facing predicate syntax. Explicit examples outside the domain are
+rejected; nested predicates keep their element scope during specialization.
+See [the List refinement examples](examples/specs/list_refinements.lawspec).
+
+Generic definition signatures can contain List payload refinements, including
+calls to generic Boolean helpers. Native entry points check these contracts.
+The totality prover retains universal element facts for each List identity.
+A stronger exact numeric bound can satisfy a weaker callee contract, including
+nested Lists. Matching calls to pure Boolean helpers can also be reused after
+specialization. Returned inputs and explicitly constructed Lists can establish
+universal postconditions; the empty list satisfies every element predicate.
+See [the List contract examples](examples/specs/list_contracts.lawspec).
+
+Proof binders are fresh and scoped. An element condition never implies that a
+list is nonempty, and facts about one list do not transfer to another list or to
+an unrelated scalar. In a `Cons first rest` branch, `first` inherits the element
+predicate and `rest` retains the universal predicate with its original outer
+dependencies. Both are strict structural subterms for termination checking. A
+`Nil` branch knows only that its matched list is empty. These facts stay inside
+their branch and can establish branch-specific result contracts.
+
+For example, a definition over `List (value :: Int8 where value != 0)` can divide
+by each matched head and recursively process the tail. The bundled List contract
+examples include exact reciprocal sums and nested rows. More complex implications,
+including facts requiring a callee's result contract to be unfolded, remain
+conservative and may be rejected.
+
+Verified callee results are available to the total-definition proof checker.
+A helper's postcondition can establish a nonzero divisor, justify checked integer
+narrowing, or satisfy the next helper's input contract. For example:
+
+```lawspec
+definition nonzero (value :: Int8 where value != 0)
+  :: (result :: Int8 where result != 0)
+is value end
+
+definition reciprocal (value :: Int8 where value != 0) :: Rational is
+  1 / nonzero value
+end
+```
+
+The checker first proves the call's preconditions and, for recursive calls,
+strict structural descent. Only then does it use the result guarantee. Recursive
+List construction can therefore prove element postconditions by induction over
+the tail. A returned List does not itself acquire structural-subterm status.
+Guarantees remain scoped to evaluated branches and short-circuit operands;
+a skipped call cannot justify arithmetic elsewhere. Every helper's own result
+contract is checked, including helpers unused by laws.
+
+Constructor-sensitive matching also preserves payload refinements in total
+functions. A `Maybe` payload fact is available in the `Just` branch; an `Either`
+fact belongs to its corresponding `Left` or `Right` branch. Constructed results
+are checked against the matching alternative, including nested sums.
+
+Whole-value refinements on named products can relate fields explicitly:
+
+```lawspec
+type Range is Range lower :: Int8 upper :: Int8 end
+
+definition gap
+  (range :: Range where match range with | Range lo hi -> hi > lo end)
+  :: Rational
+is
+  match range with | Range lo hi -> 1 / (hi - lo) end
+end
+```
+
+The field relation justifies the nonzero denominator within that branch. It
+cannot establish a fact about a different value or another constructor's payload.
+This example uses a refinement on the function's whole input value; direct
+constructor-field refinements can express the relation at the data declaration.
+
+
+## Named data payloads
+
+A product or sum can receive refined type arguments. The predicate
+applies wherever that parameter is stored, including recursive named
+types, List elements, and Maybe/Either payloads. Other alternatives remain
+unconstrained when they do not store that parameter.
+
+```lawspec
+unit example.positive_pair
+
+type Pair (a :: Type) (b :: Type) is
+  Pair first :: a second :: b
+end
+
+refinement Positive is (value :: Int8 where value > 0) end
+
+definition reciprocal (pair :: Pair Positive Bool) :: Rational is
+  match pair with
+    | Pair first second -> 1 / first
+  end
+end
+
+law `half` is
+  definition is
+    `for all` (pair :: Pair Positive Bool) . reciprocal pair > 0
+  end
+  example `two` is
+    pair = Pair 2 false
+    expect reciprocal pair = rational(1, 2)
+  end
+end
+```
+
+The compiler lowers the payload requirement to a scoped traversal in the shared
+Core. Generators, concrete examples, adapter contracts, and checked definition
+entry points use that predicate. The native representation remains
+`Pair Int8 Bool`; the refinement does not introduce a new wrapper type. Definition proofs
+can use the selected field's predicate to establish that division is defined.
+
+Free value names in a type argument retain the scope where the argument was
+written. In `Pair Int8 (n :: Int8 where n > first)`, `first` refers to an earlier
+outer input; a constructor field also named `first` does not capture it.
+
+Recursive payloads such as `Tree Positive` use the same operation. Traversal
+follows stored parameter positions, including mutual recursion and growing
+arguments such as `Nest (List a)`. A fixed `Int8` field is not constrained merely
+because another parameter is instantiated as `Int8`. Empty and phantom storage
+satisfies its payload predicate without evaluating a callback. See the bundled
+[recursive refinement example](examples/specs/recursive_refinements.lawspec),
+which proves a positive result for a recursive sum and preserves outer thresholds.
+
+The front end checks direct constructor field contracts:
+
+```lawspec
+type Gap is
+  Gap first :: Int8 second :: (n :: Int8 where n > first)
+end
+
+definition inverseGap (gap :: Gap) :: Rational is
+  match gap with | Gap x y -> 1 / (y - x) end
+end
+```
+
+A field predicate may refer to that field and earlier fields. Construction in a
+total definition must prove the predicates; matching makes them available in the
+selected branch. Concrete example inputs and expected values are checked too.
+The reference interpreter enforces predicates on definition inputs and results.
+All eight backends enforce these
+contracts in generated runtime checks and native Hypothesis/fast-check/proptest/
+JetCheck/Kotest/Rapid/Hedgehog strategies. Each generated case
+shares one Symbol fixture context across witnesses, inputs, adapter checks and
+assertions. Witnesses supplement native strategies; sampled alternatives may
+retain large counterexamples even when native branches can shrink further.
+Web and Rust generation bound whole-value retries with `maxAttempts`; an exhausted search
+reports failure rather than claiming that the domain is empty. Input guards use
+fast-check preconditions, preserving its skip and shrink handling. Rust carries
+predicate evaluation errors into property failures rather than treating them as
+rejected candidates. Java preserves native JetCheck filtering/shrinking, caps each
+filter at the smaller of `maxAttempts` and the framework's 100-attempt limit, and
+reports evaluator errors as contextual generation failures. It uses one native
+session per requested constructor-contract case to avoid session-wide draw
+uniqueness exhaustion for fixture identities. Kotlin bounds candidate sampling
+while retaining native shrink trees; case state carries evaluator errors past
+input guards to the property failure. Go uses Rapid's bounded native filtering
+and replay-based shrinking, with per-sample error state that prevents later fields
+from hiding an evaluator failure. Required conjunctive Symbol equalities bind the
+fixture identity directly; disjunctions retain their alternatives. Go's structural
+properties honor `cases` with scoped Rapid settings, restoring the previous flag
+after each sequential generated test. Rapid's explicit short-test mode may reduce
+that count. Each filter uses at most the smaller of `maxAttempts` and Rapid's
+five-attempt native limit; enclosing native generators and the engine retain
+their own retry limits. For structural Go properties, minimization uses Rapid's
+`-rapid.shrinktime` setting, not the scalar refinement engine's `maxShrinks`
+step budget. Haskell constructor properties use native Hedgehog strategies with
+one Symbol context per case. Each dependent draw is forced before the next draw;
+evaluator failures cannot disappear behind a later discard. Native `filterT`
+prunes rejected shrink branches instead of searching all their descendants.
+Hedgehog receives `cases` as its test limit, `maxAttempts` as its property discard
+limit, and `maxShrinks` as its shrink limit. Internal generator filters retain
+Hedgehog's own retry policy; `maxAttempts` is not a total count of candidate draws.
+Recursively refined named payloads use scoped payload predicates that follow
+declared type-parameter positions through constructor fields.
+
+Common domain planning filters finite constructor domains through their field
+predicates. For larger domains, it searches combinations of field boundaries and
+literal values from contracts. This covers dependent fields such as `Gap` and
+sparse Symbol fixture identities. Recursive expansion and candidate combinations
+have finite search budgets; every returned witness satisfies the contracts.
+Exhausting that search reports that no witness was found, rather than declaring
+the domain empty. Bounded samples are never reported as an exhaustive domain.
+
+Expression annotations select a representation, such as `(127 :: Int8)`; they
+do not establish a refinement contract. Inline refinement predicates in expression
+annotations are rejected. Put the refinement on a quantified input or function
+signature so that generation, checking, and definition proofs enforce it.

package/RELEASE-0.9.md

@@ -0,0 +1,61 @@
+# LawSpec 0.9.0
+
+This release adds structural data and checked total definitions across Java,
+Python, JavaScript, TypeScript, Go, Haskell, Kotlin, and Rust.
+
+## Language
+
+- `List a` supports nested contextual literals, structural equality, exact
+  length, deterministic boundaries, and native framework generation/shrinking.
+- Algebraic `Maybe a` and `Either a b` provide `Nothing`/`Just` and `Left`/`Right`.
+  They remain distinct from interoperability `Nullable` and `Optional` values.
+- Named parameterized products and sums have constructors and ordered fields.
+  Generated native types and typed adapters preserve their structure.
+- Total definitions support exhaustive matching and checked structural recursion.
+  The compiler rejects partial matches and recursion it cannot establish as
+  terminating. Generic definitions specialize to their concrete uses.
+- Refined definition signatures become executable native contracts. Scoped
+  payload predicates preserve type-parameter roles through recursive and mutual
+  data declarations, including predicates that depend on preceding inputs.
+
+Existing scalar semantics remain intact: exact arithmetic does not wrap,
+conversions to bounded adapter parameters are checked, floating equality follows
+IEEE rules, and Symbol equality uses identity.
+
+## Generated output
+
+Readable code is the default for runtimes, declarations, definitions, adapters,
+tests, and scaffolds. Explicit `--minify` selects compact output for `init`,
+`generate`, and `examples`; the compiler API accepts `minify: true`.
+
+Output follows Google language-specific guidance where applicable, PEP 8 for
+Python, standard Go and Rust formatting, and an 80-column Haskell layout.
+Formatting is deterministic in both native and WASM compilation and requires
+no formatter download. Compact output preserves required layout, literal
+contents, and semantics. Changing formatting mode does not overwrite edited
+adapters or create false adapter-signature updates.
+
+## API and compatibility
+
+API schema 3 adds named data declarations, structural values, checked definitions,
+construction/matching expressions, and scoped payload predicates. Existing scalar
+wire encodings are unchanged. Exhaustive expression visitors must handle the
+new variants; see [API migration](API-MIGRATION.md).
+
+Java 25+, Python 3.13+, Node 22+, and Rust 1.85+ baselines remain unchanged.
+Machine-width profiles, custom source/test directories, generation manifests,
+and user ownership of adapters/build files remain supported. Framework-specific
+strategies stay separate from reusable runtime source.
+
+GADTs, indexed families, and general dependent types remain future work. See
+[the language reference](LANGUAGE.md) and the target guides for native type
+representations and framework-specific refinement/shrinking limits.
+
+## Examples and release acceptance
+
+Bundled examples cover reverse involution, sorting idempotence/sortedness/length/
+permutation, nested presence, products/sums, exhaustive matches, total functions,
+and recursive payload refinements. Release acceptance includes compiler and
+native/WASM checks, native execution on all eight targets, deliberately incorrect
+adapters, independent formatting/syntax checks, regeneration protection, and
+installation of the packed npm artifact. Publication is a separate step.

package/RUST.md

@@ -1,4 +1,4 @@
-# Rust backend (0.8)
+# Rust backend
 
 Rust is the first backend built on LawSpec's typed core and testing plan. The
 compiler remains implemented in Haskell. Rust generation does not parse source
@@ -27,6 +27,59 @@ preserves edited adapters and reports required signature updates.
 The numeric runtime has no Proptest dependency. Framework support lives in a
 separate generated file, `tests/support/lawspec_strategies.rs`.
 
+## Total definitions (0.9)
+
+Unit-level definitions supply executable implementations alongside laws:
+
+```lawspec
+unit example.total
+
+definition size (xs :: List Int8) :: BigInt is
+  match xs with
+    | Nil -> 0
+    | Cons head tail -> 1 + size tail
+  end
+end
+```
+
+The compiler checks types, exhaustive matching, structural termination, and
+potentially failing operations before emission. Definitions may call other
+checked definitions, including forward references; they cannot call adapters.
+Generic definitions specialize to concrete uses. Refinement predicates may call
+checked definitions. Refined definition signatures become checked native contracts.
+
+Rust emits their implementations into the generated source file
+`lawspec_definitions.rs`. They are not user-owned adapter stubs. Typed native
+entry points are grouped by unit, for example:
+
+```rust
+let mut context = lawspec_runtime::Context::default();
+let count = lawspec_definitions::example_total::size(&mut context, vec![1, 2, 3])?;
+```
+
+These entry points return `lawspec_runtime::Result<T>` and check native values
+at the boundary. Share the context when Symbol fixture identities must match.
+Native machine-sized bindings check the architecture, including fields in
+unselected data variants. The implementation has no Proptest dependency and can
+be used by the application library. Generated properties invoke the same checked
+implementation; remaining external declarations still receive adapter stubs.
+
+`tools/rust-definitions-integration.mjs` verifies both machine profiles, custom
+source/test roots, native calls, readable and compact source, exact `rustfmt`
+layout, incorrect adapters, and regeneration ownership.
+
+## Formatting (0.9)
+
+Rust source uses four-space indentation and structured line wrapping. Request
+compact layout explicitly with `lawspec generate --minify`, or `minify: true`
+in the compiler API. The mode is not saved in project configuration. Formatting
+switches preserve user-owned adapters and their canonical interface references.
+
+`tools/rust-formatting-integration.mjs` compares all Rust artifacts generated
+from the bundled examples and the total-definition fixture against rustfmt,
+under both machine profiles. Formatting is implemented in the compiler; generated
+projects do not need rustfmt to run. The bundled WASM uses the same layout.
+
 ## Owned adapter values
 
 Arguments and results are owned Rust values. LawSpec does not add borrowing,
@@ -50,6 +103,10 @@ expression needs to use an input more than once.
 | `Symbol` | Generated identity type; cloning preserves identity |
 | `Unit`, `Null`, `Undefined` | `()`, distinct generated absence types |
 | `Nullable a`, `Optional a` | Distinct generated enums, including nested presence |
+| `List a` | `Vec<A>` |
+| `Maybe a` | `Option<A>` |
+| `Either a b` | Generated `Either<A, B>` |
+| User-defined products and sums | Named generic enums in `lawspec_data` |
 
 Names such as `Integer` and `Decimal` above are exported by the generated
 `lawspec_runtime` module. Machine-sized native bindings check the requested
@@ -75,6 +132,38 @@ arithmetic is exact; explicit rounding uses the requested scale and ties to
 even. Exact-to-float conversion rounds directly to the requested IEEE precision,
 including subnormal and halfway cases.
 
+## Native data declarations
+
+User-defined data emits reusable `lawspec_data.rs` and `lawspec_schema.rs` in the
+source directory. Adapters receive native enum values with named, typed fields.
+A product uses an enum with one record variant. Parameterized fields retain
+Rust generic types; recursive fields use `Box` where an inline cycle requires
+indirection, while `Vec` already supplies it. Mutually recursive declarations
+are resolved together. When two units use the same type name, generated names
+are qualified by their unit identities.
+
+The runtime's `FromValue` and `IntoValue` traits provide conversion bridges.
+Generated calls validate the complete logical value before conversion and the
+native result before checking postconditions. This preserves raw UTF-16 units,
+bytes, nested presence, and primitive range checks inside custom fields.
+Machine-width checks also apply to machine integers inside custom data.
+
+Generated enums derive `Clone` and `Debug`. LawSpec equality remains a runtime
+operation: it compares fields structurally, retains IEEE NaN and signed-zero
+rules, and compares Symbols by identity. It does not replace these rules with a
+derived Rust `Eq` implementation.
+
+Unused or exclusively recursive type parameters use a `PhantomData` marker.
+Types with no constructors remain uninhabited; they do not acquire a synthetic
+variant. Generated schemas and conversion support have no Proptest dependency.
+The test support composes native Proptest strategies for recursive values and
+shrinking, with deterministic boundary cases and finite-domain enumeration.
+The structural budget counts each scalar, container, and constructor as one
+node. Generation reserves every product field's minimum before distributing
+remaining nodes. List length and element budgets vary together, so a deep
+singleton remains reachable and lists have no hidden four-element limit.
+Native shrinking preserves the schema and the structural budget.
+
 ## Refinements and generation
 
 Small finite domains are enumerated. Larger domains use native Proptest
@@ -95,3 +184,28 @@ result, and then check postconditions on that result.
 test directories other than `tests`, register generated test files using Cargo
 `[[test]]` entries. Doctor checks the selected Cargo package, edition, resolved
 dependencies, library directory, and custom test registration.
+
+Internal typed Core definitions with attached contracts are proved before Rust
+emission. Generated source checks preconditions after argument validation and
+postconditions after result validation, without property-framework dependencies.
+Checks sequence through Result, preserving ordered predicates and contextual
+failures. Native wrappers share logical enforcement. Readable contract bodies
+match rustfmt exactly.
+The shared native fixture passes both machine profiles and formatting modes,
+including exact division, narrowing, nested calls, direct logical entry checks,
+and rejection of corrupted results. Refined source definition signatures now
+produce these contracts through template proof and specialization.
+
+## Constructor field contracts
+
+Rust checks constructor predicates at logical definition and native adapter
+boundaries. Generated proptest strategies validate complete candidates, retain
+native shrinking, and share each case's Symbol context with witness literals and
+assertions. Only false predicates trigger retries; evaluation errors fail the
+property. `maxAttempts` bounds local and global rejection, and exhaustion does
+not prove an empty domain.
+
+Validated witnesses seed nested payloads. Builtin lists and presence/sum
+containers retain native structural shrinking; sampled named witnesses can
+still produce larger counterexamples than native branches. Recursive named
+refined payloads remain outside the currently supported contract fragment.