lawspec 0.3.0 → 0.5.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.5 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.5.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.5.0 -- lawspec init --target javascript
+npm install --save-dev lawspec@0.5.0
 npx lawspec check
 npx lawspec explain 'example.atoi_codec::itoa and then atoi yields a'
 npx lawspec doctor
@@ -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.5'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
 ```
@@ -157,10 +159,11 @@ 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
-quantified `Int32` and `Text` inputs, including mixed and multiple inputs. Both
-types can also be intermediate or compared results. Functions are synchronous
+quantification, `implies`, Boolean predicates, scalar literals, and equality.
+Function signatures use `Int32`, `Text`, and `Bool`; generic variables are
+supported in reusable laws. v0.5 generates quantified inputs of all three types,
+including mixed and multiple inputs. These types can also be intermediate or
+compared results. Functions are synchronous
 and unary. Text literals are double-quoted, with escapes such as `\"`, `\\`,
 `\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.
@@ -168,7 +171,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 +179,114 @@ Additional primitives, external law packages, cross-unit imports beyond the
 prelude, async functions, direct existing-symbol binding and browser hosting are
 outside this release.
 
+## Predicates and conditional laws (0.5)
+
+A predicate is a unary function returning `Bool`. Use `true` and `false` in
+expressions, example bindings, and expected results. A Boolean expression can
+stand alone as a law's definition: it must evaluate to `true`.
+
+`condition implies consequence` checks the consequence only when the condition
+is true. Conditions must have type `Bool`; nested implications short-circuit in
+source order. The consequence can be an equality, another implication, a Boolean
+predicate, or a reusable law application. Quantify any inputs before using them.
+
+```lawspec
+unit example.parse_port
+
+validPort :: Int32 -> Bool
+render    :: Int32 -> Text
+parse     :: Text -> Int32
+
+law `valid ports round trip` is
+  definition is
+    `for all` (x :: Int32) .
+      validPort x implies
+        parse (render x) = x
+  end
+
+  example `ordinary port` is
+    x = 443
+    expect validPort x = true
+    expect render x = "443"
+    expect parse (render x) = 443
+  end
+
+  example `zero is rejected; the round trip is skipped` is
+    x = 0
+    expect validPort x = false
+  end
+end
+```
+
+The [complete port example](https://github.com/brain-fuel/lawspec/blob/v0.5.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
+never reach `render` or `parse` through the law. Predicate errors still fail the
+test; they are not treated as false.
+
+Implication is logical implication, not generator filtering or an assumption.
+Randomized tests still sample the full input domain and count a false condition
+as satisfying the law. A narrow predicate may therefore exercise few or no
+consequences during a random run. Explicit valid examples ensure the important
+cases run, and expectations of both `true` and `false` catch always-false and
+always-true predicate implementations.
+
+The prelude includes `satisfies predicate` (the predicate holds for every input)
+and `left inverse when predicate parse render` (the guarded round trip above).
+These reusable laws preserve the condition and its lexical bindings when expanded.
+`equivalent` can also compare two predicates, since `Bool` supports equality.
+The [Boolean flags example](https://github.com/brain-fuel/lawspec/blob/v0.5.0/examples/specs/boolean_flags.lawspec)
+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.
+
+In 0.5, `implies`, `true`, and `false` become reserved words. Existing 0.4 specs
+that use those words as identifiers need renaming. The API adds `BoolLit`,
+`Holds`, and `Implies` AST variants, Boolean literal values, and an ordered
+`guards` array on expanded laws. `lawspec explain` prints the conditions.
+
+Kotlin adapters now group functions in an `object` named after the unit (for
+example, `object ParsePort` in package `example`). This allows both the port and
+alternatives units to define `render(Int)`. When upgrading a Kotlin project,
+move existing top-level adapter functions into the indicated object; generation
+preserves your adapter and reports the required stub shape. Generated tests call
+`ParsePort.validPort(...)`, `ParsePort.render(...)`, and `ParsePort.parse(...)`.
+
+## Expected results and migration from 0.3
+
+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
+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 +303,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 +315,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.5.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 +328,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`, `Text`, or `Bool`.
 
 ## Text properties and idempotence
 
