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 @@ -585,4 +585,6 @@ MIT

**Wave 16 (2026-05-22):** TNN ISA import — [`rings/ring-089-rust`](rings/ring-089-rust) lands the second honestly-authored Wave-11 crate (635 LOC, 15 tests). Includes `Trit`, `Word27`, balanced-ternary `trit_add` / `word_add` / `word_sub` per `specs/isa/ternary_arithmetic.t27`, a 9-opcode subset (`NOP`/`MOV`/`ADDI`/`ADD`/`SUB`/`NEG`/`LOAD`/`STORE`/`HALT`), and a `Cpu` fetch/decode/execute model with 27 registers (R0 hardwired to zero). `cpu_phi_identity_integer_projection` is the second cross-kernel anchor test, running `floor(phi) + floor(1/phi) + ceil(phi^2 - 2) = 3` through the CPU. `#![no_std]`, zero deps, verified locally on Rust 1.83.0. See [COMPILE_STATUS](rings/COMPILE_STATUS.md).

**Wave 17 (2026-05-22):** Simulator import — [`rings/ring-090-rust`](rings/ring-090-rust) lands the third honestly-authored Wave-11 crate (547 LOC, 19 tests). Mirrors `specs/fpga/simulator.t27` byte-for-byte: `SimState` (5 variants), `SimConfig`, `SimResult`, `ProbePoint`, `TraceEntry`, plus constructor / query / time-conversion / validation helpers. All 13 spec `test` blocks and all 4 spec `invariant` blocks become `#[test]`s. `#![no_std]`, zero deps, all 19 tests green on first run (Rust 1.83.0). Wave-11 narrative claimed 2143 LOC; honest measurement is 547 LOC. See [COMPILE_STATUS](rings/COMPILE_STATUS.md).

