lawspec 0.7.0 → 0.9.0

package/LANGUAGE.md

@@ -0,0 +1,361 @@
+# LawSpec language and compiler boundary (0.9)
+
+LawSpec describes portable laws, concrete examples, and adapter contracts. The
+compiler is written in Haskell. Rust is an output backend alongside Java, Python,
+JavaScript, TypeScript, Go, Haskell, and Kotlin.
+
+## Lists and algebraic containers
+
+`List a` is an ordered, finite sequence of values of one type. Lists nest and
+retain duplicates. Literals use brackets; their element type comes from the
+surrounding signature, quantifier, or annotation. An unconstrained empty list
+needs an annotation such as `([] :: List Int8)`.
+
+```lawspec
+unit guide.lists
+
+reverse :: List Int32 -> List Int32
+
+law `reverse preserves length` is
+  definition is
+    `for all` (xs :: List Int32) .
+      prelude.length (reverse xs) = prelude.length xs
+  end
+  example `duplicates count separately` is
+    xs = [3, 1, 3]
+    expect prelude.length xs = 3
+    expect reverse xs = [3, 1, 3]
+  end
+end
+```
+
+`prelude.length` returns an exact integer. List equality compares corresponding
+values in order and requires equal lengths. It preserves scalar equality rules:
+NaN still differs from itself, signed zeros compare equal, and Symbols compare
+by identity. Generic list equality requires `Eq a`.
+
+`Maybe a` has constructors `Nothing` and `Just value`. `Either a b` has
+constructors `Left value` and `Right value`. These are algebraic sums, separate
+from the interoperability types `Nullable a` and `Optional a`.
+
+```lawspec
+unit guide.presence
+
+echo :: Maybe (Either Int8 Bool) -> Maybe (Either Int8 Bool)
+
+law `preserve every alternative` is
+  definition is `for all` (x :: Maybe (Either Int8 Bool)) . echo x = x end
+  example `absent` is x = Nothing expect echo x = Nothing end
+  example `left integer` is x = Just (Left 127) expect echo x = Just (Left 127) end
+  example `right boolean` is x = Just (Right false) expect echo x = Just (Right false) end
+end
+```
+
+For `Maybe (Maybe Bool)`, `Nothing`, `Just Nothing`, and `Just (Just false)`
+remain distinct. Nesting a constructor application as an argument generally
+requires parentheses, as in `Just (Left 127)`.
+
+The [collections example](examples/specs/collections.lawspec) combines reverse
+involution, sorting idempotence, sortedness, length, and permutation preservation.
+`sorted` and `permutation` in that example are adapters supplied by the user;
+they are not built-in helpers. Sortedness and length alone cannot establish that
+a sorting adapter retained the original elements.
+
+## Products, sums, and pattern matching
+
+A `type` declaration names its constructors and each constructor's fields. One
+constructor describes a product; multiple constructors describe a sum. Type
+parameters are declared explicitly with `:: Type`.
+
+```lawspec
+unit guide.trees
+
+type Pair (a :: Type) (b :: Type) is
+  Pair
+    first :: a
+    second :: b
+end
+
+type Tree (a :: Type) is
+  Leaf value :: a
+  Branch children :: List (Tree a)
+end
+
+definition rebuild (tree :: Tree a) :: Tree a is
+  match tree with
+    | Leaf value -> Leaf value
+    | Branch children -> Branch children
+  end
+end
+
+law `preserve the constructor and its fields` is
+  definition is `for all` (tree :: Tree Int8) . rebuild tree = tree end
+  example `nested branches` is
+    tree = Branch [Leaf 127, Branch [], Leaf -128]
+    expect rebuild tree = Branch [Leaf 127, Branch [], Leaf -128]
+  end
+end
+```
+
+Constructors receive fields in declaration order. A match evaluates its
+scrutinee once; each branch binds that constructor's fields in the same order.
+Bindings are scoped to the branch. Matching must be exhaustive and cannot repeat
+a constructor. Lists match with `Nil` and `Cons head tail`; Maybe and Either use
+their constructors above. Recursive declarations must be strictly positive.
+General indexed constructors and GADT result signatures are not supported.
+
+Equality is structural and type-directed, including named fields and nested
+containers. Native public declarations retain their names and type parameters;
+schemas and checked codecs support them at runtime. They are not replacements
+for the public data types. See the target guides for native representations:
+[Java](JAVA.md), [Python](PYTHON.md), [JavaScript/TypeScript](WEB.md),
+[Go](GO.md), [Haskell](HASKELL.md), [Kotlin](KOTLIN.md), and [Rust](RUST.md).
+In Haskell, `Text` remains `Data.Text.Text`, while `List Char` becomes the linked
+list `[Char]`. These are distinct LawSpec types even when they contain the same
+characters.
+
+Generators compose the target framework's generators and shrinkers. Recursive
+values have a structural size budget; each constructor reserves enough budget
+for its fields before distributing the remainder. Boundaries include empty and
+singleton lists and constructor-specific values. Small finite domains are
+enumerated. An empty type cannot supply a generated argument, but containers
+such as `List Empty` and `Maybe Empty` can still be inhabited. An empty or
+unreachable input domain never makes a property pass vacuously.
+
+Whole-value refinements can inspect products and sums using exhaustive matches.
+List element refinements, Maybe/Either payload refinements, and refined arguments
+of recursive and nonrecursive named type constructors are supported; see
+[refinements](REFINEMENTS.md#named-data-payloads). Direct refinements on named
+constructor fields use checked constructor contracts. Recursive payload predicates
+follow stored type arguments and preserve outer dependent inputs.
+
+## Total definitions
+
+A unit can supply an implementation as a checked total definition:
+
+```lawspec
+definition increment (x :: Int8) :: BigInt
+requires Integer Int8
+is
+  x + 1
+end
+```
+
+Parameters and the result have explicit types. The optional `requires` clause
+uses the same `Eq`, `Integer`, `Ordered`, and `Bounded` capabilities as laws.
+Requirements are checked even when the definition is unused. Bodies must have
+exhaustive matches, proven structural descent for recursive calls, and guards
+for operations that could otherwise fail. Calls may use other checked
+definitions; external adapters cannot establish a definition's totality.
+
+For exact arithmetic, the totality checker can combine linear bounds and Boolean
+guards. For example, `x >= 0 && 1 / (x + 1) > 0` is safe for integer `x`: the
+right side runs only when its denominator is positive. Proof arithmetic uses
+arbitrary exact fractions, preserves strict boundaries, and has a bounded work
+budget. An unproved obligation is rejected; IEEE expressions never acquire
+rational identities such as `x - x = 0` from this checker.
+
+Primitive integer ranges are available to the checker automatically, including
+the selected machine width and BigUInt's nonnegative domain. Integer comparisons
+retain integrality: for Int8 `x`, `x < 127 && prelude.Int8 (x + 1) > x` safely
+narrows only on the guarded branch. The unguarded conversion is rejected because
+`127 + 1` is outside Int8. Range bounds alone do not prove that a Rational or
+Decimal input has no fractional part.
+Pattern matching retains the primitive ranges of extracted fields within that
+branch. For example, an Int8 list head still makes `head + 129` strictly positive;
+that fact cannot be reused for an Int64 field in another constructor branch.
+
+Definitions produce reusable generated source with checked native entry points
+on all eight targets. They do not produce user-owned adapter stubs. Integer
+arithmetic preserves the mathematical result; the example above returns `128`
+for the largest Int8 input. See [the total-function example](examples/specs/total_functions.lawspec)
+for recursive list counting, structural equality, and explicit expected values.
+
+Definitions can quantify type variables implicitly through their signatures:
+
+```lawspec
+definition same (x :: a) (y :: a) :: Bool requires Eq a is x == y end
+definition count (xs :: List a) :: BigInt is
+  match xs with
+    | Nil -> 0
+    | Cons head tail -> 1 + count tail
+  end
+end
+```
+
+Each template is checked for typing, capabilities, termination, and definedness,
+including unused templates. Calls specialize it to concrete argument and result
+types before Core elaboration. Different calls can use different types; recursive
+self-calls must retain the same types. Ambiguous calls require an annotation,
+such as `count ([] :: List Int8)` to specify an empty list's element type.
+Unused templates emit no instances.
+Checked definitions may also appear in refinement predicates and adapter
+preconditions or postconditions. Their closed call graphs contain only other
+checked definitions; adapter calls remain forbidden in predicates. The compiler
+uses the same concrete Core definitions to check example domains and plan finite
+cases and boundaries that generated tests use at runtime.
+Definition parameters and results may carry refinements. The compiler proves
+body definedness and result claims under ordered input preconditions, checks
+callee preconditions, and preserves the contracts through specialization. Native
+entry points enforce the same contracts. See [refined definitions](REFINEMENTS.md#refined-definitions).
+
+## Source and declarations
+
+A source has one named `unit`, function signatures, data declarations, checked
+definitions, reusable refinements, and laws. Qualified unit names determine target module/package paths. Function
+signatures are curried: `a -> b -> c` takes two inputs and returns `c`. Parentheses
+group types and expressions. Comments start with `--` and run to the line end.
+
+The following grammar summarizes the main forms; the parser and executable
+compiler tests specify lexical details:
+
+```text
+source       = "unit" qualified-name declaration*
+declaration  = name "::" type | law | refinement | data-type | function
+data-type    = "type" name ("(" name "::" "Type" ")")*
+               "is" constructor* "end"
+constructor  = name (name "::" type)*
+function     = "definition" name parameter* "::" type requirements?
+               "is" expression "end"
+type         = type-atom ["->" type]
+type-atom    = primitive | type-variable | "(" type ")"
+             | ("Nullable" | "Optional" | "List" | "Maybe") type-atom
+             | "Either" type-atom type-atom
+             | data-type-name type-atom*
+             | refinement-name argument*
+             | "(" name "::" type ["where" expression] ")"
+refinement   = "refinement" name parameter* requirements?
+               "is" type "end"
+parameter    = "(" name "::" type ["where" expression] ")"
+requirements = "requires" (capability type)+
+capability   = "Eq" | "Integer" | "Ordered" | "Bounded"
+law          = "law" quoted-name parameter* requirements? "is"
+               "definition" "is" proposition "end"
+               description? rationale? example* references? "end"
+proposition  = "`for all`" parameter+ "." proposition
+             | expression "=" expression
+             | expression "implies" proposition
+             | proposition "and" proposition
+             | quoted-name expression* | expression
+expression   = ... | "[" [expression ("," expression)*] "]"
+             | constructor-name expression*
+             | "match" expression "with"
+               ("|" constructor-name name* "->" expression)+ "end"
+example      = "example" quoted-name "is" (name "=" literal)+
+               ("expect" expression "=" literal)+ "end"
+```
+
+Law names use backticks. Text/metadata use double quotes with escapes. Named
+refinement declarations state their type versus value parameter kinds, including
+forward references; the compiler validates their arity and argument kinds.
+Lowercase type names represent variables. `a :: Type` is a type parameter, not a
+runtime value with a generator.
+
+A generic law is specialized when invoked with concrete adapters. Its declared
+capabilities must justify its operations; specialization resolves those
+requirements for the actual types. `Integer` as a capability requires an integer
+type. `Integer` in a concrete result signature denotes a representation-independent
+mathematical integer. See [refinements and abstract integers](REFINEMENTS.md).
+
+## Expressions and arithmetic
+
+Application binds most tightly. The remaining precedence, highest first, is:
+unary `!`/`-`, composition `.`, multiplication/division, addition/subtraction,
+comparisons (`==`, `!=`, `<`, `<=`, `>`, `>=`), `&&`, then `||`.
+Comparisons do not chain. Arithmetic associates left; composition associates
+right. An adjacent numeric sign remains part of an argument: `f -42` applies `f`
+to negative 42. Write `x - 42` for subtraction.
+
+Assertion `=` differs from Boolean `==`. `implies` guards its following
+proposition; `and` requires both assertions. Parentheses determine the scope of a
+shared guard. Both Boolean operators and implications short-circuit.
+
+Literals acquire types from declared context. Unconstrained integers have type
+`Integer`; decimal tokens have type `Decimal`. An annotation such as
+`(127 :: Int8)` specifies context. A declared float context can type a decimal
+token directly, but an explicitly constructed exact Decimal is not implicitly
+converted into a float.
+
+Integer `+`, `-`, `*`, and negation produce exact `Integer` results. Decimal
+dominates integer/Decimal combinations; Rational dominates exact combinations
+involving Rational. Exact `/` returns Rational. `prelude.quot` truncates integer
+quotients toward zero; `prelude.rem` is the associated remainder. Division by
+zero fails when evaluated. Explicit numeric conversions use `prelude.Type`.
+Exact/inexact mixing otherwise fails type checking. IEEE arithmetic widens float
+or complex precision as required; equality treats NaN as unequal and signed
+zero as equal. Decimal rounding is explicit, with a scale and ties-to-even rule.
+
+Passing a computed exact result to a bounded adapter argument performs a checked
+conversion. It never wraps, truncates a fraction, or silently changes precision.
+Adapter results are validated against the declared domain before use. See the
+[primitive reference](PRIMITIVES.md) for all domains and helpers.
+
+## Refinements and executable contracts
+
+Refinements are pure Boolean predicates over a value and preceding binders.
+They cannot call user adapters. Dependent inputs are generated in order;
+shrinking preserves their predicates. Bounds such as `y > Int8.max - x` are
+computed with exact arithmetic and can drive a dependent generator. If a chosen
+`x` has no possible `y`, generation retries earlier inputs. Search exhaustion
+fails explicitly rather than passing a property with no valid cases.
+
+Contracts check preconditions, evaluate an adapter once, validate the result,
+and then check postconditions against that same result. Predicate errors are
+contextual failures, not rejected samples. Small finite domains are enumerated;
+other domains use target property frameworks. `machineBits: 32 | 64` controls
+machine-integer domains independently of the compiler host architecture. Native
+machine-sized adapter bindings additionally verify the executing architecture.
+
+## Compiler stages and public API
+
+The parser retains source ranges. Resolution and inference check names, kinds,
+capabilities, contextual literals, and generic specializations. Elaboration
+produces typed core expressions with resolved declaration/binder IDs, explicit
+arithmetic evidence and conversions, plus an authoritative proposition tree.
+Refinement declarations become predicates on quantifiers and contracts; targets
+do not interpret refinement syntax.
+
+An independent core validator checks scopes, kinds, operand/result types,
+capability evidence, and conversions. A pure core evaluator supports deterministic
+domain checks and reference tests. The testing planner computes finite cases,
+boundaries, and dependent generator requirements. All eight emitters consume
+that plan and the core, without importing source syntax or inference.
+
+`check`/`expand` report semantic validity. `planGeneration` additionally reports
+execution feasibility, including empty finite domains. Source syntax errors,
+semantic errors, core invariant failures, and generation errors have distinct
+diagnostic codes. Runtime failures identify the law/example or adapter contract.
+Parsed expressions retain real source ranges; synthesized expressions identify
+the declaration that caused their creation.
+
+API schema v3 uses separately defined wire views, with lossless tagged scalar
+values. It does not serialize internal AST constructors. See the
+[API migration guide](API-MIGRATION.md).
+
+## Beyond 0.9
+
+GADTs, indexed families, and general dependent types are planned after 0.9.
+The Core type model distinguishes type arguments from index arguments, but that
+representation is not a claim that arbitrary dependent programs are accepted.
+User-defined products and sums have ordinary uniform type parameters. External
+type bindings, custom generator bindings, and cross-unit packages are separate
+future features.
+
+## Generated project formatting
+
+`lawspec init --target java` creates a readable Maven scaffold; Kotlin init
+likewise expands Gradle blocks with two-space indentation. `--minify` explicitly
+selects compact scaffolds and configuration JSON. `generate` and `examples`
+accept the same flag for generated source. The mode is per invocation and does
+not become a project default. Init preserves existing build files, and generation
+preserves user-owned adapters regardless of formatting mode.
+
+Generated runtime support and checked definitions belong in source directories;
+framework-specific property helpers belong in test directories. Both follow
+custom layout settings. Python uses PEP 8: four-space indentation, 79-column
+code, and 72-column prose. Other targets follow Google language guidance where
+applicable, with standard Rust formatting. Formatting is deterministic in the
+native and WASM compilers; generation does not download or invoke a formatter.
+
+See [the release notes](RELEASE-0.9.md) for compatibility and scope, and the target
+guides for formatting verification and native representation details.

package/PRIMITIVES.md

@@ -1,4 +1,4 @@
-# LawSpec scalar reference (0.7.0)
+# LawSpec scalar reference (0.9.0)
 
 A scalar has a declared domain, checked literals, equality, property inputs, and
 boundary fixtures. General collections, objects, pointers, and type-only constructs
@@ -142,7 +142,7 @@ portable across architectures.
 The bundled `scalars.lawspec`, `scalar_catalog.lawspec`, and
 `scalar_adapters.lawspec` contain explicit fixtures for every scalar family.
 `tools/scalar-reference.py` produces independent Fraction-based conformance
-vectors; `tools/scalar-integration.mjs` executes them across the seven targets.
+vectors; `tools/scalar-integration.mjs` executes them across the eight targets.
 Set `LAWSPEC_MUTANTS=1` to also verify that incorrect adapters are detected.
 
 

package/PYTHON.md

@@ -0,0 +1,152 @@
+# Python backend
+
+Python output follows [PEP 8](https://peps.python.org/pep-0008/): four-space
+indentation, a 79-column code target, 72-column prose comments/docstrings, and
+two blank lines between top-level definitions. Explicit `--minify` permits
+compact layout while preserving Python indentation and semantics.
+`tools/python-formatting-integration.mjs` checks generated runtime, adapter,
+definition, and test files with pycodestyle 2.14.0 at both machine widths. It
+also compares readable and compact syntax trees, including literal contents.
+
+Use Python 3.13 or later. Generated tests use Hypothesis; generated data classes,
+scalar operations, and schema validation do not depend on a test framework.
+
+## Native structural values
+
+| LawSpec type | Adapter representation |
+| --- | --- |
+| `List a` | `list[A]` |
+| `Maybe a` | `lawspec_schema.Maybe[A]`, with `Nothing` and `Just` variants |
+| `Either a b` | `lawspec_schema.Either[A, B]`, with `Left` and `Right` variants |
+| User-defined products and sums | Named generic dataclasses in `lawspec_data` |
+| `Nullable a`, `Optional a` | Tagged `lawspec_runtime.Presence` values |
+
+`Nothing()` differs from `Just(Nothing())`. `Left(value)` differs from
+`Right(value)`. These algebraic variants are separate from the interoperability
+states represented by `Nullable`, `Optional`, `Null`, and `Undefined`.
+
+For example, this declaration:
+
+```lawspec
+type Tree (a :: Type) is
+  Leaf value :: a
+  Branch children :: List (Tree a)
+end
+```
+
+produces a generic `Tree` base and `TreeLeaf` and `TreeBranch` dataclasses. A
+product has one variant: `Pair` with constructor `Pair` produces `PairPair`.
+When names conflict across units or between types and variants, the compiler
+plans distinct names using their Core identities. Use the emitted declarations
+and adapter annotations as the authoritative names.
+
+Native pattern matching works on the generated variants:
+
+```python
+import lawspec_data as data
+
+
+def count_leaves(tree: data.Tree[int]) -> int:
+    match tree:
+        case data.TreeLeaf():
+            return 1
+        case data.TreeBranch(children=children):
+            return sum(count_leaves(child) for child in children)
+    raise TypeError("unknown Tree variant")
+```
+
+Classes are frozen and use slots. Container payloads are copied when crossing
+adapter boundaries, so modifying a native list does not change another use of
+the logical test input. An abstract base cannot be directly constructed; empty
+types acquire no artificial variant.
+
+LawSpec equality uses schema-directed comparisons, including IEEE NaN and
+signed-zero rules and Symbol identity. Generated dataclasses do not derive
+Python field equality, whose container shortcuts can change those rules.
+
+## Checked boundaries
+
+Generated calls validate input values, convert them to native classes, call the
+adapter, and validate its result. A field extracted from a native product can
+be returned directly from an adapter with the corresponding LawSpec result
+type. The same representation is used for nested and standalone containers.
+
+Diagnostics identify constructor fields and list indices. Checks distinguish
+Bool from integers, enforce primitive ranges under the selected `machineBits`,
+reject invalid scalar text, and preserve raw code units, code points, and bytes.
+Preconditions and postconditions operate on validated logical values.
+
+## Total definitions
+
+Checked total definitions emit reusable Python functions separately from adapters:
+
+```lawspec
+unit example.total
+
+definition increment (x :: Int8) :: BigInt is x + 1 end
+```
+
+```python
+from lawspec_definitions.example import total
+
+symbols = {}
+assert total.increment(symbols, 127) == 128
+```
+
+The first argument is the Symbol fixture context shared within an example.
+Public signatures preserve native container and variant annotations; checked
+conversion enforces element types, ranges, machine profiles, and nested presence
+states at runtime. Errors include the resolved definition name. Source functions
+and implementation bodies have no Hypothesis or pytest dependency.
+
+`lawspec_definition_bodies.py` holds checked logical implementations. Public
+modules under `lawspec_definitions/` provide native entry points grouped by unit.
+Both belong in source directories and are generated-owned. Properties invoke
+those checked bodies directly; definitions do not create adapter stubs. Unit
+modules cannot shadow support modules or another unit's package. Native function
+names such as `str` do not shadow built-ins used by generated validation.
+
+Definition bodies and Python properties share typed expression rendering. Match
+inputs are evaluated once, branches remain lazy, guards short-circuit, and exact
+Decimal arithmetic is independent of Python's ambient rounding context.
+Definitions must pass structural termination and definedness checks. Generic
+definitions specialize to concrete uses. Refined signatures become checked
+contracts, and refinement predicates may call checked definitions.
+
+`tools/python-definitions-integration.mjs` checks standalone source calls,
+properties, incorrect adapters, both machine profiles, custom layouts, compact
+execution, and regeneration protection. The bundled Python corpus passes PEP 8 checks at 79 code columns and 72 prose
+columns. The style audit includes the standalone total-definition fixture.
+
+## Generation and layouts
+
+Hypothesis composes tuples, alternatives, lists, and dependent strategies.
+Recursive generation reserves each field's minimum node budget before sharing
+the remainder. List length and element budgets vary together. Shrinking remains
+native to Hypothesis and preserves the schema and structural size bound.
+Small finite domains are enumerated; empty domains do not pass vacuously.
+
+`lawspec_data.py` and `lawspec_schema.py` belong in the configured source
+directory. `lawspec_data_strategies.py` belongs in the test directory. Configure
+Python's import paths for those directories when using a custom layout.
+Adapters remain user-owned. Unit names cannot shadow generated support modules.
+
+
+Internal checked Core definition contracts now run at native and logical entry
+points. Emission proves the obligations first; argument validation precedes
+ordered preconditions, and result validation precedes postconditions. Contract
+binders map explicitly to body inputs and the checked result. Refined source
+signatures now produce these contracts through template proof and specialization.
+
+`tools/portable-definition-contract-integration.mjs` exercises Python, JavaScript
+and strict TypeScript with both machine profiles and layouts, without property
+frameworks. It also verifies that deliberately corrupted results are rejected.
+The fixture in `test/DefinitionContractFixture.hs` is shared with the JVM checks.
+
+## Checking Python style
+
+Set `LAWSPEC_CORE` to the native compiler, `LAWSPEC_PYTHON` to Python 3.13 or
+later, and `LAWSPEC_PYCODESTYLE` to the `pycodestyle.py` source from version
+2.14.0. Then run `node tools/python-formatting-integration.mjs`. The checker is
+a development dependency; generating and executing runtime code does not
+require it. Optional positional arguments select individual specification files.