lawspec 0.3.0 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 **State the law once. Check it everywhere.**
 
-LawSpec 0.3 compiles reusable laws into native property tests, executable examples,
+LawSpec 0.4 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.
 
@@ -11,7 +11,7 @@ WebAssembly with a Node CLI and an asynchronous, typed JavaScript API.
 Install [LawSpec from npm](https://www.npmjs.com/package/lawspec):
 
 ```sh
-npm install --save-dev lawspec@0.3.0
+npm install --save-dev lawspec@0.4.0
 npx lawspec --version
 ```
 
@@ -25,8 +25,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.3.0 -- lawspec init --target javascript
-npm install --save-dev lawspec@0.3.0
+npm exec --package=lawspec@0.4.0 -- lawspec init --target javascript
+npm install --save-dev lawspec@0.4.0
 npx lawspec check
 npx lawspec explain 'example.atoi_codec::itoa and then atoi yields a'
 npx lawspec doctor
@@ -52,7 +52,7 @@ properties with the selected framework's shrinking and failure reporting.
 
 | Target | Build setup | Test libraries | Test command |
 | --- | --- | --- | --- |
-| `java` | Maven, JDK 25, release 25 | JetCheck 0.3.0, JUnit Jupiter 5.14.x | `mvn test` |
+| `java` | Maven, JDK 25, release 25 | JetCheck 0.4.0, JUnit Jupiter 5.14.x | `mvn test` |
 | `python` | Python 3.13 or 3.14, pyproject | pytest 8.4.x, Hypothesis 6.135.26+ (6.x) | `python -m pytest` |
 | `javascript` | Node 22+, npm, ESM | fast-check 4.x, node:test | `npm test` |
 | `typescript` | Node 22+, npm, TypeScript 5.9.x, ESM | fast-check 4.x, node:test | `npm test` |
@@ -61,7 +61,7 @@ properties with the selected framework's shrinking and failure reporting.
 | `kotlin` | JDK/JVM 25, Gradle 9.1–9.3, Kotlin 2.3.21 | Kotest 5.9.1 | `gradle test` |
 
 Java 25 and Python 3.13 are the minimum baselines. New JVM releases are admitted
-through compatibility profiles after testing; v0.3's current JVM profile certifies
+through compatibility profiles after testing; v0.4's current JVM profile certifies
 25. Python templates declare `requires-python = ">=3.13"` and runtime checks
 currently recognize 3.13 and 3.14. Kotlin templates pin Gradle's supported build
 configuration to Kotlin 2.3.21 and target JVM 25.
@@ -113,7 +113,7 @@ uses `test/Spec.hs` with `hspec-discover`.
 Commands:
 
 - `check`: parse, resolve, type-check and expand laws without target dependencies.
-- `explain [unit::law]`: display expansion steps and inherited example inputs.
+- `explain [unit::law]`: display expansions, example inputs, and expected results.
 - `doctor`: inspect selected native environments and print corrective instructions.
 - `generate`: check environments, validate every output, then write artifacts.
 - `generate --dry-run`: show proposed file operations without applying them.
@@ -139,8 +139,10 @@ law `round trip` is
   description is
     "applying {itoa} and then {atoi} recovers the original integer"
   end
-  example `negative` is
+  example `negative integers use a minus sign and round-trip unchanged` is
     x = -42
+    expect itoa x = "-42"
+    expect atoi (itoa x) = -42
   end
 end
 ```
@@ -158,7 +160,7 @@ for all (x :: Int32) . atoi (itoa (x)) = x
 Reusable laws can declare typed unary function parameters and `requires Eq a`.
 Definitions support law application, function application/composition, universal
 quantification, integer and text literals, and equality. Function signatures use `Int32`
-and `Text`; generic variables are supported in reusable laws. v0.3 generates
+and `Text`; generic variables are supported in reusable laws. v0.4 generates
 quantified `Int32` and `Text` inputs, including mixed and multiple inputs. Both
 types can also be intermediate or compared results. Functions are synchronous
 and unary. Text literals are double-quoted, with escapes such as `\"`, `\\`,
@@ -168,7 +170,7 @@ Text values contain Unicode scalar values; surrogate code points are rejected.
 Examples refer to the expanded input names, including names inherited from the
 prelude. Bind every input exactly once. Ambiguous names and out-of-range values
 are errors. Descriptions and rationales use `{function}` references; `{{` and `}}`
-produce literal braces. Metadata blocks follow the order shown in `scratch.md`:
+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.
 
@@ -176,6 +178,40 @@ Additional primitives, external law packages, cross-unit imports beyond the
 prelude, async functions, direct existing-symbol binding and browser hosting are
 outside this release.
 
+## Expected results and migration to 0.4
+
+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` or `Text` type as 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.
+
+An example passes only when **all its expected results and its enclosing law**
+pass. Expected results are authored specifications, never inferred by executing
+your adapter. They apply to that example's inputs; randomized and boundary tests
+continue to check the general law. Generated assertions show compared values and
+identify the example, input bindings and expression. A failing assertion stops
+that individual test; other tests remain independent.
+
+This is an intentional syntax break from 0.3: input-only examples are rejected,
+and `expect` is now a reserved keyword. Laws can still omit examples altogether.
+For an existing input-only example, retain its bindings and add the intended
+result before `end`:
+
+```lawspec
+example `zero renders as 0 and round-trips unchanged` is
+  x = 0
+  expect itoa x = "0"
+  expect atoi (itoa x) = 0
+end
+```
+
+Update every example before running `check` or `generate`. Use
+`npx lawspec explain` to inspect the law expansion, example inputs and expected
+results; this command displays the specification without executing adapters.
+Existing implementation adapters remain user-owned and are never overwritten.
+The historical `scratch.md` is a design draft, not the current syntax reference.
+
 ## Comparing alternative implementations
 
 `equivalent` compares two functions with the same input and output types. Its
@@ -192,8 +228,10 @@ law `decimal renderers agree` is
   definition is
     `equivalent` render referenceRender
   end
-  example `negative integer` is
+  example `both renderers produce a negative decimal string` is
     x = -42
+    expect render x = "-42"
+    expect referenceRender x = "-42"
   end
 end
 ```
@@ -202,7 +240,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.3.0/examples/specs/equivalent.lawspec) compares decimal
+[The complete example](https://github.com/brain-fuel/lawspec/blob/v0.4.0/examples/specs/equivalent.lawspec) compares decimal
 renderers and two implementations that clamp negative integers to zero. For
 JavaScript, their adapters can be:
 
@@ -215,9 +253,9 @@ export const referenceClamp = x => x < 0 ? 0 : x;
 
 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. Agreement does not
-establish that either implementation meets an independent specification; two
-implementations can share the same bug. Quantified inputs can be `Int32` or `Text`.
+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` or `Text`.
 
 ## Text properties and idempotence
 
@@ -231,13 +269,15 @@ law `normalizers agree` is
   definition is
     `equivalent` normalize referenceNormalize
   end
-  example `ordinary text` is
+  example `spaces become hyphens; punctuation is preserved` is
     x = "Hello, World!"
+    expect normalize x = "Hello,-World!"
+    expect referenceNormalize x = "Hello,-World!"
   end
 end
 ```
 
-The [slug example](https://github.com/brain-fuel/lawspec/blob/v0.3.0/examples/specs/slug.lawspec)
+The [slug example](https://github.com/brain-fuel/lawspec/blob/v0.4.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()`,
@@ -257,10 +297,14 @@ law `canonicalization reaches a fixed point` is
   definition is
     `idempotent` canonicalize
   end
+  example `all trailing slashes are removed in one pass` is
+    x = "https://example.com/path///"
+    expect canonicalize x = "https://example.com/path"
+  end
 end
 ```
 
-The [canonical URL example](https://github.com/brain-fuel/lawspec/blob/v0.3.0/examples/specs/canonical_url.lawspec)
+The [canonical URL example](https://github.com/brain-fuel/lawspec/blob/v0.4.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:
 
@@ -269,9 +313,10 @@ 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.3.0/examples/specs/mixed_inputs.lawspec)
+The [mixed-input example](https://github.com/brain-fuel/lawspec/blob/v0.4.0/examples/specs/mixed_inputs.lawspec)
 shows `Text` and `Int32` in the same quantified property and executable example.
-The JavaScript API represents example values as `number | string`.
+The JavaScript API represents input bindings and expected values as `number | string`.
+Each example includes `expectations: { actual: Expr; expected: number | string }[]`.
 
 ## Generate all example artifacts
 
@@ -333,7 +378,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.3.0.tgz`.
+`npm pack ./npm` and install it with `npm install --save-dev ./lawspec-0.4.0.tgz`.
 The package payload lives in `npm/`.
 
 ```sh

package/bin/lawspec.mjs

@@ -151,16 +151,43 @@ 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 showExpression(expr) {
+  const value = expr.contents;
+  if (expr.tag === "Var") return value;
+  if (expr.tag === "Number" || expr.tag === "StringLit")
+    return JSON.stringify(value);
+  if (expr.tag === "Apply")
+    return `${showExpression(value[0])} (${showExpression(value[1])})`;
+  return `(${showExpression(value[0])} . ${showExpression(value[1])})`;
+}
+function explainExamples(law) {
+  return law.original.examples
+    .map(
+      (ex) =>
+        `\nexample ${JSON.stringify(ex.exampleName)}\n` +
+        ex.bindings
+          .map(([n, v]) => `  ${n} = ${JSON.stringify(v)}`)
+          .join("\n") +
+        "\n" +
+        ex.expectations
+          .map(
+            (e) =>
+              `  expect ${showExpression(e.actual)} = ${JSON.stringify(e.expected)}`,
+          )
+          .join("\n"),
+    )
+    .join("\n");
+}
 async function main() {
   if (!verb || ["help", "--help", "-h"].includes(verb)) {
     output(
-      "LawSpec 0.3.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.4.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: " +
         targets.join(", "),
     );
     return;
   }
   if (verb === "--version") {
-    output("0.3.0");
+    output("0.4.0");
     return;
   }
   if (positional.length > (verb === "explain" ? 1 : 0))
@@ -250,7 +277,7 @@ async function main() {
         : indices
             .map(
               ({ e, i }) =>
-                `${e.owner}::${e.name}\n${e.trace.join("\n=> ")}\n=> ${result.expansions[i]}`,
+                `${e.owner}::${e.name}\n${e.trace.join("\n=> ")}\n=> ${result.expansions[i]}${explainExamples(e)}`,
             )
             .join("\n\n"),
     );

package/build.json

@@ -17,23 +17,23 @@
     "wasm/lawspec-wasm.cabal"
   ],
   "digests": {
-    "package.yaml": "a04aefef41a1245f28d4f1d63ea38a5266b1f5302242c9fc3a840252ea7ce3ec",
+    "package.yaml": "2c1176c912901bd218743a88df1b67fb1ee8d58ed73fcbe7e2f23827f10a3a0f",
     "src/LawSpec/Api.hs": "00b1e4bc81231ebd387f10652463904084ebf9c3c4486fd2c2217a6d4dbfc157",
-    "src/LawSpec/Compile.hs": "cb32f1ff2f2ded5e93e25b11658fec6a2ffb1d24e0caaa2ffec94b510f4bfe40",
-    "src/LawSpec/Emit.hs": "c72ff20088dcaf74576710e144e79d35f9441f37fc933603033584fdff309fbe",
-    "src/LawSpec/Gen.hs": "b3d924fddc7e8417665635f049a3f641ea15c2f6f997571287db17a70b1f37b6",
-    "src/LawSpec/Model.hs": "5d550a5b75cd6b00f1b01d276100527a066c35bb69e95adb6b549b6603bab196",
-    "src/LawSpec/Parser.hs": "0a70a57b6535cfa33121e9ada595f518ced4f7b35bf09bc4732a1362c05a253f",
+    "src/LawSpec/Compile.hs": "336eca415ed6c8594612ad5acfc7ff6f29ef387cf3cb374b60b2407f811c31c7",
+    "src/LawSpec/Emit.hs": "2e23ca38aa5c4c65305283705633209843dd6ba116c43ba8a42ee8731040f7c3",
+    "src/LawSpec/Gen.hs": "305d7710dbc69b25d95fa6c0ac9a59622481f6b89682c1e5c9048def3962315a",
+    "src/LawSpec/Model.hs": "d1eda2b420edbc327b1adbf437c6f39a9e576ef0ab9b82f468c28202a433eb96",
+    "src/LawSpec/Parser.hs": "7fef1876c52d2204f852704150288910bb0c12bcde1d3159219ad25526a879b6",
     "src/LawSpec/Prelude.hs": "0b60dd85bdf0642077dfb497043c63606d507e71e12d3ed8bfe2bf773214c66b",
     "stack.yaml": "20ccf4d599e355e60b7aa4f814a7cd4299fe2048616cc2e6dbdc22a7bd8cec73",
     "stack.yaml.lock": "ae222b9c81af920c56e50fa4596fa57786e7fa5a7b461390362b2b2ff63818c7",
     "wasm/app/Exports.hs": "4ecbdac8faa2449e6fc61b93c82e6278fa14374154f29b4dacf0eef433f06a47",
     "wasm/cabal.project": "021e560afdc5eb4cb7169e7119ecb8f92c9ee170245af909c94b612941bff5cc",
     "wasm/cabal.project.freeze": "733dbed3d2ecccb26e874fd58f136296dad772184deb1658c196b5d54a0814dc",
-    "wasm/lawspec-wasm.cabal": "9f61a4c9e5c7715d1de2c42e518f3fe9cf088a3677182bda4c3f4601aa930ba9",
-    "npm/core.wasm": "674f19955c07f0bd987df27463cb0ba35c5e9756a8d22309aa21bff7488e7ed0",
+    "wasm/lawspec-wasm.cabal": "098f1d0fc52575907312c95095846d1d4f6e7ace7cfbe0419a305b9fe8a75a92",
+    "npm/core.wasm": "0a4ce15cefcd866cd7dd584c32d683c7f8a46823104afcceba1298570883a88a",
     "npm/core_jsffi.js": "88d136efe92f7cff5758c8fec8d9b6bbc9707fe37741cebeeb415fe34ce3d72b",
     "npm/api.mjs": "d6df654600172131ac66a55b86876fc29cde2a76a0a63bbefff3183488a4837b",
-    "npm/index.d.ts": "94c4842654d280796aeedcf7b438ffc63e96d0ff639203f93d04610f1de07c53"
+    "npm/index.d.ts": "85ad409ae09d243d3b3f21243d0784390d7b0209e2a09fc7c3b733e8dd2e8765"
   }
 }

package/examples/specs/atoi_codec.lawspec

@@ -16,12 +16,16 @@ law `itoa and then atoi yields a` is
     "representing an Int32 as Text must not change its value"
   end
 
-  example `negative integer` is
+  example `negative integers use a minus sign and round-trip unchanged` is
     x = -42
+    expect itoa x = "-42"
+    expect atoi (itoa x) = -42
   end
 
-  example `zero` is
+  example `zero renders as 0 and round-trips unchanged` is
     x = 0
+    expect itoa x = "0"
+    expect atoi (itoa x) = 0
   end
 
   references are

package/examples/specs/canonical_url.lawspec

@@ -9,13 +9,16 @@ law `canonicalization reaches a fixed point` is
   description is
     "{canonicalize} removes trailing slashes until the result is stable"
   end
-  example `trailing slashes` is
+  example `all trailing slashes are removed in one pass` is
     x = "https://example.com/path///"
+    expect canonicalize x = "https://example.com/path"
   end
-  example `already canonical` is
+  example `a URL without trailing slashes stays unchanged` is
     x = "https://example.com/path"
+    expect canonicalize x = "https://example.com/path"
   end
-  example `empty` is
+  example `empty input remains empty` is
     x = ""
+    expect canonicalize x = ""
   end
 end

package/examples/specs/equivalent.lawspec

@@ -15,11 +15,15 @@ law `decimal renderers agree` is
   rationale is
     "changing the formatting implementation must preserve its result"
   end
-  example `negative integer` is
+  example `both renderers produce "-42"` is
     x = -42
+    expect render x = "-42"
+    expect referenceRender x = "-42"
   end
-  example `zero` is
+  example `both renderers produce "0"` is
     x = 0
+    expect render x = "0"
+    expect referenceRender x = "0"
   end
 end
 
@@ -30,10 +34,14 @@ law `nonnegative clamps agree` is
   description is
     "{clamp} agrees with {referenceClamp} when clamping negative inputs to zero"
   end
-  example `negative boundary` is
+  example `both clamps return 0 for -2147483648` is
     x = -2147483648
+    expect clamp x = 0
+    expect referenceClamp x = 0
   end
-  example `positive boundary` is
+  example `both clamps return 2147483647 for 2147483647` is
     x = 2147483647
+    expect clamp x = 2147483647
+    expect referenceClamp x = 2147483647
   end
 end

package/examples/specs/mixed_inputs.lawspec

@@ -3,25 +3,29 @@ unit example.mixed.inputs
 normalize :: Text -> Text
 identity :: Int32 -> Int32
 
-law `text and integer inputs remain independent` is
+law `text normalization reaches a fixed point with an unused integer input` is
   definition is
     `for all` (text :: Text) (number :: Int32) .
       normalize text = normalize (normalize text)
   end
-  example `mixed inputs` is
+  example `text normalization and integer identity have explicit results` is
     text = "Hello, World!"
     number = -42
+    expect normalize text = "Hello,-World!"
+    expect identity number = -42
   end
 end
 
-law `integer behavior with a text context` is
+law `integer identity with an unused text input` is
   definition is
     `for all` (text :: Text) (number :: Int32) .
       identity number = number
   end
-  example `Unicode context` is
+  example `text normalization and integer identity have explicit results` is
     text = "λ 😀"
     number = 2147483647
+    expect normalize text = "λ-😀"
+    expect identity number = 2147483647
   end
 end
 
@@ -30,4 +34,8 @@ law `normalizing an empty literal` is
     `for all` (text :: Text) .
       normalize "" = ""
   end
+  example `empty literal stays empty; quantified text is unused` is
+    text = "unused context"
+    expect normalize "" = ""
+  end
 end

package/examples/specs/slug.lawspec

@@ -10,16 +10,24 @@ law `normalizers agree` is
   description is
     "{normalize} and {referenceNormalize} replace ASCII spaces with hyphens"
   end
-  example `ordinary text` is
+  example `spaces become hyphens; punctuation is preserved` is
     x = "Hello, World!"
+    expect normalize x = "Hello,-World!"
+    expect referenceNormalize x = "Hello,-World!"
   end
-  example `empty` is
+  example `empty text remains empty` is
     x = ""
+    expect normalize x = ""
+    expect referenceNormalize x = ""
   end
-  example `Unicode` is
+  example `Unicode is preserved while spaces become hyphens` is
     x = "café 日本語 😀"
+    expect normalize x = "café-日本語-😀"
+    expect referenceNormalize x = "café-日本語-😀"
   end
-  example `escaped text` is
+  example `quotes, backslashes and controls survive space replacement` is
     x = "quote: \" slash: \\ newline: \n tab: \t dollar: $"
+    expect normalize x = "quote:-\"-slash:-\\-newline:-\n-tab:-\t-dollar:-$"
+    expect referenceNormalize x = "quote:-\"-slash:-\\-newline:-\n-tab:-\t-dollar:-$"
   end
 end

package/index.d.ts

@@ -7,7 +7,8 @@ export interface Artifact { path: string; content: string; ownership: 'user' | '
 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: 'Apply' | 'Compose'; contents: [Expr, Expr]};
 export type Definition = {tag: 'Forall'; contents: [[string, Type][], Definition]} | {tag: 'Equal'; contents: [Expr, Expr]} | {tag: 'Invoke'; contents: [string, Expr[]]};
-export interface Example { exampleName: string; bindings: [string, number | string][] }
+export interface Expectation { actual: Expr; expected: number | string }
+export interface Example { exampleName: string; bindings: [string, number | string][]; 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 Expanded { owner: string; name: string; inputs: {inputName: string; inputId: string; inputType: Type}[]; left: Expr; right: Expr; trace: string[]; original: Law }
 export interface CheckRequest { sources: Source[] }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lawspec",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "State the law once. Check it everywhere.",
   "license": "MIT",
   "type": "module",

package/starter.lawspec

@@ -16,12 +16,16 @@ law `itoa and then atoi yields a` is
     "representing an Int32 as Text must not change its value"
   end
 
-  example `negative integer` is
+  example `negative integers use a minus sign and round-trip unchanged` is
     x = -42
+    expect itoa x = "-42"
+    expect atoi (itoa x) = -42
   end
 
-  example `zero` is
+  example `zero renders as 0 and round-trips unchanged` is
     x = 0
+    expect itoa x = "0"
+    expect atoi (itoa x) = 0
   end
 
   references are