docs(book): Add the eunomia datatype-law book (outline)

.github/workflows/book-pages.yml

@@ -0,0 +1,33 @@
+name: Deploy mdBook
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/book/**"
+      - ".github/workflows/book-pages.yml"
+  pull_request:
+    paths:
+      - "docs/book/**"
+      - ".github/workflows/book-pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: book-pages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    # Body owned once by Atlas (ADR 0035); the caller passes only the
+    # built output directory. Enable Pages once per repository under
+    # Settings -> Pages -> Source: GitHub Actions.
+    uses: ryancinsight/atlas/.github/workflows/book-pages.yml@2d071b077d12357c158c1a2eb4854d540b7d6833
+    permissions:
+      contents: read
+      pages: write
+      id-token: write # OIDC Pages artifact flow; no deploy key.
+    with:
+      output-path: target/book/eunomia

docs/book/README.md

@@ -0,0 +1,54 @@
+# eunomia: The Datatype Law of Atlas
+
+Eunomia is the **datatype law** of the Atlas stack: the single source of
+truth for the numeric and scalar datatype vocabulary every other Atlas crate
+computes over. It owns the representations — and nothing else.
+
+In myth, Eunomia ("good order") is the daughter of Themis, the *placement
+law* of the stack ([`themis`](https://github.com/ryancinsight/themis)
+owns NUMA/tier/worker locality). Where themis decides *where* data lives,
+eunomia decides *what* data is.
+
+## What eunomia owns
+
+- **Scalar wrapper types** — `F16`, `Bf16`, `F32`, `F64`, `I8`/`I16`/`I32`,
+  and sub-byte `F4`/`F8`/`Bf4`/`Bf8` — with exact byte-layout guarantees and
+  one native conversion kernel providing exact widening and
+  round-to-nearest-ties-to-even narrowing across every reduced format.
+- **`Complex<T>`** — the native `re + im·i` vocabulary type that replaces the
+  third-party `num_complex::Complex` across the stack.
+- **Packed sub-byte formats** — `Packed4`/`PackedBf4`/`PackedF4` storage,
+  COW buffers, rkyv archival, and SIMD-accelerated unpack.
+- **Conversion lattices** — `CastFrom`/`CastTo`.
+- **Element traits** — `NumericElement`, `FloatElement`.
+- **Scalar field traits** — `RealField`/`ComplexField` (the `nalgebra`
+  scalar-field analogues), so generic numeric code runs over `f32`/`f64` and
+  `Complex` without pulling in nalgebra.
+
+## What it does not own
+
+No computation kernels, allocation, scheduling, or backend code. No
+vector/matrix/geometry types — those live in `leto` (CPU arrays) and
+`hephaestus` (GPU). Execution, SIMD, and allocation belong to `hermes`,
+`mnemosyne`, and `moirai`.
+
+## How to read this book
+
+The book teaches the numeric foundation from first principles:
+
+1. **Part I** — the scalar vocabulary: what each IEEE-754 format means, and
+   when to choose it;
+2. **Part II** — the element and field traits that let generic code run over
+   any scalar;
+3. **Part III** — conversion and casting: how values move between precisions
+   without silent precision loss;
+4. **Part IV** — byte layout and packed formats: the reinterpretation
+   contract that GPU/FFI boundaries rely on;
+5. **Part V** — numeric semantics: relative equality and element operations;
+6. **Part VI** — where the crate sits in the Atlas stack and why the
+   dependency direction points inward.
+
+Each chapter maps the theory onto the crate's public API, and worked examples
+in `examples/` show the abstractions in use. This is the outline edition: the
+chapter structure is complete, and the chapters themselves land as DoR items
+per subsystem.

docs/book/SUMMARY.md

@@ -0,0 +1,38 @@
+# Summary
+
+[Introduction](README.md)
+
+# Part I — The Scalar Vocabulary
+
+- [1. Floating-Point Scalar Types](scalar_types.md)
+  - [Example: Choosing a Precision](examples/choosing_precision.md)
+- [2. Integer Scalar Types](integer_types.md)
+- [3. Complex Numbers](complex_numbers.md)
+  - [Example: Complex Arithmetic in a Solver](examples/complex_arithmetic.md)
+
+# Part II — Element Traits
+
+- [4. NumericElement: The Monomorphization Extension Point](numeric_element.md)
+- [5. FloatElement: The Transcendental Surface](float_element.md)
+- [6. Scalar Fields: RealField and ComplexField](scalar_fields.md)
+- [7. UnitScalar: The Physical-Unit Seam](unit_scalar.md)
+
+# Part III — Conversion and Casting
+
+- [8. The Cast Lattice: CastFrom and CastTo](cast_lattice.md)
+- [9. The Native Conversion Kernel](conversion_kernel.md)
+  - [Example: Rounding Behaviour](examples/rounding_behaviour.md)
+
+# Part IV — Layout and Packing
+
+- [10. Byte Layout: Pod and Zeroable](byte_layout.md)
+- [11. Packed Sub-byte Formats](packed_formats.md)
+
+# Part V — Numeric Semantics
+
+- [12. Relative Equality](relative_equality.md)
+- [13. Element Operations](element_operations.md)
+
+# Part VI — The Crate in the Stack
+
+- [14. Position in the Atlas Stack](stack_position.md)

docs/book/book.toml

@@ -0,0 +1,22 @@
+# mdBook configuration for the eunomia datatype-law book.
+# Build:  mdbook build docs/book      Serve:  mdbook serve docs/book
+# The chapter Markdown lives alongside this file (src = "."); the table of
+# contents and part structure are defined in SUMMARY.md.
+[book]
+title = "eunomia: The Datatype Law of Atlas"
+authors = ["Ryan Clanton"]
+description = "The numeric and scalar vocabulary of the Atlas stack — IEEE-754 scalar wrappers, Complex<T>, packed sub-byte formats, element and field traits, and the native conversion kernel."
+src = "."
+language = "en"
+
+[build]
+build-dir = "../../target/book/eunomia"
+create-missing = false
+
+[output.html]
+no-section-label = false
+mathjax-support = true
+site-url = "/eunomia/"
+git-repository-url = "https://github.com/ryancinsight/eunomia"
+edit-url-template = "https://github.com/ryancinsight/eunomia/edit/main/docs/book/{path}"
+default-theme = "rust"

docs/book/byte_layout.md

@@ -0,0 +1,50 @@
+# 10. Byte Layout: Pod and Zeroable
+
+## Governing equations
+
+Reinterpreting a value as raw bytes is safe only when the type's layout
+permits it. Two facts must hold:
+
+1. **Zeroable** — the all-zero bit pattern is a valid, inhabited value
+   (this excludes types with a validity niche at zero, such as `NonZeroU32`
+   or `&T`).
+2. **Pod** (plain-old-data) — every bit pattern of `size_of::<Self>()`
+   bytes is a valid `Self`, and the type carries no padding or invalid
+   representations.
+
+These layout facts are the datatype-law statement of *which representations
+are safe to reinterpret as bytes* — the contract GPU device buffers, FFI
+boundaries, and serialization all rely on.
+
+## The crate's abstraction
+
+Eunomia owns the native `Zeroable`/`Pod` vocabulary rather than borrowing it
+from `bytemuck`:
+
+```rust,ignore
+pub unsafe trait Zeroable: Sized {
+    fn zeroed() -> Self { /* SAFETY: Self: Zeroable */ }
+}
+
+pub unsafe trait Pod: Sized {
+    // any bit pattern of size_of::<Self>() bytes is a valid Self
+}
+```
+
+- **`unsafe` marker traits.** The compiler cannot verify the layout facts
+  they assert; every impl carries a `// SAFETY:` justification, and the
+  scalar wrappers' `const _` size/alignment assertions pin the layout the
+  impls rely on.
+- **`bytemuck` bridge.** The `bytemuck` feature bridges these to
+  `bytemuck::{Pod, Zeroable}` for GPU/FFI boundaries that fix that contract.
+- **Whole-vocabulary coverage.** `F16`/`Bf16`/`F32`/`F64`/`F4`/`F8`/`Bf4`/
+  `Bf8`/`I8`/`I16`/`I32` and `Complex<T>` (when `T` is) are `Pod`/`Zeroable`
+  — every value is a valid byte string.
+
+## Outline of this chapter
+
+- Why layout facts gate byte reinterpretation
+- `Zeroable` and the zero-niche exclusion
+- `Pod`: no padding, no invalid bit patterns
+- The `// SAFETY:` discipline and the `const _` layout pins
+- The `bytemuck` bridge for GPU/FFI boundaries

