lawspec 0.7.0 → 0.9.0

package/API-MIGRATION.md

@@ -1,27 +1,120 @@
-# Compiler API migration: schema 1 → schema 2
+# Compiler API migration: 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` (or any other version) 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
+now `{id, name, type, value}` rather than `[name, value]`. `value` retains the
+lossless tagged scalar representation from schema 2. Expected results are typed
+expressions in an assertion, for example `example.expectations[0].right.node.value`.
+
+Every expression has `{type, origin, text, node}`. `text` is for presentation;
+inspect `node` for semantics. Nodes explicitly distinguish constants, resolved
+locals, declaration calls, arithmetic with capability evidence, short-circuit
+operators, helpers, and conversions. Conversion mode `checked` means an exact
+result must fit its adapter parameter; `explicit` records a source conversion.
+There is no separate `typedExpressions` side table to match against source ASTs.
+
+Assertions are the authoritative proposition tree:
+
+- `{kind: "equal", evidence, left, right}`
+- `{kind: "implies", guard, body}`
+- `{kind: "all", items}`
+
+The `left`, `right`, and `guards` compatibility projections on laws are removed.
+Traverse the tree to preserve shared guard scope and conjunction order. Do not
+flatten guards or turn refinement predicates into implications.
+
+Inputs use `{id, name, type, predicates, bounds}`. IDs identify binders;
+display names need not be globally unique. Bounds are derived generation hints
+`{operator, value}` over preceding inputs. Predicates remain authoritative.
+`generationPlan` and `inputRefinements` are replaced by these explicit fields.
+Contracts expose typed argument/result binders, preconditions, and postconditions.
+Refinement declarations expose documented parameter kinds, requirements, and a
+printed definition; they are not serialized source ASTs.
+
+## Types, identity, and locations
+
+Types are discriminated views, not `tag`/`contents` encodings:
 
-LawSpec 0.7.0 responses include `schemaVersion: 2`. Requests may omit the version
-or explicitly send `schemaVersion: 2`; unsupported versions receive a request
-diagnostic. Existing specification source remains compatible. Consumers of the
-JSON AST must migrate together with the compiler.
-
-## Scalar values
+```js
+{ kind: "constructor", name: "Int8", arguments: [] }
+{ kind: "constructor", name: "Optional", arguments: [
+  { kind: "type", type: { kind: "constructor", name: "Int8", arguments: [] } }
+] }
+```
 
-Example bindings and expected values are uniformly tagged. Do not coerce every
-numeric value to JavaScript Number.
+Function types use `{kind: "function", parameter, result}`; type variables use
+`{kind: "variable", id}`. The argument model distinguishes types, natural indices
+(encoded as decimal strings), and index variables. This representation does not
+make unimplemented containers or dependent families available in 0.8.
 
-```js
-// Previously: ["x", 42]
-// Now:
-["x", { type: "Int32", value: "42" }]
+Declaration/property/binder IDs remain stable when unrelated laws are inserted.
+Origins are either `{kind: "source", span: {start, end}}` or
+`{kind: "generated", declaration}`. Source ranges come from parsing, including
+expressions in reused laws and refinements. Generated nodes identify their owner
+instead of inventing source coordinates. Positions use one-based lines/columns;
+end positions are exclusive and can include trailing parser whitespace.
 
-// Lossless unsigned 64-bit example:
-{ type: "UInt64", value: "18446744073709551615" }
-```
+## Scalar values remain lossless
 
 | Domain | Payload after `type` |
 | --- | --- |
-| All integers | `value`: decimal string |
+| Integers, including logical Integer | `value`: decimal string |
 | Bool | `value`: Boolean |
 | Decimal | `coefficient`, `exponent`: decimal strings |
 | Rational | `numerator`, `denominator`: decimal strings; reduced, denominator positive |
@@ -33,53 +126,79 @@ numeric value to JavaScript Number.
 | Unit / Null / Undefined | No payload |
 | Nullable / Optional | `value`: null for missing, otherwise a tagged scalar |
 
