lawspec 0.7.0 → 0.9.0

package/RUST.md

@@ -0,0 +1,211 @@
+# Rust backend
+
+Rust is the first backend built on LawSpec's typed core and testing plan. The
+compiler remains implemented in Haskell. Rust generation does not parse source
+expressions, infer their types, or expand refinement declarations.
+
+## Project setup
+
+Use Rust 1.85 or later, edition 2024, and Cargo. The generated project pins
+Proptest 1.11.0, num-bigint 0.4.8, num-rational 0.4.2, num-complex 0.4.6, and
+num-traits 0.2.19.
+
+```sh
+lawspec init --target rust
+lawspec doctor
+lawspec generate
+cargo test
+cargo test --release
+```
+
+Adapters are user-owned files under `src/`. LawSpec maintains
+`lawspec_runtime.rs`, module declarations in `lawspec_modules.rs`, and tests
+under `tests/`. The scaffolded `src/lib.rs` includes the generated declarations;
+an existing library can include those declarations explicitly. Generation
+preserves edited adapters and reports required signature updates.
+
+The numeric runtime has no Proptest dependency. Framework support lives in a
+separate generated file, `tests/support/lawspec_strategies.rs`.
+
+## Total definitions (0.9)
+
+Unit-level definitions supply executable implementations alongside laws:
+
+```lawspec
+unit example.total
+
+definition size (xs :: List Int8) :: BigInt is
+  match xs with
+    | Nil -> 0
+    | Cons head tail -> 1 + size tail
+  end
+end
+```
+
+The compiler checks types, exhaustive matching, structural termination, and
+potentially failing operations before emission. Definitions may call other
+checked definitions, including forward references; they cannot call adapters.
+Generic definitions specialize to concrete uses. Refinement predicates may call
+checked definitions. Refined definition signatures become checked native contracts.
+
+Rust emits their implementations into the generated source file
+`lawspec_definitions.rs`. They are not user-owned adapter stubs. Typed native
+entry points are grouped by unit, for example:
+
+```rust
+let mut context = lawspec_runtime::Context::default();
+let count = lawspec_definitions::example_total::size(&mut context, vec![1, 2, 3])?;
+```
+
+These entry points return `lawspec_runtime::Result<T>` and check native values
+at the boundary. Share the context when Symbol fixture identities must match.
+Native machine-sized bindings check the architecture, including fields in
+unselected data variants. The implementation has no Proptest dependency and can
+be used by the application library. Generated properties invoke the same checked
+implementation; remaining external declarations still receive adapter stubs.
+
+`tools/rust-definitions-integration.mjs` verifies both machine profiles, custom
+source/test roots, native calls, readable and compact source, exact `rustfmt`
+layout, incorrect adapters, and regeneration ownership.
+
+## Formatting (0.9)
+
+Rust source uses four-space indentation and structured line wrapping. Request
+compact layout explicitly with `lawspec generate --minify`, or `minify: true`
+in the compiler API. The mode is not saved in project configuration. Formatting
+switches preserve user-owned adapters and their canonical interface references.
+
+`tools/rust-formatting-integration.mjs` compares all Rust artifacts generated
+from the bundled examples and the total-definition fixture against rustfmt,
+under both machine profiles. Formatting is implemented in the compiler; generated
+projects do not need rustfmt to run. The bundled WASM uses the same layout.
+
+## Owned adapter values
+
+Arguments and results are owned Rust values. LawSpec does not add borrowing,
+lifetimes, or pointer operations to its language. Tests clone values where an
+expression needs to use an input more than once.
+
+| LawSpec domain | Rust adapter representation |
+| --- | --- |
+| `Bool` | `bool` |
+| Fixed signed/unsigned integers | `i8`…`i64`, `u8`…`u64` |
+| `IntSize`, `UIntSize`, `UIntPtr` | `isize`, `usize`, `usize` |
+| `BigInt`, `BigUInt` | `BigInt`, `BigUint` |
+| `Integer` input | `BigInt` |
+| `Integer` result | `Integer`, with lossless `From` implementations |
+| `Decimal`, `Rational` | Generated `Decimal`, `BigRational` |
+| `Float32`, `Float64` | `f32`, `f64` |
+| `Complex64`, `Complex128` | `Complex32`, `Complex64` from num-complex |
+| `Char`, `Text` | `char`, `String` |
+| `CodePoint`, `CodePointText` | Generated checked wrappers |
+| `CodeUnit16`, `Utf16Text`, `Bytes` | `u16`, generated UTF-16 wrapper, `Vec<u8>` |
+| `Symbol` | Generated identity type; cloning preserves identity |
+| `Unit`, `Null`, `Undefined` | `()`, distinct generated absence types |
+| `Nullable a`, `Optional a` | Distinct generated enums, including nested presence |
+| `List a` | `Vec<A>` |
+| `Maybe a` | `Option<A>` |
+| `Either a b` | Generated `Either<A, B>` |
+| User-defined products and sums | Named generic enums in `lawspec_data` |
+
+Names such as `Integer` and `Decimal` above are exported by the generated
+`lawspec_runtime` module. Machine-sized native bindings check the requested
+`machineBits` against the executing architecture.
+
+For a declaration such as `successor :: Int8 -> Integer`, an implementation can
+return a wider native integer through the logical result wrapper:
+
+```rust
+use crate::lawspec_runtime as ls;
+
+pub fn successor(value: i8) -> ls::Integer {
+    (i16::from(value) + 1).into()
+}
+```
+
+Exact arithmetic in laws uses arbitrary precision. Passing its result to an
+`i8` adapter parameter performs a checked conversion. A fractional or
+out-of-range value fails with the adapter's context.
+
+`Decimal` stores an arbitrary integer coefficient and exponent. Decimal
+arithmetic is exact; explicit rounding uses the requested scale and ties to
+even. Exact-to-float conversion rounds directly to the requested IEEE precision,
+including subnormal and halfway cases.
+
+## Native data declarations
+
+User-defined data emits reusable `lawspec_data.rs` and `lawspec_schema.rs` in the
+source directory. Adapters receive native enum values with named, typed fields.
+A product uses an enum with one record variant. Parameterized fields retain
+Rust generic types; recursive fields use `Box` where an inline cycle requires
+indirection, while `Vec` already supplies it. Mutually recursive declarations
+are resolved together. When two units use the same type name, generated names
+are qualified by their unit identities.
+
+The runtime's `FromValue` and `IntoValue` traits provide conversion bridges.
+Generated calls validate the complete logical value before conversion and the
+native result before checking postconditions. This preserves raw UTF-16 units,
+bytes, nested presence, and primitive range checks inside custom fields.
+Machine-width checks also apply to machine integers inside custom data.
+
+Generated enums derive `Clone` and `Debug`. LawSpec equality remains a runtime
+operation: it compares fields structurally, retains IEEE NaN and signed-zero
+rules, and compares Symbols by identity. It does not replace these rules with a
+derived Rust `Eq` implementation.
+
+Unused or exclusively recursive type parameters use a `PhantomData` marker.
+Types with no constructors remain uninhabited; they do not acquire a synthetic
+variant. Generated schemas and conversion support have no Proptest dependency.
+The test support composes native Proptest strategies for recursive values and
+shrinking, with deterministic boundary cases and finite-domain enumeration.
+The structural budget counts each scalar, container, and constructor as one
+node. Generation reserves every product field's minimum before distributing
+remaining nodes. List length and element budgets vary together, so a deep
+singleton remains reachable and lists have no hidden four-element limit.
+Native shrinking preserves the schema and the structural budget.
+
+## Refinements and generation
+
+Small finite domains are enumerated. Larger domains use native Proptest
+strategies. Integer bounds over earlier inputs become dependent strategies;
+when a prefix has no possible continuation, generation retries the prefix.
+Shrinking recomputes those dependent bounds and retains only valid tuples.
+Refinement evaluation errors fail the test rather than being counted as rejected
+samples. Generation limits prevent an empty or unreachable domain from passing
+vacuously.
+
+Contracts check preconditions, evaluate the adapter once, validate its native
+result, and then check postconditions on that result.
+
+## Custom layouts
+
+`sourceDir` and `testDir` move generated sources and imports together. Set Cargo's
+`[lib] path` to the library entry point under the selected source directory. For
+test directories other than `tests`, register generated test files using Cargo
+`[[test]]` entries. Doctor checks the selected Cargo package, edition, resolved
+dependencies, library directory, and custom test registration.
+
+Internal typed Core definitions with attached contracts are proved before Rust
+emission. Generated source checks preconditions after argument validation and
+postconditions after result validation, without property-framework dependencies.
+Checks sequence through Result, preserving ordered predicates and contextual
+failures. Native wrappers share logical enforcement. Readable contract bodies
+match rustfmt exactly.
+The shared native fixture passes both machine profiles and formatting modes,
+including exact division, narrowing, nested calls, direct logical entry checks,
+and rejection of corrupted results. Refined source definition signatures now
+produce these contracts through template proof and specialization.
+
+## Constructor field contracts
+
+Rust checks constructor predicates at logical definition and native adapter
+boundaries. Generated proptest strategies validate complete candidates, retain
+native shrinking, and share each case's Symbol context with witness literals and
+assertions. Only false predicates trigger retries; evaluation errors fail the
+property. `maxAttempts` bounds local and global rejection, and exhaustion does
+not prove an empty domain.
+
+Validated witnesses seed nested payloads. Builtin lists and presence/sum
+containers retain native structural shrinking; sampled named witnesses can
+still produce larger counterexamples than native branches. Recursive named
+refined payloads remain outside the currently supported contract fragment.