@@ -231,13 +344,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.5.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 +372,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.5.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 +388,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.5.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 | boolean`.
+Each example includes `expectations: { actual: Expr; expected: number | string | boolean }[]`.
 
 ## Generate all example artifacts
 
@@ -333,7 +453,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.5.0.tgz`.
 The package payload lives in `npm/`.
 
 ```sh

package/bin/lawspec.mjs

@@ -151,16 +151,47 @@ 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" ||
+    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 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.5.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.5.0");
     return;
   }
   if (positional.length > (verb === "explain" ? 1 : 0))
@@ -180,7 +211,7 @@ async function main() {
         : result
             .map(
               (r) =>
-                `${r.target}: ${r.files.length} artifacts in ${r.directory}; ${r.preservedAdapters.length} user adapters preserved.`,
+                `${r.target}: ${r.files.length} artifacts in ${r.directory}; ${r.preservedAdapters.length} user adapters preserved.${r.adapterUpdates.length ? "\nReview required adapter signatures:\n" + r.adapterUpdates.map((a) => a.path + "\n" + a.requiredAdapter).join("\n") : ""}`,
             )
             .join("\n") +
             "\nInspection artifacts only; native toolchains and dependencies are not checked. Stubs must be implemented before running tests.",
@@ -250,7 +281,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": "deae9eb35385fd0e08aa44432ae718e7ba6bad8e8320c728018ee9d224733c8c",
     "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/Prelude.hs": "0b60dd85bdf0642077dfb497043c63606d507e71e12d3ed8bfe2bf773214c66b",
+    "src/LawSpec/Compile.hs": "fd696c774025cb0ec6eb29f71661ab71ac603314865ef068778ae9df1355b6cb",
+    "src/LawSpec/Emit.hs": "7f53109a18d2450313c9dc9f9ff0fe31d80f533858baf9b2c30e36b8849b416c",
+    "src/LawSpec/Gen.hs": "c4b5d4f003c52fb31983794187890ef0dad09c86a451d8e1145974605a5ca0e8",
+    "src/LawSpec/Model.hs": "148f133296be537d4e076c2716219fdafa6d2a44b26c9de4b033f87694870911",
+    "src/LawSpec/Parser.hs": "12b652dbbf174a7091609385c4564bd47b99e45329cfc1bcdaa3936901b2f966",
+    "src/LawSpec/Prelude.hs": "98cc20e242d2f70510fa09e59d0f3e387d1ebe438b4d3435ba2f32a1192cfb4e",
     "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": "4c96fa2ec9c6cb61ca16f705c23cdae8723054bb252d27d8ef58043f8e31b868",
+    "npm/core.wasm": "581d42431681aa93b64bcd775d403612974f5cb9c7350be4b07d3ed49575c18e",
     "npm/core_jsffi.js": "88d136efe92f7cff5758c8fec8d9b6bbc9707fe37741cebeeb415fe34ce3d72b",
     "npm/api.mjs": "d6df654600172131ac66a55b86876fc29cde2a76a0a63bbefff3183488a4837b",
-    "npm/index.d.ts": "94c4842654d280796aeedcf7b438ffc63e96d0ff639203f93d04610f1de07c53"
+    "npm/index.d.ts": "9687bedaa439c0888aa54cb94279f4fbda536122f0e55f6ab4ec3ea82ddb4283"
   }
 }

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/boolean_flags.lawspec

@@ -0,0 +1,21 @@
+unit example.boolean_flags
+
+flipFlag :: Bool -> Bool
+
+law `flipping twice restores either flag` is
+  definition is
+    `left inverse` flipFlag flipFlag
+  end
+
+  example `disabled becomes enabled and then disabled again` is
+    x = false
+    expect flipFlag x = true
+    expect flipFlag (flipFlag x) = false
+  end
+
+  example `enabled becomes disabled and then enabled again` is
+    x = true
+    expect flipFlag x = false
+    expect flipFlag (flipFlag x) = true
+  end
+end

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/parse_port.lawspec

@@ -0,0 +1,66 @@
+unit example.parse_port
+
+validPort :: Int32 -> Bool
+render    :: Int32 -> Text
+parse     :: Text -> Int32
+
+law `valid ports round trip` is
+  definition is
+    `for all` (x :: Int32) .
+      validPort x implies
+        parse (render x) = x
+  end
+
+  description is
+    "For ports in 1 through 65535, {parse} recovers the value written by {render}"
+  end
+
+  example `ordinary port` is
+    x = 443
+    expect validPort x = true
+    expect render x = "443"
+    expect parse (render x) = 443
+  end
+
+  example `lowest port is accepted and round trips` is
+    x = 1
+    expect validPort x = true
+    expect render x = "1"
+    expect parse (render x) = 1
+  end
+
+  example `highest port is accepted and round trips` is
+    x = 65535
+    expect validPort x = true
+    expect render x = "65535"
+    expect parse (render x) = 65535
+  end
+
+  example `zero is rejected; rendering and parsing are skipped` is
+    x = 0
+    expect validPort x = false
+  end
+
+  example `negative port is rejected; rendering and parsing are skipped` is
+    x = -1
+    expect validPort x = false
+  end
+
+  example `65536 is rejected; rendering and parsing are skipped` is
+    x = 65536
+    expect validPort x = false
+  end
+end
+
+law `the same port contract via the prelude` is
+  definition is
+    `left inverse when` validPort parse render
+  end
+
+  example `port 8080 satisfies the inherited condition and round trips` is
+    x = 8080
+    expect validPort x = true
+    expect render x = "8080"
+    expect parse (render x) = 8080
+  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

@@ -5,11 +5,12 @@ 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: '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 type Expr = {tag: 'Var' | 'StringLit'; contents: string} | {tag: 'Number'; contents: number} | {tag: 'BoolLit'; contents: boolean} | {tag: 'Apply' | 'Compose'; contents: [Expr, Expr]};
+export type Definition = {tag: 'Forall'; contents: [[string, Type][], Definition]} | {tag: 'Equal'; contents: [Expr, Expr]} | {tag: 'Holds'; contents: Expr} | {tag: 'Implies'; contents: [Expr, 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 Expanded { owner: string; name: string; inputs: {inputName: string; inputId: string; inputType: Type}[]; left: Expr; right: Expr; trace: string[]; original: Law }
+export interface Expanded { owner: string; name: string; inputs: {inputName: string; inputId: string; inputType: Type}[]; left: Expr; right: Expr; guards: Expr[]; trace: string[]; original: Law }
 export interface CheckRequest { sources: Source[] }
 export interface GenerationRequest extends CheckRequest { target: Target; sourceDir?: string; testDir?: string }
 export interface Result { diagnostics: Diagnostic[]; laws?: Expanded[]; expansions?: string[]; files?: Artifact[] }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lawspec",
-  "version": "0.3.0",
+  "version": "0.5.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