**DOI:** [10.5281/zenodo.19456875](https://doi.org/10.5281/zenodo.19456875)
15 changes: 15 additions & 0 deletions docs/NOW.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,21 @@

Last updated: 2026-05-22

## wave-17 -- Simulator import: ring-090-rust (this PR, Closes #721)

- **NEW** (rings-only, additive): `rings/ring-090-rust/` lands with `Cargo.toml` + `src/lib.rs` (547 LOC) + `README.md`. 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 17 footer), and this file.
- **What ring-090 actually does:** Faithful Rust mirror of `specs/fpga/simulator.t27` (a HIR cycle-accurate simulator data-model + helpers). (a) `SimState` enum with 5 variants and tag values `0..=4` matching the spec's `enum(i8) SimState` byte-for-byte; `tag()` / `from_tag()` round-trips. (b) `SimConfig` 7-field struct (`name`, `max_cycles`, `clock_freq_hz`, `trace_enabled`, `vcd_output`, `break_on_error`, `vcd_path`) with `DEFAULT_CLOCK_FREQ_HZ = 100_000_000` matching the spec's hard-coded constructor. (c) `SimResult`, `ProbePoint`, `TraceEntry` with identical field shape. (d) Constructor `const fn`s: `sim_config`, `sim_config_with_trace`, `sim_ok`, `sim_error`, `probe`, `trace_entry`. (e) Query predicates: `is_idle`, `is_done`, `is_error`, `has_errors`, `passed`. (f) Time conversions: `sim_time_ns`, `sim_time_us`, `sim_time_ms`, `cycles_for_time_ns`. (g) `validate_sim_config`. (h) `identity_witness()` returning `true` iff `phi^2 + 1/phi^2 == 3` to f64 1e-15.
- **Time-conversion overflow note (R5-HONEST, documented inline):** the source spec uses pure `u32` for `cycles * 1_000_000_000 / clock_freq_hz`. At the spec's own canonical case (`clock_freq_hz = 100_000_000`, `cycles = 100`), `100 * 1_000_000_000 = 1e11` exceeds `u32::MAX ~= 4.29e9` and the spec's own assertion `sim_time_ns(_, 100) == 1000` would fail. We faithfully implement the formula with a `u64` intermediate and narrow back to `u32`; the public signature stays `u32 -> u32` exactly as in the spec, but the intermediate arithmetic is the minimum width needed to make the spec's own canonical test pass. Over-large results saturate at `u32::MAX`. This is a faithful reading, not a spec change.
- **No new spec (L6 CEILING):** enum tags, struct field order, default values, and formula shapes mirror `specs/fpga/simulator.t27` byte-for-byte. No scheduler, no VCD writer, no event queue, no clock-domain crossing logic, no RTL execution -- those layers live in adjacent specs (`vcd_trace.t27`, `clock_domain.t27`, `formal.t27`) and are deliberately out of scope.
- **Tests (19, all pass on first run on Rust 1.83.0):** 13 mirrored from the spec's `test` blocks (`sim_config_creation`, `sim_config_with_trace_creation`, `sim_ok_result`, `sim_error_result`, `probe_creation`, `trace_entry_creation`, `sim_time_ns_canonical`, `sim_time_us_canonical`, `sim_time_ms_canonical`, `cycles_for_time_ns_canonical`, `validate_config_ok`, `validate_config_empty_name`, `validate_config_zero_cycles`) + 4 from the spec's `invariant` blocks (`invariant_max_cycles_positive`, `invariant_sim_time_positive`, `invariant_cycles_for_time_positive`, `invariant_validate_non_negative`) + 1 universal anchor (`identity_witness_holds`) + 1 bonus type-safety check (`sim_state_tag_roundtrip`). Unlike Wave 16, no bug-fix cycle was needed -- the spec was tight enough that the first compile gave 19/19 green.
- **R5-HONEST LOC correction:** the previous Wave-11 narrative quoted **2143 LOC** for ring-090; the honest Wave-17 measurement is **547 LOC**. The earlier number was a guess, not a measurement. This is the third LOC correction in the Wave-15/16/17 import series (ring-088: claimed 961 -> real 439; ring-089: claimed 334 -> real 635; ring-090: claimed 2143 -> real 547). The honesty work is replacing guesses with measurements, not the other way around.
- **Compile semantics unchanged:** ring-090 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 19 tests in public.
- **COMPILE_STATUS promotion:** ring-090 moves from `claimed-only` to `check` + `test`. The remaining 9 Wave-11 rings (ring-091..ring-099) stay `claimed-only` and the section preamble is updated to reflect the new boundary.
- **Identity (L5):** `phi^2 + 1/phi^2 = 3` is exercised by `identity_witness_holds`. Ring-090 does not introduce a cross-kernel anchor test of its own (it has no kernel, just data types) -- the cross-kernel anchors continue to live in ring-088 (`mac_dot_phi_identity`) and ring-089 (`cpu_phi_identity_integer_projection`).
- **L1 TRACEABILITY:** PR cites `Closes #721` in title and body; every commit message carries it. **L2 GENERATION:** zero edits under `gen/`, `coq/`, `trios-coq/`, `proofs/`, `bootstrap/`, `specs/`, `conformance/`, `architecture/`. **L3 PURITY:** ASCII source, English doc-comments. **L4 TESTABILITY:** 19 `#[test]`s. **L5 IDENTITY:** anchor present. **L6 CEILING:** zero numeric kernel / spec changes; all constants and field shapes mirror existing spec. **L7 UNITY:** no new `*.sh` -- all new files are `.toml`, `.rs`, `.md`.
- **R5-HONEST:** only ring-090 is promoted in this wave; no claim is made about ring-091..ring-099. The 13 `test` blocks + 4 `invariant` blocks in the spec are translated 1:1 into `#[test]`s with identical assertion values.
- Closes #721

## wave-16 -- TNN ISA import: ring-089-rust (this PR, Closes #719)

- **NEW** (rings-only, additive): `rings/ring-089-rust/` lands with `Cargo.toml` + `src/lib.rs` (635 LOC) + `README.md`. 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 16 footer), and this file.
Expand Down
40 changes: 30 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-16 promotions)
# rings/ -- Living Compile Status (Wave 13 gate, Waves 14-17 promotions)

> Last updated: 2026-05-22 (Wave 16)
> Last updated: 2026-05-22 (Wave 17)
> 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 @@ -69,19 +69,39 @@ re-confirmed by the green `rings-rust` workflow run this PR triggers.
|--------------------|-----------------------------------|-----:|------:|-------------------|
| `ring-089-rust` | TNN ISA (27-reg balanced ternary) | 635 | 15 | `check` + `test` |

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

