lawspec 0.9.0 → 0.11.0

package/API-MIGRATION.md

@@ -1,8 +1,15 @@
-# Compiler API migration: schema 2 → schema 3
+# Compiler API migration
+
+This document covers the published schema-3 interface and the schema-4 native
+binding interface introduced in 0.10. See
+[schema 4 native bindings](#schema-4-native-bindings) when adding
+application types or generators to an existing project.
+
+## Schema 2 → schema 3
 
 LawSpec 0.8 introduced API schema version **3**, which 0.9 continues to use.
 Requests may omit `schemaVersion` or
-send `3`. An explicit `2` (or any other version) receives a request diagnostic;
+send `3`. An explicit `2` receives a request diagnostic;
 it is never silently reinterpreted. LawSpec specification syntax remains compatible.
 The generated `index.d.ts` describes the public protocol. Internal Haskell
 constructors and record fields are no longer the wire format.
@@ -202,3 +209,72 @@ definition and constructor contracts support recursive payload proof facts. Cons
 matches/constructions participate in the constructor dependency-cycle check.
 The TypeScript declarations now include both
 `allElements` and `allPayloads`; exhaustive visitors should handle both.
+
+## Schema 4 native bindings
+
+Binding requests use `schemaVersion: 4`. Schema-3 requests remain supported for
+existing specifications without bindings. This negotiation is deliberate: an
+older compiler must reject a binding request rather than silently use generated
+types in place of application types.
+
+The JavaScript API selects schema 4 when `nativeBindings` is provided, unless an
+explicit `schemaVersion` overrides it. A nonempty binding configuration with
+schema 3 is rejected. Results and diagnostics report the negotiated schema.
+
+`nativeBindings` contains optional `types`, `functions`, `generators`,
+`rustCrate` and `goImports` fields. Native symbols use arrays of identifier segments; unknown
+configuration fields are rejected. See [the native-binding scope and current
+implementation status](NATIVE-BINDINGS.md). Rust, Python, JavaScript, TypeScript,
+Java and Kotlin support application type bridges and native generator factories.
+Go supports package-local and imported application types with native Rapid
+factories. Haskell supports application types and native Hedgehog factories.
+Custom codec hooks are available on all eight targets; see the native-binding
+reference for target-specific signatures and current integration limitations.
+
+### Go imports in schema 4 binding requests
+
+`nativeBindings.goImports` is an optional array of `{alias, path}` entries.
+References such as `["domain", "Price"]` select exported names from that alias's
+Go import path. One-component references continue to select package-local names.
+Types, constructors, functions and generator factories share the import table;
+only imports used by each generated file are emitted. Other targets reject this
+option. Paths must be module import paths without empty or traversal segments.
+
+Go reserves local application symbols before generating canonical data names.
+Colliding generated families receive a fresh `Canonical` prefix (and a numeric
+suffix in that prefix if necessary). Logical type and constructor IDs do not
+change. Hooks that name generated data types should use the emitted canonical
+names; imported application types keep their original names.
+
+### Codec hooks in schema 4 type bindings
+
+`NativeTypeBinding` now accepts either `constructors` or
+`codec: {toNative: NativeReference, fromNative: NativeReference}`. Both hook
+references are required and constructor mappings cannot be combined with hooks.
+The canonical side uses generated LawSpec data types, while the native side uses
+`native`; generic hooks receive one directional child converter per type argument.
+All eight targets implement emission. Go hooks return `(value, error)` and the
+verified fixture places them beside the generated canonical types to avoid package
+import cycles. See `NATIVE-BINDINGS.md` for signatures and
+validation behavior.
+
+### Native-binding ownership transitions
+
+Existing user adapters are protected when their paths become generated bridges.
+Move application implementations into the configured native modules and save the
+old adapters elsewhere before adopting bindings. Removing bindings preserves the
+old bridge as user-owned content and reports a required adapter update; it does
+not silently replace that content with a stub. Generated layout changes do not
+move application-owned model, hook or factory files. See `NATIVE-BINDINGS.md` for
+the migration sequence and all-target filesystem acceptance checks.
+
+### Optional generator scaffolds in schema 4
+
+`NativeGeneratorBinding` accepts `stub?: boolean`, defaulting to false. Python,
+Rust, JavaScript, TypeScript, Java, Kotlin, Go and Haskell support `stub: true` to
+create a user-owned factory in the test directory. Go
+requires a package-local factory and a quantified use to determine placement.
+Existing factory files remain untouched. Factory signature changes
+use the existing `adapterUpdates` reporting channel. See `NATIVE-BINDINGS.md`
+for grouping, module collision checks, and layout
+migration behavior.

package/HASKELL.md

@@ -41,6 +41,7 @@ have no constructors. They can appear in inhabited containers such as
 | `Nullable a` | `LS.Nullable a`, with `NullValue` and `NullableValue` |
 | `Optional a` | `LS.Optional a`, with `UndefinedValue` and `OptionalValue` |
 | `BigInt`, `BigUInt`, `Integer` | `Integer`, with domain checks |
+| `Integer` adapter result | `LS.IntegerValue`, built from any `Integral` with `LS.integerValue` |
 | `Decimal` | `LS.Decimal`, wrapping an exact finite base-ten `Rational` |
 | `Rational` | `Rational` |
 | `Complex64`, `Complex128` | `Complex Float`, `Complex Double` |

package/KOTLIN.md

@@ -61,6 +61,11 @@ arbitrary integers, and machine-profile integers use `BigInteger` with explicit
 domain checks. These portable machine-profile representations do not bind a
 host machine-sized primitive.
 
+An adapter whose result is the abstract `Integer` returns Kotlin `Number`.
+`Integer` is the top of the integral tower, so an implementation may return
+`Int`, `Long` or `BigInteger`; the result bridge rejects non-integral values
+such as `Double` and checks the logical domain. Arguments remain `BigInteger`.
+
 Decimal uses exact `BigDecimal`; Rational uses the normalized
 `LawSpecRuntime.Ratio`. Complex components use `LawSpecRuntime.Complex`, with
 Float32 precision validated for Complex64. Raw code-point text uses `IntArray`,

package/LANGUAGE.md

@@ -1,4 +1,4 @@
-# LawSpec language and compiler boundary (0.9)
+# LawSpec language and compiler boundary (0.11)
 
 LawSpec describes portable laws, concrete examples, and adapter contracts. The
 compiler is written in Haskell. Rust is an output backend alongside Java, Python,
@@ -102,7 +102,8 @@ 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.
+Constructors may refine natural indices; see [indexed families](#natural-indexed-families).
+GADT result signatures that refine type arguments are not supported.
 
 Equality is structural and type-directed, including named fields and nested
 containers. Native public declarations retain their names and type parameters;
@@ -129,6 +130,58 @@ of recursive and nonrecursive named type constructors are supported; see
 constructor fields use checked constructor contracts. Recursive payload predicates
 follow stored type arguments and preserve outer dependent inputs.
 
+## Natural-indexed families
+
+A data declaration may take `Natural` parameters. Each constructor states how it
+determines them with `where <index> = <expression>`:
+
+```lawspec
+type Vec (n :: Natural) (a :: Type) is
+  | VNil where n = 0
+  | VCons head :: a tail :: Vec m a where n = m + 1
+end
+
+type Tree (n :: Natural) (a :: Type) is
+  | Tip where n = 0
+  | Bin left :: Tree l a value :: a right :: Tree r a where n = l + r + 1
+end
+
+append :: (xs :: Vec n Int8) -> (ys :: Vec m Int8) -> (r :: Vec (n + m) Int8)
+zip :: (xs :: Vec n Int8) -> (ys :: Vec n Bool) -> (r :: Vec n Bool)
+```
+
+Index expressions are sums of natural literals and index variables. A variable
+such as `m` is bound by the field whose type mentions it, and every index needs
+exactly one equation in every constructor. `Natural` is also an ordinary value
+type: an unbounded integer that is at least zero.
+
+Indices are evidence, not a second type system. The compiler elaborates a family
+before inference into three ordinary declarations:
+
+- erased data `Vec a` with the same constructors, which is the native
+  representation on every target;
+- a checked structural measure for each index, named `<index>Of<Type>` (here
+  `nOfVec` and `nOfTree`), recomputed from the constructor equations;
+- a refinement, so `Vec e a` in any signature or quantifier means
+  `(v :: Vec a where nOfVec v == e)`.
+
+`append` above is therefore an adapter contract: its result must have length
+`nOfVec xs + nOfVec ys`, and a native implementation that drops an element
+fails with the postcondition. An index variable that is otherwise unbound, like
+`n` and `m` in `append`, is implicit. It is determined by the first binder whose
+family type mentions it alone, and later occurrences read that binder's measure.
+Implicit indices must not first appear inside an expression, and a result cannot
+introduce one.
+
+Generation follows the index. For a free index, as in `append`, values come from
+the erased type and the index is their measure. For a fixed index (`Vec 3 Int8`)
+or a shared one (`zip`'s `ys`), the target is solved backwards through the
+constructor equations: `VCons` for `n = 3` needs a tail with index 2, and `Bin`
+splits `n - 1` between its subtrees. Samples are constructed, not filtered, and
+shrinking stays within the index on every target. The same planning applies to
+any user-written measure over declared data whose branches are a constant plus
+the same measure of that branch's fields.
+
 ## Total definitions
 
 A unit can supply an implementation as a checked total definition:
@@ -332,14 +385,20 @@ 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.
+## Beyond 0.11
+
+Natural-indexed families are implemented in 0.11 by elaboration to erased data,
+measures and refinements. GADTs that refine type arguments, non-linear or
+non-natural indices, index equalities between sibling fields (such as perfect
+trees whose subtrees share one index), and general dependent types remain future
+work. The Core type model distinguishes type arguments from index arguments, but
+that representation is not a claim that arbitrary dependent programs are
+accepted.
+External type bindings and custom generator bindings are implemented in the
+0.10 release; see [the binding reference](NATIVE-BINDINGS.md) for their
+interface and acceptance status. They configure native representations alongside
+the typed testing plan and do not change source-language typing or equality.
+Cross-unit packages remain future work.
 
 ## Generated project formatting
 
@@ -357,5 +416,5 @@ 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
+See [the release notes](RELEASE-0.10.md) for compatibility and scope, and the target
 guides for formatting verification and native representation details.