lawspec 0.5.0 → 0.7.0

package/API-MIGRATION.md

@@ -0,0 +1,85 @@
+# Compiler API migration: schema 1 → schema 2
+
+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
+
+Example bindings and expected values are uniformly tagged. Do not coerce every
+numeric value to JavaScript Number.
+
+```js
+// Previously: ["x", 42]
+// Now:
+["x", { type: "Int32", value: "42" }]
+
+// Lossless unsigned 64-bit example:
+{ type: "UInt64", value: "18446744073709551615" }
+```
+
+| Domain | Payload after `type` |
+| --- | --- |
+| All integers | `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 |
+
+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.

package/PRIMITIVES.md

@@ -0,0 +1,150 @@
+# LawSpec scalar reference (0.7.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 seven 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,28 @@
 
 **State the law once. Check it everywhere.**
 
-LawSpec 0.5 compiles reusable laws into native property tests, executable examples,
+LawSpec 0.6 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.
 
+## Portable scalars in 0.7.0
+
+LawSpec now supports 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 seven 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 v2 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.5.0
+npm install --save-dev lawspec@0.7.0
 npx lawspec --version
 ```
 
@@ -25,8 +37,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.5.0 -- lawspec init --target javascript
-npm install --save-dev lawspec@0.5.0
+npm exec --package=lawspec@0.7.0 -- lawspec init --target javascript
+npm install --save-dev lawspec@0.7.0
 npx lawspec check
 npx lawspec explain 'example.atoi_codec::itoa and then atoi yields a'
 npx lawspec doctor
@@ -61,7 +73,7 @@ properties with the selected framework's shrinking and failure reporting.
 | `kotlin` | JDK/JVM 25, Gradle 9.1–9.3, Kotlin 2.3.21 | Kotest 5.9.1 | `gradle test` |
 
 Java 25 and Python 3.13 are the minimum baselines. New JVM releases are admitted
-through compatibility profiles after testing; v0.5's current JVM profile certifies
+through compatibility profiles after testing; v0.6's 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,14 +169,14 @@ 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.5 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 unary. Text literals are double-quoted, with escapes such as `\"`, `\\`,
+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,10 +187,144 @@ 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.
 