docs/book/cast_lattice.md

@@ -0,0 +1,48 @@
+# 8. The Cast Lattice: CastFrom and CastTo
+
+## Governing equations
+
+Converting a value from one numeric representation to another is a *cast*.
+Rust's `as` operator provides the primitive semantics: float-to-integer
+conversions truncate toward zero and saturate values outside the destination
+range. The lattice problem is to express "cast any scalar to any other
+scalar" generically, so a kernel can accept an element of one precision and
+deliver an element of another without naming every pair.
+
+## The crate's abstraction
+
+`CastFrom`/`CastTo` form the generic casting lattice:
+
+```rust,ignore
+pub trait CastFrom<T>: Copy {
+    fn cast_from(val: T) -> Self;
+}
+
+pub trait CastTo: Copy {
+    fn cast_to<U>(self) -> U
+    where
+        U: CastFrom<Self>,
+    {
+        U::cast_from(self)
+    }
+}
+```
+
+- **Primitive semantics preserved.** Primitive numeric implementations
+  follow Rust's `as` conversion semantics — truncation toward zero for
+  float-to-integer, saturation outside the destination range.
+- **One direction, both spellings.** `CastFrom` is the primitive direction;
+  `CastTo` is the blanket-enabled reverse spelling (`T::cast_from(self)`)
+  so callers can write `x.cast_to::<F32>()` or `F32::cast_from(x)`.
+- **Lattice, not lossless promise.** A cast may lose precision — the lattice
+  says *how*, deterministically, not that it cannot lose. Precision-correct
+  conversions between float formats go through the native kernel (§9).
+
+## Outline of this chapter
+
+- The cast lattice: every scalar to every scalar, generically
+- `as` semantics: truncation and saturation on the primitive boundaries
+- `CastFrom` as the primitive direction, `CastTo` as the reverse spelling
+- Lattice vs lossless conversion — when to use `cast_from` vs the native
+  kernel
+- Generic kernels converting between precisions at their boundaries

