lawspec 0.6.0 → 0.8.0

package/API-MIGRATION.md

@@ -0,0 +1,103 @@
+# Compiler API migration: schema 2 → schema 3
+
+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;
+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.
+
+## 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:
+
+```js
+{ kind: "constructor", name: "Int8", arguments: [] }
+{ kind: "constructor", name: "Optional", arguments: [
+  { kind: "type", type: { kind: "constructor", name: "Int8", arguments: [] } }
+] }
+```
+
+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.
+
+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.
+
+## Scalar values remain lossless
+
+| Domain | Payload after `type` |
+| --- | --- |
+| Integers, including logical Integer | `value`: decimal string |
+| Bool | `value`: Boolean |
+| Decimal | `coefficient`, `exponent`: decimal strings |
+| Rational | `numerator`, `denominator`: decimal strings; reduced, denominator positive |
+| Float32 / Float64 | `bits`: 8 / 16 hexadecimal digits in IEEE bit order |
+| Complex64 / Complex128 | `real`, `imaginary`: tagged component scalars |
+| Char / CodePoint / CodeUnit16 | `value`: numeric unit |
+| Text / CodePointText / Utf16Text / Bytes | `units`: numeric unit array |
+| Symbol | `id`, `description`: strings; identity comes from the ID |
+| Unit / Null / Undefined | No payload |
+| Nullable / Optional | `value`: null for missing, otherwise a tagged scalar |
+
+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.

package/LANGUAGE.md