package/WEB.md

@@ -0,0 +1,144 @@
+# JavaScript and TypeScript backends
+
+LawSpec emits ES modules. JavaScript uses `.mjs`; TypeScript uses `.ts` with `.js`
+import paths for NodeNext compilation. Generated data and numeric support belong
+in source directories and do not depend on fast-check. Generated properties use
+fast-check's native generators and shrinkers.
+
+## Native structural values
+
+`List a` uses `Array<A>`. `Maybe a` and `Either a b` use named classes and, in
+TypeScript, generic unions from `lawspec_data`. User products and sums likewise
+have named native variant classes. TypeScript retains payload types and nominal
+variant identity, including recursive fields and phantom parameters.
+
+`Nullable a` and `Optional a` use tagged `data.Presence<A>` values, preserving
+nested states separately from algebraic `Maybe`. Runtime checks enforce the
+presence kind and payload domain. Scalar and structural presence values both use
+the schema bridge when crossing native adapter boundaries.
+
+Checked conversions copy containers, reject sparse arrays and invalid fields,
+validate numeric ranges and machine profiles, and preserve raw text and bytes.
+LawSpec equality follows the schema: NaN differs from itself, signed zeros compare
+equal, and Symbols compare by identity. Ordinary JavaScript object equality is
+not a replacement for structural LawSpec equality.
+
+## Total definitions
+
+Checked definitions produce reusable source functions:
+
+```lawspec
+unit example.total
+
+definition increment (x :: Int8) :: BigInt is x + 1 end
+```
+
+```javascript
+import {increment} from './lawspec_definitions/example/total.mjs';
+
+const symbols = new Map();
+const result = increment(symbols, 127); // 128n
+```
+
+The TypeScript entry point has `symbols: Map<string, symbol>`, `value0: number`,
+and a `bigint` result. Native signatures preserve lists, products, sums, and
+nested presence payloads. Runtime validation also rejects invalid number ranges,
+fractional primitive inputs, and malformed values from JavaScript callers.
+Failures identify the resolved definition.
+
+The first argument shares Symbol fixture identity across calls within an example.
+Equal descriptions in separate contexts do not create equal Symbols. Exact
+integers use bigint; exact Decimal and Rational operations use the scalar runtime
+without passing through Number arithmetic.
+
+Public modules live under `lawspec_definitions/`, grouped by unit. Checked logical
+bodies live in `lawspec_definition_bodies`. Both are generated-owned source.
+Properties call the implementations directly; a definition never becomes an
+adapter stub. Ordinary adapters remain user-owned. Support-module collisions and
+bindings that shadow generated global access are rejected before output.
+
+Definitions and properties share typed Core expression rendering. Match inputs
+are evaluated once, only the selected branch runs, and Boolean guards
+short-circuit. Totality validation checks structural descent and potentially
+failing operations. Generic definitions specialize to concrete uses. Refined signatures become
+checked contracts, and refinement predicates may call checked definitions.
+
+## Formatting and verification
+
+Definition output uses two-space blocks, four-space continuations, single-quoted
+strings, and an 80-column layout. String tokens preserve escaped and raw payloads
+in readable and compact modes. Compact mode removes optional document breaks.
+The public `--minify` path covers runtime, declaration, definition, adapter, and
+test artifacts. `tools/web-formatting-integration.mjs` checks the full bundled
+corpus for formatting rules and readable/compact syntax-tree equivalence. It
+records Prettier differences separately: Prettier's continuation layout is not
+the Google four-space continuation rule used here.
+
+`tools/web-definitions-integration.mjs` checks both targets and machine profiles,
+strict TypeScript entry points and rejected assignments, source-only execution,
+recursive properties, incorrect adapters, compact output, custom directories,
+and regeneration protection. The implementation modules pass strict TypeScript
+without `any` or `@ts-nocheck`. Existing schema and numeric runtime TypeScript
+files still use `@ts-nocheck`; their public data declarations and definition
+entry points are checked separately.
+
+## Runtime source formatting
+
+The checked-in JavaScript scalar runtime, schema runtime, and fast-check helpers
+use two-space indentation, single quotes, and an 80-column target, formatted with
+Prettier 3.6.2. `node tools/format-web-runtimes.mjs` checks these sources;
+`--write` formats them. Set `LAWSPEC_PRETTIER` to the formatter's `index.mjs` when
+it is not in `.artifacts/formatter-deps/prettier/`. This development tool never
+runs in generated projects or during compiler requests.
+
+Run `python3 tools/embed-runtimes.py` after runtime edits, then use `--check` to
+verify that native/WASM source embedding is current. Both JavaScript and
+TypeScript receive the reviewed runtime source, with the existing typed-schema
+constructor annotation and module-extension adjustments for TypeScript.
+
+
+Internal checked Core definition contracts now run at native and logical entry
+points. Emission proves the obligations first; argument validation precedes
+ordered preconditions, and result validation precedes postconditions. Contract
+binders map explicitly to body inputs and the checked result. Refined source
+signatures now produce these contracts through template proof and specialization.
+
+`tools/portable-definition-contract-integration.mjs` exercises Python, JavaScript
+and strict TypeScript with both machine profiles and layouts, without property
+frameworks. It also verifies that deliberately corrupted results are rejected.
+The fixture in `test/DefinitionContractFixture.hs` is shared with the JVM checks.
+
+
+## Generated source style checks
+
+JavaScript and TypeScript emitters use two-space blocks and four-space
+continuations. The latter follows the [Google JavaScript line-wrapping guide](https://google.github.io/styleguide/jsguide.html#s4.5-line-wrapping).
+Binary operators remain on the preceding line when an expression wraps.
+Generated adapter error messages and tagged scalar values use the shared
+single-quoted JavaScript literal renderer.
+
+`tools/web-formatting-integration.mjs` independently parses both output modes
+with TypeScript, compares their syntax trees and literal contents, and checks
+quote choice, binary-operator breaks, continuation and statement-block indentation,
+the 80-column limit, tabs, and trailing
+whitespace. Module imports/re-exports and indivisible source excerpts on their
+own comment line are explicit column exceptions. Ordinary prose and code remain
+subject to the limit. Long scalar string values use escaped concatenated chunks;
+property names remain single tokens. It runs
+both machine profiles for the bundled examples and total-definition fixture.
+Set `LAWSPEC_CORE` to the native compiler; optional `LAWSPEC_TYPESCRIPT` and
+`LAWSPEC_PRETTIER` paths select the cached development tools. Prettier must be
+version 3.6.2. Positional arguments select specification files.
+
+Prettier differences are saved for inspection, not treated as an exact Google
+style oracle: its continuation indentation differs from Google's. These checks
+are partial style evidence. Additional indentation cases (such as switch bodies
+and type declarations) and Kotlin formatter acceptance remain tracked in the 0.9 plan; passing this script alone does not
+establish complete style conformance.
+
+The development-only runtime formatter (`tools/format-web-runtimes.mjs`) applies
+Prettier layout and then syntax-tree-directed continuation indentation. It verifies
+that JavaScript tokens remain unchanged, retains relative callback block indentation,
+and rejects adjustments inside multiline template literals. It is idempotent and
+checks the resulting 80-column limit. Reviewed runtime source is embedded at build
+time; generated projects never download or invoke these development tools.

package/api.mjs

@@ -1,6 +1,12 @@
 // Generated from LawSpec.Gen. Do not edit.
-import { loadCore } from './launcher.mjs';
+import {loadCore} from './launcher.mjs';
+
 export async function createCompiler() {
   const call = await loadCore();
-  return { check: (input) => call({ ...input, method: 'check' }), expand: (input) => call({ ...input, method: 'expand' }), planGeneration: (input) => call({ ...input, method: 'planGeneration' }) };
+  return {
+    check: (input) => call({schemaVersion: 3, ...input, method: 'check'}),
+    expand: (input) => call({schemaVersion: 3, ...input, method: 'expand'}),
+    planGeneration: (input) =>
+        call({schemaVersion: 3, ...input, method: 'planGeneration'}),
+  };
 }

package/bin/lawspec.mjs

@@ -23,7 +23,7 @@ for (let i = 0; i < args.length; i++) {
     if (!args[i + 1] || args[i + 1].startsWith("--"))
       throw new Error(`Missing value for ${arg}`);
     options[arg.slice(2)] = args[++i];
-  } else if (["--dry-run", "--check", "--json"].includes(arg))
+  } else if (["--dry-run", "--check", "--json", "--minify"].includes(arg))
     options[arg.slice(2)] = true;
   else if (arg.startsWith("--")) throw new Error(`Unknown option: ${arg}`);
   else positional.push(arg);
