lawspec 0.6.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

@@ -6,12 +6,24 @@ LawSpec 0.6 compiles reusable laws into native property tests, executable exampl
 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.6.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.6.0 -- lawspec init --target javascript
-npm install --save-dev lawspec@0.6.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
@@ -157,13 +169,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 +187,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 +244,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.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.
 
@@ -300,7 +312,7 @@ their entire consequence. Every conjunct is type-checked and emitted. As with
 existing assertions, the first failure stops that individual test. `and` is now
 a reserved word.
 
-[Currying examples](https://github.com/brain-fuel/lawspec/blob/v0.6.0/examples/specs/currying.lawspec) demonstrate a four-argument
+[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
@@ -352,7 +364,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.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
@@ -370,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.6.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.
@@ -391,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.
 
@@ -449,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.6.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:
 
@@ -464,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
 
@@ -486,7 +498,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.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()`,
@@ -513,7 +525,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.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:
 
@@ -522,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.6.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 }[]`.
@@ -587,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.6.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
@@ -625,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).

package/REFINEMENTS.md

@@ -0,0 +1,158 @@
+# Refinements and abstract integers (0.7.0)
+
+A refinement restricts a scalar domain with a pure Boolean expression. LawSpec
+checks concrete examples, generates satisfying input tuples, and checks adapter
+contracts during testing. It does not prove that an adapter is correct.
+
+## Exact integers without a storage width
+
+`Integer` is the mathematical integer domain. Integer literals default to it;
+integer addition, subtraction, multiplication, negation, quotient, and remainder
+produce it. Calculations use arbitrary precision internally. `BigInt` remains
+available when a concrete arbitrary-precision adapter representation is wanted.
+
+```lawspec
+unit example.increment
+successor :: (x :: Int8) -> (result :: Integer where result == x + 1)
+```
+
+This signature generates contract tests without a separate law. The maximum
+input, `127`, requires the value `128`. Returning a wrapped `-128` fails.
+`Integer` does not assert which storage width the implementation used.
+
+Abstract integer results accept Python `int` (excluding `bool`), JavaScript or
+TypeScript `bigint` and safe integral `number` values, Java/Kotlin standard signed
+integral wrappers and `BigInteger` through `Number`, and Go signed/unsigned integer
+values or `big.Int` values/pointers through `any`. Floating representations are
+rejected even when their current value is integral. Haskell uses `IntegerValue`:
+
+```haskell
+successor :: Int8 -> IntegerValue
+successor x = integerValue (toInteger x + 1)
+```
+
+`integerValue :: Integral a => a -> IntegerValue` erases the width losslessly.
+Abstract integer arguments use the target's arbitrary-precision integer type.
+Concrete signatures keep their existing checked native mappings.
+
+## Inline and named refinements
+
+Use `where` on a quantified input, function argument, or function result:
+
+```lawspec
+`for all` (x :: Int8) (y :: Int8 where y > Int8.max - x) .
+  add x y = x + y
+```
+
+A predicate can reference its own value and earlier inputs. A function result
+predicate can also reference the function's named arguments. Forward value
+references are errors. `Int8.min` and `Int8.max` denote representation bounds;
+machine-sized bounds use the requested `machineBits` profile.
+
+Named refinements distinguish type parameters from value parameters:
+
+```lawspec
+refinement Between
+  (T :: Type) (minimum :: T) (maximum :: T)
+  requires Ordered T is
+  (value :: T where minimum <= value && value <= maximum)
+end
+
+refinement AdditionOverflows
+  (T :: Type) (left :: T)
+  requires Integer T Bounded T is
+  (right :: T where left + right > T.max)
+end
+
+add :: (x :: Int8)
+    -> (y :: AdditionOverflows Int8 x)
+    -> (result :: Integer where result == x + y)
+```
+
+`(x :: Between Int8 1 10)` applies a refinement. Parenthesize compound arguments,
+for example `Between Int8 (-10) (5 + 5)`. Later value-parameter types can use
+earlier parameters. Value arguments must satisfy their declared domains,
+including refinements. Substitution avoids capturing names from the call site.
+Declarations can appear in any order within a unit; recursive aliases are errors.
+Fixed refinements are the zero-parameter form:
+
+```lawspec
+refinement PositiveInt8 is (value :: Int8 where value > 0) end
+```
+
+Aliases preserve their underlying native representation. They can be nested in
+`Nullable` and `Optional`; inner predicates are checked only for present values.
+Type parameters range over the supported scalar types, including presence types.
+
+`requires Integer T` describes integer capabilities in a generic declaration.
+`Integer` entails `Eq` and `Ordered`. `Ordered` currently covers exact real numbers
+and floats, with the existing IEEE comparisons (including NaN behavior).
+`Bounded` covers fixed and machine-sized integers. Bounds refer to the underlying
+integer representation, rather than a tighter interval inferred from a predicate.
+Capabilities are checked on generic declarations and their specializations.
+
+## Predicate expressions and contracts
+
+Predicates support existing pure arithmetic, comparisons, scalar constructors,
+conversions, and built-in helpers. `&&`, `||`, and `!` short-circuit; comparisons
+bind more tightly than `&&`, which binds more tightly than `||`. Assertion `and`
+continues to combine law conclusions. Exact/inexact mixing still needs an explicit
+conversion, and floating expressions retain their declared precision.
+
+`prelude.length` counts Unicode scalars for Text, code points for CodePointText,
+UTF-16 units for Utf16Text, and octets for Bytes. `prelude.isPresent` and
+`prelude.presentValue` inspect tagged presence values; guard extraction with
+`isPresent` before accessing a possibly absent value.
+
+Adapter calls are forbidden in refinements. Predicate errors such as division by
+zero are reported as failures when evaluated; they are not ordinary rejection of
+an input. Short-circuited branches are not evaluated by generation optimizations.
+
+Every refined function signature creates a standalone property. Calls from other
+laws also check argument preconditions, invoke the adapter once, snapshot its
+result, and check postconditions. Calling a function outside its precondition is
+a test failure, not a discarded example. Ordinary `implies` guards retain their
+existing conditional behavior.
+
+## Dependent generation and shrinking
+
+A quantified law ranges over satisfying tuples. For `AdditionOverflows Int8 x`,
+`x = 0` has no admissible `y`. The generator backtracks to choose another `x`;
+it does not count that dead end as a passing test. Valid pairs satisfy:
+
+```text
+1 <= x <= 127
+128 - x <= y <= 127
+```
+
+The generator derives integer bounds from affine comparisons and conjunctions,
+seeds direct comparison values and boundaries, and checks the complete predicate.
+Predicates outside that analysis use bounded sampling. Small finite base-domain
+products are enumerated exhaustively, retaining only satisfying tuples.
+
+Shrinking checks refinements again and repairs dependent later inputs when an
+earlier value changes. An overflowing counterexample can shrink to `(1, 127)`;
+it cannot shrink to `(0, 127)` because that pair is outside the domain.
+
+Compiler requests and `lawspec.json` accept:
+
+```json
+{
+  "generation": {
+    "cases": 100,
+    "maxAttempts": 10000,
+    "maxShrinks": 1000,
+    "exhaustiveLimit": 4096
+  }
+}
+```
+
+All limits are positive integers. These are the defaults for refinement properties.
+`cases` counts accepted property inputs; explicit examples and boundary fixtures
+are additional checks. Exhausted searches report an error with reproduction
+information. Exhaustion does not prove that the mathematical domain is empty.
+Statically established empty executable domains and invalid examples are rejected.
+
+See [the bundled examples](examples/specs/refinements.lawspec) for overflow,
+abstract integer arguments/results, dependent bounds, optional refinements,
+floating classification, and raw-byte lengths.

package/bin/lawspec.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import { createCompiler } from "../api.mjs";
 import { targets, templates, commands, setup } from "../templates.mjs";
 import { generateExamples } from "../examples-command.mjs";
+import { showScalar } from "../scalars.mjs";
 import { doctor } from "../doctor.mjs";
 import {
   readOptional,
@@ -18,7 +19,7 @@ const options = {};
 const positional = [];
 for (let i = 0; i < args.length; i++) {
   const arg = args[i];
-  if (["--target", "--project", "--config", "--output"].includes(arg)) {
+  if (["--target", "--project", "--config", "--output", "--machine-bits"].includes(arg)) {
     if (!args[i + 1] || args[i + 1].startsWith("--"))
       throw new Error(`Missing value for ${arg}`);
     options[arg.slice(2)] = args[++i];
@@ -138,6 +139,7 @@ async function init() {
       await readFile(new URL("../starter.lawspec", import.meta.url), "utf8"),
       true,
     );
+  if (options.machineBits !== undefined) config.machineBits = options.machineBits;
   config.targets.push({
     language,
     root: path.relative(configRoot, root) || ".",
@@ -151,9 +153,19 @@ async function init() {
     `Configured ${language}. ${hasBuild ? "Existing build files preserved." : "Created missing project build files."}\n${setup[language]}\nNext: lawspec doctor, then lawspec generate.`,
   );
 }
+function showType(type) {
+  if (type.tag === 'Named' || type.tag === 'Variable') return type.contents;
+  if (type.tag === 'Applied') return `${type.contents[0]} (${showType(type.contents[1])})`;
+  return `${showType(type.contents[0])} -> ${showType(type.contents[1])}`;
+}
 function showExpression(expr) {
   const value = expr.contents;
-  if (expr.tag === "Var") return value;
+  if (expr.tag === "Var" || expr.tag === "Number") return value;
+  if (expr.tag === "DecimalNumber") return `${value[0]}e${value[1]}`;
+  if (expr.tag === "ScalarLit") return showScalar(value);
+  if (expr.tag === "Binary") return `(${showExpression(value[1])} ${value[0]} ${showExpression(value[2])})`;
+  if (expr.tag === "Unary") return `${value[0]}(${showExpression(value[1])})`;
+  if (expr.tag === "Annotate") return `(${showExpression(value[0])} :: ${showType(value[1])})`;
   if (
     expr.tag === "Number" ||
     expr.tag === "StringLit" ||
@@ -170,28 +182,32 @@ function explainExamples(law) {
       (ex) =>
         `\nexample ${JSON.stringify(ex.exampleName)}\n` +
         ex.bindings
-          .map(([n, v]) => `  ${n} = ${JSON.stringify(v)}`)
+          .map(([n, v]) => `  ${n} = ${showScalar(v)}`)
           .join("\n") +
         "\n" +
         ex.expectations
           .map(
             (e) =>
-              `  expect ${showExpression(e.actual)} = ${JSON.stringify(e.expected)}`,
+              `  expect ${showExpression(e.actual)} = ${showScalar(e.expected)}`,
           )
           .join("\n"),
     )
     .join("\n");
 }
 async function main() {
+  if (options['machine-bits'] !== undefined) {
+    options.machineBits = Number(options['machine-bits']);
+    if (![32,64].includes(options.machineBits)) throw new Error('machineBits must be 32 or 64');
+  }
   if (!verb || ["help", "--help", "-h"].includes(verb)) {
     output(
-      "LawSpec 0.6.0\nUsage: lawspec init --target <language> [--project <directory>]\n       lawspec check | doctor | explain <unit>::<law> | generate\n       lawspec examples [--target <language>] [--output example_artifacts]\nOptions: --config <path>, --target <language>, --json\nGeneration: --dry-run, --check\nTargets: " +
+      "LawSpec 0.7.0\nUsage: lawspec init --target <language> [--project <directory>]\n       lawspec check | doctor | explain <unit>::<law> | generate\n       lawspec examples [--target <language>] [--output example_artifacts]\nOptions: --config <path>, --target <language>, --machine-bits <32|64>, --json\nGeneration: --dry-run, --check\nTargets: " +
         targets.join(", "),
     );
     return;
   }
   if (verb === "--version") {
-    output("0.6.0");
+    output("0.7.0");
     return;
   }
   if (positional.length > (verb === "explain" ? 1 : 0))
@@ -256,7 +272,8 @@ async function main() {
     if (reports.some((r) => !r.ok)) process.exitCode = 1;
     return;
   }
-  const input = { sources: await sources(config) };
+  if (config.machineBits !== undefined && ![32, 64].includes(config.machineBits)) throw new Error("machineBits must be 32 or 64");
+  const input = { sources: await sources(config), generation: config.generation, machineBits: options.machineBits ?? config.machineBits ?? 64 };
   const compiler = await createCompiler();
   if (verb === "check") {
     const result = diagnostics(await compiler.check(input));

package/build.json

@@ -2,38 +2,64 @@
   "version": 1,
   "compilerSources": [
     "package.yaml",
+    "runtime/LawSpecRuntime.hs",
+    "runtime/LawSpecRuntime.java",
+    "runtime/lawspec_runtime.go",
+    "runtime/lawspec_runtime.mjs",
+    "runtime/lawspec_runtime.py",
     "src/LawSpec/Api.hs",
     "src/LawSpec/Compile.hs",
+    "src/LawSpec/Domain.hs",
     "src/LawSpec/Emit.hs",
+    "src/LawSpec/Eval.hs",
     "src/LawSpec/Gen.hs",
     "src/LawSpec/Model.hs",
+    "src/LawSpec/NativeScalarEmit.hs",
     "src/LawSpec/Parser.hs",
     "src/LawSpec/Prelude.hs",
+    "src/LawSpec/Refinement.hs",
+    "src/LawSpec/RuntimeSources.hs",
+    "src/LawSpec/Scalar.hs",
+    "src/LawSpec/ScalarEmit.hs",
     "stack.yaml",
     "stack.yaml.lock",
+    "tools/embed-runtimes.py",
     "wasm/app/Exports.hs",
     "wasm/cabal.project",
     "wasm/cabal.project.freeze",
     "wasm/lawspec-wasm.cabal"
   ],
   "digests": {
-    "package.yaml": "25d79d741039fe21e1164d789fdf4f698f135df7e4c96c82560e4f7efe8fbdf9",
-    "src/LawSpec/Api.hs": "00b1e4bc81231ebd387f10652463904084ebf9c3c4486fd2c2217a6d4dbfc157",
-    "src/LawSpec/Compile.hs": "64aa042ce2f0f460d691ea43fa27bf75576a49a6e852a068f62a2cf5a28e81b7",
-    "src/LawSpec/Emit.hs": "85ab85d789c4e2c98703e2768075cb1c0bed42b987c45b5060b9a9df56e8d291",
-    "src/LawSpec/Gen.hs": "c596e411790a47cb15b2945d391b9909cbec1972bf6e502ed8c069db2c67e991",
-    "src/LawSpec/Model.hs": "549f553d1cc5d65c804a5acfac0cc06e63ff10eb80674893e32fcd3c0a71a5b3",
-    "src/LawSpec/Parser.hs": "ae7c5ad29871b99441db2dae10548afafb2ae4931dd1a62208ca0f5e3545002c",
+    "package.yaml": "ca15186d8aa807c58258a4b0fef8fa7d64afaa828f2e71803b4e8741066422fe",
+    "runtime/LawSpecRuntime.hs": "1c3ca22232c64227717d836a57d375d906f748ecde6b79705944a2319ce5064d",
+    "runtime/LawSpecRuntime.java": "5637914bd491f75ad0c75fb19d1bec798164295b7bcf9d23e1549e8ebf780d01",
+    "runtime/lawspec_runtime.go": "62d2041c33760b67db619e0a803501768a505c4dfd9837bca85e158fff81fda9",
+    "runtime/lawspec_runtime.mjs": "7d0abd53fa45dd9828c10ff2ffa7876162e965e7bb4913f4c460af13e06142fa",
+    "runtime/lawspec_runtime.py": "7541353effebd133e50cd00a3f4d8999651c93ba751a6d951164b1f390ce0c15",
+    "src/LawSpec/Api.hs": "f1a283fd3696e8e0dd1bd6240ba636a4c1abe19c6e0ea25d6d80a1af89f762cb",
+    "src/LawSpec/Compile.hs": "a67ee7cb19ebeea644bbf8dbdc0647323a77197b15f8e87fe2227deb6c995b8e",
+    "src/LawSpec/Domain.hs": "8ad50ad3a37aacb3a429c2d7924279e2a3b973204ce3c5c04c634c1b9ada0151",
+    "src/LawSpec/Emit.hs": "0b29d449f762af635bb65e5fcbf1f4cfffb1b91b28db115b08b2309557498693",
+    "src/LawSpec/Eval.hs": "9bdb694352ec4bd7140cdf8ab18045978b7407e93db5b661270160d08e4e9b7d",
+    "src/LawSpec/Gen.hs": "d4b4e5a21f5a2886dcdc98f56f649980d961c0570d9463154bed459844ab66aa",
+    "src/LawSpec/Model.hs": "67cad75f1d344bc2dfc997731c37f68994c6a6b568e03209e5b446484ae54674",
+    "src/LawSpec/NativeScalarEmit.hs": "67f50a7ea381ddada8ecbfc7534917c53f4074f8ce1d4fb6948adb8b7dfb2007",
+    "src/LawSpec/Parser.hs": "b6e5ee4a8c58b0ab2709420460f1fcabe287714f6defc0fab6cf52ccd0c416a5",
     "src/LawSpec/Prelude.hs": "b1e155c12f58e7c346551a0c65c5d5af76d045b3f1625977ca2a5d1c97cb8c46",
+    "src/LawSpec/Refinement.hs": "060f7bdaaa9cebc17969fa28474e9402cc918ceea0f18cac54050d25010b473c",
+    "src/LawSpec/RuntimeSources.hs": "4a49d98919971bdbe2b9eabda4eb2e7cda643aaa65ef1a4e6892b6da40ee8acd",
+    "src/LawSpec/Scalar.hs": "d89d8233abd893f65bb20d4dabe11066340eb51b982ad6fa7bce04d3e22c3547",
+    "src/LawSpec/ScalarEmit.hs": "e1f05d255db08c8634b6af98fd5d0b938f9a3735f8adf13a952f092a90ee884c",
     "stack.yaml": "20ccf4d599e355e60b7aa4f814a7cd4299fe2048616cc2e6dbdc22a7bd8cec73",
     "stack.yaml.lock": "ae222b9c81af920c56e50fa4596fa57786e7fa5a7b461390362b2b2ff63818c7",
+    "tools/embed-runtimes.py": "7520956a91f4b4ec8a6ab12078195cf1243c989b388a3f9d0b10a0fa60193bc3",
     "wasm/app/Exports.hs": "4ecbdac8faa2449e6fc61b93c82e6278fa14374154f29b4dacf0eef433f06a47",
     "wasm/cabal.project": "021e560afdc5eb4cb7169e7119ecb8f92c9ee170245af909c94b612941bff5cc",
     "wasm/cabal.project.freeze": "733dbed3d2ecccb26e874fd58f136296dad772184deb1658c196b5d54a0814dc",
-    "wasm/lawspec-wasm.cabal": "d0d9c395b96de75264d5dc62f7995f02b285aebc696a2cf603a62b4e280f9132",
-    "npm/core.wasm": "e90e71610ca9f58a1b1e88d65f593c74d2a5b09347a4b47802bd771c954b7e42",
+    "wasm/lawspec-wasm.cabal": "afdb97eb4a08de190f7533b7be79c6ba11fab9ef30792aca71ef5fb448001106",
+    "npm/core.wasm": "32e3f553dc8346a0d7aac63ad556eacc0e791803b8957f0804a609b883ed0ea8",
     "npm/core_jsffi.js": "88d136efe92f7cff5758c8fec8d9b6bbc9707fe37741cebeeb415fe34ce3d72b",
     "npm/api.mjs": "d6df654600172131ac66a55b86876fc29cde2a76a0a63bbefff3183488a4837b",
-    "npm/index.d.ts": "628016928dc71dc735d59d15ccde45500d9a4133e3b20c8d3c21cb9c65ccb604"
+    "npm/index.d.ts": "ec19e731ed33e0d0481345888c73778ae0d3f2db58e4c3310ba684b801e698bc"
   }
 }

package/examples/specs/refinements.lawspec

@@ -0,0 +1,75 @@
+unit example.refinements
+
+refinement Between (T :: Type) (minimum :: T) (maximum :: T)
+  requires Ordered T is
+  (value :: T where minimum <= value && value <= maximum)
+end
+
+refinement Positive (T :: Type) requires Integer T is
+  (value :: T where value > 0)
+end
+
+refinement AdditionOverflows (T :: Type) (left :: T)
+  requires Integer T Bounded T is
+  (right :: T where left + right > T.max)
+end
+
+add :: (x :: Int8)
+    -> (y :: AdditionOverflows Int8 x)
+    -> (result :: Integer where result == x + y)
+successor :: (x :: Int8) -> (result :: Integer where result == x + 1)
+count :: (text :: Text where prelude.length text > 0)
+      -> (result :: Integer where result == prelude.length text)
+preserve :: (x :: UInt64) -> (result :: Integer where result == x)
+positive :: (x :: Positive Int8) -> (result :: Positive Int8 where result == x)
+
+law `maximum input` is
+  definition is `for all` (x :: Int8) . successor x = x + 1 end
+  example `beyond Int8` is x = 127 expect successor x = 128 end
+end
+
+law `overflow pairs` is
+  definition is
+    `for all` (x :: Int8) (y :: AdditionOverflows Int8 x) .
+      add x y = x + y
+  end
+  example `smallest overflowing sum` is x = 127 y = 1 expect add x y = 128 end
+  example `largest sum` is x = 127 y = 127 expect add x y = 254 end
+end
+
+law `bounded input` is
+  definition is `for all` (x :: Between Int8 1 3) . positive x = x end
+  example `middle` is x = 2 expect positive x = 2 end
+end
+
+law `large integer` is
+  definition is `for all` (x :: UInt64) . preserve x = x end
+  example `maximum UInt64` is x = 18446744073709551615 expect preserve x = 18446744073709551615 end
+end
+
+abstractEcho :: (x :: Integer) -> (result :: Integer where result == x)
+
+law `nested presence` is
+  definition is `for all` (x :: Optional (Nullable (Positive Int8))) . x = x end
+end
+
+law `finite positive floats` is
+  definition is
+    `for all` (x :: Float32 where prelude.isFinite x && x > 0) .
+      prelude.isFinite x
+  end
+  example `positive` is x = 0.5 expect x = 0.5 end
+end
+
+law `raw byte length` is
+  definition is `for all` (x :: Bytes where prelude.length x == 3) . prelude.length x = 3 end
+  example `arbitrary octets` is x = bytes([0,128,255]) expect prelude.length x = 3 end
+end
+
+law `guarded predicate arithmetic` is
+  definition is `for all` (x :: Int8) (y :: Int8 where x != 0 && y > 10 / x) . y > 10 / x end
+end
+
+law `machine bound` is
+  definition is `for all` (x :: IntSize where x == IntSize.max) . x = IntSize.max end
+end

package/examples/specs/scalar_adapters.lawspec

@@ -0,0 +1,83 @@
+unit example.scalar_adapters
+echoChar :: Char -> Char
+echoCodePoint :: CodePoint -> CodePoint
+echoCodeUnit :: CodeUnit16 -> CodeUnit16
+echoBytes :: Bytes -> Bytes
+echoComplex :: Complex64 -> Complex64
+successor :: Int8 -> BigInt
+narrow :: Int8 -> Int8
+addDecimal :: Decimal -> Decimal -> Decimal
+sameSymbol :: Symbol -> Symbol -> Bool
+echoRaw :: Utf16Text -> Utf16Text
+echoPresence :: Optional (Nullable Int8) -> Optional (Nullable Int8)
+finish :: Unit -> Unit
+preserveBig :: UInt64 -> UInt64
+machineEcho :: IntSize -> IntSize
+
+law `promoted successor` is
+  definition is `for all` (x :: Int8) . successor x = x + 1 end
+  example `no overflow` is x = 127 expect successor x = 128 end
+end
+law `checked bridge` is
+  definition is `for all` (x :: Int8) . narrow (x + 0) = x end
+  example `maximum` is x = 127 expect narrow (x + 0) = 127 end
+end
+law `exact decimal adapter` is
+  definition is `for all` (x :: Decimal) (y :: Decimal) . addDecimal x y = x + y end
+  example `tenths` is x = 0.1 y = 0.2 expect addDecimal x y = 0.3 end
+end
+law `symbol identity adapter` is
+  definition is `for all` (x :: Symbol) (y :: Symbol) . sameSymbol x x and sameSymbol y y end
+  example `same description distinct identities` is
+    x = symbol("a", "same") y = symbol("b", "same")
+    expect sameSymbol x y = false
+    expect sameSymbol x x = true
+  end
+end
+law `raw adapter` is
+  definition is `for all` (x :: Utf16Text) . echoRaw x = x end
+  example `lone surrogate` is x = utf16([55296]) expect echoRaw x = utf16([55296]) end
+end
+law `presence adapter` is
+  definition is `for all` (x :: Optional (Nullable Int8)) . echoPresence x = x end
+  example `missing` is x = undefined expect echoPresence x = undefined end
+  example `null present` is x = optional(null) expect echoPresence x = optional(null) end
+end
+law `unit adapter` is
+  definition is `for all` (x :: Unit) . finish x = unitValue end
+  example `completed` is x = unitValue expect finish x = unitValue end
+end
+
+law `no safe-number truncation` is
+  definition is `for all` (x :: UInt64) . preserveBig x = x end
+  example `unsigned maximum` is x = 18446744073709551615 expect preserveBig x = 18446744073709551615 end
+end
+law `machine profile binding` is
+  definition is `for all` (x :: IntSize) . machineEcho x = x end
+  example `portable width` is x = 2147483647 expect machineEcho x = 2147483647 end
+end
+
+law `Char native bridge` is
+  definition is `for all` (x :: Char) . echoChar x = x end
+  example `native value` is x = char(128512) expect echoChar x = char(128512) end
+end
+
+law `CodePoint native bridge` is
+  definition is `for all` (x :: CodePoint) . echoCodePoint x = x end
+  example `native value` is x = codePoint(55296) expect echoCodePoint x = codePoint(55296) end
+end
+
+law `CodeUnit16 native bridge` is
+  definition is `for all` (x :: CodeUnit16) . echoCodeUnit x = x end
+  example `native value` is x = codeUnit16(65535) expect echoCodeUnit x = codeUnit16(65535) end
+end
+
+law `Bytes native bridge` is
+  definition is `for all` (x :: Bytes) . echoBytes x = x end
+  example `native value` is x = bytes([0,128,255]) expect echoBytes x = bytes([0,128,255]) end
+end
+
+law `Complex64 native bridge` is
+  definition is `for all` (x :: Complex64) . prelude.isNaN (prelude.real (echoComplex x)) = prelude.isNaN (prelude.real x) end
+  example `native value` is x = complex64(1,2) expect echoComplex x = complex64(1,2) end
+end

package/examples/specs/scalar_catalog.lawspec

@@ -0,0 +1,166 @@
+unit example.scalar_catalog
+
+law `Bool representation` is
+  definition is `for all` (x :: Bool) . x = x end
+  example `explicit value` is x = true expect x = true end
+end
+
+law `Int8 representation` is
+  definition is `for all` (x :: Int8) . x = x end
+  example `explicit value` is x = -128 expect x = -128 end
+end
+
+law `Int16 representation` is
+  definition is `for all` (x :: Int16) . x = x end
+  example `explicit value` is x = 32767 expect x = 32767 end
+end
+
+law `Int32 representation` is
+  definition is `for all` (x :: Int32) . x = x end
+  example `explicit value` is x = 2147483647 expect x = 2147483647 end
+end
+
+law `Int64 representation` is
+  definition is `for all` (x :: Int64) . x = x end
+  example `explicit value` is x = 9223372036854775807 expect x = 9223372036854775807 end
+end
+
+law `UInt8 representation` is
+  definition is `for all` (x :: UInt8) . x = x end
+  example `explicit value` is x = 255 expect x = 255 end
+end
+
+law `UInt16 representation` is
+  definition is `for all` (x :: UInt16) . x = x end
+  example `explicit value` is x = 65535 expect x = 65535 end
+end
+
+law `UInt32 representation` is
+  definition is `for all` (x :: UInt32) . x = x end
+  example `explicit value` is x = 4294967295 expect x = 4294967295 end
+end
+
+law `UInt64 representation` is
+  definition is `for all` (x :: UInt64) . x = x end
+  example `explicit value` is x = 18446744073709551615 expect x = 18446744073709551615 end
+end
+
+law `IntSize representation` is
+  definition is `for all` (x :: IntSize) . x = x end
+  example `explicit value` is x = 2147483647 expect x = 2147483647 end
+end
+
+law `UIntSize representation` is
+  definition is `for all` (x :: UIntSize) . x = x end
+  example `explicit value` is x = 4294967295 expect x = 4294967295 end
+end
+
+law `UIntPtr representation` is
+  definition is `for all` (x :: UIntPtr) . x = x end
+  example `explicit value` is x = 4294967295 expect x = 4294967295 end
+end
+
+law `BigInt representation` is
+  definition is `for all` (x :: BigInt) . x = x end
+  example `explicit value` is x = -1234567890123456789012345678901234567890 expect x = -1234567890123456789012345678901234567890 end
+end
+
+law `BigUInt representation` is
+  definition is `for all` (x :: BigUInt) . x = x end
+  example `explicit value` is x = 1234567890123456789012345678901234567890 expect x = 1234567890123456789012345678901234567890 end
+end
+
+law `Decimal representation` is
+  definition is `for all` (x :: Decimal) . x = x end
+  example `explicit value` is x = 0.000000000000000000000000000000000001 expect x = 0.000000000000000000000000000000000001 end
+end
+
+law `Rational representation` is
+  definition is `for all` (x :: Rational) . x = x end
+  example `explicit value` is x = rational(-7, 11) expect x = rational(-7, 11) end
+end
+
+law `Float32 representation` is
+  definition is `for all` (x :: Float32) . prelude.isNaN x = prelude.isNaN x end
+  example `explicit value` is x = float32Bits("80000000") expect x = float32Bits("80000000") end
+end
+
+law `Float64 representation` is
+  definition is `for all` (x :: Float64) . prelude.isNaN x = prelude.isNaN x end
+  example `explicit value` is x = float64Bits("7ff0000000000000") expect x = float64Bits("7ff0000000000000") end
+end
+
+law `Complex64 representation` is
+  definition is `for all` (x :: Complex64) . prelude.isNaN (prelude.real x) = prelude.isNaN (prelude.real x) end
+  example `explicit value` is x = complex64(1, -2) expect x = complex64(1, -2) end
+end
+
+law `Complex128 representation` is
+  definition is `for all` (x :: Complex128) . prelude.isNaN (prelude.real x) = prelude.isNaN (prelude.real x) end
+  example `explicit value` is x = complex128(0.5, -3.5) expect x = complex128(0.5, -3.5) end
+end
+
+law `Char representation` is
+  definition is `for all` (x :: Char) . x = x end
+  example `explicit value` is x = char(128512) expect x = char(128512) end
+end
+
+law `CodePoint representation` is
+  definition is `for all` (x :: CodePoint) . x = x end
+  example `explicit value` is x = codePoint(55296) expect x = codePoint(55296) end
+end
+
+law `CodeUnit16 representation` is
+  definition is `for all` (x :: CodeUnit16) . x = x end
+  example `explicit value` is x = codeUnit16(65535) expect x = codeUnit16(65535) end
+end
+
+law `Text representation` is
+  definition is `for all` (x :: Text) . x = x end
+  example `explicit value` is x = "λ日本語😀" expect x = "λ日本語😀" end
+end
+
+law `CodePointText representation` is
+  definition is `for all` (x :: CodePointText) . x = x end
+  example `explicit value` is x = codePoints([55296, 1114111]) expect x = codePoints([55296, 1114111]) end
+end
+
+law `Utf16Text representation` is
+  definition is `for all` (x :: Utf16Text) . x = x end
+  example `explicit value` is x = utf16([55296, 0, 65535]) expect x = utf16([55296, 0, 65535]) end
+end
+
+law `Bytes representation` is
+  definition is `for all` (x :: Bytes) . x = x end
+  example `explicit value` is x = bytes([0, 128, 255]) expect x = bytes([0, 128, 255]) end
+end
+
+law `Symbol representation` is
+  definition is `for all` (x :: Symbol) . x = x end
+  example `explicit value` is x = symbol("catalog", "same") expect x = symbol("catalog", "same") end
+end
+
+law `Unit representation` is
+  definition is `for all` (x :: Unit) . x = x end
+  example `explicit value` is x = unitValue expect x = unitValue end
+end
+
+law `Null representation` is
+  definition is `for all` (x :: Null) . x = x end
+  example `explicit value` is x = null expect x = null end
+end
+
+law `Undefined representation` is
+  definition is `for all` (x :: Undefined) . x = x end
+  example `explicit value` is x = undefined expect x = undefined end
+end
+
+law `Nullable Int8 representation` is
+  definition is `for all` (x :: Nullable Int8) . x = x end
+  example `explicit value` is x = nullable(127) expect x = nullable(127) end
+end
+
+law `Optional Int8 representation` is
+  definition is `for all` (x :: Optional Int8) . x = x end
+  example `explicit value` is x = undefined expect x = undefined end
+end

package/examples/specs/scalars.lawspec

@@ -0,0 +1,138 @@
+unit example.scalars
+
+law `integer promotion` is
+  definition is `for all` (x :: Int8) . x + 1 = 1 + x end
+  example `overflow is preserved` is
+    x = 127
+    expect x + 1 = 128
+  end
+end
+
+law `unsigned precision` is
+  definition is `for all` (x :: UInt64) . x + 0 = x end
+  example `maximum` is
+    x = 18446744073709551615
+    expect x + 1 = 18446744073709551616
+  end
+end
+
+law `decimal exactness` is
+  definition is `for all` (x :: Decimal) . x + 0.1 = 0.1 + x end
+  example `tenths` is
+    x = 0.1
+    expect x + 0.2 = 0.3
+  end
+end
+
+law `exact division` is
+  definition is `for all` (x :: Int16) . x / 2 = x / 2 end
+  example `one half` is
+    x = 1
+    expect x / 2 = rational(1, 2)
+    expect prelude.quot -7 3 = -2
+    expect prelude.rem -7 3 = -1
+    expect prelude.round rational(125, 100) 1 = 1.2
+  end
+end
+
+law `IEEE classification` is
+  definition is `for all` (x :: Float32) . prelude.isNaN x = prelude.isNaN x end
+  example `NaN` is
+    x = float32Bits("7fc00000")
+    expect prelude.isNaN x = true
+  end
+  example `negative zero` is
+    x = float32Bits("80000000")
+    expect prelude.isNegativeZero x = true
+    expect x = (0 :: Float32)
+  end
+  example `infinity` is
+    x = float32Bits("7f800000")
+    expect prelude.isInfinite x = true
+    expect prelude.Float32 0.1 = (0.1 :: Float32)
+  end
+end
+
+law `complex arithmetic` is
+  definition is `for all` (x :: Unit) . complex64(1, 2) * complex64(3, 4) = complex64(-5, 10) end
+  example `product` is
+    x = unitValue
+    expect complex64(1, 2) * complex64(3, 4) = complex64(-5, 10)
+  end
+end
+
+law `raw units survive` is
+  definition is `for all` (x :: Utf16Text) . x = x end
+  example `unpaired surrogate` is
+    x = utf16([55296, 0, 56320])
+    expect x = utf16([55296, 0, 56320])
+  end
+end
+
+law `arbitrary bytes` is
+  definition is `for all` (x :: Bytes) . x = x end
+  example `octets` is
+    x = bytes([0, 128, 255])
+    expect x = bytes([0, 128, 255])
+  end
+end
+
+law `symbol fixture identity` is
+  definition is `for all` (x :: Symbol) . x = x end
+  example `same reference` is
+    x = symbol("first", "description")
+    expect x = symbol("first", "description")
+  end
+end
+
+law `nested absence` is
+  definition is `for all` (x :: Optional (Nullable Int8)) . x = x end
+  example `undefined` is
+    x = undefined
+    expect x = undefined
+  end
+  example `present null` is
+    x = optional(null)
+    expect x = optional(null)
+  end
+  example `present integer` is
+    x = optional(nullable(7))
+    expect x = optional(nullable(7))
+  end
+end
+
+law `supplementary scalar` is
+  definition is `for all` (x :: Char) . x = x end
+  example `emoji` is
+    x = char(128512)
+    expect x = char(128512)
+  end
+end
+
+law `surrogate code point` is
+  definition is `for all` (x :: CodePointText) . x = x end
+  example `surrogate` is
+    x = codePoints([55296, 128512])
+    expect x = codePoints([55296, 128512])
+  end
+end
+
+law `explicit float rounding` is
+  definition is `for all` (x :: Unit) . x = x end
+  example `IEEE halfway cases` is
+    x = unitValue
+    expect prelude.Complex128 complex64(1, 2) = complex128(1, 2)
+    expect prelude.Complex64 complex128(1.25, -2.5) = complex64(1.25, -2.5)
+    expect prelude.Float32 rational(16777217, 16777216) = float32Bits("3f800000")
+    expect prelude.Float32 rational(1208925891672223212634113, 1208925819614629174706176) = float32Bits("3f800001")
+    expect prelude.Float64 rational(9007199254740993, 9007199254740992) = float64Bits("3ff0000000000000")
+    expect prelude.Float64 rational(1606938044258990453947923680586147734807949174969684883144705, 1606938044258990275541962092341162602522202993782792835301376) = float64Bits("3ff0000000000001")
+    expect prelude.Float32 rational(1, 1427247692705959881058285969449495136382746624) = float32Bits("00000000")
+    expect prelude.Float32 rational(1125899906842625, 1606938044258990275541962092341162602522202993782792835301376) = float32Bits("00000001")
+  end
+end
+
+law `short circuit exact failures` is
+  definition is `for all` (x :: Unit) . false implies 1 / 0 = rational(1, 2) end
+  example `guard prevents division` is x = unitValue expect x = unitValue end
+end

package/examples-command.mjs

@@ -21,7 +21,7 @@ export async function generateExamples(options) {
   const compiler = await createCompiler();
   const artifacts = [];
   for (const target of selected) {
-    const result = await compiler.planGeneration({ sources, target });
+    const result = await compiler.planGeneration({ sources, target, machineBits: options.machineBits ?? 64 });
     if (result.diagnostics.length)
       throw Object.assign(new Error("Bundled examples failed to compile"), {
         diagnostics: result.diagnostics,

package/index.d.ts

@@ -3,17 +3,27 @@ export type Target = 'java' | 'python' | 'javascript' | 'typescript' | 'go' | 'h
 export interface Source { path: string; content: string }
 export interface Location { file: string; line: number; column: number }
 export interface Diagnostic { code: string; message: string; at: Location | null }
-export interface Artifact { path: string; content: string; ownership: 'user' | 'generated' }
-export type Type = {tag: 'Named' | 'Variable'; contents: string} | {tag: 'Arrow'; contents: [Type, Type]};
-export type Expr = {tag: 'Var' | 'StringLit'; contents: string} | {tag: 'Number'; contents: number} | {tag: 'BoolLit'; contents: boolean} | {tag: 'Apply' | 'Compose'; contents: [Expr, Expr]};
+export interface Artifact { path: string; content: string; ownership: 'user' | 'generated'; placement: 'source' | 'test' }
+export type Type = {tag: 'Named' | 'Variable'; contents: string} | {tag: 'Arrow'; contents: [Type, Type]} | {tag: 'Applied'; contents: ['Nullable' | 'Optional', Type]} | {tag:'Refined'; contents:[string, Type, Expr | null]} | {tag:'Qualified'; contents:[Constraint[],Type]} | {tag:'CheckedType'; contents:[Expr[],Type]} | {tag:'RefinementApp'; contents:[string,RefinementArgument[]]};
+export interface Constraint {tag:'Capability'; contents:['Eq'|'Integer'|'Ordered'|'Bounded',Type]}
+export type RefinementArgument = {tag:'TypeArgument'; contents:Type} | {tag:'ValueArgument'; contents:Expr};
+export interface Refinement {refinementName:string; refinementParameters:[string,Type][]; refinementRequirements:Constraint[]; refinementBody:Type}
+export interface Contract {contractName:string; contractArguments:[string,Type][]; contractResult:[string,Type]; contractPreconditions:Expr[]; contractPostconditions:Expr[]}
+export interface Generation {cases:number; maxAttempts:number; maxShrinks:number; exhaustiveLimit:number}
+export interface Input {inputName:string; inputId:string; inputType:Type; inputRefinements:Expr[]}
+export interface DomainPlan {domainInput:Input; domainBounds:[string,Expr][]}
+export type IntegerType = 'Int8' | 'Int16' | 'Int32' | 'Int64' | 'UInt8' | 'UInt16' | 'UInt32' | 'UInt64' | 'IntSize' | 'UIntSize' | 'UIntPtr' | 'Integer' | 'BigInt' | 'BigUInt';
+export type ScalarValue = {type: IntegerType; value: string} | {type: 'Bool'; value: boolean} | {type: 'Decimal'; coefficient: string; exponent: string} | {type: 'Rational'; numerator: string; denominator: string} | {type: 'Float32' | 'Float64'; bits: string} | {type: 'Complex64' | 'Complex128'; real: ScalarValue; imaginary: ScalarValue} | {type: 'Char' | 'CodePoint' | 'CodeUnit16'; value: number} | {type: 'Text' | 'CodePointText' | 'Utf16Text' | 'Bytes'; units: number[]} | {type: 'Symbol'; id: string; description: string} | {type: 'Unit' | 'Null' | 'Undefined'} | {type: 'Nullable' | 'Optional'; value: ScalarValue | null};
+export type Expr = {tag: 'Var' | 'StringLit'; contents: string} | {tag: 'Number'; contents: string} | {tag: 'DecimalNumber'; contents: [string, string]} | {tag: 'BoolLit'; contents: boolean} | {tag: 'Apply' | 'Compose'; contents: [Expr, Expr]} | {tag: 'ScalarLit'; contents: ScalarValue} | {tag: 'Annotate'; contents: [Expr, Type]} | {tag: 'Unary'; contents: [string, Expr]} | {tag: 'Binary'; contents: [string, Expr, Expr]} | {tag:'TypeBound'; contents:['min'|'max',Type]};
 export type Definition = {tag: 'Forall'; contents: [[string, Type][], Definition]} | {tag: 'Equal'; contents: [Expr, Expr]} | {tag: 'Holds'; contents: Expr} | {tag: 'Implies'; contents: [Expr, Definition]} | {tag: 'And'; contents: [Definition, Definition]} | {tag: 'Invoke'; contents: [string, Expr[]]};
-export interface Expectation { actual: Expr; expected: number | string | boolean }
-export interface Example { exampleName: string; bindings: [string, number | string | boolean][]; expectations: Expectation[] }
-export interface Law { lawName: string; parameters: [string, Type][]; requirements: Type[]; definition: Definition; description: string; rationale: string; examples: Example[]; references: string[]; location: Location }
+export interface Expectation { actual: Expr; expected: ScalarValue }
+export interface Example { exampleName: string; bindings: [string, ScalarValue][]; expectations: Expectation[] }
+export interface Law { lawName: string; parameters: [string, Type][]; requirements: Constraint[]; definition: Definition; description: string; rationale: string; examples: Example[]; references: string[]; location: Location }
 export type Assertion = {tag: 'AssertEqual'; contents: [Expr, Expr]} | {tag: 'AssertImplies'; contents: [Expr, Assertion]} | {tag: 'AssertAll'; contents: Assertion[]};
-export interface Expanded { owner: string; name: string; inputs: {inputName: string; inputId: string; inputType: Type}[]; left: Expr; right: Expr; guards: Expr[]; assertion: Assertion; trace: string[]; original: Law }
-export interface CheckRequest { sources: Source[] }
+export interface Expanded { owner: string; name: string; inputs: Input[]; left: Expr; right: Expr; guards: Expr[]; assertion: Assertion; trace: string[]; original: Law; typedExpressions: TypedExpr[]; propertyKind: 'law'|'contract'; generation:Generation; generationPlan:DomainPlan[] }
+export interface TypedExpr { expressionType: Type; expression: Expr; operands: TypedExpr[]; requiredConversion: Type | null }
+export interface CheckRequest { sources: Source[]; schemaVersion?: 2; machineBits?: 32 | 64; generation?:Partial<Generation> }
 export interface GenerationRequest extends CheckRequest { target: Target; sourceDir?: string; testDir?: string }
-export interface Result { diagnostics: Diagnostic[]; laws?: Expanded[]; expansions?: string[]; files?: Artifact[] }
+export interface Result { schemaVersion: 2; machineBits?: 32 | 64; generation?:Generation; refinements?:{owner:string; declaration:Refinement}[]; contracts?:{owner:string; contract:Contract}[]; diagnostics: Diagnostic[]; laws?: Expanded[]; expansions?: string[]; files?: Artifact[] }
 export interface Compiler { check(input: CheckRequest): Promise<Result>; expand(input: CheckRequest): Promise<Result>; planGeneration(input: GenerationRequest): Promise<Result> }
 export function createCompiler(): Promise<Compiler>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lawspec",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "State the law once. Check it everywhere.",
   "license": "MIT",
   "type": "module",
@@ -8,6 +8,6 @@
   "bin": { "lawspec": "bin/lawspec.mjs" },
   "exports": { ".": { "types": "./index.d.ts", "import": "./api.mjs" } },
   "types": "index.d.ts",
-  "files": ["*.mjs", "*.json", "index.d.ts", "bin", "core.wasm", "core_jsffi.js", "README.md", "LICENSE", "starter.lawspec", "examples"],
+  "files": ["*.mjs", "*.json", "index.d.ts", "bin", "core.wasm", "core_jsffi.js", "README.md", "PRIMITIVES.md", "REFINEMENTS.md", "API-MIGRATION.md", "LICENSE", "starter.lawspec", "examples"],
   "scripts": { "test": "node --test test/*.test.mjs" }
 }

package/scalars.mjs

@@ -0,0 +1,13 @@
+// Human-readable, lossless API v2 scalar display.
+export function showScalar(v) {
+  if (!v || typeof v !== 'object') throw new TypeError('Expected an API v2 scalar');
+  if ('coefficient' in v) return `${v.coefficient}e${v.exponent}`;
+  if ('numerator' in v) return `rational(${v.numerator}, ${v.denominator})`;
+  if ('bits' in v) return `${v.type === 'Float32' ? 'float32Bits' : 'float64Bits'}(${JSON.stringify(v.bits)})`;
+  if ('real' in v) return `${v.type}(${showScalar(v.real)}, ${showScalar(v.imaginary)})`;
+  if ('units' in v) return v.type === 'Text' ? JSON.stringify(v.units.map(c => String.fromCodePoint(c)).join('')) : `${v.type}([${v.units.join(', ')}])`;
+  if (v.type === 'Symbol') return `symbol(${JSON.stringify(v.id)}, ${JSON.stringify(v.description)})`;
+  if (v.type === 'Optional' || v.type === 'Nullable') return v.value === null ? (v.type === 'Optional' ? 'undefined' : 'null') : `${v.type.toLowerCase()}(${showScalar(v.value)})`;
+  if ('value' in v) return String(v.value);
+  return {Unit:'unitValue', Null:'null', Undefined:'undefined'}[v.type] ?? v.type;
+}

package/templates.mjs

@@ -100,7 +100,7 @@ export function templates(target) {
     case "haskell":
       return {
         "stack.yaml": "snapshot: lts-24.58\npackages: [.]\n",
-        "package.yaml": `name: lawspec-example\nversion: 0.1.0\ndependencies: [base, text]\nlibrary:\n  source-dirs: src\ntests:\n  laws:\n    main: Spec.hs\n    source-dirs: test\n    dependencies: [lawspec-example, hspec, hedgehog, hspec-hedgehog]\n    build-tools: [hspec-discover]\n`,
+        "package.yaml": `name: lawspec-example\nversion: 0.1.0\ndependencies: [base, text, bytestring]\nlibrary:\n  source-dirs: src\ntests:\n  laws:\n    main: Spec.hs\n    source-dirs: test\n    dependencies: [lawspec-example, hspec, hedgehog, hspec-hedgehog]\n    build-tools: [hspec-discover]\n`,
         "test/Spec.hs": "{-# OPTIONS_GHC -F -pgmF hspec-discover #-}\n",
       };
     case "kotlin":