lawspec 0.5.0 → 0.7.0

package/examples/specs/refinements.lawspec

@@ -0,0 +1,75 @@
+unit example.refinements
+
+refinement Between (T :: Type) (minimum :: T) (maximum :: T)
+  requires Ordered T is
+  (value :: T where minimum <= value && value <= maximum)
+end
+
+refinement Positive (T :: Type) requires Integer T is
+  (value :: T where value > 0)
+end
+
+refinement AdditionOverflows (T :: Type) (left :: T)
+  requires Integer T Bounded T is
+  (right :: T where left + right > T.max)
+end
+
+add :: (x :: Int8)
+    -> (y :: AdditionOverflows Int8 x)
+    -> (result :: Integer where result == x + y)
+successor :: (x :: Int8) -> (result :: Integer where result == x + 1)
+count :: (text :: Text where prelude.length text > 0)
+      -> (result :: Integer where result == prelude.length text)
+preserve :: (x :: UInt64) -> (result :: Integer where result == x)
+positive :: (x :: Positive Int8) -> (result :: Positive Int8 where result == x)
+
+law `maximum input` is
+  definition is `for all` (x :: Int8) . successor x = x + 1 end
+  example `beyond Int8` is x = 127 expect successor x = 128 end
+end
+
+law `overflow pairs` is
+  definition is
+    `for all` (x :: Int8) (y :: AdditionOverflows Int8 x) .
+      add x y = x + y
+  end
+  example `smallest overflowing sum` is x = 127 y = 1 expect add x y = 128 end
+  example `largest sum` is x = 127 y = 127 expect add x y = 254 end
+end
+
+law `bounded input` is
+  definition is `for all` (x :: Between Int8 1 3) . positive x = x end
+  example `middle` is x = 2 expect positive x = 2 end
+end
+
+law `large integer` is
+  definition is `for all` (x :: UInt64) . preserve x = x end
+  example `maximum UInt64` is x = 18446744073709551615 expect preserve x = 18446744073709551615 end
+end
+
+abstractEcho :: (x :: Integer) -> (result :: Integer where result == x)
+
+law `nested presence` is
+  definition is `for all` (x :: Optional (Nullable (Positive Int8))) . x = x end
+end
+
+law `finite positive floats` is
+  definition is
+    `for all` (x :: Float32 where prelude.isFinite x && x > 0) .
+      prelude.isFinite x
+  end
+  example `positive` is x = 0.5 expect x = 0.5 end
+end
+
+law `raw byte length` is
+  definition is `for all` (x :: Bytes where prelude.length x == 3) . prelude.length x = 3 end
+  example `arbitrary octets` is x = bytes([0,128,255]) expect prelude.length x = 3 end
+end
+
+law `guarded predicate arithmetic` is
+  definition is `for all` (x :: Int8) (y :: Int8 where x != 0 && y > 10 / x) . y > 10 / x end
+end
+
+law `machine bound` is
+  definition is `for all` (x :: IntSize where x == IntSize.max) . x = IntSize.max end
+end

package/examples/specs/scalar_adapters.lawspec