@@ -104,6 +104,7 @@ async function init() {
     throw new Error("Target is already configured");
   await mkdir(root, { recursive: true });
   const buildFiles = [
+    "Cargo.toml",
     "pom.xml",
     "pyproject.toml",
     "package.json",
@@ -117,7 +118,7 @@ async function init() {
   const hasBuild = (await readdir(root)).some(
     (f) => buildFiles.includes(f) || f.endsWith(".cabal"),
   );
-  const additions = hasBuild ? {} : templates(language);
+  const additions = hasBuild ? {} : templates(language, {minify: options.minify === true});
   for (const name of Object.keys(additions)) {
     const file = await safePath(root, name);
     if ((await readOptional(file)) !== null)
@@ -146,53 +147,24 @@ async function init() {
   });
   await atomicWrite(
     configFile,
-    JSON.stringify(config, null, 2) + "\n",
+    JSON.stringify(config, null, options.minify ? undefined : 2) + "\n",
     current === null,
   );
   output(
     `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" || 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" ||
-    expr.tag === "BoolLit"
-  )
-    return JSON.stringify(value);
-  if (expr.tag === "Apply")
-    return `${showExpression(value[0])} (${showExpression(value[1])})`;
-  return `(${showExpression(value[0])} . ${showExpression(value[1])})`;
+function showAssertion(assertion) {
+  if (assertion.kind === "equal") return `${assertion.left.text} = ${assertion.right.text}`;
+  if (assertion.kind === "implies") return `${assertion.guard.text} implies ${showAssertion(assertion.body)}`;
+  return assertion.items.map(showAssertion).join(" and ");
 }
 function explainExamples(law) {
-  return law.original.examples
-    .map(
-      (ex) =>
-        `\nexample ${JSON.stringify(ex.exampleName)}\n` +
-        ex.bindings
-          .map(([n, v]) => `  ${n} = ${showScalar(v)}`)
-          .join("\n") +
-        "\n" +
-        ex.expectations
-          .map(
-            (e) =>
-              `  expect ${showExpression(e.actual)} = ${showScalar(e.expected)}`,
-          )
-          .join("\n"),
-    )
-    .join("\n");
+  return law.examples.map(ex =>
+    `\nexample ${JSON.stringify(ex.name)}\n` +
+    ex.bindings.map(b => `  ${b.name} = ${showScalar(b.value)}`).join("\n") + "\n" +
+    ex.expectations.map(e => `  expect ${showAssertion(e)}`).join("\n")
+  ).join("\n");
 }
 async function main() {
   if (options['machine-bits'] !== undefined) {
@@ -201,13 +173,13 @@ async function main() {
   }
   if (!verb || ["help", "--help", "-h"].includes(verb)) {
     output(
-      "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: " +
+      "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: " +
         targets.join(", "),
     );
     return;
   }
   if (verb === "--version") {
-    output("0.7.0");
+    output("0.9.0");
     return;
   }
   if (positional.length > (verb === "explain" ? 1 : 0))
@@ -219,7 +191,7 @@ async function main() {
       options["dry-run"] ||
       options.check
     )
-      throw new Error("examples supports --target, --output and --json only");
+      throw new Error("examples supports --target, --output, --json and --minify only");
     const result = await generateExamples(options);
     output(
       options.json
@@ -235,6 +207,8 @@ async function main() {
     return;
   }
   if (options.output) throw new Error("--output 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();
   if (!["check", "doctor", "explain", "generate"].includes(verb))
     throw new Error(`Unknown command: ${verb}`);
@@ -280,7 +254,7 @@ async function main() {
     output(
       options.json
         ? result
-        : `Checked ${result.laws.length} executable law(s).`,
+        : `Checked ${result.laws.length} law(s).`,
     );
     return;
   }
@@ -291,7 +265,7 @@ async function main() {
       .filter(
         ({ e }) => !positional[0] || `${e.owner}::${e.name}` === positional[0],
       );
-    if (!indices.length) throw new Error("No matching executable law");
+    if (!indices.length) throw new Error("No matching law");
     output(
       options.json
         ? indices.map(({ e, i }) => ({ ...e, expansion: result.expansions[i] }))
@@ -315,11 +289,12 @@ async function main() {
           target: target.language,
           sourceDir: target.sourceDir,
           testDir: target.testDir,
+          minify: options.minify === true,
         }),
       ).files,
     );
   const reports = await Promise.all(
-    selected.map((t, i) => doctor(t, roots[i])),
+    selected.map((t, i) => doctor(t, roots[i], artifacts[i])),
   );
   const failed = reports.filter((r) => !r.ok);
   if (failed.length)