@@ -0,0 +1,136 @@
+# LawSpec language and compiler boundary (0.8)
+
+LawSpec describes portable laws, concrete examples, and adapter contracts. The
+compiler is written in Haskell. Rust is an output backend alongside Java, Python,
+JavaScript, TypeScript, Go, Haskell, and Kotlin.
+
+## Source and declarations
+
+A source has one named `unit`, function signatures, reusable refinements, and
+laws. Qualified unit names determine target module/package paths. Function
+signatures are curried: `a -> b -> c` takes two inputs and returns `c`. Parentheses
+group types and expressions. Comments start with `--` and run to the line end.
+
+The following grammar summarizes the main forms; the parser and executable
+compiler tests specify lexical details:
+
+```text
+source       = "unit" qualified-name declaration*
+declaration  = name "::" type | law | refinement
+type         = type-atom ["->" type]
+type-atom    = primitive | type-variable | "(" type ")"
+             | ("Nullable" | "Optional") type-atom
+             | refinement-name argument*
+             | "(" name "::" type ["where" expression] ")"
+refinement   = "refinement" name parameter* requirements?
+               "is" type "end"
+parameter    = "(" name "::" type ["where" expression] ")"
+requirements = "requires" (capability type)+
+capability   = "Eq" | "Integer" | "Ordered" | "Bounded"
+law          = "law" quoted-name parameter* requirements? "is"
+               "definition" "is" proposition "end"
+               description? rationale? example* references? "end"
+proposition  = "`for all`" parameter+ "." proposition
+             | expression "=" expression
+             | expression "implies" proposition
+             | proposition "and" proposition
+             | quoted-name expression* | expression
+example      = "example" quoted-name "is" (name "=" literal)+
+               ("expect" expression "=" literal)+ "end"
+```
+
+Law names use backticks. Text/metadata use double quotes with escapes. Named
+refinement declarations state their type versus value parameter kinds, including
+forward references; the compiler validates their arity and argument kinds.
+Lowercase type names represent variables. `a :: Type` is a type parameter, not a
+runtime value with a generator.
+
+A generic law is specialized when invoked with concrete adapters. Its declared
+capabilities must justify its operations; specialization resolves those
+requirements for the actual types. `Integer` as a capability requires an integer
+type. `Integer` in a concrete result signature denotes a representation-independent
+mathematical integer. See [refinements and abstract integers](REFINEMENTS.md).
+
+## Expressions and arithmetic
+
+Application binds most tightly. The remaining precedence, highest first, is:
+unary `!`/`-`, composition `.`, multiplication/division, addition/subtraction,
+comparisons (`==`, `!=`, `<`, `<=`, `>`, `>=`), `&&`, then `||`.
+Comparisons do not chain. Arithmetic associates left; composition associates
+right. An adjacent numeric sign remains part of an argument: `f -42` applies `f`
+to negative 42. Write `x - 42` for subtraction.
+
+Assertion `=` differs from Boolean `==`. `implies` guards its following
+proposition; `and` requires both assertions. Parentheses determine the scope of a
+shared guard. Both Boolean operators and implications short-circuit.
+
+Literals acquire types from declared context. Unconstrained integers have type
+`Integer`; decimal tokens have type `Decimal`. An annotation such as
+`(127 :: Int8)` specifies context. A declared float context can type a decimal
+token directly, but an explicitly constructed exact Decimal is not implicitly
+converted into a float.
+
+Integer `+`, `-`, `*`, and negation produce exact `Integer` results. Decimal
+dominates integer/Decimal combinations; Rational dominates exact combinations
+involving Rational. Exact `/` returns Rational. `prelude.quot` truncates integer
+quotients toward zero; `prelude.rem` is the associated remainder. Division by
+zero fails when evaluated. Explicit numeric conversions use `prelude.Type`.
+Exact/inexact mixing otherwise fails type checking. IEEE arithmetic widens float
+or complex precision as required; equality treats NaN as unequal and signed
+zero as equal. Decimal rounding is explicit, with a scale and ties-to-even rule.
+
+Passing a computed exact result to a bounded adapter argument performs a checked
+conversion. It never wraps, truncates a fraction, or silently changes precision.
+Adapter results are validated against the declared domain before use. See the
+[primitive reference](PRIMITIVES.md) for all domains and helpers.
+
+## Refinements and executable contracts
+
+Refinements are pure Boolean predicates over a value and preceding binders.
+They cannot call user adapters. Dependent inputs are generated in order;
+shrinking preserves their predicates. Bounds such as `y > Int8.max - x` are
+computed with exact arithmetic and can drive a dependent generator. If a chosen
+`x` has no possible `y`, generation retries earlier inputs. Search exhaustion
+fails explicitly rather than passing a property with no valid cases.
+
+Contracts check preconditions, evaluate an adapter once, validate the result,
+and then check postconditions against that same result. Predicate errors are
+contextual failures, not rejected samples. Small finite domains are enumerated;
+other domains use target property frameworks. `machineBits: 32 | 64` controls
+machine-integer domains independently of the compiler host architecture. Native
+machine-sized adapter bindings additionally verify the executing architecture.
+
+## Compiler stages and public API
+
+The parser retains source ranges. Resolution and inference check names, kinds,
+capabilities, contextual literals, and generic specializations. Elaboration
+produces typed core expressions with resolved declaration/binder IDs, explicit
+arithmetic evidence and conversions, plus an authoritative proposition tree.
+Refinement declarations become predicates on quantifiers and contracts; targets
+do not interpret refinement syntax.
+
+An independent core validator checks scopes, kinds, operand/result types,
+capability evidence, and conversions. A pure core evaluator supports deterministic
+domain checks and reference tests. The testing planner computes finite cases,
+boundaries, and dependent generator requirements. All eight emitters consume
+that plan and the core, without importing source syntax or inference.
+
+`check`/`expand` report semantic validity. `planGeneration` additionally reports
+execution feasibility, including empty finite domains. Source syntax errors,
+semantic errors, core invariant failures, and generation errors have distinct
+diagnostic codes. Runtime failures identify the law/example or adapter contract.
+Parsed expressions retain real source ranges; synthesized expressions identify
+the declaration that caused their creation.
+
+API schema v3 uses separately defined wire views, with lossless tagged scalar
+values. It does not serialize internal AST constructors. See the
+[API migration guide](API-MIGRATION.md).
+
+## Next language features
+
+`List`, algebraic `Maybe`/`Either`, user-defined sums and products, pattern
+matching, GADTs, and general dependent types are outside 0.8. The core type model
+supports arbitrary constructor arity and distinguishes type and index arguments
+so those features can be added without target-specific surface interpretation.
+`Nullable` and `Optional` retain their interoperability semantics; they do not
+stand in for future algebraic sum types.