@@ -0,0 +1,83 @@
+unit example.scalar_adapters
+echoChar :: Char -> Char
+echoCodePoint :: CodePoint -> CodePoint
+echoCodeUnit :: CodeUnit16 -> CodeUnit16
+echoBytes :: Bytes -> Bytes
+echoComplex :: Complex64 -> Complex64
+successor :: Int8 -> BigInt
+narrow :: Int8 -> Int8
+addDecimal :: Decimal -> Decimal -> Decimal
+sameSymbol :: Symbol -> Symbol -> Bool
+echoRaw :: Utf16Text -> Utf16Text
+echoPresence :: Optional (Nullable Int8) -> Optional (Nullable Int8)
+finish :: Unit -> Unit
+preserveBig :: UInt64 -> UInt64
+machineEcho :: IntSize -> IntSize
+
+law `promoted successor` is
+  definition is `for all` (x :: Int8) . successor x = x + 1 end
+  example `no overflow` is x = 127 expect successor x = 128 end
+end
+law `checked bridge` is
+  definition is `for all` (x :: Int8) . narrow (x + 0) = x end
+  example `maximum` is x = 127 expect narrow (x + 0) = 127 end
+end
+law `exact decimal adapter` is
+  definition is `for all` (x :: Decimal) (y :: Decimal) . addDecimal x y = x + y end
+  example `tenths` is x = 0.1 y = 0.2 expect addDecimal x y = 0.3 end
+end
+law `symbol identity adapter` is
+  definition is `for all` (x :: Symbol) (y :: Symbol) . sameSymbol x x and sameSymbol y y end
+  example `same description distinct identities` is
+    x = symbol("a", "same") y = symbol("b", "same")
+    expect sameSymbol x y = false
+    expect sameSymbol x x = true
+  end
+end
+law `raw adapter` is
+  definition is `for all` (x :: Utf16Text) . echoRaw x = x end
+  example `lone surrogate` is x = utf16([55296]) expect echoRaw x = utf16([55296]) end
+end
+law `presence adapter` is
+  definition is `for all` (x :: Optional (Nullable Int8)) . echoPresence x = x end
+  example `missing` is x = undefined expect echoPresence x = undefined end
+  example `null present` is x = optional(null) expect echoPresence x = optional(null) end
+end
+law `unit adapter` is
+  definition is `for all` (x :: Unit) . finish x = unitValue end
+  example `completed` is x = unitValue expect finish x = unitValue end
+end
+
+law `no safe-number truncation` is
+  definition is `for all` (x :: UInt64) . preserveBig x = x end
+  example `unsigned maximum` is x = 18446744073709551615 expect preserveBig x = 18446744073709551615 end
+end
+law `machine profile binding` is
+  definition is `for all` (x :: IntSize) . machineEcho x = x end
+  example `portable width` is x = 2147483647 expect machineEcho x = 2147483647 end
+end
+
+law `Char native bridge` is
+  definition is `for all` (x :: Char) . echoChar x = x end
+  example `native value` is x = char(128512) expect echoChar x = char(128512) end
+end
+
+law `CodePoint native bridge` is
+  definition is `for all` (x :: CodePoint) . echoCodePoint x = x end
+  example `native value` is x = codePoint(55296) expect echoCodePoint x = codePoint(55296) end
+end
+
+law `CodeUnit16 native bridge` is
+  definition is `for all` (x :: CodeUnit16) . echoCodeUnit x = x end
+  example `native value` is x = codeUnit16(65535) expect echoCodeUnit x = codeUnit16(65535) end
+end
+
+law `Bytes native bridge` is
+  definition is `for all` (x :: Bytes) . echoBytes x = x end
+  example `native value` is x = bytes([0,128,255]) expect echoBytes x = bytes([0,128,255]) end
+end
+
+law `Complex64 native bridge` is
+  definition is `for all` (x :: Complex64) . prelude.isNaN (prelude.real (echoComplex x)) = prelude.isNaN (prelude.real x) end
+  example `native value` is x = complex64(1,2) expect echoComplex x = complex64(1,2) end
+end

package/examples/specs/scalar_catalog.lawspec

