lawspec 0.8.0 → 0.10.0

package/API-MIGRATION.md

@@ -1,11 +1,67 @@
-# Compiler API migration: schema 2 → schema 3
+# Compiler API migration
 
-LawSpec 0.8 uses API schema version **3**. Requests may omit `schemaVersion` or
-send `3`. An explicit `2` (or any other version) receives a request diagnostic;
+This document covers the published schema-3 interface and the schema-4 native
+binding interface introduced in 0.10. See
+[schema 4 native bindings](#schema-4-native-bindings) when adding
+application types or generators to an existing project.
+
+## Schema 2 → schema 3
+
+LawSpec 0.8 introduced API schema version **3**, which 0.9 continues to use.
+Requests may omit `schemaVersion` or
+send `3`. An explicit `2` receives a request diagnostic;
 it is never silently reinterpreted. LawSpec specification syntax remains compatible.
 The generated `index.d.ts` describes the public protocol. Internal Haskell
 constructors and record fields are no longer the wire format.
 
+## 0.9 structural data and definition metadata
+
+Successful results also expose `dataTypes: DataTypeDeclaration[]`. Each named
+declaration has a resolved `id`, a display `name`, parameter IDs, an origin, and
+constructors with resolved IDs and ordered typed fields. Use resolved IDs to
+join references; constructors with the same display name can belong to different
+units. Built-in container types do not need user declarations in this array.
+
+Example bindings now use `DataValue`: either an existing tagged scalar or
+`{kind: "data", type: Type, constructor: string, fields: DataValue[]}`. List values
+use `List::Nil` and `List::Cons`, with head and tail fields; Maybe and Either use
+their qualified constructor IDs. Do not flatten these values to JSON arrays or
+nullable fields: that would lose constructor and nested-presence distinctions.
+
+Expressions add `construct` nodes with a constructor ID and argument expressions,
+and `match` nodes with a scrutinee and cases. Each case has a constructor ID,
+ordered typed binders, and a body. Its binders are local to that case. Structural
+expressions are represented by these nodes, not by scalar `constant` nodes.
+Exhaustive API visitors must handle the added expression variants even though
+the protocol continues to use schema version 3.
+
+Successful results add `definitions: Definition[]`. Each entry contains `owner`,
+the resolved declaration `id`, typed `arguments: Binder[]`, and a typed `body`.
+The matching entry in `units[].declarations` supplies the signature and origin.
+Calls retain their declaration ID; consumers can join against `definitions` to
+distinguish checked bodies from external adapters. An empty array means the
+program has no definitions.
+
+The native frontend checks these bodies for typing, exhaustive matching,
+structural termination, and potentially failing operations. Native reference
+execution and source emission for Rust, Java, Kotlin, Python, JavaScript,
+TypeScript, Go, and Haskell are implemented, including generic definitions
+specialized to concrete signatures. The API exposes concrete instances with
+generated names and resolved IDs, not unspecialized templates. Calls sharing a
+signature reuse an instance; unused templates emit none. Consumers should join
+by ID rather than parse generated names. Refinement-bearing definitions are
+checked and emitted by both the native compiler and bundled WASM distribution.
+Definition bodies produce generated source rather than
+user-owned adapter stubs. Haskell native entry points take an `LS.SymbolContext`
+and return `Either String a`; generated tests allocate a context per example or
+property iteration so Symbol fixture identity does not escape its scope.
+
+Refinement and contract expressions may now contain calls whose IDs resolve to
+checked `definitions`. Validation still rejects calls to external adapters in
+these expressions. Test planning evaluates the closed definitions when filtering
+finite cases, boundaries, and concrete example inputs. Calls remain ordinary
+typed call nodes; consumers need no source-level refinement interpreter.
+
 ## Laws and typed expressions
 
 Read `result.laws[i].examples` instead of `law.original.examples`. A binding is
@@ -101,3 +157,124 @@ All nonempty test plans now emit the portable scalar runtime. Existing Haskell
 projects must include `text` and `bytestring` in the component that compiles
 that source. Doctor reports the missing dependencies before generation. Build
 files remain user-owned; new scaffolds already include these dependencies.
+
+## Formatting requests and adapter references (0.9)
+
+`GenerationRequest` accepts `minify?: boolean`, defaulting to `false`. The CLI
+passes an explicit `--minify` from `generate` and `examples`. `init --minify`
+also compacts newly created scaffolds and the configuration JSON; the choice is
+not saved as a project setting. Existing project build files stay user-owned. Source/test placement is independent of
+formatting. Compact rendering preserves mandatory newlines, indentation, token
+separators, comments, and literal contents.
+
+User-owned artifacts may include `adapterReference`, the compiler's canonical
+readable scaffold. It is comparison data, not the user's implementation and not
+an additional file to write. Manifest writers should hash this reference when
+present, falling back to `content` for older producers. Continue hashing actual
+`content` for generated-file ownership. This keeps a switch of formatting mode
+from producing false adapter-update reports, while declared interface changes
+still request review. Never normalize, overwrite, or hash user implementations
+as the required adapter interface. Existing version-1 manifests remain readable.
+
+Native and bundled WASM requests share this formatting behavior. CLI scaffolds,
+generated sources, and tests preserve the same ownership rules in both modes.
+
+
+Scoped List payload predicates use the schema-3 expression node
+`{kind: "allElements", value: Expr, binder: Binder, predicate: Expr}`. The binder
+is local to `predicate`; `value` is evaluated in the surrounding scope. The
+predicate and result have type Bool. Visitors must handle this node alongside
+`match`, including empty-list truth and short-circuit evaluation.
+
+The Core also defines a scoped recursive payload operation:
+`{kind: "allPayloads", value: Expr, predicates: PayloadPredicate[]}`, where each
+`PayloadPredicate` contains a `binder: Binder` and `predicate: Expr`. Entries
+correspond, in order, to the root data type's type arguments. Each binder has
+that argument's type and is local only to its own predicate; sibling predicates
+cannot refer to it. The scrutinee is evaluated in the surrounding scope, and
+both each predicate and the whole operation have type Bool.
+
+Traversal follows stored parameter occurrences through recursive declarations,
+including nested containers and changing type arguments. It does not constrain
+unrelated fixed fields that happen to have the same concrete type. Empty and
+phantom occurrences are vacuously true; rejection short-circuits traversal.
+
+Source named-payload refinements now elaborate to this discriminator, including
+recursive applications. API consumers should handle it in checked Core views.
+All eight Core emitters support this operation in definitions, properties and
+constructor predicates.
+The internal surface predicate node is type checked and lowered through
+specialization and template proofs into this same Core operation. Internal
+definition and constructor contracts support recursive payload proof facts. Constructor predicates are audited in order, and callback
+matches/constructions participate in the constructor dependency-cycle check.
+The TypeScript declarations now include both
+`allElements` and `allPayloads`; exhaustive visitors should handle both.
+
+## Schema 4 native bindings
+
+Binding requests use `schemaVersion: 4`. Schema-3 requests remain supported for
+existing specifications without bindings. This negotiation is deliberate: an
+older compiler must reject a binding request rather than silently use generated
+types in place of application types.
+
+The JavaScript API selects schema 4 when `nativeBindings` is provided, unless an
+explicit `schemaVersion` overrides it. A nonempty binding configuration with
+schema 3 is rejected. Results and diagnostics report the negotiated schema.
+
+`nativeBindings` contains optional `types`, `functions`, `generators`,
+`rustCrate` and `goImports` fields. Native symbols use arrays of identifier segments; unknown
+configuration fields are rejected. See [the native-binding scope and current
+implementation status](NATIVE-BINDINGS.md). Rust, Python, JavaScript, TypeScript,
+Java and Kotlin support application type bridges and native generator factories.
+Go supports package-local and imported application types with native Rapid
+factories. Haskell supports application types and native Hedgehog factories.
+Custom codec hooks are available on all eight targets; see the native-binding
+reference for target-specific signatures and current integration limitations.
+
+### Go imports in schema 4 binding requests
+
+`nativeBindings.goImports` is an optional array of `{alias, path}` entries.
+References such as `["domain", "Price"]` select exported names from that alias's
+Go import path. One-component references continue to select package-local names.
+Types, constructors, functions and generator factories share the import table;
+only imports used by each generated file are emitted. Other targets reject this
+option. Paths must be module import paths without empty or traversal segments.
+
+Go reserves local application symbols before generating canonical data names.
+Colliding generated families receive a fresh `Canonical` prefix (and a numeric
+suffix in that prefix if necessary). Logical type and constructor IDs do not
+change. Hooks that name generated data types should use the emitted canonical
+names; imported application types keep their original names.
+
+### Codec hooks in schema 4 type bindings
+
+`NativeTypeBinding` now accepts either `constructors` or
+`codec: {toNative: NativeReference, fromNative: NativeReference}`. Both hook
+references are required and constructor mappings cannot be combined with hooks.
+The canonical side uses generated LawSpec data types, while the native side uses
+`native`; generic hooks receive one directional child converter per type argument.
+All eight targets implement emission. Go hooks return `(value, error)` and the
+verified fixture places them beside the generated canonical types to avoid package
+import cycles. See `NATIVE-BINDINGS.md` for signatures and
+validation behavior.
+
+### Native-binding ownership transitions
+
+Existing user adapters are protected when their paths become generated bridges.
+Move application implementations into the configured native modules and save the
+old adapters elsewhere before adopting bindings. Removing bindings preserves the
+old bridge as user-owned content and reports a required adapter update; it does
+not silently replace that content with a stub. Generated layout changes do not
+move application-owned model, hook or factory files. See `NATIVE-BINDINGS.md` for
+the migration sequence and all-target filesystem acceptance checks.
+
+### Optional generator scaffolds in schema 4
+
+`NativeGeneratorBinding` accepts `stub?: boolean`, defaulting to false. Python,
+Rust, JavaScript, TypeScript, Java, Kotlin, Go and Haskell support `stub: true` to
+create a user-owned factory in the test directory. Go
+requires a package-local factory and a quantified use to determine placement.
+Existing factory files remain untouched. Factory signature changes
+use the existing `adapterUpdates` reporting channel. See `NATIVE-BINDINGS.md`
+for grouping, module collision checks, and layout
+migration behavior.

package/GO.md

@@ -0,0 +1,144 @@
+# Native Go data
+
+LawSpec 0.9 generates native named Go types for parameterized products and sums.
+The compiler consumes checked Core declarations, plans names across all units,
+and emits sealed interfaces plus named variant structs, following Go+'s enum
+lowering approach.
+
+For example:
+
+```lawspec
+unit example.trees
+
+type Tree (a :: Type) is
+  Leaf value :: a
+  Branch children :: List (Tree a)
+end
+
+echo :: Tree Int8 -> Tree Int8
+
+law `echo preserves the tree` is
+  definition is `for all` (x :: Tree Int8) . echo x = x end
+end
+```
+
+The adapter receives `Tree[int8]`. Its native variants are `TreeLeaf[int8]`,
+with an exported `Value` field, and `TreeBranch[int8]`, with an exported
+`Children []Tree[int8]` field. The interface's private marker method includes
+the type parameters, so even a nullary or phantom variant retains its generic
+identity. Go rejects a `TreeLeaf[bool]` where `Tree[int8]` is required.
+
+A correct identity adapter is:
+
+```go
+func Echo(value0 Tree[int8]) Tree[int8] {
+	return value0
+}
+```
+
+Adapters remain user-owned. Generated files belong to the same unit package;
+custom Go layouts keep source and tests in a shared directory tree. Duplicate
+type names across units receive qualified generated names. The compiler rejects
+adapter names that collide with generated native declarations or runtime names.
+
+## Containers and presence
+
+- `List a` uses `[]T`. Nil and empty slices represent the same empty list.
+- `Maybe a` uses `LawSpecMaybe[T]`, constructed with `LawSpecNothing[T]()` or
+  `LawSpecJust(value)`. `Value()` returns the payload and its presence flag.
+- `Either a b` uses `LawSpecEither[L, R]`, constructed with
+  `LawSpecLeft[L, R](value)` or `LawSpecRight[L, R](value)`. Its zero value is
+  invalid and checked conversion rejects it.
+- `Nullable a` and `Optional a` use distinct generic support structs with
+  `Present` and `Value` fields. These tags preserve nested absence states.
+
+Native scalar fields retain their domains: UInt64 uses `uint64`, arbitrary
+integers use `*LawSpecBigInt`, rational values use `*LawSpecRational`, and raw
+UTF-16 text uses `[]uint16`. Text uses a valid UTF-8 Go string; arbitrary bytes
+use `[]byte`. Unit, Null, and Undefined have distinct named support types when
+stored inside data. Native void adapter results continue to normalize to Unit.
+
+## Total definitions
+
+Checked source definitions emit native methods on `LawSpecDefinitions` in the
+unit's package:
+
+```lawspec
+unit example.total
+
+definition increment (x :: Int8) :: BigInt is x + 1 end
+```
+
+```go
+symbols := map[string]*LawSpecSymbol{}
+result := LawSpecDefinitions.Increment(symbols, 127) // big integer 128
+```
+
+The method accepts `int8` and returns `*LawSpecBigInt`. Lists, products, sums, and
+nested presence retain their native parameterized types. A dedicated method
+namespace allows a definition named `architecture` to coexist with the native
+`Architecture` data type. Ordinary adapter functions retain their existing names.
+
+Reuse the Symbol context within one example. Checked codecs copy and validate
+native arguments and results; failures panic with the resolved definition name.
+Machine-sized native bindings check the architecture across the complete type,
+including alternatives not selected by the current value. Logical evaluation
+still follows the explicitly selected machine profile.
+
+`lawspec_definitions.go` belongs in source directories and does not import Rapid.
+It contains the unit's native entry points and checked logical bodies. Properties
+call the bodies directly; definitions never become user-owned adapter stubs.
+Definitions and properties share typed expression rendering, preserving lazy
+branches, short-circuit guards, single evaluation of match inputs, exact
+arithmetic, and structural equality.
+
+The frontend checks structural termination and potentially failing operations.
+Generic definitions specialize to concrete uses. Refined signatures become
+checked contracts, and refinement predicates may call checked definitions.
+
+`tools/go-definitions-integration.mjs` checks source-only packages, four rejected
+native type mismatches, both profiles and architecture diagnostics, recursive
+properties, incorrect adapters, custom layouts, compact execution, and
+regeneration protection. Readable definition source matches `gofmt` exactly.
+Compact Go documents retain tabs rather than expanding them into spaces.
+
+## Checked bridges and tests
+
+Generated codecs validate both conversion directions and copy mutable payloads.
+An adapter cannot mutate a list, byte slice, or big integer in a test fixture
+through an input alias. Unexpected or nil native variants, invalid scalar
+representations, and cyclic values fail with type/field context. Shared acyclic
+subtrees remain valid. Native machine-sized fields require the selected
+`machineBits` profile to match the Go architecture.
+
+Generated equality follows LawSpec semantics, including componentwise floating
+comparison and Symbol identity. It does not substitute Go pointer identity or
+reflection-based equality for structural equality.
+
+Rapid generation composes native generators and shrinkers. A structural node
+budget bounds recursive values, reserves each product field's minimum cost,
+and permits list lengths supported by the remaining budget. Empty domains,
+nullary constructors, and nested absence states are handled explicitly.
+
+The reusable source files (`lawspec_runtime.go`, `lawspec_schema.go`,
+`lawspec_codecs.go`, and generated data/schema/codec declarations) do not import
+Rapid. Framework-specific generation lives in
+`lawspec_data_strategies_test.go`; generated laws live in `lawspec_test.go`.
+
+Native declarations, schema descriptions, codecs, runtime support, and generated
+tests use structured formatting that matches `gofmt`. The bundled examples and
+total-definition fixture are checked against `gofmt` under both machine profiles.
+No external formatter is needed when generating code.
+
+The compiler and CLI accept explicit `--minify` for generated output.
+Readable output remains the default; formatting changes preserve adapter ownership
+and edited-file protection. The bundled WASM uses the same layout.
+
+Internal typed Core definitions with attached contracts are proved before Go
+emission. Generated logical entry points validate arguments, check preconditions
+in order, validate the result, and check postconditions; native wrappers share
+these checks. The standalone contract fixture exercises both machine profiles
+and formatting modes, including exact division, checked narrowing, nested calls,
+and rejection of deliberately corrupted results. Readable contract bodies match
+`gofmt`. Refined source definition signatures now produce these contracts through
+template proof and specialization.

package/HASKELL.md

@@ -0,0 +1,171 @@
+# Native Haskell data
+
+LawSpec 0.9 emits ordinary parameterized algebraic data types from checked Core
+products and sums. Constructors and record selectors have stable names planned
+across all units. For example:
+
+```lawspec
+unit example.trees
+
+type Tree (a :: Type) is
+  Leaf value :: a
+  Branch children :: List (Tree a)
+end
+
+echo :: Tree Int8 -> Tree Int8
+```
+
+The generated `LawSpecData` module supplies `Tree a`, `TreeLeaf`, and
+`TreeBranch`. An adapter can implement identity directly:
+
+```haskell
+echo :: Data.Tree I.Int8 -> Data.Tree I.Int8
+echo value = value
+```
+
+The generated adapter imports `LawSpecData` as `Data` and `Data.Int` as `I`.
+Adapters remain user-owned. Recursive and mutually recursive fields use native
+Haskell recursion; phantom parameters remain in signatures. Empty data types
+have no constructors. They can appear in inhabited containers such as
+`Maybe Empty`, but cannot supply a standalone generated argument.
+
+## Containers and scalar representations
+
+| LawSpec | Haskell |
+| --- | --- |
+| `List a` | `[a]` |
+| `Text` | `Data.Text.Text` |
+| `List Char` | `[Char]`, the linked-list representation |
+| `Maybe a` | `Maybe a`, with `Nothing` and `Just` |
+| `Either a b` | `Either a b`, with `Left` and `Right` |
+| `Nullable a` | `LS.Nullable a`, with `NullValue` and `NullableValue` |
+| `Optional a` | `LS.Optional a`, with `UndefinedValue` and `OptionalValue` |
+| `BigInt`, `BigUInt`, `Integer` | `Integer`, with domain checks |
+| `Decimal` | `LS.Decimal`, wrapping an exact finite base-ten `Rational` |
+| `Rational` | `Rational` |
+| `Complex64`, `Complex128` | `Complex Float`, `Complex Double` |
+| `CodePoint` | `Char`, including surrogate code points |
+| `CodeUnit16` | `Word16` |
+| `CodePointText`, `Utf16Text` | `LS.CodePointText [Char]`, `LS.Utf16Text [Word16]` |
+| `Bytes` | `ByteString` |
+| `Symbol` | `LS.Symbol`, with scoped fixture identities |
+| `Unit` | `()` |
+| `Null`, `Undefined` | `LS.Null`, `LS.Undefined` |
+
+`Char` and `Text` exclude surrogate code points. Checked codecs reject invalid
+native values rather than replacing characters. `Symbol` equality uses its
+identity; matching descriptions alone do not establish equality. Distinct
+presence wrappers preserve nested absence states. IEEE NaN and signed-zero
+equality remain the same inside containers and custom types.
+
+## Generated support and testing
+
+`LawSpecData`, `LawSpecDataSchema`, `LawSpecDataCodecs`, `LawSpecSchema`,
+`LawSpecCodecs`, and `LawSpecRuntime` belong in the source directory. They have no
+property-framework dependency. Native conversion returns contextual failures for
+invalid domains, fields, tags, or arities. Binding machine-sized native types
+requires the selected `machineBits` profile to match the host, including fields
+of unselected variants.
+
+`LawSpecDataStrategies` belongs in the test directory and composes native Hedgehog
+generators and shrinkers. Bounded recursive generation reserves every product
+field's minimum size before distributing spare nodes. Lists have variable lengths
+within the available budget. Shrinking uses Hedgehog's choices, integers, and
+lists, retaining schema-valid representations.
+
+The Haskell scaffold uses Hspec, Hedgehog, hspec-hedgehog, containers, and mtl in
+its test component. Source and test roots can be customized independently.
+Readable/compact declaration fixtures are covered by
+`tools/haskell-data-integration.mjs`; main compiler output and incorrect adapters
+are covered by `tools/haskell-data-properties.mjs`.
+
+## Formatting
+
+Haskell output uses an 80-column layout with spaces for indentation. Runtime
+sources, native declarations, adapter stubs, definitions, and property files are
+readable by default. Explicit `--minify` selects compact documents while retaining
+the layout required by Haskell. Generation uses the same deterministic document
+renderer in native and WASM builds; it does not invoke a downloaded formatter.
+
+`tools/haskell-formatting-integration.mjs` checks the bundled corpus at both
+machine widths for line length, tabs, and trailing whitespace. It compares
+readable and compact parsed syntax using `tools/HaskellSyntaxCheck.hs`, built
+against the installed GHC parser. The comparison discards source locations and
+layout annotations while retaining literals, operators, and program structure.
+Set `LAWSPEC_CORE`, `LAWSPEC_GHC`, and `LAWSPEC_HASKELL_SYNTAX_CHECK` to the
+corresponding executables. This is a development check, not a package dependency.
+
+## Total definitions
+
+Checked definitions become native functions in `LawSpecDefinitions.<Unit>`:
+
+```lawspec
+unit example.total
+
+definition increment (x :: Int8) :: BigInt is x + 1 end
+```
+
+The generated native signature is equivalent to:
+
+```haskell
+increment :: LS.SymbolContext -> I.Int8 -> Either String Integer
+```
+
+Create a context with `LS.newSymbolContext`, then pass it to calls belonging to
+the same example. A repeated Symbol fixture ID has the same identity in that
+context; separate contexts remain distinct even when IDs and descriptions match.
+Codecs preserve the identity of already-scoped native Symbols. Creating the
+context uses IO; evaluating a definition is pure.
+
+Native entry points check arguments and results and return contextual `Left`
+diagnostics for invalid native representations. Native machine-sized bindings
+check the whole type, including unselected constructors, against `machineBits`.
+`LawSpecDefinitionBodies` contains the shared logical implementation, which uses
+the configured machine profile independently of the host architecture.
+
+Definitions do not create adapter stubs. Their source modules and scalar/schema
+support have no Hspec or Hedgehog dependency. Generated tests allocate a context
+per example, boundary, or property iteration. Properties and definitions share a
+typed expression renderer with lazy guards, exhaustive matching, structural
+equality, checked conversions, and exact integer promotion.
+
+`tools/haskell-definitions-integration.mjs` exercises native and property calls,
+both machine profiles, readable/compact definitions, complete minified projects,
+custom source/test roots,
+native type errors, incorrect adapters, generic specialization, and regeneration
+protection. Refined definition signatures are checked before emission and
+enforced at native entry points.
+
+
+Hspec property files now use structured documents for helpers, examples,
+boundaries/finite cases, native Hedgehog strategies, dependent refinement domains,
+guarded assertions and contract wrappers. Adapter bridges compose checked codecs
+and force argument values before calling native code. Contracts retain lazy
+precondition checks and force the result before checking postconditions. Fresh
+Symbol contexts cover refined properties as well as ordinary native strategies.
+Scalar literals and diagnostic strings now use document-level encoding. Long
+strings concatenate independently escaped chunks; large integers parse exact
+decimal strings with their required Integer type.
+
+`tools/haskell-data-properties.mjs` accepts `LAWSPEC_MINIFY=1` and
+`LAWSPEC_MACHINE_BITS=32,64`. Its scalar scenario includes bundled examples and
+shared arithmetic conformance vectors; its refinements scenario includes four
+faulty adapters. Native machine-sized adapter bindings require a matching host
+architecture; the scalar scenario defaults to 64 bits.
+
+`tools/haskell-message-integration.mjs` uses native code-point strings and integer
+constants independent of the emitter to check Unicode, escapes, whitespace,
+large signed integers and diagnostic prefixes in readable and compact modes.
+Its executable fixture lines fit within 80 columns. Long metadata comments wrap
+to the output width.
+
+Internal typed Core definitions with attached contracts are proved before Haskell
+emission. Generated source checks preconditions after argument validation and
+postconditions after result validation, without property-framework dependencies.
+Checks sequence through Either, so a rejected precondition prevents later
+predicates and the body from running. Results are forced and validated before
+postconditions. Readable contract fixtures fit within 80 columns.
+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.

package/JAVA.md

@@ -0,0 +1,113 @@
+# Java backend (0.9)
+
+Java targets Java 25+, JUnit, and JetCheck. The compiler emits native named
+products and sums, checked scalar/data codecs, reusable runtime sources, and
+separate property-test helpers. Native type parameters remain visible in public
+data declarations and adapter signatures.
+
+## Total definitions
+
+A unit-level definition supplies its implementation together with its signature:
+
+```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 the body even when no law uses it. It requires exhaustive
+matching, established structural descent for recursion, and proof that partial
+operations are defined. Calls may target other checked definitions, including
+forward declarations; definitions cannot call external adapters. Generic definitions specialize to concrete uses. Refined signatures become
+checked contracts, and refinement predicates may call checked definitions.
+
+Java writes native entry points beneath `lawspec.definitions`, preserving the
+unit's package and class mapping. The example above provides
+`lawspec.definitions.example.Total.size`:
+
+```java
+var symbols = new java.util.HashMap<String, Object>();
+var count = lawspec.definitions.example.Total.size(symbols, java.util.List.of((byte) 1, (byte) 2));
+```
+
+Arguments and results use the same checked native representations as generated
+data codecs: `List<Byte>` and `BigInteger` in this example. Domains without a
+faithful Java representation retain their tagged runtime support values,
+including nested Nullable/Optional states and machine-profile integers. Share
+the Symbol map when fixture IDs should refer to the same identity.
+
+`LawSpecDefinitionBodies.java` contains generated checked implementation helpers.
+Generated properties call those same bodies. The native entry points validate
+and copy values through codecs, and invalid native values report the definition
+identity in an `IllegalArgumentException`. Logical machine integers enforce the
+selected 32- or 64-bit range independently of the JVM architecture.
+
+These files belong to source directories and have no JUnit or JetCheck dependency.
+Definitions never receive user-owned adapter stubs. External declarations still
+receive stubs, and regeneration preserves edited adapters. Edits to generated
+definition files are protected by the generation manifest.
+
+## Verification and layout
+
+`tools/java-definitions-integration.mjs` executes recursive list/tree definitions,
+forward calls, scalars, sums, raw code units, Symbol identity, and nested absence
+under both profiles. It checks custom source/test roots, typed native misuse,
+incorrect adapters, framework-independent compilation, and ownership.
+
+Readable generated sources and tests use structured formatting that matches
+Google Java Format. `tools/java-formatting-integration.mjs` checks all bundled
+examples and the total-definition fixture under both machine profiles. The
+compiler emits this layout directly; generation does not invoke a formatter.
+JetCheck combinators retain native shrinking and the existing scalar domains.
+
+The CLI/API accept explicit minify. Native integration checks run
+both readable and fully minified generation plans, including properties and
+contracts. Independent Java execution checks preserve long diagnostics,
+supplementary Unicode, escaping and arbitrary integers when literals wrap.
+The bundled WASM package is checked against the native compiler.
+
+
+For internal checked Core definitions, shared JVM implementation bodies now
+prove attached contracts before emission and enforce ordered preconditions and
+validated-result postconditions at runtime. Native wrappers and direct logical
+entry points both use those checks. `tools/jvm-definition-contract-integration.mjs`
+verifies both JVM languages, profiles and layouts without a test-framework
+dependency, including corrupted-result rejection. Refined source signatures
+now produce these contracts through template proof and specialization.
+
+
+## Constructor contracts
+
+Public Java generation supports typed constructor callbacks, context-aware codecs
+and definition boundaries. Property emission supplies validated witnesses and one
+Symbol context shared by generation, adapter conversions and assertions.
+Required conjunctive Symbol equalities can use fixture/prior-input values;
+equalities beneath disjunctions contribute candidates without restricting the
+whole domain to one alternative.
+
+The test helper's `checkedGenerator` composes JetCheck generators with native
+`suchThat` filtering at nested and outer value boundaries. False predicates reject
+candidates; predicate evaluation errors are retained for the property to report.
+Each filter respects the smaller of `maxAttempts` and JetCheck 0.3's native
+100-attempt limit. The counter for smaller budgets is recreated on replay, so
+native filtering still discards invalid shrinks. Validated witnesses contribute typed nested seeds. Sampled seeds
+can limit payload shrinking; native list and constructor generation remains an
+alternative, and shrinking does not promise a globally minimal counterexample.
+
+`tools/java-checked-strategies.mjs` verifies valid generation/shrinking, nested
+witness use, exhaustion, error classification and shared Symbol identity at both
+machine widths, with compiled behavioral mutants. These helpers depend on
+JetCheck; the value/schema/codec runtime remains framework-independent.
+
+Constructor-contract properties run the requested case count as one-iteration
+JetCheck sessions with increasing size hints. This preserves native shrinking and
+avoids session-wide draw-uniqueness exhaustion for fixture-identity domains. It
+does not claim those domains are finite; domains proven finite by Core retain
+exhaustive cases. `tools/java-field-properties.mjs` executes public generation at
+both widths and layouts, including custom placement, adapter mutants, disjunctive
+Symbol candidates and generation-time evaluator errors.