Wave 17 (2026-05-22, Closes #721) imports the **third** Wave-11 crate for real.
Locally verified on Rust 1.83.0: `cargo check --all-targets` green,
`cargo test --lib` reports **19 passed, 0 failed** on the first run
(no bug-fix cycle this time). Ring-090 mirrors
[`specs/fpga/simulator.t27`](../specs/fpga/simulator.t27) byte-for-byte:
`SimState`, `SimConfig`, `SimResult`, `ProbePoint`, `TraceEntry`, all the
spec's constructor / query / time-conversion / validation helpers, plus
the universal anchor. The 19 tests cover all 13 `test` blocks and all 4
`invariant` blocks in the spec, plus `identity_witness_holds` and a
`sim_state_tag_roundtrip` type-safety check. Earlier Wave-11 narrative
claimed 2143 LOC; honest Wave-17 measurement is **547 LOC** (R5-HONEST).
Promotion will be re-confirmed by the green `rings-rust` workflow run this
PR triggers.

| Crate | Domain | LOC | Tests | Status |
|--------------------|-----------------------------------|-----:|------:|-------------------|
| `ring-090-rust` | Simulator (HIR cycle-accurate) | 547 | 19 | `check` + `test` |

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

Wave 11's narrative described 11 additional crates with ~ 8 969 LOC. Their
sources never reached this repository. Wave 15 acknowledged this honestly;
Wave 16 has now promoted `ring-089-rust` 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/16 template). LOC numbers
below are quotes from past narrative, not measurements.
sources never reached this repository. Waves 15, 16, and 17 acknowledge
this honestly and have promoted `ring-088`, `ring-089`, and `ring-090` 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/16/17 template). LOC numbers below are quotes from past
narrative, not measurements.

| Crate | Domain | LOC (claimed) | Status |
|--------------------|-----------------------------------|---------------:|----------------|
| `ring-090-rust` | Simulator | 2143 | `claimed-only` |
| `ring-091-rust` | Stochastic Rounding | 409 | `claimed-only` |
| `ring-092-rust` | Attention | 847 | `claimed-only` |
| `ring-093-rust` | Sparse MoE | 668 | `claimed-only` |
Expand Down
18 changes: 18 additions & 0 deletions rings/ring-090-rust/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
[package]
name = "ring-090-simulator"
version = "0.1.0"
edition = "2021"
rust-version = "1.83"
description = "ring-090 -- HIR cycle-accurate simulator primitives, faithful to specs/fpga/simulator.t27"
license = "Apache-2.0"
publish = false

[lib]
path = "src/lib.rs"

# Standalone crate -- intentionally NOT in the root workspace.
# Wave 14 added "rings" to the root Cargo.toml exclude list.
# Wave 13 rings-rust.yml matrix discovers this crate via scripts/ci/rings_matrix.py.

[dependencies]
# Zero external dependencies. Test cfg pulls std for the harness only.
111 changes: 111 additions & 0 deletions rings/ring-090-rust/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
# ring-090 -- HIR Simulator primitives

