lawspec 0.14.0 → 0.15.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/PRIMITIVES.md DELETED
@@ -1,150 +0,0 @@
1
- # LawSpec scalar reference (0.14.0)
2
-
3
- A scalar has a declared domain, checked literals, equality, property inputs, and
4
- boundary fixtures. General collections, objects, pointers, and type-only constructs
5
- such as `never` are outside this release.
6
-
7
- | Domain | Types | Representation and equality |
8
- | --- | --- | --- |
9
- | Boolean | `Bool` | `true` or `false`; distinct from integers |
10
- | Signed integers | `Int8`, `Int16`, `Int32`, `Int64` | −2^(bits−1) through 2^(bits−1)−1 |
11
- | Unsigned integers | `UInt8`, `UInt16`, `UInt32`, `UInt64` | 0 through 2^bits−1 |
12
- | Machine integers | `IntSize`, `UIntSize`, `UIntPtr` | Explicit 32- or 64-bit profile; no pointer operations |
13
- | Abstract integers | `Integer` | Exact mathematical values, independent of storage width |
14
- | Arbitrary integers | `BigInt`, `BigUInt` | Unbounded integer; BigUInt is nonnegative |
15
- | Exact fractions | `Decimal`, `Rational` | Finite coefficient × 10^exponent; reduced numerator / positive denominator |
16
- | Floating point | `Float32`, `Float64` | IEEE binary32 / binary64; NaN differs from itself, signed zeros compare equal |
17
- | Complex | `Complex64`, `Complex128` | Two Float32 / Float64 components; componentwise IEEE equality |
18
- | Characters | `Char`, `CodePoint`, `CodeUnit16` | Unicode scalar; code point including surrogates; arbitrary 16-bit unit |
19
- | Sequences | `Text`, `CodePointText`, `Utf16Text`, `Bytes` | Unicode scalars; code points; UTF-16 units; octets |
20
- | Identity | `Symbol` | Identity, independent of description |
21
- | Absence | `Unit`, `Null`, `Undefined` | Three distinct singleton domains |
22
- | Presence | `Nullable a`, `Optional a` | Null or a present scalar; Undefined or a present scalar |
23
-
24
- `Char` and `Text` exclude U+D800–U+DFFF. Code points range from 0 through
25
- 0x10FFFF. UTF-16 units range from 0 through 65535. Bytes range from 0 through
26
- 255. Raw constructors preserve units without decoding or replacement.
27
-
28
- ## Literals and arithmetic
29
-
30
- Integer literals inherit a declared parameter or example type, otherwise they
31
- have type `Integer`. Decimal literals default to exact `Decimal`. An annotation
32
- supplies context: `(127 :: Int8)`, `(0.1 :: Float32)`. Literals outside the
33
- contextual domain are rejected during checking.
34
-
35
- ```lawspec
36
- unit example.increment
37
- successor :: (x :: Int8) -> (result :: Integer where result == x + 1)
38
- law `promotes instead of wrapping` is
39
- definition is `for all` (x :: Int8) . successor x = x + 1 end
40
- example `maximum input` is x = 127 expect successor x = 128 end
41
- end
42
- ```
43
-
44
- Integer `+`, `-`, `*`, and negation produce `Integer`. Decimal dominates integer
45
- operands; Rational dominates exact operands. Exact `/` always produces Rational.
46
- `prelude.quot` truncates toward zero, and `prelude.rem a b` satisfies
47
- `a = quot a b * b + rem a b`. Division by zero fails when evaluated. Implication
48
- guards short-circuit, including arithmetic and adapter calls.
49
-
50
- Float32 operations round at binary32 precision; Float64 operations use binary64.
51
- Mixed inexact operations widen to the greater component precision and to complex
52
- when needed. Exact and inexact variables require explicit conversion:
53
- `prelude.Float32 x`, `prelude.Float64 x`, `prelude.Rational x`,
54
- `prelude.Decimal x`, or `prelude.Int8 x` (and the other numeric type names).
55
- Fractional and out-of-range conversions to integers fail. A Rational conversion
56
- to Decimal must terminate. Nonfinite floats cannot convert to exact numbers.
57
-
58
- `prelude.round value scale` rounds an exact value to a specified number of decimal
59
- places using ties-to-even. Negative scales round to powers of ten. Decimal
60
- operations use exact arithmetic, independent of Python's decimal context or other
61
- ambient rounding settings.
62
-
63
- Comparison operators are `<`, `<=`, `>`, `>=`, `==`, and `!=`. Numeric comparisons
64
- follow arithmetic's exact/inexact restriction. Complex numbers are not ordered.
65
- `=` remains a law assertion. `==` and `!=` produce Bool and also support other
66
- scalar domains. Multiplication and division bind more tightly than addition and
67
- subtraction. Application and composition retain their existing syntax.
68
-
69
- An adjacent sign remains an argument, as in `f -42`. Write `x - 42` for
70
- subtraction, or parenthesize arithmetic arguments: `f (x - 42)`.
71
-
72
- ## Constructors and helpers
73
-
74
- | Expression | Meaning |
75
- | --- | --- |
76
- | `decimal(123, -2)` | Exact 1.23 |
77
- | `rational(1, 2)` | Exact 1/2 |
78
- | `complex64(1, -2)`, `complex128(1, -2)` | Complex components at declared precision |
79
- | `float32Bits("7fc00000")` | A binary32 NaN |
80
- | `float64Bits("7ff0000000000000")` | Positive binary64 infinity |
81
- | `float32Bits("80000000")` | Negative binary32 zero |
82
- | `char(128512)` | Supplementary Unicode scalar |
83
- | `codePoint(55296)` | Surrogate code point |
84
- | `codeUnit16(55296)` | Lone UTF-16 surrogate unit |
85
- | `codePoints([55296, 128512])` | Raw code-point sequence |
86
- | `utf16([55296])` | Raw UTF-16 sequence |
87
- | `bytes([0, 128, 255])` | Raw octets |
88
- | `symbol("fixture-id", "description")` | Identity shared by the same ID within an example |
89
- | `unitValue`, `null`, `undefined` | Distinct singleton values |
90
- | `nullable(7)`, `optional(nullable(7))` | Present states, including nested states |
91
- | `prelude.isNaN x`, `prelude.isInfinite x`, `prelude.isFinite x` | Float classification |
92
- | `prelude.isNegativeZero x` | Float sign-bit classification |
93
- | `prelude.real z`, `prelude.imag z` | Complex component access |
94
-
95
- For `Optional (Nullable Int8)`, `undefined`, `optional(null)`, and
96
- `optional(nullable(7))` are different values. Tagged support types preserve this
97
- nesting, including on targets whose native null/optional types would collapse it.
98
-
99
- ## Target bridges and generated runtime
100
-
101
- Existing Int32/Text/Bool-only specifications retain their adapter signatures.
102
- Scalar specifications use native representations where the bridge implements the
103
- whole domain, and generated support values elsewhere:
104
-
105
- - Python: native int, bool, str, bytes, float, complex, Decimal and Fraction;
106
- `Raw`, `Presence`, `Symbol`, and absence support values.
107
- - JavaScript/TypeScript: number for small integers and floats, bigint for larger
108
- integers, native strings, Uint8Array bytes and symbols; Decimal, Rational, Complex, Raw and
109
- Presence support types. Unit is normalized from a void return.
110
- - Java/Kotlin: native signed primitives and widened unsigned primitives,
111
- BigInteger, BigDecimal, strings, byte arrays, code points, UTF-16 units and floating primitives; `LawSpecRuntime.Value`
112
- for remaining domains. Unit-returning adapters normalize native void/Unit.
113
- - Go: native integer widths, machine integers, floats and complex values,
114
- `math/big.Int` and `math/big.Rat` (exported aliases), strings, runes, byte arrays and UTF-16 arrays;
115
- `LawSpecValue` for remaining domains.
116
- - Haskell: native fixed integers, Integer, Rational, Float, Double, Complex, Char, Text, ByteString and `()`;
117
- the `Scalar` support type for remaining domains. `Text` maps to `Data.Text.Text`,
118
- not Haskell’s linked-list `String` (`[Char]`). General list types such as `[Char]`
119
- are outside this scalar release.
120
-
121
- Input bridges check primitive bounds before native calls. Result bridges validate
122
- returned values. In particular, Text bridges reject invalid Unicode rather than
123
- repairing it. Use raw domains when preserving arbitrary bytes or UTF-16 units.
124
-
125
- The runtime sources are emitted separately from framework-specific tests. They
126
- have no property-testing or assertion-library dependencies. Runtime files are
127
- generated-owned **source** artifacts; adapters are user-owned source artifacts.
128
- Custom source/test directories and generation manifests preserve that distinction.
129
- Haskell scalar projects require the standard `bytestring` package in their library
130
- dependencies (included by new project templates).
131
- Kotlin uses the shared Java runtime under `src/main/java` by default; custom
132
- projects must include the configured source directory in their Java source set.
133
-
134
- ## Machine profiles
135
-
136
- Set `"machineBits": 32` or `64` in `lawspec.json`, the compiler request, or use
137
- `--machine-bits 32`. The default is 64. Bounds, examples, generators, and bridges
138
- use this profile. Go and Haskell native machine-sized bridges report an
139
- architecture mismatch when the native word size differs. Fixed-width types remain
140
- portable across architectures.
141
-
142
- The bundled `scalars.lawspec`, `scalar_catalog.lawspec`, and
143
- `scalar_adapters.lawspec` contain explicit fixtures for every scalar family.
144
- `tools/scalar-reference.py` produces independent Fraction-based conformance
145
- vectors; `lawspec-acceptance scalar` executes them across the eight targets and
146
- verifies that incorrect adapters are detected.
147
-
148
-
149
- Refinements, parameterized domains, abstract native integer results, and executable
150
- function contracts are described in [REFINEMENTS.md](REFINEMENTS.md).
package/PYTHON.md DELETED
@@ -1,152 +0,0 @@
1
- # Python backend
2
-
3
- Python output follows [PEP 8](https://peps.python.org/pep-0008/): four-space
4
- indentation, a 79-column code target, 72-column prose comments/docstrings, and
5
- two blank lines between top-level definitions. Explicit `--minify` permits
6
- compact layout while preserving Python indentation and semantics.
7
- `tools/python-formatting-integration.mjs` checks generated runtime, adapter,
8
- definition, and test files with pycodestyle 2.14.0 at both machine widths. It
9
- also compares readable and compact syntax trees, including literal contents.
10
-
11
- Use Python 3.13 or later. Generated tests use Hypothesis; generated data classes,
12
- scalar operations, and schema validation do not depend on a test framework.
13
-
14
- ## Native structural values
15
-
16
- | LawSpec type | Adapter representation |
17
- | --- | --- |
18
- | `List a` | `list[A]` |
19
- | `Maybe a` | `lawspec_schema.Maybe[A]`, with `Nothing` and `Just` variants |
20
- | `Either a b` | `lawspec_schema.Either[A, B]`, with `Left` and `Right` variants |
21
- | User-defined products and sums | Named generic dataclasses in `lawspec_data` |
22
- | `Nullable a`, `Optional a` | Tagged `lawspec_runtime.Presence` values |
23
-
24
- `Nothing()` differs from `Just(Nothing())`. `Left(value)` differs from
25
- `Right(value)`. These algebraic variants are separate from the interoperability
26
- states represented by `Nullable`, `Optional`, `Null`, and `Undefined`.
27
-
28
- For example, this declaration:
29
-
30
- ```lawspec
31
- type Tree (a :: Type) is
32
- Leaf value :: a
33
- Branch children :: List (Tree a)
34
- end
35
- ```
36
-
37
- produces a generic `Tree` base and `TreeLeaf` and `TreeBranch` dataclasses. A
38
- product has one variant: `Pair` with constructor `Pair` produces `PairPair`.
39
- When names conflict across units or between types and variants, the compiler
40
- plans distinct names using their Core identities. Use the emitted declarations
41
- and adapter annotations as the authoritative names.
42
-
43
- Native pattern matching works on the generated variants:
44
-
45
- ```python
46
- import lawspec_data as data
47
-
48
-
49
- def count_leaves(tree: data.Tree[int]) -> int:
50
- match tree:
51
- case data.TreeLeaf():
52
- return 1
53
- case data.TreeBranch(children=children):
54
- return sum(count_leaves(child) for child in children)
55
- raise TypeError("unknown Tree variant")
56
- ```
57
-
58
- Classes are frozen and use slots. Container payloads are copied when crossing
59
- adapter boundaries, so modifying a native list does not change another use of
60
- the logical test input. An abstract base cannot be directly constructed; empty
61
- types acquire no artificial variant.
62
-
63
- LawSpec equality uses schema-directed comparisons, including IEEE NaN and
64
- signed-zero rules and Symbol identity. Generated dataclasses do not derive
65
- Python field equality, whose container shortcuts can change those rules.
66
-
67
- ## Checked boundaries
68
-
69
- Generated calls validate input values, convert them to native classes, call the
70
- adapter, and validate its result. A field extracted from a native product can
71
- be returned directly from an adapter with the corresponding LawSpec result
72
- type. The same representation is used for nested and standalone containers.
73
-
74
- Diagnostics identify constructor fields and list indices. Checks distinguish
75
- Bool from integers, enforce primitive ranges under the selected `machineBits`,
76
- reject invalid scalar text, and preserve raw code units, code points, and bytes.
77
- Preconditions and postconditions operate on validated logical values.
78
-
79
- ## Total definitions
80
-
81
- Checked total definitions emit reusable Python functions separately from adapters:
82
-
83
- ```lawspec
84
- unit example.total
85
-
86
- definition increment (x :: Int8) :: BigInt is x + 1 end
87
- ```
88
-
89
- ```python
90
- from lawspec_definitions.example import total
91
-
92
- symbols = {}
93
- assert total.increment(symbols, 127) == 128
94
- ```
95
-
96
- The first argument is the Symbol fixture context shared within an example.
97
- Public signatures preserve native container and variant annotations; checked
98
- conversion enforces element types, ranges, machine profiles, and nested presence
99
- states at runtime. Errors include the resolved definition name. Source functions
100
- and implementation bodies have no Hypothesis or pytest dependency.
101
-
102
- `lawspec_definition_bodies.py` holds checked logical implementations. Public
103
- modules under `lawspec_definitions/` provide native entry points grouped by unit.
104
- Both belong in source directories and are generated-owned. Properties invoke
105
- those checked bodies directly; definitions do not create adapter stubs. Unit
106
- modules cannot shadow support modules or another unit's package. Native function
107
- names such as `str` do not shadow built-ins used by generated validation.
108
-
109
- Definition bodies and Python properties share typed expression rendering. Match
110
- inputs are evaluated once, branches remain lazy, guards short-circuit, and exact
111
- Decimal arithmetic is independent of Python's ambient rounding context.
112
- Definitions must pass structural termination and definedness checks. Generic
113
- definitions specialize to concrete uses. Refined signatures become checked
114
- contracts, and refinement predicates may call checked definitions.
115
-
116
- `tools/python-definitions-integration.mjs` checks standalone source calls,
117
- properties, incorrect adapters, both machine profiles, custom layouts, compact
118
- execution, and regeneration protection. The bundled Python corpus passes PEP 8 checks at 79 code columns and 72 prose
119
- columns. The style audit includes the standalone total-definition fixture.
120
-
121
- ## Generation and layouts
122
-
123
- Hypothesis composes tuples, alternatives, lists, and dependent strategies.
124
- Recursive generation reserves each field's minimum node budget before sharing
125
- the remainder. List length and element budgets vary together. Shrinking remains
126
- native to Hypothesis and preserves the schema and structural size bound.
127
- Small finite domains are enumerated; empty domains do not pass vacuously.
128
-
129
- `lawspec_data.py` and `lawspec_schema.py` belong in the configured source
130
- directory. `lawspec_data_strategies.py` belongs in the test directory. Configure
131
- Python's import paths for those directories when using a custom layout.
132
- Adapters remain user-owned. Unit names cannot shadow generated support modules.
133
-
134
-
135
- Internal checked Core definition contracts now run at native and logical entry
136
- points. Emission proves the obligations first; argument validation precedes
137
- ordered preconditions, and result validation precedes postconditions. Contract
138
- binders map explicitly to body inputs and the checked result. Refined source
139
- signatures now produce these contracts through template proof and specialization.
140
-
141
- `tools/portable-definition-contract-integration.mjs` exercises Python, JavaScript
142
- and strict TypeScript with both machine profiles and layouts, without property
143
- frameworks. It also verifies that deliberately corrupted results are rejected.
144
- The fixture in `test/DefinitionContractFixture.hs` is shared with the JVM checks.
145
-
146
- ## Checking Python style
147
-
148
- Set `LAWSPEC_CORE` to the native compiler, `LAWSPEC_PYTHON` to Python 3.13 or
149
- later, and `LAWSPEC_PYCODESTYLE` to the `pycodestyle.py` source from version
150
- 2.14.0. Then run `node tools/python-formatting-integration.mjs`. The checker is
151
- a development dependency; generating and executing runtime code does not
152
- require it. Optional positional arguments select individual specification files.