lawspec 0.9.0 → 0.11.0

package/PRIMITIVES.md

@@ -1,4 +1,4 @@
-# LawSpec scalar reference (0.9.0)
+# LawSpec scalar reference (0.11.0)
 
 A scalar has a declared domain, checked literals, equality, property inputs, and
 boundary fixtures. General collections, objects, pointers, and type-only constructs

package/README.md

@@ -2,7 +2,7 @@
 
 **State the law once. Check it everywhere.**
 
-LawSpec 0.9 compiles reusable laws into native property tests, executable examples,
+LawSpec 0.11 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.
 
@@ -36,12 +36,40 @@ Compiler API consumers should read the [schema v3 migration guide](API-MIGRATION
 Scalar values use tagged, lossless encodings; generated runtime placement is
 separate from artifact ownership. Java 25+ and Python 3.13+ baselines are unchanged.
 
+## Native domain bindings in 0.10
+
+LawSpec 0.10 adds configuration for existing application products and sums,
+function bindings, checked conversion hooks, and native property-generator
+factories on all eight targets. Generators retain their framework's shrinkers;
+explicit examples, boundaries, and finite-domain checks remain independent.
+See the [native-binding reference and acceptance status](NATIVE-BINDINGS.md),
+the [release notes](RELEASE-0.10.md), and
+[schema 4 migration notes](API-MIGRATION.md#schema-4-native-bindings).
+Existing specifications without bindings retain their behavior.
+
+## Natural-indexed families in 0.11
+
+LawSpec 0.11 adds data indexed by natural numbers, such as length-indexed
+vectors and size-indexed trees. Each constructor states its index equation;
+the compiler elaborates the family to ordinary native data, a checked measure,
+and a refinement. Dependent signatures like
+`append :: (xs :: Vec n a) -> (ys :: Vec m a) -> (r :: Vec (n + m) a)` become
+checked adapter contracts, and generators construct values with a required
+index instead of filtering for it. See the
+[language reference](LANGUAGE.md#natural-indexed-families), the
+[indexed example](examples/specs/indexed_families.lawspec), and the
+[release notes](RELEASE-0.11.md).
+
 ## Install and try it
 
+LawSpec has its own [syntax-highlighting grammar and VS Code extension](editors/vscode/README.md)
+for keywords, types, refinements, literals, and law names. GitHub needs upstream Linguist
+support to use it; GitHub currently uses the Haskell fallback.
+
 Install [LawSpec from npm](https://www.npmjs.com/package/lawspec):
 
 ```sh
-npm install --save-dev lawspec@0.9.0
+npm install --save-dev lawspec@0.11.0
 npx lawspec --version
 ```
 
@@ -55,8 +83,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.9.0 -- lawspec init --target javascript
-npm install --save-dev lawspec@0.9.0
+npm exec --package=lawspec@0.11.0 -- lawspec init --target javascript
+npm install --save-dev lawspec@0.11.0
 npx lawspec check
 npx lawspec explain 'example.atoi_codec::itoa and then atoi yields a'
 npx lawspec doctor
@@ -192,11 +220,13 @@ Reusable laws can declare typed unary function parameters and `requires Eq a`, n
 [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 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.
+Function signatures and quantified inputs support the [scalar catalog](PRIMITIVES.md)
+and [structural types](LANGUAGE.md), including mixed and multiple inputs.
+Generic variables are supported in reusable laws. Scalar and structural values
+can also be intermediate or compared results. Functions are synchronous and
+support curried signatures with any positive number of arguments. Text literals
+are double-quoted, with escapes such as `\"`, `\\`, `\n`, and `\t`; examples must
+bind each input to a concrete value of its declared type.
 Text values contain Unicode scalar values; surrogate code points are rejected.
 
 Examples refer to the expanded input names, including names inherited from the
@@ -206,9 +236,10 @@ 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.
 
-General collections, external law packages, cross-unit imports beyond the
-prelude, async functions, direct existing-symbol binding and browser hosting are
-outside this release.
+Collections beyond `List`, external law packages, cross-unit imports beyond the
+prelude, async functions and browser hosting remain outside the language.
+Direct existing-symbol bindings are part of LawSpec 0.10 described
+above; the published 0.9 release uses implementation adapters.
 
 ## Algebra and currying (0.6)
 
@@ -263,7 +294,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.9.0/examples/specs/algebra.lawspec), including both sides of every
+[algebra.lawspec](https://github.com/brain-fuel/lawspec/blob/v0.11.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.
 
@@ -331,7 +362,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.9.0/examples/specs/currying.lawspec) demonstrate a four-argument
+[Currying examples](https://github.com/brain-fuel/lawspec/blob/v0.11.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
@@ -383,7 +414,7 @@ law `valid ports round trip` is
 end
 ```
 
-The [complete port example](https://github.com/brain-fuel/lawspec/blob/v0.9.0/examples/specs/parse_port.lawspec)
+The [complete port example](https://github.com/brain-fuel/lawspec/blob/v0.11.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
@@ -401,7 +432,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.9.0/examples/specs/boolean_flags.lawspec)
+The [Boolean flags example](https://github.com/brain-fuel/lawspec/blob/v0.11.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.
@@ -480,7 +511,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.9.0/examples/specs/equivalent.lawspec) compares decimal
+[The complete example](https://github.com/brain-fuel/lawspec/blob/v0.11.0/examples/specs/equivalent.lawspec) compares decimal
 renderers and two implementations that clamp negative integers to zero. For
 JavaScript, their adapters can be:
 
@@ -517,7 +548,7 @@ law `normalizers agree` is
 end
 ```
 
-The [slug example](https://github.com/brain-fuel/lawspec/blob/v0.9.0/examples/specs/slug.lawspec)
+The [slug example](https://github.com/brain-fuel/lawspec/blob/v0.11.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()`,
@@ -544,7 +575,7 @@ law `canonicalization reaches a fixed point` is
 end
 ```
 
-The [canonical URL example](https://github.com/brain-fuel/lawspec/blob/v0.9.0/examples/specs/canonical_url.lawspec)
+The [canonical URL example](https://github.com/brain-fuel/lawspec/blob/v0.11.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:
 
@@ -553,13 +584,31 @@ 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.9.0/examples/specs/mixed_inputs.lawspec)
+The [mixed-input example](https://github.com/brain-fuel/lawspec/blob/v0.11.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 }[]`.
+The JavaScript API represents example bindings as typed records whose values use
+`DataValue`: lossless tagged scalar payloads or structural constructors. Expected results are
+typed expressions inside `Assertion` trees, not untyped JavaScript primitives.
+See the [API migration guide](API-MIGRATION.md) for their wire representation.
 
 ## Generate all example artifacts
 
+To use native domain bindings, export the runnable payment
+example (omit `--target` to export all eight languages):
+
+```sh
+lawspec examples --example payments --target rust --output native_payments
+cd native_payments/rust
+# Install the dependencies listed in README.md, then:
+lawspec check
+lawspec generate
+cargo test
+```
+
+These projects include application-owned types, native generators, binding
+configuration, and build files. Re-exporting preserves edits and leaves the
+compiler's generation manifest separate from the example export manifest.
+
 ```sh
 npx lawspec examples
 # Or select a target and a relative output directory:
@@ -618,7 +667,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.9.0.tgz`.
+`npm pack ./npm` and install it with `npm install --save-dev ./lawspec-0.11.0.tgz`.
 The package payload lives in `npm/`.
 
 ```sh
@@ -657,6 +706,20 @@ unchanged. Arguments select individual targets. `LAWSPEC_PYTHON=3.14` selects th
 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.
 
+The native-binding acceptance command uses the installed npm archive, public CLI,
+and the selected target's normal test command:
+
+```sh
+node tools/native-example-integration.mjs rust
+LAWSPEC_MACHINE_BITS=32 LAWSPEC_MINIFY=1 node tools/native-example-integration.mjs rust
+```
+
+Replace `rust` with any supported target. It exports the payment project, verifies
+correct behavior, rejects an incorrect fee, and checks regeneration. Per-command
+logs live in `.artifacts/native-example-integration/`. See the
+[acceptance reference](NATIVE-BINDINGS.md) for dependency overrides and remaining
+verification gates.
+
 
 Refinement predicates can depend on earlier inputs. Generated tests backtrack from
 impossible prefixes, preserve the domain during shrinking, and validate function

package/REFINEMENTS.md

@@ -1,4 +1,4 @@
-# Refinements and abstract integers (0.9.0)
+# Refinements and abstract integers (0.11.0)
 
 A refinement restricts a scalar domain with a pure Boolean expression. LawSpec
 checks concrete examples, generates satisfying input tuples, and checks adapter
@@ -154,6 +154,11 @@ 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.
 
+A refinement `m x == e` over declared data, where `m` is a linear structural
+measure (each branch is a constant plus `m` of that branch's fields), is solved
+rather than sampled: values are constructed with measure exactly `e`. Indexed
+families rely on this; see [natural-indexed families](LANGUAGE.md#natural-indexed-families).
+
 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.

package/RELEASE-0.10.md

@@ -0,0 +1,60 @@
+# LawSpec 0.10.0
+
+## Existing application models
+
+Native bindings connect LawSpec products and sums to existing application types
+on Java, Python, JavaScript, TypeScript, Go, Haskell, Kotlin and Rust. Configure
+constructor and field mappings, bind adapter declarations to existing functions,
+or supply paired conversion hooks for representations requiring custom code.
+Bindings resolve against typed declaration identities; they do not change the
+meaning of arithmetic, equality, definitions or refinements.
+
+Checked bridges compose through generic and recursive types and the built-in
+containers. They preserve exact numeric values, Symbol identity and distinct
+absence states. Invalid native inputs, results, generator samples and shrink
+candidates fail with context.
+
+## Native generators
+
+Factories return their framework's generator: JetCheck, Hypothesis, fast-check,
+Rapid, Hedgehog, Kotest or Proptest. Generic factories receive child generators.
+Composition retains native shrinking. Explicit examples, deterministic boundaries
+and finite-domain enumeration still run when the factory's distribution excludes
+those values.
+
+A factory can ignore an uninhabited parameter, as in `Phantom Empty`. Requesting a
+value from that parameter fails generation; it cannot turn a property into a
+vacuous success. Finite inhabited containers such as `List Empty` still enumerate.
+
+Optional `stub: true` generator bindings create user-owned implementation files.
+Regeneration preserves edits and reports changed factory signatures for review.
+
+## API and migration
+
+Native binding requests negotiate schema 4. Schema 3 remains supported for
+specifications without bindings. Structured native references and strict
+configuration validation prevent older compilers from silently ignoring mappings.
+Go additionally supports explicit import aliases; Rust binds tests to the
+application library's type identities.
+
+Existing adapter files cannot be overwritten by adopting a binding. Move their
+implementations into the application module and save the old adapters before
+generation. Generated source bridges, test helpers and user-owned application
+files retain separate placement and ownership. See the
+[migration guide](API-MIGRATION.md#schema-4-native-bindings) and
+[ownership instructions](NATIVE-BINDINGS.md#ownership-regeneration-and-migration).
+
+## Runnable payment projects
+
+`lawspec examples --example payments` exports a project for every target; use
+`--target rust` or another language to select one. Each project includes an
+application model, native generator, configuration, build files and instructions.
+The shared specification checks exact fees, currency preservation, sum payloads,
+ordered archives, duplicates and absence. Re-exporting preserves application
+edits and the separate compiler generation manifest.
+
+Both 32-bit and 64-bit logical machine profiles and readable/compact output are
+covered by the acceptance matrices. Java 25+, Python 3.13+ and the other published
+toolchain baselines remain unchanged. Python output follows PEP 8.
+
+GADTs, dependent indices and cross-unit packages remain subsequent work.

package/RELEASE-0.11.md

@@ -0,0 +1,62 @@
+# LawSpec 0.11.0
+
+## Natural-indexed families
+
+Data declarations may take `Natural` parameters, and each constructor states
+its index equation:
+
+```lawspec
+type Vec (n :: Natural) (a :: Type) is
+  | VNil where n = 0
+  | VCons head :: a tail :: Vec m a where n = m + 1
+end
+
+append :: (xs :: Vec n Int8) -> (ys :: Vec m Int8) -> (r :: Vec (n + m) Int8)
+```
+
+A family elaborates before inference into ordinary erased data, a checked
+structural measure per index (`nOfVec`), and a refinement relating the measure
+to the index. Core and all eight emitters are unchanged. Native code works with
+the erased type, and every index claim is evidence checked at test time: a
+dependent result such as `Vec (n + m) Int8` is an adapter postcondition.
+
+An index variable that is otherwise unbound is implicit. The first binder whose
+family type mentions it determines it, and later occurrences read that binder's
+measure. Index expressions are sums of natural literals and index variables.
+`Natural` is also available as a value type. Diagnostics use the `indexed` code.
+
+## Index-directed generation
+
+A quantifier constrained by a linear structural measure, including a fixed index
+(`Vec 3 Int8`) or a shared one (`zip`'s second argument), is generated by solving
+the constructor equations backwards instead of filtering. Multi-field equations
+such as `Bin … where n = l + r + 1` split the remaining index across fields.
+Python, JavaScript, TypeScript, Java, Kotlin, Go, Haskell and Rust construct these
+values natively, and framework shrinking stays within the index. The same
+planning applies to user-written linear measures over declared data.
+
+`examples/specs/indexed_families.lawspec` runs on all eight targets through
+`tools/indexed-integration.mjs`. Correct adapters pass free, fixed and shared
+index laws; mutants that add, drop or lose elements fail their dependent
+contracts.
+
+## Tower-polymorphic Integer results restored
+
+0.9 had narrowed Kotlin and Haskell adapters whose result is the abstract
+`Integer` to `BigInteger` and `Integer`. They again return `Number` (Kotlin) and
+`LS.IntegerValue` (Haskell), as in 0.8 and as Java always did. `Integer` is the top
+of the integral tower: an implementation may return any integral native value,
+and the result bridge rejects non-integral values and checks the logical domain.
+Adapters written against 0.9 or 0.10 stubs that return `BigInteger` or `Integer`
+still compile, because both are integral.
+
+This regression had kept the Kotlin and Haskell CI target jobs failing since
+0.9. Those jobs, and the scalar mutation fixtures, now pass with the documented
+typed Symbol, Decimal, Utf16Text and Optional representations.
+
+## Compatibility
+
+Specifications without indexed families generate the same code as 0.10, apart
+from the Integer result signatures above. API schemas 3 and 4 are unchanged.
+GADTs that refine type arguments, non-linear indices and index equalities between
+sibling fields remain future work.

package/api.mjs

@@ -4,9 +4,29 @@ import {loadCore} from './launcher.mjs';
 export async function createCompiler() {
   const call = await loadCore();
   return {
-    check: (input) => call({schemaVersion: 3, ...input, method: 'check'}),
-    expand: (input) => call({schemaVersion: 3, ...input, method: 'expand'}),
+    check: (input) =>
+        call(
+            {
+              schemaVersion: input.nativeBindings === undefined ? 3 : 4,
+              ...input,
+              method: 'check',
+            }
+        ),
+    expand: (input) =>
+        call(
+            {
+              schemaVersion: input.nativeBindings === undefined ? 3 : 4,
+              ...input,
+              method: 'expand',
+            }
+        ),
     planGeneration: (input) =>
-        call({schemaVersion: 3, ...input, method: 'planGeneration'}),
+        call(
+            {
+              schemaVersion: input.nativeBindings === undefined ? 3 : 4,
+              ...input,
+              method: 'planGeneration',
+            }
+        ),
   };
 }

package/bin/lawspec.mjs

@@ -19,7 +19,7 @@ const options = {};
 const positional = [];
 for (let i = 0; i < args.length; i++) {
   const arg = args[i];
-  if (["--target", "--project", "--config", "--output", "--machine-bits"].includes(arg)) {
+  if (["--target", "--project", "--config", "--output", "--machine-bits", "--example"].includes(arg)) {
     if (!args[i + 1] || args[i + 1].startsWith("--"))
       throw new Error(`Missing value for ${arg}`);
     options[arg.slice(2)] = args[++i];
@@ -173,13 +173,13 @@ async function main() {
   }
   if (!verb || ["help", "--help", "-h"].includes(verb)) {
     output(
-      "LawSpec 0.9.0\nUsage: lawspec init --target <language> [--project <directory>] [--minify]\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, --minify\nTargets: " +
+      "LawSpec 0.11.0\nUsage: lawspec init --target <language> [--project <directory>] [--minify]\n       lawspec check | doctor | explain <unit>::<law> | generate\n       lawspec examples [--example payments] [--target <language>] [--output <directory>]\nOptions: --config <path>, --target <language>, --machine-bits <32|64>, --json\nGeneration: --dry-run, --check, --minify\nTargets: " +
         targets.join(", "),
     );
     return;
   }
   if (verb === "--version") {
-    output("0.9.0");
+    output("0.11.0");
     return;
   }
   if (positional.length > (verb === "explain" ? 1 : 0))
@@ -191,8 +191,15 @@ async function main() {
       options["dry-run"] ||
       options.check
     )
-      throw new Error("examples supports --target, --output, --json and --minify only");
+      throw new Error("examples supports --example, --target, --output, --machine-bits, --json and --minify only");
     const result = await generateExamples(options);
+    if (options.example) {
+      output(options.json ? result : result.map(r =>
+        `${r.target}: payment project in ${r.directory}; ${r.preservedAdapters.length} user files preserved.` +
+        (r.adapterUpdates.length ? `\nReview changed example files: ${r.adapterUpdates.map(a => a.path).join(", ")}` : "")
+      ).join("\n") + "\nOpen each project's README.md, run lawspec generate, then its native test command.");
+      return;
+    }
     output(
       options.json
         ? result
@@ -207,6 +214,7 @@ async function main() {
     return;
   }
   if (options.output) throw new Error("--output is only supported by examples");
+  if (options.example) throw new Error("--example is only supported by examples");
   if (options.minify && !["init", "generate", "examples"].includes(verb))
     throw new Error("--minify applies to init, generate and examples");
   if (verb === "init") return init();
@@ -251,6 +259,10 @@ async function main() {
   const compiler = await createCompiler();
   if (verb === "check") {
     const result = diagnostics(await compiler.check(input));
+    for (const target of selected) {
+      if (target.nativeBindings !== undefined)
+        diagnostics(await compiler.check({...input, nativeBindings: target.nativeBindings}));
+    }
     output(
       options.json
         ? result
@@ -289,6 +301,7 @@ async function main() {
           target: target.language,
           sourceDir: target.sourceDir,
           testDir: target.testDir,
+          nativeBindings: target.nativeBindings,
           minify: options.minify === true,
         }),
       ).files,