@@ -0,0 +1,166 @@
+unit example.scalar_catalog
+
+law `Bool representation` is
+  definition is `for all` (x :: Bool) . x = x end
+  example `explicit value` is x = true expect x = true end
+end
+
+law `Int8 representation` is
+  definition is `for all` (x :: Int8) . x = x end
+  example `explicit value` is x = -128 expect x = -128 end
+end
+
+law `Int16 representation` is
+  definition is `for all` (x :: Int16) . x = x end
+  example `explicit value` is x = 32767 expect x = 32767 end
+end
+
+law `Int32 representation` is
+  definition is `for all` (x :: Int32) . x = x end
+  example `explicit value` is x = 2147483647 expect x = 2147483647 end
+end
+
+law `Int64 representation` is
+  definition is `for all` (x :: Int64) . x = x end
+  example `explicit value` is x = 9223372036854775807 expect x = 9223372036854775807 end
+end
+
+law `UInt8 representation` is
+  definition is `for all` (x :: UInt8) . x = x end
+  example `explicit value` is x = 255 expect x = 255 end
+end
+
+law `UInt16 representation` is
+  definition is `for all` (x :: UInt16) . x = x end
+  example `explicit value` is x = 65535 expect x = 65535 end
+end
+
+law `UInt32 representation` is
+  definition is `for all` (x :: UInt32) . x = x end
+  example `explicit value` is x = 4294967295 expect x = 4294967295 end
+end
+
+law `UInt64 representation` is
+  definition is `for all` (x :: UInt64) . x = x end
+  example `explicit value` is x = 18446744073709551615 expect x = 18446744073709551615 end
+end
+
+law `IntSize representation` is
+  definition is `for all` (x :: IntSize) . x = x end
+  example `explicit value` is x = 2147483647 expect x = 2147483647 end
+end
+
+law `UIntSize representation` is
+  definition is `for all` (x :: UIntSize) . x = x end
+  example `explicit value` is x = 4294967295 expect x = 4294967295 end
+end
+
+law `UIntPtr representation` is
+  definition is `for all` (x :: UIntPtr) . x = x end
+  example `explicit value` is x = 4294967295 expect x = 4294967295 end
+end
+
+law `BigInt representation` is
+  definition is `for all` (x :: BigInt) . x = x end
+  example `explicit value` is x = -1234567890123456789012345678901234567890 expect x = -1234567890123456789012345678901234567890 end
+end
+
+law `BigUInt representation` is
+  definition is `for all` (x :: BigUInt) . x = x end
+  example `explicit value` is x = 1234567890123456789012345678901234567890 expect x = 1234567890123456789012345678901234567890 end
+end
+
+law `Decimal representation` is
+  definition is `for all` (x :: Decimal) . x = x end
+  example `explicit value` is x = 0.000000000000000000000000000000000001 expect x = 0.000000000000000000000000000000000001 end
+end
+
+law `Rational representation` is
+  definition is `for all` (x :: Rational) . x = x end
+  example `explicit value` is x = rational(-7, 11) expect x = rational(-7, 11) end
+end
+
+law `Float32 representation` is
+  definition is `for all` (x :: Float32) . prelude.isNaN x = prelude.isNaN x end
+  example `explicit value` is x = float32Bits("80000000") expect x = float32Bits("80000000") end
+end
+
+law `Float64 representation` is
+  definition is `for all` (x :: Float64) . prelude.isNaN x = prelude.isNaN x end
+  example `explicit value` is x = float64Bits("7ff0000000000000") expect x = float64Bits("7ff0000000000000") end
+end
+
+law `Complex64 representation` is
+  definition is `for all` (x :: Complex64) . prelude.isNaN (prelude.real x) = prelude.isNaN (prelude.real x) end
+  example `explicit value` is x = complex64(1, -2) expect x = complex64(1, -2) end
+end
+
+law `Complex128 representation` is
+  definition is `for all` (x :: Complex128) . prelude.isNaN (prelude.real x) = prelude.isNaN (prelude.real x) end
+  example `explicit value` is x = complex128(0.5, -3.5) expect x = complex128(0.5, -3.5) end
+end
+
+law `Char representation` is
+  definition is `for all` (x :: Char) . x = x end
+  example `explicit value` is x = char(128512) expect x = char(128512) end
+end
+
+law `CodePoint representation` is
+  definition is `for all` (x :: CodePoint) . x = x end
+  example `explicit value` is x = codePoint(55296) expect x = codePoint(55296) end
+end
+
+law `CodeUnit16 representation` is
+  definition is `for all` (x :: CodeUnit16) . x = x end
+  example `explicit value` is x = codeUnit16(65535) expect x = codeUnit16(65535) end
+end
+
+law `Text representation` is
+  definition is `for all` (x :: Text) . x = x end
+  example `explicit value` is x = "λ日本語😀" expect x = "λ日本語😀" end
+end
+
+law `CodePointText representation` is
+  definition is `for all` (x :: CodePointText) . x = x end
+  example `explicit value` is x = codePoints([55296, 1114111]) expect x = codePoints([55296, 1114111]) end
+end
+
+law `Utf16Text representation` is
+  definition is `for all` (x :: Utf16Text) . x = x end
+  example `explicit value` is x = utf16([55296, 0, 65535]) expect x = utf16([55296, 0, 65535]) end
+end
+
+law `Bytes representation` is
+  definition is `for all` (x :: Bytes) . x = x end
+  example `explicit value` is x = bytes([0, 128, 255]) expect x = bytes([0, 128, 255]) end
+end
+
+law `Symbol representation` is
+  definition is `for all` (x :: Symbol) . x = x end
+  example `explicit value` is x = symbol("catalog", "same") expect x = symbol("catalog", "same") end
+end
+
+law `Unit representation` is
+  definition is `for all` (x :: Unit) . x = x end
+  example `explicit value` is x = unitValue expect x = unitValue end
+end
+
+law `Null representation` is
+  definition is `for all` (x :: Null) . x = x end
+  example `explicit value` is x = null expect x = null end
+end
+
+law `Undefined representation` is
+  definition is `for all` (x :: Undefined) . x = x end
+  example `explicit value` is x = undefined expect x = undefined end
+end
+
+law `Nullable Int8 representation` is
+  definition is `for all` (x :: Nullable Int8) . x = x end
+  example `explicit value` is x = nullable(127) expect x = nullable(127) end
+end
+
+law `Optional Int8 representation` is
+  definition is `for all` (x :: Optional Int8) . x = x end
+  example `explicit value` is x = undefined expect x = undefined end
+end

