Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -597,4 +597,6 @@ MIT

**Wave 22 (2026-05-22):** phi-Adam optimizer import — [`rings/ring-095-rust`](rings/ring-095-rust) lands the eighth honestly-authored Wave-11 crate (808 LOC, 25 tests). Mirrors `specs/ml/optimizer/{adam, adamw}.t27`: spec constants byte-for-byte (`DEFAULT_LEARNING_RATE=1e-3`, `DEFAULT_BETA1=0.9`, `DEFAULT_BETA2=0.999`, `DEFAULT_WEIGHT_DECAY=0.01`, `DEFAULT_EPSILON=1e-8`, `PHI_BETA1 = 0.9/phi ~= 0.556`, `PHI_BETA2 = 0.999/phi ~= 0.617`); `AdamWConfig` with `defaults()` (classic AdamW) and `phi_preset()` (phi-damped betas) constructors; caller-owned `AdamWState<'_>` (no allocation); spec-named helpers (`compute_bias_correction`, `update_first_moment`, `update_second_moment`, `apply_weight_decay`, `compute_update`); full `step()` orchestrator with decoupled weight decay, bias-corrected `lr_t = lr * sqrt(1 - beta2^t) / (1 - beta1^t)`, moment recurrences, AMSGrad max-of-v, and the parameter update. Private no_std math (`pow_u64`, `sqrt_newton`) bypasses libm. `phi_adam_phi_identity_via_betas` is the **seventh cross-kernel anchor test** in the project, routing `phi^2 + 1/phi^2 = 3` through the optimizer's `pow_u64` and through the phi-damped moment update `m_1 = (1 - 0.9/phi) * phi = phi - 0.9`. Wave-11 narrative claimed 659 LOC; honest measurement is 808 LOC. All 25 tests green on Rust 1.83.0. See [COMPILE_STATUS](rings/COMPILE_STATUS.md).

**Wave 23 (2026-05-22):** Quantization import — [`rings/ring-096-rust`](rings/ring-096-rust) lands the ninth honestly-authored Wave-11 crate (641 LOC, 42 tests). Mirrors `specs/numeric/formats.t27`: GF16 bit layout (`SIGN_MASK=0x8000`, `EXP_MASK=0x7E00`, `MANT_MASK=0x01FF`, `EXP_SHIFT=9`, `SIGN_SHIFT=15`, `BIAS=31`, `EXP_MAX=63`, `EXP_MIN=0`) byte-for-byte; full GF16 codec `gf16_to_f32` / `f32_to_gf16` (signed zero, denormals, normals, Inf, NaN, round-to-nearest with mantissa-overflow exponent carry); ternary quantization `f32_to_ternary` / `ternary_to_f32` with the spec's strict threshold `|x| > 0.5`; the `Format` enum (`Fp32`, `Fp16`, `Bf16`, `Gf16`, `Ternary`); `format_bytes`; and the `quantize_value` utility. A private `pow_u64` (fast exponentiation by squaring) replaces libm in `no_std`. `quantization_phi_identity` is the **eighth cross-kernel anchor test** in the project, routing `phi^2 + 1/phi^2 = 3` through the GF16 codec: it computes `phi^2` and `phi^-2` via `pow_u64`, encodes via `f32_to_gf16`, decodes via `gf16_to_f32`, and verifies the sum lies within GF16 mantissa tolerance of 3.0 (~0.03 absolute). Wave-11 narrative claimed 464 LOC; honest measurement is 641 LOC. All 42 tests green on Rust 1.83.0. See [COMPILE_STATUS](rings/COMPILE_STATUS.md).