docs/book/complex_numbers.md

@@ -0,0 +1,50 @@
+# 3. Complex Numbers
+
+## Governing equations
+
+A complex number is the pair
+
+$$z = \text{re} + \text{im}\cdot i,$$
+
+with arithmetic defined field-wise for `Add`/`Sub`/`Neg` and by the complex
+product and quotient for `Mul`/`Div`:
+
+$$(a + bi)(c + di) = (ac - bd) + (ad + bc)i.$$
+
+Complex values appear throughout Atlas where real arithmetic is insufficient
+— phasors in acoustics, spectra in optics, and the eigen/signal surfaces in
+linear algebra.
+
+## The crate's abstraction
+
+`Complex<T>` is the SSOT vocabulary type for `re + im·i`, replacing the
+third-party `num_complex::Complex` across the stack:
+
+```rust,ignore
+#[repr(C)]
+pub struct Complex<T> {
+    pub re: T,
+    pub im: T,
+}
+
+pub type Complex32 = Complex<f32>;
+pub type Complex64 = Complex<f64>;
+```
+
+- **Layout-compatible.** `#[repr(C)]` `{ re, im }` with `bytemuck::Pod`/
+  `Zeroable` when `T` is, so values round-trip through GPU device buffers and
+  FFI boundaries identically to `num_complex::Complex`.
+- **Field-wise semantics.** The imaginary component is *quadrature*, not a
+  second physical unit — the `UnitScalar` seam (§7) scales complex values
+  componentwise by a real coefficient.
+- **Floating-point surface.** The complex module carries the arithmetic
+  (`ops`), constants (`consts`), the float surface (`float`), and reduction
+  helpers (`reduce`).
+
+## Outline of this chapter
+
+- Complex field arithmetic: `Add`/`Sub`/`Neg`/`Mul`/`Div`
+- `#[repr(C)]` layout and the FFI/GPU round-trip guarantee
+- `Complex32`/`Complex64` aliases and interop with the numeric stack
+- The quadrature rule: one observable unit, no imaginary SI unit
+- Worked example in [Complex Arithmetic in a Solver](examples/complex_arithmetic.md)