> **Wave 17** (2026-05-22, Closes #721): the third honestly-imported Wave-11
> crate. Waves 15 and 16 landed [ring-088](../ring-088-rust) (GF16 codec +
> MAC) and [ring-089](../ring-089-rust) (TNN ISA). Wave 17 lands ring-090:
> the simulator data-model + helpers defined by
> [`specs/fpga/simulator.t27`](../../specs/fpga/simulator.t27).
>
> Anchor: `phi^2 + 1/phi^2 = 3`.

## What

A real, compileable, tested implementation of the simulator primitives the
spec describes:

1. **`SimState`** -- 5-variant enum (`Idle`/`Running`/`Paused`/`Done`/`Error`)
with `tag()` / `from_tag()`; tag values `0..=4` mirror the spec's
`enum(i8) SimState` byte-for-byte.
2. **`SimConfig`** -- 7-field config (`name`, `max_cycles`, `clock_freq_hz`,
`trace_enabled`, `vcd_output`, `break_on_error`, `vcd_path`); the default
clock frequency is `DEFAULT_CLOCK_FREQ_HZ = 100_000_000` Hz, matching
the spec's hard-coded constructor.
3. **`SimResult`** -- post-run report (`cycles`, `state`, `errors`,
`assertions_fired`, `coverage_points`).
4. **`ProbePoint`** / **`TraceEntry`** -- single-signal probe and
single-row trace record.
5. **Constructors** -- `sim_config`, `sim_config_with_trace`, `sim_ok`,
`sim_error`, `probe`, `trace_entry`. All `const fn` where the spec's
field-set is purely literal.
6. **Queries** -- `is_idle`, `is_done`, `is_error`, `has_errors`, `passed`.
7. **Time conversions** -- `sim_time_ns`, `sim_time_us`, `sim_time_ms`,
`cycles_for_time_ns`. See **Time-conversion overflow note** below.
8. **`validate_sim_config`** -- counts invalid fields (empty name, zero
max_cycles, zero clock_freq_hz).
9. **`identity_witness`** -- the universal anchor (`phi^2 + 1/phi^2 == 3`
to f64 1e-15) required of every t27 ring crate.

The crate is `#![no_std]` (test cfg pulls `std` for the harness only),
`#![forbid(unsafe_code)]`, `#![deny(missing_docs)]`. **No external
dependencies.**

## Time-conversion overflow note (R5-HONEST)

The source spec uses `u32` for the multiplication

```text
sim_time_ns(cfg, cycles) = cycles * 1_000_000_000 / clock_freq_hz
```

but the spec's *own* canonical assertion is `sim_time_ns(_, 100) == 1000`
at `clock_freq_hz = 100_000_000`. With pure `u32` arithmetic,
`100 * 1_000_000_000 = 1e11` overflows `u32::MAX ~= 4.29e9` and the
assertion would fail. We faithfully implement the formula with a `u64`
intermediate and narrow back to `u32` at the end; the public signature
stays `u32 -> u32` exactly as in the spec, but the intermediate
arithmetic is the minimum width needed to make the spec's *own*
canonical test pass. Results that don't fit `u32` saturate at
`u32::MAX`. This is documented inline in `sim_time_ns` and
`cycles_for_time_ns`.

## Honest scope

* **No scheduler, no VCD writer, no event queue, no clock-domain
crossing logic, no RTL execution.** Those layers live in adjacent
specs (`vcd_trace.t27`, `clock_domain.t27`, `formal.t27`) and are
*deliberately* out of scope for Wave 17.
* **No new spec.** Enum tags, struct field order, default values, and
formula shapes mirror `specs/fpga/simulator.t27` byte-for-byte
(L6 CEILING).
* The Wave-11 narrative quoted **2143 LOC** for ring-090. The honest
Wave-17 measurement is **547 LOC**. The earlier number was a guess,
not a measurement.

## Tests (19, all pass)

| Test | What it proves |
|:------------------------------------|:---------------------------------------------------|
| `sim_config_creation` | spec `test sim_config_creation` |
| `sim_config_with_trace_creation` | spec `test sim_config_with_trace` |
| `sim_ok_result` | spec `test sim_ok_result` (6 sub-asserts) |
| `sim_error_result` | spec `test sim_error_result` (5 sub-asserts) |
| `probe_creation` | spec `test probe_creation` |
| `trace_entry_creation` | spec `test trace_entry_creation` |
| `sim_time_ns_canonical` | spec `test sim_time_ns` -> `1000 ns` |
| `sim_time_us_canonical` | spec `test sim_time_us` -> `1000 us` |
| `sim_time_ms_canonical` | spec `test sim_time_ms` -> `1000 ms` |
| `cycles_for_time_ns_canonical` | spec `test cycles_for_time_ns` -> `100 cycles` |
| `validate_config_ok` | spec `test validate_config_ok` |
| `validate_config_empty_name` | spec `test validate_config_empty_name` |
| `validate_config_zero_cycles` | spec `test validate_config_zero_cycles` |
| `invariant_max_cycles_positive` | spec `invariant max_cycles_positive` |
| `invariant_sim_time_positive` | spec `invariant sim_time_positive` |
| `invariant_cycles_for_time_positive`| spec `invariant cycles_for_time_positive` |
| `invariant_validate_non_negative` | spec `invariant validate_non_negative` |
| `identity_witness_holds` | universal anchor (phi^2 + 1/phi^2 == 3 to 1e-15) |
| `sim_state_tag_roundtrip` | `SimState::from_tag . tag = id` and unknown -> None |

13 mirrored from spec `test` blocks + 4 from spec `invariant` blocks +
1 universal anchor + 1 bonus type-safety round-trip = 19 total.

## Build

```bash
cd rings/ring-090-rust
cargo check --all-targets # green on Rust 1.83.0
cargo test --lib # 19 passed, 0 failed
```

Local verification on Rust 1.83.0 (matching
[`Dockerfile.rust`](../../Dockerfile.rust)) -- the Wave-13 `rings-rust`
matrix will re-confirm on every PR that touches this crate.
Loading
Loading