**DOI:** [10.5281/zenodo.19456875](https://doi.org/10.5281/zenodo.19456875)
19 changes: 18 additions & 1 deletion docs/NOW.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,24 @@

Last updated: 2026-05-22

## wave-22 -- phi-Adam optimizer import: ring-095-rust (this PR, Closes #731)
## wave-23 -- Quantization import: ring-096-rust (this PR, Closes #733)

- **NEW** (rings-only, additive): `rings/ring-096-rust/` lands with `Cargo.toml` + `src/lib.rs` (641 LOC) + `README.md` + `.gitignore`. Zero edits under `gen/`, `coq/`, `trios-coq/`, `proofs/`, `bootstrap/`, `specs/`, `conformance/`, `architecture/`, root `Cargo.toml`, or any other crate. Doc-only updates to `rings/COMPILE_STATUS.md`, `README.md` (Wave 23 footer), and this file.
- **What ring-096 actually does:** Faithful Rust mirror of the realizable subset of `specs/numeric/formats.t27`. (a) GF16 bit-layout constants byte-for-byte: `SIGN_MASK = 0x8000`, `EXP_MASK = 0x7E00`, `MANT_MASK = 0x01FF`, `EXP_SHIFT = 9`, `SIGN_SHIFT = 15`, `BIAS = 31`, `EXP_MAX = 63`, `EXP_MIN = 0`. (b) `gf16_to_f32(x: u16) -> f64` decoder handling signed zero (e=0,m=0), denormals (e=0,m!=0 -> `(m/2^9) * 2^(1-bias)`), normals (e in (0, ExpMax) -> `(1 + m/2^9) * 2^(e-bias)`), positive/negative infinity (e=ExpMax,m=0), and NaN (e=ExpMax,m!=0). (c) `f32_to_gf16(a: f64) -> u16` encoder: signed-zero preserved, NaN -> 0x7F01, Inf -> 0x[7|F]E00, normal magnitude reduced by repeated *2 / *0.5 into [1, 2), mantissa = `(frac * 2^9) + 0.5` round-to-nearest, mantissa-overflow carries into the exponent, underflow into denormal range, overflow clamped to Inf encoding. (d) Ternary primitives: `f32_to_ternary` with the spec's strict threshold `|x| > 0.5` -> Pos/Neg, otherwise Zero; `ternary_to_f32` returns 1.0 / 0.0 / -1.0 exactly; `Trit::{Neg=-1, Zero=0, Pos=1}` enum with `to_i8` / `from_i8`. (e) `Format` enum mirrors the spec's `enum(u8)`: `Fp32`, `Fp16`, `Bf16`, `Gf16`, `Ternary`. (f) `format_bytes(Format) -> usize` returns 4 / 2 / 2 / 2 / 1. (g) `quantize_value(x, fmt)`: Fp32/Fp16/Bf16 are pass-through (codec width identical-or-wider than GF16; full IEEE 754 binary16/bf16 converters are out of scope here -- those belong to a later ring); Gf16 round-trips through encoder + decoder; Ternary round-trips through `f32_to_ternary` + `ternary_to_f32`. (h) `pow_u64(base, exp)` -- fast exponentiation by squaring with negative-exponent inversion, used for all 2^k computations and for the anchor identity. (i) `fabs_no_std`, `is_nan`, `is_inf` -- no-libm helpers. (j) `QuantError::{Overflow, Underflow, Nan}` (reserved for future encoders). (k) `identity_witness()` for the universal anchor (closed-form `phi^2 + 1/phi^2`).
- **GF16 round-trip semantics:** encoder uses iterative magnitude normalization (multiplicative ladder) instead of `frexp`, bounded by `EXP_MAX = 63` from above and `0` from below, so the loop terminates in <= 63 iterations for any finite input. Mantissa rounding can promote the next-exponent boundary; the encoder handles this by clearing mantissa to 0 and incrementing exponent (with overflow-to-Inf check). The local roundtrip test `f32_to_gf16_roundtrip_normal_values` verifies relative error < 1% for the values {1.5, 2.0, 0.5, -1.5, 100.0, -100.0, 0.125}.
- **Ternary boundary semantics:** the spec defines the threshold as strict `|x| > 0.5`, which means `0.5` and `-0.5` quantize to `Zero`, not `Pos` / `Neg`. This is the boundary tested by `ternary_at_threshold_is_zero` and is symmetric (`ternary_symmetry` verifies `q(+0.7) = -q(-0.7)` after round-trip).
- **no_std math:** the spec uses arbitrary 2^k computations and float arithmetic; the crate replaces libm with `pow_u64` (fast exponentiation, integer exponent) plus pure-arithmetic `fabs_no_std` / `is_nan` / `is_inf`. The crate is `#![no_std]` and `#![deny(warnings)]`.
- **No new spec (L6 CEILING + L2 GENERATION):** every constant, every formula, the Format enum's variant set and ordering, the ternary threshold value, and the byte sizes follow `specs/numeric/formats.t27` byte-for-byte. The spec wraps decoded values in `gf16` (alias for a float); we use `f64` directly because the kernel semantics are identical and avoiding an extra wrapper keeps the ring crates independent (no inter-ring deps). No file under `specs/`, `coq/`, `proofs/`, `bootstrap/`, `gen/` is touched.
- **Tests (42, all green on first run):** spec constants (`const_sign_mask`, `const_exp_mask`, `const_mant_mask`, `const_exp_shift_sign_shift_bias`, `const_exp_max_min`); GF16 decode (`gf16_to_f32_zero_positive`, `gf16_to_f32_zero_negative`, `gf16_to_f32_denormal_positive`, `gf16_to_f32_one`, `gf16_to_f32_positive_inf`, `gf16_to_f32_negative_inf`, `gf16_to_f32_nan`); GF16 encode (`f32_to_gf16_zero_positive`, `f32_to_gf16_zero_negative`, `f32_to_gf16_one_roundtrip`, `f32_to_gf16_inf_positive`, `f32_to_gf16_inf_negative`, `f32_to_gf16_nan`, `f32_to_gf16_roundtrip_normal_values`); ternary (`ternary_positive`, `ternary_zero`, `ternary_negative`, `ternary_above_threshold`, `ternary_below_neg_threshold`, `ternary_at_threshold_is_zero`, `ternary_to_f32_roundtrip`, `ternary_symmetry`); Format (`format_bytes_fp32`, `format_bytes_fp16`, `format_bytes_bf16`, `format_bytes_gf16`, `format_bytes_ternary`); quantize_value (`quantize_value_fp32_preserves`, `quantize_value_ternary_above_threshold`, `quantize_value_ternary_below_neg_threshold`, `quantize_value_gf16_roundtrip`); Trit helpers (`trit_from_to_i8`); pow_u64 (`pow_u64_zero_exp`, `pow_u64_positive_exp`, `pow_u64_negative_exp`); identity witness (`identity_witness_value`); cross-kernel anchor (`quantization_phi_identity`). Zero bug-fix cycles needed -- the boundary semantics, mantissa-overflow carry, and Inf/NaN encoding all worked correctly on the first compile.
- **Eighth cross-kernel anchor test:** `quantization_phi_identity` is the eighth time `phi^2 + 1/phi^2 = 3` is exercised through actual numeric kernels (after Wave 15 `mac_dot_phi_identity`, Wave 16 `cpu_phi_identity_integer_projection`, Wave 18 `sr_quantize_phi_unbiased`, Wave 19 `attention_phi_identity_via_softmax_matmul`, Wave 20 `moe_phi_identity_via_gating_and_ffn`, Wave 21 `runtime_phi_identity_via_scheduler_credits`, Wave 22 `phi_adam_phi_identity_via_betas`). Construction: (1) compute `phi^2` and `phi^-2` via the crate's own `pow_u64` and verify the f64-precision sum is within 1e-9 of 3.0 (pre-codec identity). (2) Encode both values via `f32_to_gf16` -> u16, then decode via `gf16_to_f32` -> f64; verify the post-codec sum lies within GF16 mantissa tolerance of 3.0 (absolute < 0.03 against the 9-bit mantissa precision budget). (3) Run the same round-trip through the higher-level `quantize_value(x, Format::Gf16)` API and verify the same bound holds. This anchors the identity through the full codec stack, not just `pow_u64`.
- **R5-HONEST LOC observation:** the Wave-11 narrative quoted **464 LOC** for ring-096; the honest Wave-23 measurement is **641 LOC**. Pattern across the Wave-15..23 import series: 088 (961 -> 439), 089 (334 -> 635), 090 (2143 -> 547), 091 (409 -> 462), 092 (847 -> 760), 093 (668 -> 950), 094 (774 -> 1210), 095 (659 -> 808), 096 (464 -> 641). The honesty work is replacing guesses with measurements, in both directions.
- **R5-HONEST out of scope:** full IEEE 754 binary16 (`fp16`) / Brain Float (`bf16`) bit-level encoders -- their `quantize_value` paths are pass-through in this ring; they will arrive as a dedicated codec ring. INT4 / INT8 quantization (a separate sub-format space not present in `specs/numeric/formats.t27`). Strict rounding-mode controls beyond round-to-nearest. Quantization-aware training hooks (those belong in the optimizer ring, ring-095).
- **Compile semantics unchanged:** ring-096 lives outside `[workspace].members` (Wave-14 `exclude = [..., "rings"]` covers it automatically). `rings-rust.yml` discovers it via the matrix generator and runs `cargo check` + `cargo test`, both `continue-on-error: true`. The CI run triggered by this PR will be the first to exercise these 42 tests in public.
- **COMPILE_STATUS promotion:** ring-096 moves from `claimed-only` to `check` + `test`. The remaining 3 Wave-11 rings (ring-097, ring-098, ring-099) stay `claimed-only` and the section preamble is updated to reflect the new boundary.
- **L1 TRACEABILITY:** PR cites `Closes #733` in title and body; every commit message carries it. **L2 GENERATION:** zero edits under generated trees. **L3 PURITY:** ASCII source, English doc-comments. **L4 TESTABILITY:** 42 `#[test]`s. **L5 IDENTITY:** anchor exercised through `pow_u64`, the GF16 codec, and `quantize_value`. **L6 CEILING:** zero numeric kernel / spec changes; spec constants mirror existing spec byte-for-byte. **L7 UNITY:** no new `*.sh` -- all new files are `.toml`, `.rs`, `.md`, `.gitignore`.
- Closes #733

## wave-22 -- phi-Adam optimizer import: ring-095-rust (Closes #731)

- **NEW** (rings-only, additive): `rings/ring-095-rust/` lands with `Cargo.toml` + `src/lib.rs` (808 LOC) + `README.md` + `.gitignore`. Zero edits under `gen/`, `coq/`, `trios-coq/`, `proofs/`, `bootstrap/`, `specs/`, `conformance/`, `architecture/`, root `Cargo.toml`, or any other crate. Doc-only updates to `rings/COMPILE_STATUS.md`, `README.md` (Wave 22 footer), and this file.
- **What ring-095 actually does:** Faithful Rust mirror of the realizable subset of `specs/ml/optimizer/{adam, adamw}.t27`. AdamW (Loshchilov & Hutter 2019) with decoupled weight decay, plus AMSGrad (Reddi et al. 2018) variant, plus the spec's explicit **phi-Adam** branch with phi-damped betas. (a) Spec constants byte-for-byte: `DEFAULT_LEARNING_RATE = 1e-3`, `DEFAULT_BETA1 = 0.9`, `DEFAULT_BETA2 = 0.999`, `DEFAULT_WEIGHT_DECAY = 0.01`, `DEFAULT_EPSILON = 1e-8`, `DEFAULT_AMSGRAD = false`, `PHI_BETA1 = 0.9 / phi ~= 0.556`, `PHI_BETA2 = 0.999 / phi ~= 0.617`. (b) `AdamWConfig` with `defaults()` (classic AdamW), `phi_preset()` (phi-damped betas + use_phi_betas=true), `effective_beta1()` / `effective_beta2()` (honouring use_phi_betas), `is_valid()` (range check). (c) `AdamWState<'_>` -- caller-owned mutable references to `m`, `v`, optional `v_max` buffers; `AdamWState::init` zeroes all buffers and validates shape. (d) Helpers named after the spec: `compute_bias_correction`, `update_first_moment`, `update_second_moment`, `apply_weight_decay` (in-place), `compute_update`. (e) `step()` orchestrator: increments `state.step`, computes `bc1 = 1 - beta1^t`, `bc2 = 1 - beta2^t`, `lr_t = lr * sqrt(bc2) / bc1`, applies decoupled weight decay if `weight_decay > 0`, then for each parameter: updates moments, optionally tracks AMSGrad `v_max`, computes `lr_t * m / (sqrt(v_or_vmax) + epsilon)`, subtracts from parameter, accumulates squared updates for `step_norm`. Returns `StepResult { step_norm, lr_t, step }`. (f) `pow_u64` -- fast exponentiation, used for `pow(beta, t)`. (g) `sqrt_newton` -- Newton-Raphson square root with relative-tolerance early exit. (h) `OptimError::{ShapeMismatch, InvalidConfig}`. (i) `identity_witness()` for the universal anchor.
Expand Down
49 changes: 39 additions & 10 deletions rings/COMPILE_STATUS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# rings/ -- Living Compile Status (Wave 13 gate, Waves 14-22 promotions)
# rings/ -- Living Compile Status (Wave 13 gate, Waves 14-23 promotions)

> Last updated: 2026-05-22 (Wave 22)
> Last updated: 2026-05-22 (Wave 23)
> Anchor: phi^2 + 1/phi^2 = 3
> CI workflow: [`.github/workflows/rings-rust.yml`](../.github/workflows/rings-rust.yml)
> Toolchain: pinned via [`Dockerfile.rust`](../Dockerfile.rust) -- `rust:1.83-bookworm`
Expand Down Expand Up @@ -228,20 +228,49 @@ this PR triggers.
|--------------------|-----------------------------------|-----:|------:|-------------------|
| `ring-095-rust` | phi-Adam optimizer (AdamW + phi) | 808 | 25 | `check` + `test` |

## Wave 11 -- ring-096..ring-099 (claimed-only, off-disk)
## Wave 23 import -- ring-096 (on disk, real)

Wave 23 (2026-05-22, Closes #733) imports the **ninth** Wave-11 crate for real.
Locally verified on Rust 1.83.0: `cargo check` green, `cargo test --lib`
reports **42 passed, 0 failed** on the first run. Ring-096 mirrors
[`specs/numeric/formats.t27`](../specs/numeric/formats.t27) byte-for-byte:
GF16 bit layout (`SIGN_MASK = 0x8000`, `EXP_MASK = 0x7E00`,
`MANT_MASK = 0x01FF`, `EXP_SHIFT = 9`, `SIGN_SHIFT = 15`, `BIAS = 31`,
`EXP_MAX = 63`, `EXP_MIN = 0`); the GF16 codec `gf16_to_f32` /
`f32_to_gf16` (handles signed zero, denormals, normals, Inf, NaN,
round-to-nearest with mantissa-overflow exponent carry); ternary
quantization `f32_to_ternary` / `ternary_to_f32` with the spec's strict
threshold (`|x| > 0.5`); the `Format` enum (`Fp32`, `Fp16`, `Bf16`,
`Gf16`, `Ternary`); `format_bytes`; and the `quantize_value` utility.
A private `pow_u64` (fast exponentiation by squaring) replaces libm in
`no_std`. The crate's `quantization_phi_identity` is the **eighth
cross-kernel anchor test** in the project (after ring-088, ring-089,
ring-091, ring-092, ring-093, ring-094, ring-095), routing
`phi^2 + 1/phi^2 = 3` through the GF16 codec: it computes `phi^2` and
`phi^-2` via `pow_u64`, encodes each via `f32_to_gf16`, decodes via
`gf16_to_f32`, and verifies the sum lies within GF16 mantissa tolerance
of 3.0 (~0.03 absolute). Earlier Wave-11 narrative claimed 464 LOC;
honest Wave-23 measurement is **641 LOC**. Promotion will be
re-confirmed by the green `rings-rust` workflow run this PR triggers.

| Crate | Domain | LOC | Tests | Status |
|--------------------|-----------------------------------|-----:|------:|-------------------|
| `ring-096-rust` | Quantization (GF16 codec+ternary) | 641 | 42 | `check` + `test` |

## Wave 11 -- ring-097..ring-099 (claimed-only, off-disk)

Wave 11's narrative described 11 additional crates with ~ 8 969 LOC. Their
sources never reached this repository. Waves 15-22 acknowledge this
sources never reached this repository. Waves 15-23 acknowledge this
honestly and have promoted `ring-088`, `ring-089`, `ring-090`, `ring-091`,
`ring-092`, `ring-093`, `ring-094`, and `ring-095` out of this table. The
rows below are **claimed-only** placeholders, *not* deliverables. They will
be promoted to `check` + `test` one ring at a time, each via its own PR
that carries real source + local verification (the Wave-15..22 template).
LOC numbers below are quotes from past narrative, not measurements.
`ring-092`, `ring-093`, `ring-094`, `ring-095`, and `ring-096` out of this
table. The rows below are **claimed-only** placeholders, *not* deliverables.
They will be promoted to `check` + `test` one ring at a time, each via its
own PR that carries real source + local verification (the Wave-15..23
template). LOC numbers below are quotes from past narrative, not
measurements.

| Crate | Domain | LOC (claimed) | Status |
|--------------------|-----------------------------------|---------------:|----------------|
| `ring-096-rust` | Quantization | 464 | `claimed-only` |
| `ring-097-rust` | Chain-of-Thought | 624 | `claimed-only` |
| `ring-098-rust` | World Model | 920 | `claimed-only` |
| `ring-099-rust` | Integration | 1127 | `claimed-only` |
Expand Down
1 change: 1 addition & 0 deletions rings/ring-096-rust/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Cargo.lock
9 changes: 9 additions & 0 deletions rings/ring-096-rust/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
[package]
name = "ring-096-quantization"
version = "0.1.0"
edition = "2021"
description = "ring-096: Format quantization primitives (GF16 codec, ternary, Format enum) mirroring specs/numeric/formats.t27"
license = "Apache-2.0"

[lib]
path = "src/lib.rs"
51 changes: 51 additions & 0 deletions rings/ring-096-rust/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# ring-096-quantization

Format quantization primitives — GF16 codec, ternary quantization, Format enum.

Mirrors `specs/numeric/formats.t27` byte-for-byte.

## Primitives

- **GF16 bit layout**: `SIGN_MASK=0x8000`, `EXP_MASK=0x7E00`, `MANT_MASK=0x01FF`, `BIAS=31`
- **`gf16_to_f32(u16) -> f64`** — decode: handles signed zero, denormals, normals, Inf, NaN
- **`f32_to_gf16(f64) -> u16`** — encode (round-to-nearest): handles signed zero, Inf, NaN, overflow, underflow
- **`f32_to_ternary(f64) -> Trit`** — ternary quantization with threshold 0.5
- **`ternary_to_f32(Trit) -> f64`** — convert ternary back to float
- **`Format` enum** — `Fp32`, `Fp16`, `Bf16`, `Gf16`, `Ternary`
- **`format_bytes(Format) -> usize`** — byte size lookup
- **`quantize_value(f64, Format) -> f64`** — generic quantization utility

## no_std math

Pure `no_std` — no `libm`. Internal helpers:
- `pow_u64` — fast integer exponentiation by squaring
- `fabs_no_std` — branch-based absolute value

## Anchor #8

`quantization_phi_identity` routes the Trinity identity `phi^2 + 1/phi^2 = 3` through:
- `pow_u64(phi, 2)` and `pow_u64(phi, -2)`
- Encode both via `f32_to_gf16`
- Decode via `gf16_to_f32`
- Sum and verify ≈ 3.0 within GF16 mantissa tolerance (~0.03 absolute)

## Build & test

```
cargo check
cargo test --lib
```

## Constitutional compliance

- L1 TRACEABILITY — `Closes #733`
- L2 GENERATION — zero edits under `specs/`, `gen/`, `coq/`
- L3 PURITY — ASCII source, English doc-comments
- L4 TESTABILITY — `#[test]` blocks
- L5 IDENTITY — `phi^2 + 1/phi^2 = 3` exercised
- L6 CEILING — spec constants byte-for-byte
- L7 UNITY — no `*.sh` files

---

`phi^2 + 1/phi^2 = 3`
Loading
Loading