docs/book/conversion_kernel.md

@@ -0,0 +1,50 @@
+# 9. The Native Conversion Kernel
+
+## Governing equations
+
+Converting between IEEE-754 formats of different widths is the operation
+that decides whether a reduced-precision pipeline loses accuracy silently.
+The correct rounding rule is round-to-nearest, ties-to-even (RNE): a real
+value is mapped to the nearest representable value, and exact ties map to
+the neighbour with an even significand. This bounds the conversion error at
+half an ulp of the destination format — the smallest achievable.
+
+## The crate's abstraction
+
+Eunomia's conversion module is the native soft-float conversion SSOT — one
+generic const-parameterized kernel converts between `f32` and any reduced
+IEEE-754 binary format `(E, M)`:
+
+```rust,ignore
+use eunomia::convert::{narrow, widen};
+
+// binary16 round-trips 1.0 exactly.
+let one_f16 = narrow::<5, 10>(1.0f32.to_bits());
+assert_eq!(one_f16, 0x3C00);
+assert_eq!(f32::from_bits(widen::<5, 10>(one_f16)), 1.0);
+```
+
+| Format | `E` | `M` | Bias |
+| --- | --- | --- | --- |
+| `binary16` (`F16`) | 5 | 10 | 15 |
+| `bfloat16` (`Bf16`) | 8 | 7 | 127 |
+
+- **One implementation, all precisions.** `narrow::<E, M>` / `widen::<E, M>`
+  are const-parameterized over the format geometry, so every precision shares
+  one authoritative, monomorphized implementation — including the sub-byte
+  formats' conversions.
+- **RNE guaranteed.** Round-to-nearest, ties-to-even is baked into the
+  kernel; finite-variant kernels (`narrow_finite`/`widen_finite`) are
+  provided where the format has no infinity/NaN encoding.
+- **Replacement for `half`.** This kernel replaces `half`'s `f16`/`bf16`
+  conversions; `half` remains only as a dev-only differential oracle in
+  eunomia's own conversion tests.
+
+## Outline of this chapter
+
+- Round-to-nearest-ties-to-even and the half-ulp error bound
+- Format geometry as const parameters `(E, M)`
+- `narrow`/`widen` and the finite variants
+- Why one kernel replaces the `half` crate (and how `half` survives as a
+  test oracle)
+- Worked example in [Rounding Behaviour](examples/rounding_behaviour.md)

docs/book/element_operations.md

@@ -0,0 +1,34 @@
+# 13. Element Operations
+
+## Governing equations
+
+Element operations are the pointwise arithmetic of the scalar vocabulary —
+the `Add`/`Sub`/`Mul`/`Div` (and their `Assign` forms) that kernels assume
+of any element. For floats these are IEEE-754 operations with their rounding
+rules; for integers, two's-complement wrap arithmetic; for complex values,
+the field operations of §3.
+
+## The crate's abstraction
+
+The `ops` module provides the operation impls across the vocabulary:
+
+- `ops::floats` — arithmetic for the float wrappers (`F16`/`Bf16`/`F32`/
+  `F64` and the sub-byte formats), with float-semantic ordering.
+- `ops::ints` — arithmetic for `I8`/`I16`/`I32`, with exact wrap semantics.
+
+Together with the operator supertraits on `NumericElement` (§4), this gives
+generic kernels a complete, uniform arithmetic surface:
+
+```rust,ignore
+fn l2_norm_sq<T: NumericElement>(x: T, y: T) -> T {
+    x * x + y * y   // Add, Mul, and AddAssign are assumed by the trait
+}
+```
+
+## Outline of this chapter
+
+- The element arithmetic surface: `Add`/`Sub`/`Mul`/`Div`/`Assign`
+- Float operations and their rounding rules
+- Integer wrap arithmetic and why it is exact
+- Complex field operations
+- Building kernels over the operator supertraits of `NumericElement`