package/examples/specs/scalars.lawspec

@@ -0,0 +1,138 @@
+unit example.scalars
+
+law `integer promotion` is
+  definition is `for all` (x :: Int8) . x + 1 = 1 + x end
+  example `overflow is preserved` is
+    x = 127
+    expect x + 1 = 128
+  end
+end
+
+law `unsigned precision` is
+  definition is `for all` (x :: UInt64) . x + 0 = x end
+  example `maximum` is
+    x = 18446744073709551615
+    expect x + 1 = 18446744073709551616
+  end
+end
+
+law `decimal exactness` is
+  definition is `for all` (x :: Decimal) . x + 0.1 = 0.1 + x end
+  example `tenths` is
+    x = 0.1
+    expect x + 0.2 = 0.3
+  end
+end
+
+law `exact division` is
+  definition is `for all` (x :: Int16) . x / 2 = x / 2 end
+  example `one half` is
+    x = 1
+    expect x / 2 = rational(1, 2)
+    expect prelude.quot -7 3 = -2
+    expect prelude.rem -7 3 = -1
+    expect prelude.round rational(125, 100) 1 = 1.2
+  end
+end
+
+law `IEEE classification` is
+  definition is `for all` (x :: Float32) . prelude.isNaN x = prelude.isNaN x end
+  example `NaN` is
+    x = float32Bits("7fc00000")
+    expect prelude.isNaN x = true
+  end
+  example `negative zero` is
+    x = float32Bits("80000000")
+    expect prelude.isNegativeZero x = true
+    expect x = (0 :: Float32)
+  end
+  example `infinity` is
+    x = float32Bits("7f800000")
+    expect prelude.isInfinite x = true
+    expect prelude.Float32 0.1 = (0.1 :: Float32)
+  end
+end
+
+law `complex arithmetic` is
+  definition is `for all` (x :: Unit) . complex64(1, 2) * complex64(3, 4) = complex64(-5, 10) end
+  example `product` is
+    x = unitValue
+    expect complex64(1, 2) * complex64(3, 4) = complex64(-5, 10)
+  end
+end
+
+law `raw units survive` is
+  definition is `for all` (x :: Utf16Text) . x = x end
+  example `unpaired surrogate` is
+    x = utf16([55296, 0, 56320])
+    expect x = utf16([55296, 0, 56320])
+  end
+end
+
+law `arbitrary bytes` is
+  definition is `for all` (x :: Bytes) . x = x end
+  example `octets` is
+    x = bytes([0, 128, 255])
+    expect x = bytes([0, 128, 255])
+  end
+end
+
+law `symbol fixture identity` is
+  definition is `for all` (x :: Symbol) . x = x end
+  example `same reference` is
+    x = symbol("first", "description")
+    expect x = symbol("first", "description")
+  end
+end
+
+law `nested absence` is
+  definition is `for all` (x :: Optional (Nullable Int8)) . x = x end
+  example `undefined` is
+    x = undefined
+    expect x = undefined
+  end
+  example `present null` is
+    x = optional(null)
+    expect x = optional(null)
+  end
+  example `present integer` is
+    x = optional(nullable(7))
+    expect x = optional(nullable(7))
+  end
+end
+
+law `supplementary scalar` is
+  definition is `for all` (x :: Char) . x = x end
+  example `emoji` is
+    x = char(128512)
+    expect x = char(128512)
+  end
+end
+
+law `surrogate code point` is
+  definition is `for all` (x :: CodePointText) . x = x end
+  example `surrogate` is
+    x = codePoints([55296, 128512])
+    expect x = codePoints([55296, 128512])
+  end
+end
+
+law `explicit float rounding` is
+  definition is `for all` (x :: Unit) . x = x end
+  example `IEEE halfway cases` is
+    x = unitValue
+    expect prelude.Complex128 complex64(1, 2) = complex128(1, 2)
+    expect prelude.Complex64 complex128(1.25, -2.5) = complex64(1.25, -2.5)
+    expect prelude.Float32 rational(16777217, 16777216) = float32Bits("3f800000")
+    expect prelude.Float32 rational(1208925891672223212634113, 1208925819614629174706176) = float32Bits("3f800001")
+    expect prelude.Float64 rational(9007199254740993, 9007199254740992) = float64Bits("3ff0000000000000")
+    expect prelude.Float64 rational(1606938044258990453947923680586147734807949174969684883144705, 1606938044258990275541962092341162602522202993782792835301376) = float64Bits("3ff0000000000001")
+    expect prelude.Float32 rational(1, 1427247692705959881058285969449495136382746624) = float32Bits("00000000")
+    expect prelude.Float32 rational(1125899906842625, 1606938044258990275541962092341162602522202993782792835301376) = float32Bits("00000001")
+  end
+end
+
+law `short circuit exact failures` is
+  definition is `for all` (x :: Unit) . false implies 1 / 0 = rational(1, 2) end
+  example `guard prevents division` is x = unitValue expect x = unitValue end
+end