+## Algebra and currying (0.6)
+
+Version 0.6 adds algebra laws, scalar law parameters, curried signatures,
+and conjunctions.
+
+```lawspec
+unit example.addition
+
+add :: Int32 -> Int32 -> Int32
+
+law `addition commutes` is
+  definition is
+    `commutative` add
+  end
+
+  example `3 plus 5 and 5 plus 3 both produce 8` is
+    x = 3
+    y = 5
+    expect add x y = 8
+    expect add y x = 8
+  end
+end
+
+law `zero is an identity on both sides` is
+  definition is
+    `identity` add 0
+  end
+
+  example `zero preserves 3 on either side` is
+    x = 3
+    expect add 0 x = 3
+    expect add x 0 = 3
+  end
+end
+```
+
+Arrows associate to the right and application associates to the left:
+`f :: a -> b -> c` takes two arguments, and `f x y` means `(f x) y`.
+A partial application such as `add 1` can be passed to a reusable unary law;
+`sumFour 1 2` can be passed to a binary law. Partial applications also compose.
+The compiler specializes these expressions before emission. Java, Kotlin,
+Python, JavaScript, TypeScript and Go adapters take ordinary positional arguments
+(`add(x, y)`); Haskell adapters use native currying (`add x y`). Argument order
+and types are preserved, including mixtures of `Text`, `Bool` and `Int32`.
+
+Law parameters can also be scalar values: `(e :: a)` supplies an identity and
+`(zero :: a)` supplies an absorbing element. Pass literals directly, for example
+`left identity` with arguments `add 0`, or `absorbing element` with `multiply 0`.
+Functions declared by a unit take one or more scalar inputs and return a scalar;
+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.7.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.
+
+| Law and arguments | Equations checked for every quantified input |
+| --- | --- |
+| `commutative f` | `f x y = f y x` |
+| `associative f` | `f (f x y) z = f x (f y z)` |
+| `left identity f e` | `f e x = x` |
+| `right identity f e` | `f x e = x` |
+| `identity f e` | Both identity equations |
+| `left absorbing element f zero` | `f zero x = zero` |
+| `right absorbing element f zero` | `f x zero = zero` |
+| `absorbing element f zero` | Both absorbing equations |
+| `left distributive f g` | `f x (g y z) = g (f x y) (f x z)` |
+| `right distributive f g` | `f (g x y) z = g (f x z) (f y z)` |
+| `distributive f g` | Both distributive equations |
+| `idempotent operation f` | `f x x = x` (the existing `idempotent` law is unary) |
+| `left inverse element f inverse e` | `f (inverse x) x = e` |
+| `right inverse element f inverse e` | `f x (inverse x) = e` |
+| `invertible f inverse e` | Both inverse equations |
+| `left division f divideLeft` | `f x (divideLeft x y) = y` and `divideLeft x (f x y) = y` |
+| `right division f divideRight` | `f (divideRight x y) y = x` and `divideRight (f x y) y = x` |
+| `divisible f divideLeft divideRight` | All four division equations |
+| `involution f` | `f (f x) = x` |
+
+Here **divisible** means algebraic left/right division. `divideLeft x y` solves
+`f x result = y`; `divideRight x y` solves `f result y = x`. The subtraction
+example deliberately uses a noncommutative operation: with `x = 3` and `y = 5`,
+the left solution is `-2` and the right solution is `8`. Recovery is checked in
+both directions. These are total laws; a partially defined division needs an
+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.
+
+Use `and` to require multiple conclusions in one law. For example:
+
+```lawspec
+unit example.absorption
+multiply :: Int32 -> Int32 -> Int32
+
+law `zero absorbs on both sides` is
+  definition is
+    `for all` (x :: Int32) .
+      multiply 0 x = 0 and multiply x 0 = 0
+  end
+
+  example `3 times zero and zero times 3 both produce zero` is
+    x = 3
+    expect multiply 0 x = 0
+    expect multiply x 0 = 0
+  end
+end
+```
+
+Quantification and implication extend through the following conjunction:
+`p x implies A and B` guards both conclusions. Write `(p x implies A) and B`
+to guard only the first. A shared guard runs once per check; false guards skip
+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.7.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).
+
+The expanded API's **`assertion` tree is authoritative**: `AssertEqual` contains
+two expressions, `AssertImplies` contains a condition and consequence, and
+`AssertAll` contains every conjunct. Existing `left`, `right`, and `guards`
+fields are compatibility projections of the first conclusion only; consumers
+checking compound laws must traverse `assertion`. Source definitions add `And`.
+`lawspec explain` prints the full conjunction and its conditional scope.
+
 ## Predicates and conditional laws (0.5)
 
 A predicate is a unary function returning `Bool`. Use `true` and `false` in
@@ -218,7 +364,7 @@ law `valid ports round trip` is
 end
 ```
 
-The [complete port example](https://github.com/brain-fuel/lawspec/blob/v0.5.0/examples/specs/parse_port.lawspec)
+The [complete port example](https://github.com/brain-fuel/lawspec/blob/v0.7.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
@@ -236,7 +382,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.5.0/examples/specs/boolean_flags.lawspec)
+The [Boolean flags example](https://github.com/brain-fuel/lawspec/blob/v0.7.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.
@@ -257,7 +403,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.
 
@@ -315,7 +461,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.5.0/examples/specs/equivalent.lawspec) compares decimal
+[The complete example](https://github.com/brain-fuel/lawspec/blob/v0.7.0/examples/specs/equivalent.lawspec) compares decimal
 renderers and two implementations that clamp negative integers to zero. For
 JavaScript, their adapters can be:
 
@@ -330,7 +476,7 @@ The same specification generates native tests for all seven 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
 
@@ -352,7 +498,7 @@ law `normalizers agree` is
 end
 ```
 
-The [slug example](https://github.com/brain-fuel/lawspec/blob/v0.5.0/examples/specs/slug.lawspec)
+The [slug example](https://github.com/brain-fuel/lawspec/blob/v0.7.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()`,
@@ -379,7 +525,7 @@ law `canonicalization reaches a fixed point` is
 end
 ```
 
-The [canonical URL example](https://github.com/brain-fuel/lawspec/blob/v0.5.0/examples/specs/canonical_url.lawspec)
+The [canonical URL example](https://github.com/brain-fuel/lawspec/blob/v0.7.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:
 
@@ -388,7 +534,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.5.0/examples/specs/mixed_inputs.lawspec)
+The [mixed-input example](https://github.com/brain-fuel/lawspec/blob/v0.7.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 }[]`.
@@ -453,7 +599,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.5.0.tgz`.
+`npm pack ./npm` and install it with `npm install --save-dev ./lawspec-0.7.0.tgz`.
 The package payload lives in `npm/`.
 
 ```sh
@@ -491,3 +637,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).