package/PRIMITIVES.md

@@ -0,0 +1,150 @@
+# LawSpec scalar reference (0.8.0)
+
+A scalar has a declared domain, checked literals, equality, property inputs, and
+boundary fixtures. General collections, objects, pointers, and type-only constructs
+such as `never` are outside this release.
+
+| Domain | Types | Representation and equality |
+| --- | --- | --- |
+| Boolean | `Bool` | `true` or `false`; distinct from integers |
+| Signed integers | `Int8`, `Int16`, `Int32`, `Int64` | −2^(bits−1) through 2^(bits−1)−1 |
+| Unsigned integers | `UInt8`, `UInt16`, `UInt32`, `UInt64` | 0 through 2^bits−1 |
+| Machine integers | `IntSize`, `UIntSize`, `UIntPtr` | Explicit 32- or 64-bit profile; no pointer operations |
+| Abstract integers | `Integer` | Exact mathematical values, independent of storage width |
+| Arbitrary integers | `BigInt`, `BigUInt` | Unbounded integer; BigUInt is nonnegative |
+| Exact fractions | `Decimal`, `Rational` | Finite coefficient × 10^exponent; reduced numerator / positive denominator |
+| Floating point | `Float32`, `Float64` | IEEE binary32 / binary64; NaN differs from itself, signed zeros compare equal |
+| Complex | `Complex64`, `Complex128` | Two Float32 / Float64 components; componentwise IEEE equality |
+| Characters | `Char`, `CodePoint`, `CodeUnit16` | Unicode scalar; code point including surrogates; arbitrary 16-bit unit |
+| Sequences | `Text`, `CodePointText`, `Utf16Text`, `Bytes` | Unicode scalars; code points; UTF-16 units; octets |
+| Identity | `Symbol` | Identity, independent of description |
+| Absence | `Unit`, `Null`, `Undefined` | Three distinct singleton domains |
+| Presence | `Nullable a`, `Optional a` | Null or a present scalar; Undefined or a present scalar |
+
+`Char` and `Text` exclude U+D800–U+DFFF. Code points range from 0 through
+0x10FFFF. UTF-16 units range from 0 through 65535. Bytes range from 0 through
+255. Raw constructors preserve units without decoding or replacement.
+
+## Literals and arithmetic
+
+Integer literals inherit a declared parameter or example type, otherwise they
+have type `Integer`. Decimal literals default to exact `Decimal`. An annotation
+supplies context: `(127 :: Int8)`, `(0.1 :: Float32)`. Literals outside the
+contextual domain are rejected during checking.
+
+```lawspec
+unit example.increment
+successor :: (x :: Int8) -> (result :: Integer where result == x + 1)
+law `promotes instead of wrapping` is
+  definition is `for all` (x :: Int8) . successor x = x + 1 end
+  example `maximum input` is x = 127 expect successor x = 128 end
+end
+```
+
+Integer `+`, `-`, `*`, and negation produce `Integer`. Decimal dominates integer
+operands; Rational dominates exact operands. Exact `/` always produces Rational.
+`prelude.quot` truncates toward zero, and `prelude.rem a b` satisfies
+`a = quot a b * b + rem a b`. Division by zero fails when evaluated. Implication
+guards short-circuit, including arithmetic and adapter calls.
+
+Float32 operations round at binary32 precision; Float64 operations use binary64.
+Mixed inexact operations widen to the greater component precision and to complex
+when needed. Exact and inexact variables require explicit conversion:
+`prelude.Float32 x`, `prelude.Float64 x`, `prelude.Rational x`,
+`prelude.Decimal x`, or `prelude.Int8 x` (and the other numeric type names).
+Fractional and out-of-range conversions to integers fail. A Rational conversion
+to Decimal must terminate. Nonfinite floats cannot convert to exact numbers.
+
+`prelude.round value scale` rounds an exact value to a specified number of decimal
+places using ties-to-even. Negative scales round to powers of ten. Decimal
+operations use exact arithmetic, independent of Python's decimal context or other
+ambient rounding settings.
+
+Comparison operators are `<`, `<=`, `>`, `>=`, `==`, and `!=`. Numeric comparisons
+follow arithmetic's exact/inexact restriction. Complex numbers are not ordered.
+`=` remains a law assertion. `==` and `!=` produce Bool and also support other
+scalar domains. Multiplication and division bind more tightly than addition and
+subtraction. Application and composition retain their existing syntax.
+
+An adjacent sign remains an argument, as in `f -42`. Write `x - 42` for
+subtraction, or parenthesize arithmetic arguments: `f (x - 42)`.
+
+## Constructors and helpers
+
+| Expression | Meaning |
+| --- | --- |
+| `decimal(123, -2)` | Exact 1.23 |
+| `rational(1, 2)` | Exact 1/2 |
+| `complex64(1, -2)`, `complex128(1, -2)` | Complex components at declared precision |
+| `float32Bits("7fc00000")` | A binary32 NaN |
+| `float64Bits("7ff0000000000000")` | Positive binary64 infinity |
+| `float32Bits("80000000")` | Negative binary32 zero |
+| `char(128512)` | Supplementary Unicode scalar |
+| `codePoint(55296)` | Surrogate code point |
+| `codeUnit16(55296)` | Lone UTF-16 surrogate unit |
+| `codePoints([55296, 128512])` | Raw code-point sequence |
+| `utf16([55296])` | Raw UTF-16 sequence |
+| `bytes([0, 128, 255])` | Raw octets |
+| `symbol("fixture-id", "description")` | Identity shared by the same ID within an example |
+| `unitValue`, `null`, `undefined` | Distinct singleton values |
+| `nullable(7)`, `optional(nullable(7))` | Present states, including nested states |
+| `prelude.isNaN x`, `prelude.isInfinite x`, `prelude.isFinite x` | Float classification |
+| `prelude.isNegativeZero x` | Float sign-bit classification |
+| `prelude.real z`, `prelude.imag z` | Complex component access |
+
+For `Optional (Nullable Int8)`, `undefined`, `optional(null)`, and
+`optional(nullable(7))` are different values. Tagged support types preserve this
+nesting, including on targets whose native null/optional types would collapse it.
+
+## Target bridges and generated runtime
+
+Existing Int32/Text/Bool-only specifications retain their adapter signatures.
+Scalar specifications use native representations where the bridge implements the
+whole domain, and generated support values elsewhere:
+
+- Python: native int, bool, str, bytes, float, complex, Decimal and Fraction;
+  `Raw`, `Presence`, `Symbol`, and absence support values.
+- JavaScript/TypeScript: number for small integers and floats, bigint for larger
+  integers, native strings, Uint8Array bytes and symbols; Decimal, Rational, Complex, Raw and
+  Presence support types. Unit is normalized from a void return.
+- Java/Kotlin: native signed primitives and widened unsigned primitives,
+  BigInteger, BigDecimal, strings, byte arrays, code points, UTF-16 units and floating primitives; `LawSpecRuntime.Value`
+  for remaining domains. Unit-returning adapters normalize native void/Unit.
+- Go: native integer widths, machine integers, floats and complex values,
+  `math/big.Int` and `math/big.Rat` (exported aliases), strings, runes, byte arrays and UTF-16 arrays;
+  `LawSpecValue` for remaining domains.
+- Haskell: native fixed integers, Integer, Rational, Float, Double, Complex, Char, Text, ByteString and `()`;
+  the `Scalar` support type for remaining domains. `Text` maps to `Data.Text.Text`,
+  not Haskell’s linked-list `String` (`[Char]`). General list types such as `[Char]`
+  are outside this scalar release.
+
+Input bridges check primitive bounds before native calls. Result bridges validate
+returned values. In particular, Text bridges reject invalid Unicode rather than
+repairing it. Use raw domains when preserving arbitrary bytes or UTF-16 units.
+
+The runtime sources are emitted separately from framework-specific tests. They
+have no property-testing or assertion-library dependencies. Runtime files are
+generated-owned **source** artifacts; adapters are user-owned source artifacts.
+Custom source/test directories and generation manifests preserve that distinction.
+Haskell scalar projects require the standard `bytestring` package in their library
+dependencies (included by new project templates).
+Kotlin uses the shared Java runtime under `src/main/java` by default; custom
+projects must include the configured source directory in their Java source set.
+
+## Machine profiles
+
+Set `"machineBits": 32` or `64` in `lawspec.json`, the compiler request, or use
+`--machine-bits 32`. The default is 64. Bounds, examples, generators, and bridges
+use this profile. Go and Haskell native machine-sized bridges report an
+architecture mismatch when the native word size differs. Fixed-width types remain
+portable across architectures.
+
+The bundled `scalars.lawspec`, `scalar_catalog.lawspec`, and
+`scalar_adapters.lawspec` contain explicit fixtures for every scalar family.
+`tools/scalar-reference.py` produces independent Fraction-based conformance
+vectors; `tools/scalar-integration.mjs` executes them across the eight targets.
+Set `LAWSPEC_MUTANTS=1` to also verify that incorrect adapters are detected.
+
+
+Refinements, parameterized domains, abstract native integer results, and executable
+function contracts are described in [REFINEMENTS.md](REFINEMENTS.md).

