lawspec 0.4.0 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 **State the law once. Check it everywhere.**
 
-LawSpec 0.4 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.4.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.4.0 -- lawspec init --target javascript
-npm install --save-dev lawspec@0.4.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
@@ -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.4.0, JUnit Jupiter 5.14.x | `mvn test` |
+| `java` | Maven, JDK 25, release 25 | JetCheck 0.3.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.4'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.
@@ -159,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.4 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.
@@ -178,11 +179,85 @@ 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
+## 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` or `Text` type as the expression. Expressions can reference 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.
 
@@ -240,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.4.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:
 
@@ -255,7 +330,7 @@ The same specification generates native tests for all seven targets. The
 integration suite checks both examples with matching implementations, then
 breaks each alternative separately to verify detection. The general equivalence law alone does not establish independent correctness;
 two implementations can share the same bug. Explicit expectations additionally
-check the specified outputs at the supplied example inputs. Quantified inputs can be `Int32` or `Text`.
+check the specified outputs at the supplied example inputs. Quantified inputs can be `Int32`, `Text`, or `Bool`.
 
 ## Text properties and idempotence
 
@@ -277,7 +352,7 @@ law `normalizers agree` is
 end
 ```
 
-The [slug example](https://github.com/brain-fuel/lawspec/blob/v0.4.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()`,
@@ -304,7 +379,7 @@ law `canonicalization reaches a fixed point` is
 end
 ```
 
-The [canonical URL example](https://github.com/brain-fuel/lawspec/blob/v0.4.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:
 
@@ -313,10 +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.4.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 input bindings and expected values as `number | string`.
-Each example includes `expectations: { actual: Expr; expected: 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
 
@@ -378,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.4.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

@@ -154,7 +154,11 @@ async function init() {
 function showExpression(expr) {
   const value = expr.contents;
   if (expr.tag === "Var") return value;
-  if (expr.tag === "Number" || expr.tag === "StringLit")
+  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])})`;
@@ -181,13 +185,13 @@ function explainExamples(law) {
 async function main() {
   if (!verb || ["help", "--help", "-h"].includes(verb)) {
     output(
-      "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: " +
+      "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.4.0");
+    output("0.5.0");
     return;
   }
   if (positional.length > (verb === "explain" ? 1 : 0))
@@ -207,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.",

package/build.json

@@ -17,23 +17,23 @@
     "wasm/lawspec-wasm.cabal"
   ],
   "digests": {
-    "package.yaml": "2c1176c912901bd218743a88df1b67fb1ee8d58ed73fcbe7e2f23827f10a3a0f",
+    "package.yaml": "deae9eb35385fd0e08aa44432ae718e7ba6bad8e8320c728018ee9d224733c8c",
     "src/LawSpec/Api.hs": "00b1e4bc81231ebd387f10652463904084ebf9c3c4486fd2c2217a6d4dbfc157",
-    "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",
+    "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": "098f1d0fc52575907312c95095846d1d4f6e7ace7cfbe0419a305b9fe8a75a92",
-    "npm/core.wasm": "0a4ce15cefcd866cd7dd584c32d683c7f8a46823104afcceba1298570883a88a",
+    "wasm/lawspec-wasm.cabal": "4c96fa2ec9c6cb61ca16f705c23cdae8723054bb252d27d8ef58043f8e31b868",
+    "npm/core.wasm": "581d42431681aa93b64bcd775d403612974f5cb9c7350be4b07d3ed49575c18e",
     "npm/core_jsffi.js": "88d136efe92f7cff5758c8fec8d9b6bbc9707fe37741cebeeb415fe34ce3d72b",
     "npm/api.mjs": "d6df654600172131ac66a55b86876fc29cde2a76a0a63bbefff3183488a4837b",
-    "npm/index.d.ts": "85ad409ae09d243d3b3f21243d0784390d7b0209e2a09fc7c3b733e8dd2e8765"
+    "npm/index.d.ts": "9687bedaa439c0888aa54cb94279f4fbda536122f0e55f6ab4ec3ea82ddb4283"
   }
 }

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/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/index.d.ts

@@ -5,12 +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 Expectation { actual: Expr; expected: number | string }
-export interface Example { exampleName: string; bindings: [string, number | string][]; expectations: Expectation[] }
+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.4.0",
+  "version": "0.5.0",
   "description": "State the law once. Check it everywhere.",
   "license": "MIT",
   "type": "module",