-Text is also encoded as units, making the scalar schema uniform. Raw surrogate
-code points never travel through JSON strings. The enclosing input type supplies
-the inner type of a missing presence value.
-
-`Expr.Number.contents` is now a decimal **string**. New expression nodes are
-`DecimalNumber` (coefficient/exponent strings), `ScalarLit`, `Binary`, `Unary`, and `Annotate`. `Type.Applied` represents Nullable
-and Optional. Expanded laws include `typedExpressions`, with operation operand
-and result types plus an explicit `requiredConversion` for checked adapter bridges. Assertion trees remain authoritative;
-`left`, `right`, and `guards` remain compatibility projections.
-
-## Profiles and artifacts
-
-Requests accept `machineBits?: 32 | 64`, defaulting to 64. Successful responses
-include the selected `machineBits`. A profile controls language domains, not the
-architecture of the WASM compiler itself.
-
-Artifacts now include `placement: "source" | "test"` independently of
-`ownership: "user" | "generated"`. A generated runtime belongs in a source
-directory. Do not infer its placement from generated ownership. Continue using
-the manifest writer to protect edited generated files and preserve user adapters.
-
-The generated `index.d.ts` declares the complete discriminated unions. CLI
-`explain` prints the new scalar values without converting large integers to
-floating point. Native and WASM dispatch expose the same schema.
-
-
-## Refinements in the unreleased 0.7.0 schema
-
-API v2 also carries parameterized refinements and executable contracts. `Integer`
-is a logical integer scalar tag whose `value` is a decimal string. Default integer
-literals and promoted integer operations now have logical type `Integer`; explicit
-`BigInt` declarations retain their native mappings. Both tags preserve exact values.
-
-`Law.requirements` contains `Capability` nodes (`Eq`, `Integer`, `Ordered`,
-`Bounded`) with their target types. Types add `Refined`, `RefinementApp`,
-`Qualified`, and `CheckedType` nodes. Refinement arguments explicitly distinguish
-`TypeArgument` from `ValueArgument`; declaration parameter kind `Type` is not a
-runtime scalar. Expressions add `TypeBound` and logical operators.
-
-Responses expose unit-owned `refinements` and `contracts`. Each expanded property
-has `propertyKind` (`law` or `contract`), `generation` settings, and a
-`generationPlan`. Inputs retain their underlying `inputType` and carry separate
-`inputRefinements`. Domain plans include derived comparison bounds; the complete
-predicate remains authoritative. Refinements must not be interpreted as implication
-guards or as permission to count rejected inputs as successful checks.
-
-Requests accept partial `generation` settings (`cases`, `maxAttempts`,
-`maxShrinks`, `exhaustiveLimit`). Project configuration accepts the same object.
-Generated TypeScript declarations define the complete wire shapes. These additions
-are included in schema v2 before its release; schema v1 remains unsupported.
+Do not coerce integer strings to JavaScript Number. Text uses code units or code
+points as appropriate to its domain; raw surrogates never pass through JSON
+strings. The enclosing type supplies the inner type of a missing presence value.
+
+## Checking, generation, and artifacts
+
+`check` and `expand` validate the language. `planGeneration` additionally checks
+whether its input domains can be executed. For example, a well-typed empty finite
+refinement can pass `check` and fail generation with an empty-domain diagnostic.
+Exhausted refinement searches fail explicitly; rejected inputs do not count as
+successful tests.
+
+Requests retain `machineBits?: 32 | 64` (default 64) and partial `generation`
+settings (`cases`, `maxAttempts`, `maxShrinks`, `exhaustiveLimit`). Rust joins the
+seven existing targets. Artifacts retain separate `ownership` and `placement`:
+generated runtime source belongs in source directories, adapters remain
+user-owned, and test helpers belong in test directories. Never infer placement
+from ownership or assume a fixed number of generated files. Continue using the
+manifest writer to protect edited files.
+
+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.

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.