package/examples-command.mjs

@@ -21,7 +21,7 @@ export async function generateExamples(options) {
   const compiler = await createCompiler();
   const artifacts = [];
   for (const target of selected) {
-    const result = await compiler.planGeneration({ sources, target });
+    const result = await compiler.planGeneration({ sources, target, machineBits: options.machineBits ?? 64 });
     if (result.diagnostics.length)
       throw Object.assign(new Error("Bundled examples failed to compile"), {
         diagnostics: result.diagnostics,

package/index.d.ts

@@ -3,16 +3,27 @@ export type Target = 'java' | 'python' | 'javascript' | 'typescript' | 'go' | 'h
 export interface Source { path: string; content: string }
 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: '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; guards: Expr[]; trace: string[]; original: Law }
-export interface CheckRequest { sources: Source[] }
+export interface Artifact { path: string; content: string; ownership: 'user' | 'generated'; placement: 'source' | 'test' }
+export type Type = {tag: 'Named' | 'Variable'; contents: string} | {tag: 'Arrow'; contents: [Type, Type]} | {tag: 'Applied'; contents: ['Nullable' | 'Optional', Type]} | {tag:'Refined'; contents:[string, Type, Expr | null]} | {tag:'Qualified'; contents:[Constraint[],Type]} | {tag:'CheckedType'; contents:[Expr[],Type]} | {tag:'RefinementApp'; contents:[string,RefinementArgument[]]};
+export interface Constraint {tag:'Capability'; contents:['Eq'|'Integer'|'Ordered'|'Bounded',Type]}
+export type RefinementArgument = {tag:'TypeArgument'; contents:Type} | {tag:'ValueArgument'; contents:Expr};
+export interface Refinement {refinementName:string; refinementParameters:[string,Type][]; refinementRequirements:Constraint[]; refinementBody:Type}
+export interface Contract {contractName:string; contractArguments:[string,Type][]; contractResult:[string,Type]; contractPreconditions:Expr[]; contractPostconditions:Expr[]}
+export interface Generation {cases:number; maxAttempts:number; maxShrinks:number; exhaustiveLimit:number}
+export interface Input {inputName:string; inputId:string; inputType:Type; inputRefinements:Expr[]}
+export interface DomainPlan {domainInput:Input; domainBounds:[string,Expr][]}
+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 type Expr = {tag: 'Var' | 'StringLit'; contents: string} | {tag: 'Number'; contents: string} | {tag: 'DecimalNumber'; contents: [string, string]} | {tag: 'BoolLit'; contents: boolean} | {tag: 'Apply' | 'Compose'; contents: [Expr, Expr]} | {tag: 'ScalarLit'; contents: ScalarValue} | {tag: 'Annotate'; contents: [Expr, Type]} | {tag: 'Unary'; contents: [string, Expr]} | {tag: 'Binary'; contents: [string, Expr, Expr]} | {tag:'TypeBound'; contents:['min'|'max',Type]};
+export type Definition = {tag: 'Forall'; contents: [[string, Type][], Definition]} | {tag: 'Equal'; contents: [Expr, Expr]} | {tag: 'Holds'; contents: Expr} | {tag: 'Implies'; contents: [Expr, Definition]} | {tag: 'And'; contents: [Definition, Definition]} | {tag: 'Invoke'; contents: [string, Expr[]]};
+export interface Expectation { actual: Expr; expected: ScalarValue }
+export interface Example { exampleName: string; bindings: [string, ScalarValue][]; expectations: Expectation[] }
+export interface Law { lawName: string; parameters: [string, Type][]; requirements: Constraint[]; definition: Definition; description: string; rationale: string; examples: Example[]; references: string[]; location: Location }
+export type Assertion = {tag: 'AssertEqual'; contents: [Expr, Expr]} | {tag: 'AssertImplies'; contents: [Expr, Assertion]} | {tag: 'AssertAll'; contents: Assertion[]};
+export interface Expanded { owner: string; name: string; inputs: Input[]; left: Expr; right: Expr; guards: Expr[]; assertion: Assertion; trace: string[]; original: Law; typedExpressions: TypedExpr[]; propertyKind: 'law'|'contract'; generation:Generation; generationPlan:DomainPlan[] }
+export interface TypedExpr { expressionType: Type; expression: Expr; operands: TypedExpr[]; requiredConversion: Type | null }
+export interface CheckRequest { sources: Source[]; schemaVersion?: 2; machineBits?: 32 | 64; generation?:Partial<Generation> }
 export interface GenerationRequest extends CheckRequest { target: Target; sourceDir?: string; testDir?: string }
-export interface Result { diagnostics: Diagnostic[]; laws?: Expanded[]; expansions?: string[]; files?: Artifact[] }
+export interface Result { schemaVersion: 2; machineBits?: 32 | 64; generation?:Generation; refinements?:{owner:string; declaration:Refinement}[]; contracts?:{owner:string; contract:Contract}[]; diagnostics: Diagnostic[]; laws?: Expanded[]; expansions?: string[]; files?: Artifact[] }
 export interface Compiler { check(input: CheckRequest): Promise<Result>; expand(input: CheckRequest): Promise<Result>; planGeneration(input: GenerationRequest): Promise<Result> }
 export function createCompiler(): Promise<Compiler>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lawspec",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "State the law once. Check it everywhere.",
   "license": "MIT",
   "type": "module",
@@ -8,6 +8,6 @@
   "bin": { "lawspec": "bin/lawspec.mjs" },
   "exports": { ".": { "types": "./index.d.ts", "import": "./api.mjs" } },
   "types": "index.d.ts",
-  "files": ["*.mjs", "*.json", "index.d.ts", "bin", "core.wasm", "core_jsffi.js", "README.md", "LICENSE", "starter.lawspec", "examples"],
+  "files": ["*.mjs", "*.json", "index.d.ts", "bin", "core.wasm", "core_jsffi.js", "README.md", "PRIMITIVES.md", "REFINEMENTS.md", "API-MIGRATION.md", "LICENSE", "starter.lawspec", "examples"],
   "scripts": { "test": "node --test test/*.test.mjs" }
 }

package/scalars.mjs

@@ -0,0 +1,13 @@
+// Human-readable, lossless API v2 scalar display.
+export function showScalar(v) {
+  if (!v || typeof v !== 'object') throw new TypeError('Expected an API v2 scalar');
+  if ('coefficient' in v) return `${v.coefficient}e${v.exponent}`;
+  if ('numerator' in v) return `rational(${v.numerator}, ${v.denominator})`;
+  if ('bits' in v) return `${v.type === 'Float32' ? 'float32Bits' : 'float64Bits'}(${JSON.stringify(v.bits)})`;
+  if ('real' in v) return `${v.type}(${showScalar(v.real)}, ${showScalar(v.imaginary)})`;
+  if ('units' in v) return v.type === 'Text' ? JSON.stringify(v.units.map(c => String.fromCodePoint(c)).join('')) : `${v.type}([${v.units.join(', ')}])`;
+  if (v.type === 'Symbol') return `symbol(${JSON.stringify(v.id)}, ${JSON.stringify(v.description)})`;
+  if (v.type === 'Optional' || v.type === 'Nullable') return v.value === null ? (v.type === 'Optional' ? 'undefined' : 'null') : `${v.type.toLowerCase()}(${showScalar(v.value)})`;
+  if ('value' in v) return String(v.value);
+  return {Unit:'unitValue', Null:'null', Undefined:'undefined'}[v.type] ?? v.type;
+}

package/templates.mjs

@@ -100,7 +100,7 @@ export function templates(target) {
     case "haskell":
       return {
         "stack.yaml": "snapshot: lts-24.58\npackages: [.]\n",
-        "package.yaml": `name: lawspec-example\nversion: 0.1.0\ndependencies: [base, text]\nlibrary:\n  source-dirs: src\ntests:\n  laws:\n    main: Spec.hs\n    source-dirs: test\n    dependencies: [lawspec-example, hspec, hedgehog, hspec-hedgehog]\n    build-tools: [hspec-discover]\n`,
+        "package.yaml": `name: lawspec-example\nversion: 0.1.0\ndependencies: [base, text, bytestring]\nlibrary:\n  source-dirs: src\ntests:\n  laws:\n    main: Spec.hs\n    source-dirs: test\n    dependencies: [lawspec-example, hspec, hedgehog, hspec-hedgehog]\n    build-tools: [hspec-discover]\n`,
         "test/Spec.hs": "{-# OPTIONS_GHC -F -pgmF hspec-discover #-}\n",
       };
     case "kotlin":