lawspec 0.8.0 → 0.10.0

package/examples/specs/recursive_refinements.lawspec

@@ -0,0 +1,41 @@
+unit example.recursive_refinements
+
+-- Refining a type argument follows its stored occurrences through recursion.
+-- The fixed Int8 field remains independent of the refined argument.
+type Tree (a :: Type) is
+  Leaf value :: a fixed :: Int8
+  Fork left :: Tree a right :: Tree a
+end
+
+refinement Positive is (value :: Int8 where value > 0) end
+
+-- The payload guarantee is available when proving recursive definitions.
+definition positiveSum (tree :: Tree Positive) :: (total :: BigInt where total > 0) is
+  match tree with
+    | Leaf value fixed -> value + 0
+    | Fork left right -> positiveSum left + positiveSum right
+  end
+end
+
+law `positive leaves have a positive total` is
+  definition is
+    `for all` (tree :: Tree Positive) . positiveSum tree > 0
+  end
+  example `fixed fields may be negative` is
+    tree = Fork (Leaf 1 -128) (Fork (Leaf 2 0) (Leaf 3 -1))
+    expect positiveSum tree = 6
+  end
+end
+
+-- Dependent predicates retain the enclosing input, even below several forks.
+law `every stored argument exceeds the threshold` is
+  definition is
+    `for all` (threshold :: Int8 where threshold < 127)
+      (tree :: Tree (value :: Int8 where value > threshold)) . tree = tree
+  end
+  example `nested threshold` is
+    threshold = 4
+    tree = Fork (Leaf 5 -128) (Leaf 6 0)
+    expect tree = Fork (Leaf 5 -128) (Leaf 6 0)
+  end
+end

package/examples/specs/refined_definitions.lawspec

@@ -0,0 +1,44 @@
+unit example.refined_definitions
+
+refinement Nonzero (T :: Type) requires Integer T is
+  (value :: T where value != 0)
+end
+
+-- The compiler proves division is defined under the input contract.
+-- Native callers are checked before the body runs.
+definition reciprocal (x :: Nonzero a) :: Rational
+requires Integer a
+is
+  1 / x
+end
+
+-- Arithmetic promotes before this explicit, proved narrowing conversion.
+definition increment (x :: Int8 where x < 127)
+  :: (result :: Int8 where result > x)
+is
+  prelude.Int8 (x + 1)
+end
+
+-- Later argument refinements can depend on earlier arguments.
+definition inverseGap (x :: Int8) (y :: Int8 where y > x) :: Rational is
+  1 / (y - x)
+end
+
+law `exact reciprocal` is
+  definition is `for all` (x :: Nonzero Int8) . reciprocal x = 1 / x end
+  example `one half` is x = 2 expect reciprocal x = rational(1, 2) end
+end
+
+law `checked increment` is
+  definition is `for all` (x :: Int8 where x < 127) . increment x = x + 1 end
+  example `largest admitted input` is x = 126 expect increment x = 127 end
+end
+
+law `dependent gap` is
+  definition is `for all` (x :: Int8) (y :: Int8 where y > x) .
+    inverseGap x y = 1 / (y - x)
+  end
+  example `difference exceeds Int8` is
+    x = -128 y = 127 expect inverseGap x y = rational(1, 255)
+  end
+end

package/examples/specs/sum_refinements.lawspec