package/README.md

@@ -2,16 +2,33 @@
 
 **State the law once. Check it everywhere.**
 
-LawSpec 0.6 compiles reusable laws into native property tests, executable examples,
+LawSpec 0.8 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.
 
+## Rust and the typed front end in 0.8.0
+
+Rust joins Java, Python, JavaScript, TypeScript, Go, Haskell, and Kotlin. All
+eight backends consume the same typed core and testing plan. Source expressions
+retain their ranges, resolved identities, arithmetic evidence, and checked
+conversions. See the [Rust guide](RUST.md) and [language reference](LANGUAGE.md).
+
+The scalar catalog includes fixed and arbitrary integers, exact decimals and rationals,
+IEEE floats and complex values, Unicode and raw-text domains, bytes, symbols,
+and nested absence states on all eight targets. Integer arithmetic produces representation-independent
+`Integer` values; exact division returns Rational. See the [primitive reference](PRIMITIVES.md)
+for constructors, arithmetic, native bridges, and machine-width profiles.
+
+Compiler API consumers should read the [schema v3 migration guide](API-MIGRATION.md).
+Scalar values use tagged, lossless encodings; generated runtime placement is
+separate from artifact ownership. Java 25+ and Python 3.13+ baselines are unchanged.
+
 ## Install and try it
 
 Install [LawSpec from npm](https://www.npmjs.com/package/lawspec):
 
 ```sh
-npm install --save-dev lawspec@0.6.0
+npm install --save-dev lawspec@0.8.0
 npx lawspec --version
 ```
 
@@ -25,8 +42,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.6.0 -- lawspec init --target javascript
-npm install --save-dev lawspec@0.6.0
+npm exec --package=lawspec@0.8.0 -- lawspec init --target javascript
+npm install --save-dev lawspec@0.8.0
 npx lawspec check
 npx lawspec explain 'example.atoi_codec::itoa and then atoi yields a'
 npx lawspec doctor
@@ -59,9 +76,10 @@ properties with the selected framework's shrinking and failure reporting.
 | `go` | Go modules, Go 1.22–1.26 | Rapid 1.2.0, testing | `go test ./...` |
 | `haskell` | Stack, GHC 9.10, LTS 24.58 | Hspec 2.11, Hedgehog 1.5, hspec-hedgehog 0.3 | `stack test` |
 | `kotlin` | JDK/JVM 25, Gradle 9.1–9.3, Kotlin 2.3.21 | Kotest 5.9.1 | `gradle test` |
+| `rust` | Rust 1.85+, edition 2024, Cargo | Proptest 1.11.0 | `cargo test` |
 
 Java 25 and Python 3.13 are the minimum baselines. New JVM releases are admitted
-through compatibility profiles after testing; v0.6's current JVM profile certifies
+through compatibility profiles after testing; the current JVM profile certifies
 25. Python templates declare `requires-python = ">=3.13"` and runtime checks
 currently recognize 3.13 and 3.14. Kotlin templates pin Gradle's supported build
 configuration to Kotlin 2.3.21 and target JVM 25.
@@ -157,13 +175,13 @@ function names specially. `explain` shows the final property:
 for all (x :: Int32) . atoi (itoa (x)) = x
 ```
 
-Reusable laws can declare typed unary function parameters and `requires Eq a`.
+Reusable laws can declare typed unary function parameters and `requires Eq a`, numeric capabilities such as `requires Integer a`, and
+[parameterized refinements and executable contracts](REFINEMENTS.md).
 Definitions support law application, function application/composition, universal
 quantification, `implies`, Boolean predicates, scalar literals, and equality.
-Function signatures use `Int32`, `Text`, and `Bool`; generic variables are
-supported in reusable laws. v0.6 generates quantified inputs of all three types,
-including mixed and multiple inputs. These types can also be intermediate or
-compared results. Functions are synchronous and support curried signatures with any positive
+Function signatures and quantified inputs support the [scalar catalog](PRIMITIVES.md),
+including mixed and multiple inputs. Generic variables are supported in reusable
+laws. Scalar types can also be intermediate or compared results. Functions are synchronous and support curried signatures with any positive
 number of scalar arguments. Text literals are double-quoted, with escapes such as `\"`, `\\`,
 `\n`, and `\t`; examples must bind each input to a literal of its declared type.
 Text values contain Unicode scalar values; surrogate code points are rejected.
@@ -175,7 +193,7 @@ produce literal braces. Law blocks use this order:
 definition, optional description, optional rationale, examples, optional references.
 `--` starts a line comment. Names that cannot be emitted portably are diagnosed.
 
-Additional primitives, external law packages, cross-unit imports beyond the
+General collections, external law packages, cross-unit imports beyond the
 prelude, async functions, direct existing-symbol binding and browser hosting are
 outside this release.
 
@@ -232,7 +250,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.6.0/examples/specs/algebra.lawspec), including both sides of every
+[algebra.lawspec](https://github.com/brain-fuel/lawspec/blob/v0.8.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.
 
@@ -268,10 +286,10 @@ explicit domain predicate and conditional equations.
 `invertible` checks the supplied inverse operation. Check `identity` and
 `associative` as well when specifying a group. The prelude states contracts;
 it does not supply arithmetic implementations or prove a structure from random
-tests. The numeric examples use Int32 arithmetic modulo 2^32 so their laws hold
-at overflow boundaries on every target. JavaScript uses `Math.imul` for products,
-and Python explicitly wraps results into the signed Int32 range in the test
-adapters.
+tests. The algebra and numeric currying examples use mathematical `Integer`
+values and exact native arithmetic. Explicit expectations exceed Int32 and
+machine bounds, so wrapping or lossy adapters fail even when their modular
+arithmetic happens to satisfy the algebraic identities.
 
 Use `and` to require multiple conclusions in one law. For example:
 
@@ -300,11 +318,11 @@ 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.6.0/examples/specs/currying.lawspec) demonstrate a four-argument
+[Currying examples](https://github.com/brain-fuel/lawspec/blob/v0.8.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
-in all seven target languages (126 artifacts).
+in all eight target languages.
 
 The expanded API's **`assertion` tree is authoritative**: `AssertEqual` contains
 two expressions, `AssertImplies` contains a condition and consequence, and
@@ -352,7 +370,7 @@ law `valid ports round trip` is
 end
 ```
 
-The [complete port example](https://github.com/brain-fuel/lawspec/blob/v0.6.0/examples/specs/parse_port.lawspec)
+The [complete port example](https://github.com/brain-fuel/lawspec/blob/v0.8.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
@@ -370,7 +388,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.6.0/examples/specs/boolean_flags.lawspec)
+The [Boolean flags example](https://github.com/brain-fuel/lawspec/blob/v0.8.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.
@@ -391,7 +409,7 @@ preserves your adapter and reports the required stub shape. Generated tests call
 
 Every `example` must bind all quantified inputs and then include one or more
 `expect <expression> = <literal>` assertions. The expected literal must have the
-same `Int32`, `Text`, or `Bool` type as the expression. Expressions can reference the
+contextual scalar type of the expression. Expressions can reference the
 example's inputs and the unit's functions, including composed function calls.
 Input names shadow function names within expectations, following lexical scope.
 
@@ -449,7 +467,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.6.0/examples/specs/equivalent.lawspec) compares decimal
+[The complete example](https://github.com/brain-fuel/lawspec/blob/v0.8.0/examples/specs/equivalent.lawspec) compares decimal
 renderers and two implementations that clamp negative integers to zero. For
 JavaScript, their adapters can be:
 
@@ -460,11 +478,11 @@ export const clamp = x => Math.max(0, x);
 export const referenceClamp = x => x < 0 ? 0 : x;
 ```
 
-The same specification generates native tests for all seven targets. The
+The same specification generates native tests for all eight targets. The
 integration suite checks both examples with matching implementations, then
 breaks each alternative separately to verify detection. The general equivalence law alone does not establish independent correctness;
 two implementations can share the same bug. Explicit expectations additionally
-check the specified outputs at the supplied example inputs. Quantified inputs can be `Int32`, `Text`, or `Bool`.
+check the specified outputs at the supplied example inputs. Quantified inputs can use any supported scalar domain.
 
 ## Text properties and idempotence
 
@@ -486,7 +504,7 @@ law `normalizers agree` is
 end
 ```
 
-The [slug example](https://github.com/brain-fuel/lawspec/blob/v0.6.0/examples/specs/slug.lawspec)
+The [slug example](https://github.com/brain-fuel/lawspec/blob/v0.8.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()`,
@@ -513,7 +531,7 @@ law `canonicalization reaches a fixed point` is
 end
 ```
 
-The [canonical URL example](https://github.com/brain-fuel/lawspec/blob/v0.6.0/examples/specs/canonical_url.lawspec)
+The [canonical URL example](https://github.com/brain-fuel/lawspec/blob/v0.8.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:
 
@@ -522,7 +540,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.6.0/examples/specs/mixed_inputs.lawspec)
+The [mixed-input example](https://github.com/brain-fuel/lawspec/blob/v0.8.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 }[]`.
@@ -538,7 +556,7 @@ npx lawspec examples --target java --output example_artifacts
 This command works without a project configuration or native build tools. It
 compiles every bundled example and writes its tests and user-owned stubs to
 `example_artifacts/<language>/`, using each target's normal source/test layout.
-By default it exports all seven languages; `--json` returns the file inventory.
+By default it exports all eight languages; `--json` returns the file inventory.
 From a checkout, `make examples` runs the same command.
 
 These are inspection artifacts, not initialized projects: no build files are
@@ -587,7 +605,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.6.0.tgz`.
+`npm pack ./npm` and install it with `npm install --save-dev ./lawspec-0.8.0.tgz`.
 The package payload lives in `npm/`.
 
 ```sh
@@ -611,7 +629,7 @@ compiler-source and artifact hashes in `npm/build.json`; CI rejects stale WASM
 or hand-edited generated wrappers. The npm archive is a self-contained consumer
 artifact, with no install-time compilation or download hook.
 
-For all seven native integrations, install their build tools, then:
+For all eight native integrations, install their build tools, then:
 
 ```sh
 # Set LAWSPEC_GRADLE to a Gradle 9.3.0 executable if it is not on PATH.
@@ -625,3 +643,10 @@ fail, regeneration preserves implementations, and generation leaves build files
 unchanged. Arguments select individual targets. `LAWSPEC_PYTHON=3.14` selects the
 additional Python reference environment. CI also exercises Node 22/24/26 and packs
 and installs the npm archive. Registry publication is a separate release action.
+
+
+Refinement predicates can depend on earlier inputs. Generated tests backtrack from
+impossible prefixes, preserve the domain during shrinking, and validate function
+preconditions and postconditions. `Integer` results specify exact values without
+choosing a storage width. See the [refinement reference](REFINEMENTS.md) and
+[bundled examples](examples/specs/refinements.lawspec).