@@ -0,0 +1,49 @@
+unit example.sum_refinements
+
+law `positive Maybe payloads` is
+  definition is `for all` (x :: Maybe (value :: Int8 where value > 0)) .
+    (match x with | Nothing -> true | Just payload -> payload >= 1 end) = true
+  end
+  example `absent` is x = Nothing expect x = Nothing end
+  example `present` is x = Just 1 expect x = Just 1 end
+end
+
+law `selected Either payload` is
+  definition is `for all`
+    (x :: Either (value :: Int8 where value > 0) (value :: Int8 where value < 0)) .
+    (match x with | Left payload -> payload >= 1 | Right payload -> payload <= -1 end) = true
+  end
+  example `left` is x = Left 1 expect x = Left 1 end
+  example `right` is x = Right -1 expect x = Right -1 end
+end
+
+law `nested Maybe states` is
+  definition is `for all` (x :: Maybe (Maybe (value :: Bool where value))) .
+    (match x with | Nothing -> true | Just inner ->
+      match inner with | Nothing -> true | Just payload -> payload end
+    end) = true
+  end
+  example `outer absent` is x = Nothing expect x = Nothing end
+  example `inner absent` is x = Just Nothing expect x = Just Nothing end
+  example `present` is x = Just (Just true) expect x = Just (Just true) end
+end
+
+law `finite Either variants` is
+  definition is `for all`
+    (x :: Either (value :: Bool where value) (value :: Bool where !value)) .
+    (match x with | Left payload -> payload | Right payload -> !payload end) = true
+  end
+end
+
+law `dependent payload keeps outer binding` is
+  definition is `for all` (lawspecElement :: Int8)
+    (x :: Maybe (value :: Int8 where value > lawspecElement)) .
+    (match x with | Nothing -> true | Just payload -> payload - lawspecElement >= 1 end) = true
+  end
+  example `maximum prefix has absent continuation` is
+    lawspecElement = 127 x = Nothing expect x = Nothing
+  end
+  example `present continuation` is
+    lawspecElement = 0 x = Just 1 expect x = Just 1
+  end
+end

package/examples/specs/total_functions.lawspec

@@ -0,0 +1,101 @@
+unit example.total_functions
+
+-- These functions are implemented in the specification. LawSpec checks their
+-- bodies and emits reusable source; they do not need adapter implementations.
+definition increment (x :: a) :: BigInt
+requires Integer a
+is
+  x + 1
+end
+
+definition count (xs :: List a) :: BigInt is
+  match xs with
+    | Nil -> 0
+    | Cons head tail -> 1 + count tail
+  end
+end
+
+definition nonempty (xs :: List a) :: Bool is
+  match xs with
+    | Nil -> false
+    | Cons head tail -> true
+  end
+end
+
+law `nonempty lists have positive length` is
+  definition is
+    `for all` (xs :: List Int8 where nonempty xs) . count xs > 0
+  end
+  example `singleton` is xs = [0] expect count xs = 1 end
+end
+
+-- The exact guard proves that the promoted denominator cannot be zero.
+definition positiveReciprocal (x :: a) :: Bool
+requires Integer a
+is
+  x >= 0 && 1 / (x + 1) > 0
+end
+
+law `guarded exact arithmetic` is
+  definition is
+    `for all` (x :: Int8) . positiveReciprocal x = (x >= 0)
+  end
+  example `skip zero denominator` is
+    x = -1 expect positiveReciprocal x = false
+  end
+  example `promote before division` is
+    x = 127 expect positiveReciprocal x = true
+  end
+end
+
+definition guardedNarrow (x :: Int8) :: Bool is
+  x < 127 && prelude.Int8 (x + 1) > x
+end
+
+law `narrow only after proving the range` is
+  definition is
+    `for all` (x :: Int8) . guardedNarrow x = (x < 127)
+  end
+  example `largest valid conversion` is x = 126 expect guardedNarrow x = true end
+  example `overflow branch is skipped` is x = 127 expect guardedNarrow x = false end
+end
+
+definition same (xs :: List a) (ys :: List a) :: Bool
+requires Eq a
+is
+  xs == ys
+end
+
+-- The same checked template produces independent concrete instances.
+law `count also accepts text` is
+  definition is
+    `for all` (xs :: List Text) . count xs = prelude.length xs
+  end
+  example `two words` is xs = ["hello", "world"] expect count xs = 2 end
+end
+
+law `increment preserves the mathematical result` is
+  definition is
+    `for all` (x :: Int8) . increment x = x + 1
+  end
+  example `maximum input` is
+    x = 127 expect increment x = 128
+  end
+end
+
+law `recursive count agrees with length` is
+  definition is
+    `for all` (xs :: List Int8) . count xs = prelude.length xs
+  end
+  example `empty` is xs = [] expect count xs = 0 end
+  example `duplicates still count` is xs = [7, 7, 7] expect count xs = 3 end
+end
+
+law `list equality preserves duplicates and order` is
+  definition is
+    `for all` (xs :: List Int8) (ys :: List Int8) . same xs ys = (xs == ys)
+  end
+  example `different order` is
+    xs = [1, 2] ys = [2, 1] expect same xs ys = false
+  end
+end

package/examples-command.mjs

@@ -3,11 +3,16 @@ import path from "node:path";
 import { createCompiler } from "./api.mjs";
 import { targets } from "./templates.mjs";
 import { safePath, planWrites, applyWrites } from "./files.mjs";
+import { exportNativePayments } from "./native-examples.mjs";
 
 export async function generateExamples(options) {
   const selected = options.target ? [options.target] : targets;
   if (selected.some((t) => !targets.includes(t)))
     throw new Error(`Unknown target: ${options.target}`);
+  if (options.example !== undefined) {
+    if (options.example !== "payments") throw new Error(`Unknown example: ${options.example}`);
+    return exportNativePayments(options, selected);
+  }
   const directory = new URL("./examples/specs/", import.meta.url);
   const sources = await Promise.all(
     (await readdir(directory))
@@ -21,7 +26,12 @@ export async function generateExamples(options) {
   const compiler = await createCompiler();
   const artifacts = [];
   for (const target of selected) {
-    const result = await compiler.planGeneration({ sources, target, machineBits: options.machineBits ?? 64 });
+    const result = await compiler.planGeneration({
+      sources,
+      target,
+      machineBits: options.machineBits ?? 64,
+      minify: options.minify === true,
+    });
     if (result.diagnostics.length)
       throw Object.assign(new Error("Bundled examples failed to compile"), {
         diagnostics: result.diagnostics,

package/files.mjs

@@ -63,8 +63,8 @@ export async function atomicWrite(file, content, exclusive = false) {
     }
   }
 }
-export async function planWrites(root, artifacts) {
-  const manifestPath = await safePath(root, ".lawspec/generated.json");
+export async function planWrites(root, artifacts, {manifest = ".lawspec/generated.json"} = {}) {
+  const manifestPath = await safePath(root, manifest);
   const previousText = await readOptional(manifestPath);
   const previous =
     previousText === null
@@ -89,7 +89,16 @@ export async function planWrites(root, artifacts) {
     const file = await safePath(root, artifact.path);
     const old = await readOptional(file);
     if (artifact.ownership === "user") {
-      adapterHashes[artifact.path] = digest(artifact.content);
+      if (
+        artifact.adapterReference !== undefined &&
+        typeof artifact.adapterReference !== "string"
+      )
+        throw new Error(`Invalid adapter reference: ${artifact.path}`);
+      // Compare compiler-owned canonical scaffolds, never normalized user code.
+      // Older compilers and manifests used readable content as this reference.
+      adapterHashes[artifact.path] = digest(
+        artifact.adapterReference ?? artifact.content,
+      );
       if (
         old !== null &&
         previous.adapters?.[artifact.path] !== adapterHashes[artifact.path]
@@ -135,18 +144,18 @@ export async function planWrites(root, artifacts) {
       throw new Error(`Refusing to remove edited generated file: ${relative}`);
     changes.push({ action: "remove", file, relative, expected: old });
   }
-  const manifest =
+  const manifestContent =
     JSON.stringify(
       { version: 1, files: next, adapters: adapterHashes },
       null,
       2,
     ) + "\n";
-  if (manifest !== previousText)
+  if (manifestContent !== previousText)
     changes.push({
       action: previousText === null ? "create" : "update",
       file: manifestPath,
-      relative: ".lawspec/generated.json",
-      content: manifest,
+      relative: manifest,
+      content: manifestContent,
       expected: previousText,
     });
   return { root, changes, preserved, adapterUpdates };

package/index.d.ts

@@ -1,29 +1,299 @@
 // Generated from LawSpec.Gen. Do not edit.
-export type Target = 'java' | 'python' | 'javascript' | 'typescript' | 'go' | 'haskell' | 'kotlin' | 'rust';
-export interface Source { path: string; content: string }
-export interface Location { file: string; line: number; column: number }
-export interface Span { start: Location; end: Location }
-export interface Diagnostic { code: string; message: string; at: Location | null }
-export interface Artifact { path: string; content: string; ownership: 'user' | 'generated'; placement: 'source' | 'test' }
-export type Type = {kind:'constructor'; name:string; arguments:TypeArgument[]} | {kind:'variable'; id:string} | {kind:'function'; parameter:Type; result:Type};
-export type TypeArgument = {kind:'type'; type:Type} | {kind:'natural'; value:string} | {kind:'indexVariable'; id:string};
-export type Origin = {kind:'source'; span:Span} | {kind:'generated'; declaration:string};
-export type Evidence = {kind:'numeric'|'structural'; type:Type};
-export interface Expr {type:Type; origin:Origin; text:string; node:ExprNode}
-export type ExprNode = {kind:'constant'; value:ScalarValue} | {kind:'local'; id:string} | {kind:'call'; declaration:string; arguments:Expr[]} | {kind:'binary'; operator:string; evidence:Evidence; left:Expr; right:Expr} | {kind:'unary'; operator:'-'|'!'; argument:Expr} | {kind:'shortCircuit'; operator:'&&'|'||'; left:Expr; right:Expr} | {kind:'convert'; conversion:'explicit'|'checked'; argument:Expr} | {kind:'helper'; name:string; arguments:Expr[]};
-export type Assertion = {kind:'equal'; evidence:Evidence; left:Expr; right:Expr} | {kind:'implies'; guard:Expr; body:Assertion} | {kind:'all'; items:Assertion[]};
-export interface Generation {cases:number; maxAttempts:number; maxShrinks:number; exhaustiveLimit:number}
-export interface Binder {id:string; name:string; type:Type}
-export interface Input extends Binder {predicates:Expr[]; bounds:{operator:string; value:Expr}[]}
-export interface Example {name:string; bindings:(Binder & {value:ScalarValue})[]; expectations:Assertion[]}
-export interface Law {id:string; owner:string; name:string; inputs:Input[]; assertion:Assertion; examples:Example[]; description:string; rationale:string; references:string[]; location:Location; trace:string[]; generation:Generation}
-export interface Unit {id:string; declarations:(Binder & {origin:Origin})[]}
-export interface Contract {id:string; name:string; arguments:Binder[]; result:Binder; preconditions:Expr[]; postconditions:Expr[]}
-export interface Refinement {owner:string; name:string; parameters:{name:string; kind:'type'|'value'; type:string}[]; requirements:{capability:string; type:string}[]; definition:string}
-export interface CheckRequest {sources:Source[]; schemaVersion?:3; machineBits?:32|64; generation?:Partial<Generation>}
-export interface GenerationRequest extends CheckRequest {target:Target; sourceDir?:string; testDir?:string}
-export interface Result {schemaVersion:3; machineBits?:32|64; generation?:Generation; units?:Unit[]; laws?:Law[]; contracts?:{owner:string; contract:Contract}[]; refinements?:Refinement[]; diagnostics:Diagnostic[]; expansions?:string[]; files?:Artifact[]}
-export type IntegerType = 'Int8' | 'Int16' | 'Int32' | 'Int64' | 'UInt8' | 'UInt16' | 'UInt32' | 'UInt64' | 'IntSize' | 'UIntSize' | 'UIntPtr' | 'Integer' | 'BigInt' | 'BigUInt';
-export type ScalarValue = {type: IntegerType; value: string} | {type: 'Bool'; value: boolean} | {type: 'Decimal'; coefficient: string; exponent: string} | {type: 'Rational'; numerator: string; denominator: string} | {type: 'Float32' | 'Float64'; bits: string} | {type: 'Complex64' | 'Complex128'; real: ScalarValue; imaginary: ScalarValue} | {type: 'Char' | 'CodePoint' | 'CodeUnit16'; value: number} | {type: 'Text' | 'CodePointText' | 'Utf16Text' | 'Bytes'; units: number[]} | {type: 'Symbol'; id: string; description: string} | {type: 'Unit' | 'Null' | 'Undefined'} | {type: 'Nullable' | 'Optional'; value: ScalarValue | null};
-export interface Compiler { check(input: CheckRequest): Promise<Result>; expand(input: CheckRequest): Promise<Result>; planGeneration(input: GenerationRequest): Promise<Result> }
+export type Target =
+    'java' |
+    'python' |
+    'javascript' |
+    'typescript' |
+    'go' |
+    'haskell' |
+    'kotlin' |
+    'rust';
+
+export interface Source {
+  path: string;
+  content: string;
+}
+
+export interface Location {
+  file: string;
+  line: number;
+  column: number;
+}
+
+export interface Span {
+  start: Location;
+  end: Location;
+}
+
+export interface Diagnostic {
+  code: string;
+  message: string;
+  at: Location | null;
+}
+
+export interface Artifact {
+  path: string;
+  content: string;
+  ownership: 'user' | 'generated';
+  placement: 'source' | 'test';
+  adapterReference?: string;
+}
+
+export type Type =
+    {kind: 'constructor'; name: string; arguments: TypeArgument[];} |
+    {kind: 'variable'; id: string;} |
+    {kind: 'function'; parameter: Type; result: Type;};
+
+export type TypeArgument =
+    {kind: 'type'; type: Type;} |
+    {kind: 'natural'; value: string;} |
+    {kind: 'indexVariable'; id: string;};
+
+export type Origin =
+    {kind: 'source'; span: Span;} | {kind: 'generated'; declaration: string;};
+
+export type Evidence = {kind: 'numeric' | 'structural'; type: Type;};
+
+export interface Expr {
+  type: Type;
+  origin: Origin;
+  text: string;
+  node: ExprNode;
+}
+
+export type ExprNode =
+    {kind: 'constant'; value: ScalarValue;} |
+    {kind: 'match'; value: Expr; cases: MatchCase[];} |
+    {kind: 'allElements'; value: Expr; binder: Binder; predicate: Expr;} |
+    {kind: 'allPayloads'; value: Expr; predicates: PayloadPredicate[];} |
+    {kind: 'construct'; constructor: string; arguments: Expr[];} |
+    {kind: 'local'; id: string;} |
+    {kind: 'call'; declaration: string; arguments: Expr[];} |
+    {
+      kind: 'binary';
+      operator: string;
+      evidence: Evidence;
+      left: Expr;
+      right: Expr;
+    } |
+    {kind: 'unary'; operator: '-' | '!'; argument: Expr;} |
+    {kind: 'shortCircuit'; operator: '&&' | '||'; left: Expr; right: Expr;} |
+    {kind: 'convert'; conversion: 'explicit' | 'checked'; argument: Expr;} |
+    {kind: 'helper'; name: string; arguments: Expr[];};
+
+export type Assertion =
+    {kind: 'equal'; evidence: Evidence; left: Expr; right: Expr;} |
+    {kind: 'implies'; guard: Expr; body: Assertion;} |
+    {kind: 'all'; items: Assertion[];};
+
+export interface Generation {
+  cases: number;
+  maxAttempts: number;
+  maxShrinks: number;
+  exhaustiveLimit: number;
+}
+
+export interface Binder {
+  id: string;
+  name: string;
+  type: Type;
+}
+
+export interface Definition {
+  owner: string;
+  id: string;
+  arguments: Binder[];
+  body: Expr;
+}
+
+export interface Input extends Binder {
+  predicates: Expr[];
+  bounds: {operator: string; value: Expr;}[];
+}
+
+export interface Example {
+  name: string;
+  bindings: (Binder & {value: DataValue;})[];
+  expectations: Assertion[];
+}
+
+export interface Law {
+  id: string;
+  owner: string;
+  name: string;
+  inputs: Input[];
+  assertion: Assertion;
+  examples: Example[];
+  description: string;
+  rationale: string;
+  references: string[];
+  location: Location;
+  trace: string[];
+  generation: Generation;
+}
+
+export interface Unit {
+  id: string;
+  declarations: (Binder & {origin: Origin;})[];
+}
+
+export interface DataTypeDeclaration {
+  id: string;
+  name: string;
+  parameters: string[];
+  origin: Origin;
+  constructors: {id: string; name: string; fields: Binder[]; origin: Origin;}[];
+}
+
+export interface Contract {
+  id: string;
+  name: string;
+  arguments: Binder[];
+  result: Binder;
+  preconditions: Expr[];
+  postconditions: Expr[];
+}
+
+export interface Refinement {
+  owner: string;
+  name: string;
+  parameters: {name: string; kind: 'type' | 'value'; type: string;}[];
+  requirements: {capability: string; type: string;}[];
+  definition: string;
+}
+
+export type NativeReference = string[];
+
+export interface NativeFieldBinding {
+  field: string;
+  native: string;
+}
+
+export interface NativeConstructorBinding {
+  constructor: string;
+  native: NativeReference;
+  fields?: NativeFieldBinding[];
+  style: 'record' | 'variant' | 'unit';
+}
+
+export interface NativeCodecBinding {
+  toNative: NativeReference;
+  fromNative: NativeReference;
+}
+
+export interface NativeTypeBinding {
+  type: string;
+  native: NativeReference;
+  constructors?: NativeConstructorBinding[];
+  codec?: NativeCodecBinding;
+}
+
+export interface NativeGeneratorBinding {
+  type: string;
+  factory: NativeReference;
+  stub?: boolean;
+}
+
+export interface NativeFunctionBinding {
+  declaration: string;
+  native: NativeReference;
+}
+
+export interface NativeGoImport {
+  alias: string;
+  path: string;
+}
+
+export interface NativeBindings {
+  types?: NativeTypeBinding[];
+  generators?: NativeGeneratorBinding[];
+  functions?: NativeFunctionBinding[];
+  rustCrate?: string;
+  goImports?: NativeGoImport[];
+}
+
+export interface CheckRequest {
+  sources: Source[];
+  schemaVersion?: 3 | 4;
+  machineBits?: 32 | 64;
+  generation?: Partial<Generation>;
+  nativeBindings?: NativeBindings;
+}
+
+export interface GenerationRequest extends CheckRequest {
+  target: Target;
+  sourceDir?: string;
+  testDir?: string;
+  minify?: boolean;
+}
+
+export interface Result {
+  schemaVersion: 3 | 4;
+  machineBits?: 32 | 64;
+  generation?: Generation;
+  units?: Unit[];
+  dataTypes?: DataTypeDeclaration[];
+  definitions?: Definition[];
+  laws?: Law[];
+  contracts?: {owner: string; contract: Contract;}[];
+  refinements?: Refinement[];
+  diagnostics: Diagnostic[];
+  expansions?: string[];
+  files?: Artifact[];
+}
+
+export interface PayloadPredicate {
+  binder: Binder;
+  predicate: Expr;
+}
+
+export interface MatchCase {
+  constructor: string;
+  binders: Binder[];
+  body: Expr;
+}
+
+export type DataValue =
+    ScalarValue |
+    {kind: 'data'; type: Type; constructor: string; fields: DataValue[];};
+
+export type IntegerType =
+    'Int8' |
+    'Int16' |
+    'Int32' |
+    'Int64' |
+    'UInt8' |
+    'UInt16' |
+    'UInt32' |
+    'UInt64' |
+    'IntSize' |
+    'UIntSize' |
+    'UIntPtr' |
+    'Integer' |
+    'BigInt' |
+    'BigUInt';
+
+export type ScalarValue =
+    {type: IntegerType; value: string;} |
+    {type: 'Bool'; value: boolean;} |
+    {type: 'Decimal'; coefficient: string; exponent: string;} |
+    {type: 'Rational'; numerator: string; denominator: string;} |
+    {type: 'Float32' | 'Float64'; bits: string;} |
+    {
+      type: 'Complex64' | 'Complex128';
+      real: ScalarValue;
+      imaginary: ScalarValue;
+    } |
+    {type: 'Char' | 'CodePoint' | 'CodeUnit16'; value: number;} |
+    {type: 'Text' | 'CodePointText' | 'Utf16Text' | 'Bytes'; units: number[];} |
+    {type: 'Symbol'; id: string; description: string;} |
+    {type: 'Unit' | 'Null' | 'Undefined';} |
+    {type: 'Nullable' | 'Optional'; value: ScalarValue | null;};
+
+export interface Compiler {
+  check(input: CheckRequest): Promise<Result>;
+  expand(input: CheckRequest): Promise<Result>;
+  planGeneration(input: GenerationRequest): Promise<Result>;
+}
+
 export function createCompiler(): Promise<Compiler>;