diff --git a/NOW.md b/NOW.md index 6b8113780..9fb56e011 100644 --- a/NOW.md +++ b/NOW.md @@ -1,6 +1,15 @@ -# NOW — Trinity t27 sync +# NOW -- Trinity t27 sync -Last updated: 2026-05-16 +Last updated: 2026-05-18 + +## docs(TRI-NET) -- cross-line package P0/P1/P2 (this PR, Closes #696) + +- **NEW** docs: `docs/GF16_BFLOAT16_NMSE_PROTOCOL.md`, `docs/TRI_NET_API.md`, `docs/TRI_NET_WHITEPAPER.md`, `docs/22FDX_TOPS_W_PROJECTION.md`, `docs/ZENODO_BUNDLES.md`, `docs/SCIENTIFIC_IMPROVEMENT_PLAN.md` (2026 t27-side roadmap, R5-honest labels) +- **NEW** specs: `specs/benchmarks/gf16_bfloat16_nmse.t27`, `specs/api/tri_net_api.t27` (both contain `test`+`invariant`+`bench` per L4) +- **NEW** schemas: `schemas/nmse-protocol-v1.json`, `schemas/tri-net-api-v1.json` (draft-07) +- Docs-only; no `gen/`/`coq/`/`bootstrap/` edits; no new `*.sh`; R5-HONEST preserved (projections labelled; no DOIs quoted before upload) +- Full per-deliverable detail in `docs/NOW.md` +- Closes #696 ## Wave-42 Lane II — StochRound.v Stochastic Rounding Coq diff --git a/docs/22FDX_TOPS_W_PROJECTION.md b/docs/22FDX_TOPS_W_PROJECTION.md new file mode 100644 index 000000000..60f1a26a2 --- /dev/null +++ b/docs/22FDX_TOPS_W_PROJECTION.md @@ -0,0 +1,176 @@ +# 22FDX TOPS/W Projection Methodology + +> **READ FIRST:** Every number in this document is a **projection**, not a +> measurement on silicon. No die targeting 22FDX has been received, brought +> up, or characterised. The purpose of this document is to make the +> projection method itself inspectable, so that when (and if) silicon +> arrives, the gap between projection and measurement is auditable +> line-by-line. +> +> **R5-HONEST:** Any reader who reaches a section break without seeing the +> word "projection" in the previous paragraph should treat that omission as +> a bug and file an issue. + +--- + +## 1. Why 22FDX + +GlobalFoundries' 22FDX (22 nm fully-depleted SOI with adaptive body bias) +is named here because it is the smallest, fully-public PDK at which a +TRI-NET-class ternary mesh would still benefit from body-bias techniques +(W47 RBB, W48 FBB-active, W49 CapBoost in `trios-coq/Physics/`). It is +*not* selected because we have access to 22FDX shuttles; we do not, and +this document does not assume we will. + +Other plausible PDKs (Sky130, IHP-SG13G2, IHP-SG13S, TSMC N28HPC+, +SMIC 28HKC) would change the absolute numbers but not the projection +method. The method here is the contribution; the chosen PDK is the +worked example. + +--- + +## 2. What we are projecting + +The TOPS/W projection envelope, for a single tile of the gamma surface +(32 PEs), running INT1.58 inference, **assuming** all of: + +- LUT-NPU operator `OP_LUT_NPU = 0xE3` carries the inner loop; +- AVS-48 voltage stacking microcode is engaged + (`L2_BG_AVS96_STEP_GATE` extension on top); +- Sub-V_T weak-inversion clock domain at V = 0.30 V available + (`OP_SUBTH_CLK = 0xE4`); +- Triple-Deck RBB / FBB / CapBoost engaged (W47..W49 Coq lemmas); +- Activity factor 0.5 (industry-conservative, see references). + +These are *spec-level* assumptions backed by Coq lemmas in this repo. +None of them is a silicon claim. + +--- + +## 3. Confidence-level scheme + +Every projected figure is tagged with a confidence band: + +| Band | Meaning | +|--------|--------------------------------------------------------------------------------------| +| `C1` | Algebra-bound: derived directly from a Coq-proven identity; no PDK assumption. | +| `C2` | Toolchain-bound: derived from synthesis on an open PDK (Sky130 / Yosys) at this repo.| +| `C3` | Scaling-bound: PDK-to-PDK scaling rules applied to a `C2` number; cite the rule. | +| `C4` | Vendor-cited: backed by a published 22FDX datapoint from GF or a peer-reviewed paper.| +| `C5` | Speculative: no `C1..C4` backing; included only to show envelope and labelled red. | + +A reader is entitled to ignore any `C5` row and most `C3` rows when +forming an opinion about silicon. + +--- + +## 4. Baseline (current in-repo) + +The `STATUS.md` ladder shows the gamma mesh at `SIM` level (Verilog +generated, simulation passes). No `SYNTH` row exists for a 22FDX cell +library because no 22FDX cell library is integrated into the build. The +publicly cited baseline numbers used as projection anchors are: + +| Anchor | Value | Source / band | +|----------------------|----------------------|----------------------------------------| +| W34 baseline TOPS/W | 225 | `NOW.md` Wave-35 row; band `C2` (open) | +| W35 LUT-NPU lift | x1.20 | `NOW.md` Wave-35; Coq Qed; band `C1` | +| W36 AVS-48 lift | TOPS/W >= 297 | `NOW.md` Wave-36 W-104-B; band `C1` | +| W37 Sub-V_T lift | TOPS/W >= 350 | `NOW.md` Wave-37 W-104-C; band `C1` | +| W47 RBB lift | TOPS/W +1.5% | Coq lemma `rbb_*`; band `C1` | +| W48 FBB-active lift | TOPS/W +1.5..1.9% | Coq lemma `fbb_active_tops_w_lift_*` | +| W49 CapBoost lift | TOPS/W +0.7..0.9% | Coq lemma `cap_boost_tops_w_lift_*` | + +All of those are derived from in-repo Coq lemmas and are **algebra-bound** +(`C1`). They are NOT silicon measurements. + +--- + +## 5. 22FDX scaling assumptions (`C3` to `C4`) + +To reach a 22FDX projection from a Sky130-class baseline, we apply these +scaling rules: + +| Rule | Band | Notes | +|---------------------------------------------------------------|------|----------------------------------------------------| +| Dynamic-energy / op scales with `(V_22 / V_130)^2` | `C4` | textbook CMOS, cite Rabaey 2003 | +| Cap / op shrinks with `(L_22 / L_130)`, capped at 2x | `C3` | conservative; finFET-scaling literature is mixed | +| Leakage / op increases at low V_DD; offset by RBB at idle | `C3` | Tschanz JSSC 2002; matches W47 RBB lemma | +| Forward body bias at active path reduces delay ~12% | `C4` | Mukhopadhyay 2009 + W48 FBB lemma | +| 22FDX V_DD nominal 0.8 V; subthreshold 0.4 V | `C4` | GF 22FDX datasheet | +| f_max derating at subthreshold: x0.5 vs nominal | `C1` | W37 lemma `subth_freq_derating_factor_2` | + +A worked propagation of these rules onto the in-repo anchors yields a +**projected** TOPS/W envelope at 22FDX of: + +``` + nominal V_DD, no body bias : 350 - 420 TOPS/W (band C3) + nominal V_DD, with TripleDeck: 400 - 490 TOPS/W (band C3) + subthreshold V_DD, full stack: >=600 -- 800 TOPS/W (band C3+C4 mix) +``` + +No assertion is made that 22FDX silicon would deliver any of these. The +purpose of the table is to **make the method auditable** before silicon +exists. When silicon exists, this table is what gets falsified +line-by-line. + +--- + +## 6. Falsification policy + +Each row above is associated with a falsification witness in the Coq +ledger: + +- W34 baseline: `Trinity-loss sparsity >= 0.5 @ batch=1` (W-104-A). +- W36 AVS-48: `eta >= 0.93 => TOPS/W >= 297` (W-104-B; `avs_w104_b_witness`). +- W37 Sub-V_T: `V=0.30 + AVS48 + LUT-NPU => TOPS/W >= 350` (W-104-C; + `subth_w104_c_witness`). + +A 22FDX measurement that falsifies any of these will be reported and the +Coq lemma adjusted (or, more likely, the assumption set behind the lemma +narrowed). That is the deal. + +--- + +## 7. What this document does NOT do + +- It does not state a measured 22FDX TOPS/W number. +- It does not commit to a 22FDX tape-out. +- It does not compare 22FDX projections against any commercial product. +- It does not name a date for silicon. + +If the reader sees any of those done elsewhere on the basis of this +document, that is a misreading and should be reported as an issue. + +--- + +## 8. Cross-links + +- `NOW.md` Waves W34..W49 -- the running ledger of lifts. +- `STATUS.md` -- readiness ladder; no SYNTH or GDS at 22FDX. +- `BENCHMARKS.md` -- restrained posture; what is and isn't measured. +- `COMPETITORS.md` -- no parity claim against any commercial NPU. +- `trios-coq/Physics/` -- Coq lemmas that anchor the `C1` rows. +- `docs/TRI_NET_WHITEPAPER.md` -- the line's positioning. +- `tt-trinity-euler` / `tt-trinity-gamma` (chip repos) -- silicon + targeting decisions live there, not here. +- `docs/SCIENTIFIC_IMPROVEMENT_PLAN.md` -- EN-02 names this projection + table as the t27-side toolchain deliverable for energy work. + +--- + +## 9. References (external) + +- Rabaey, Chandrakasan, Nikolic, *Digital Integrated Circuits*, 2003. +- Tschanz et al., "Adaptive Body Bias for Reducing Impacts of Die-to-Die + and Within-Die Parameter Variations on Microprocessor Frequency and + Leakage", JSSC 2002. +- Mukhopadhyay et al., "Modeling and Analysis of Loading Effect in + Leakage of Nano-Scaled Bulk-CMOS Logic Circuits", 2009. +- Larsson and Svensson, "Noise in Digital Dynamic CMOS Circuits", 1994. +- Jiang et al., capacitive supply decoupling, 2018. +- GlobalFoundries 22FDX product brief (vendor page; cite at use). + +--- + +**phi^2 + 1/phi^2 = 3 | TRINITY** diff --git a/docs/GF16_BFLOAT16_NMSE_PROTOCOL.md b/docs/GF16_BFLOAT16_NMSE_PROTOCOL.md new file mode 100644 index 000000000..df79fdeac --- /dev/null +++ b/docs/GF16_BFLOAT16_NMSE_PROTOCOL.md @@ -0,0 +1,202 @@ +# GF16 vs bfloat16 NMSE Protocol + +> **Status:** SPEC. Protocol-level only. This document standardises *how* a +> GF16-vs-bfloat16 NMSE comparison is run and reported in the TRI-NET line. +> It does **not** publish silicon numbers -- those belong with the chip repos +> when (and only when) silicon evidence is available. +> +> **Source of truth:** `specs/benchmarks/gf16_bfloat16_nmse.t27` is the +> machine-readable spec; this document is the human-readable mirror. If the +> two disagree, the `.t27` spec wins and the disagreement is an issue. +> +> **R5-HONEST:** No row in this document asserts a measured silicon result. +> Reference distributions and tolerance windows are stated as protocol +> parameters, not outcomes. + +--- + +## 1. Scope and intent + +The TRI-NET numeric kernel is **GoldenFloat GF16** (primary path; see +`FORMAT_REGISTRY.md`). The dominant industry alternative at the same width +for inference workloads is **bfloat16** (BF16). Multiple parties have asked +for a like-for-like NMSE (normalised mean-squared error) comparison. The +purpose of this document is to define **one protocol** for that comparison +so that: + +1. results produced under it are reproducible from this repo; +2. results from chip repos (`tt-trinity-phi`, `tt-trinity-euler`, + `tt-trinity-gamma`) can be compared with the same methodology; +3. nothing in the protocol presumes a TOPS race -- only numeric fidelity. + +Out of scope: latency, throughput, energy. Those have their own (also +restrained) treatments in `BENCHMARKS.md`. + +--- + +## 2. Quantities + +Let `x` be a reference real value (drawn from a defined distribution, +section 4) and let `Q(x)` be the result of round-trip +`real -> format -> real` through a numeric format. Define + +``` +NMSE(F) + = E[ (x - Q_F(x))^2 ] / E[ x^2 ] +``` + +where the expectation is taken over the protocol's reference distribution. +Two formats are compared by reporting `NMSE(GF16)` and `NMSE(BF16)` against +the same sampled `x` set and the same RNG seed. + +**Important:** the ratio `NMSE(GF16) / NMSE(BF16)` is the headline number. +A ratio of 1.0 means equal numeric fidelity at the protocol's distribution; +< 1.0 means GF16 is closer to the reference for that distribution; > 1.0 +means BF16 is closer. No claim is attached to either direction without a +specific distribution and seed. + +--- + +## 3. Format definitions used by the protocol + +### 3.1 GF16 + +GF16 is defined by `specs/numeric/gf16.t27` and recorded in the SSOT +`conformance/FORMAT-SPEC-001.json`. Bit layout (mirror of +`FORMAT_REGISTRY.md` section 1): + +``` +GF16 = [ S(1) | E(6) | M(9) ] +value = (-1)^S * 2^(E - 31) * (1 + M / 2^9) +``` + +The protocol uses the canonical round-to-nearest, ties-to-even rounding +rule defined in the spec. + +### 3.2 bfloat16 + +BF16 is defined externally by the IEEE-754 binary32 layout with mantissa +truncated to 7 bits: + +``` +BF16 = [ S(1) | E(8) | M(7) ] +value = (-1)^S * 2^(E - 127) * (1 + M / 2^7) +``` + +The protocol uses round-to-nearest, ties-to-even. No subnormal handling +deviation is permitted; BF16 implementations that flush subnormals to zero +must declare that fact in the manifest (section 6). + +### 3.3 Why the comparison is meaningful + +GF16 and BF16 occupy the same memory footprint (16 bits). They differ in +how those 16 bits are split: GF16 gives 9 bits to the mantissa, BF16 gives +7. GF16's exponent field is 6 bits with bias 31; BF16's is 8 bits with +bias 127. The expected outcome is that **GF16 wins on near-1.0 dynamic +range, BF16 wins on very large / very small values**. The protocol must +not preempt this with a distribution chosen to favour either side. + +--- + +## 4. Reference distributions + +A run reports NMSE under **each** of these distributions independently. +A single number reported without naming a distribution is invalid under +this protocol. + +| Tag | Distribution | Rationale | +|-----------|------------------------------------------------|--------------------------------------| +| `D_NORM` | `x ~ N(0, 1)` | Generic weight-like distribution | +| `D_LOG` | `log2|x| ~ U(-10, 10)`, sign uniform | Geometric coverage of dynamic range | +| `D_RELU` | `x = max(0, N(0, 1))` | Post-activation weight distribution | +| `D_PHI` | `x ~ N(phi, 1/phi)`, where `phi=(1+sqrt 5)/2` | Identity-anchored sanity (L5) | +| `D_DEEP` | mixture: 0.7 `D_NORM` + 0.3 `D_LOG` | Heuristic for transformer weights | + +Each run uses 10 million samples per distribution unless explicitly +overridden in the manifest. + +--- + +## 5. Tolerance and identity check (L5) + +Before any NMSE figure is reported, a run **must** witness: + +``` +|phi^2 - (phi + 1)| < 1e-15 // f64 identity check +|phi^2 + 1/phi^2 - 3| < 1e-15 // canonical Trinity identity +``` + +Failing either witness aborts the run. This is L5 IDENTITY enforced at the +benchmark boundary. + +--- + +## 6. Results manifest + +A run produces one JSON file conforming to `schemas/nmse-protocol-v1.json`. +The schema requires, at minimum: + +- protocol version (semver); +- toolchain seal hash (matches `bootstrap/stage0/FROZEN_HASH`); +- RNG family and seed; +- sample count per distribution; +- per-distribution `NMSE_GF16`, `NMSE_BF16`, and their ratio; +- BF16 subnormal policy (`ieee` or `ftz`); +- runner identity (host architecture, compiler version); +- timestamp (RFC3339). + +A run that omits any required field is non-conforming and must not be +cited in TRI-NET documentation. + +--- + +## 7. Test obligations (L4) + +The companion spec `specs/benchmarks/gf16_bfloat16_nmse.t27` includes: + +- a `test` block that runs the identity witness; +- an `invariant` block that asserts `NMSE >= 0` for each format; +- a `bench` block that defines the measurement procedure. + +These are the L4 TESTABILITY requirements for this benchmark family. + +--- + +## 8. Reporting policy + +When a chip-repo or third-party result is cited: + +- ratio reported only when both sides came from the same seed/distribution; +- protocol version stated; +- seal hash stated (or `unsealed` if not measured under a sealed toolchain + -- in which case the result is informational, not certifying); +- no comparison against a commercial-NPU number is permitted in this + protocol's outputs (see `COMPETITORS.md` for why). + +--- + +## 9. Cross-links + +- Numeric SSOT: `conformance/FORMAT-SPEC-001.json`, `FORMAT_REGISTRY.md`. +- Sibling repos that may emit conforming manifests: + - `tt-trinity-phi` (phi-anchor, 1x1) -- identity-domain NMSE only. + - `tt-trinity-euler` (8x2, safety) -- `D_NORM` and `D_RELU` envelopes. + - `tt-trinity-gamma` (8x4, 32-PE mesh) -- `D_DEEP` is the headline. +- TRI-NET API doc: `docs/TRI_NET_API.md` -- how an external integrator + reads NMSE manifests programmatically. +- Roadmap: `docs/SCIENTIFIC_IMPROVEMENT_PLAN.md` -- PUB-02 names "one + sealed-toolchain NMSE manifest" as a 2026 target deliverable. + +--- + +## 10. Non-claims (R5-HONEST) + +- This document does **not** claim a measured silicon NMSE for any product. +- This document does **not** claim GF16 is universally better than BF16. +- This document does **not** claim a fixed `NMSE(GF16) / NMSE(BF16)` ratio. +- It defines **how** to measure such ratios so claims, when made, are + reproducible. + +--- + +**phi^2 + 1/phi^2 = 3 | TRINITY** diff --git a/docs/NOW.md b/docs/NOW.md index 16f1064d2..25c3664db 100644 --- a/docs/NOW.md +++ b/docs/NOW.md @@ -1,7 +1,22 @@ -# NOW — Trinity t27 sync +# NOW -- Trinity t27 sync Last updated: 2026-05-18 +## docs(TRI-NET) -- cross-line package P0 NMSE / P1 API+whitepaper / P2 22FDX + Zenodo (this PR, Closes #696) + +- **NEW** (docs-only, additive): `docs/GF16_BFLOAT16_NMSE_PROTOCOL.md`, `docs/TRI_NET_API.md`, `docs/TRI_NET_WHITEPAPER.md`, `docs/22FDX_TOPS_W_PROJECTION.md`, `docs/ZENODO_BUNDLES.md`, `docs/SCIENTIFIC_IMPROVEMENT_PLAN.md` (2026 t27-side roadmap: CL-01..04 DARPA-CLARA alignment, EN-01..03 energy, SN-01..03 SNN-TRI fusion, PUB-01..03 publication, OS-01..03 open-source SDK / Coq export / contribution path; every row labelled `VERIFY`, `projection`, or `target` -- no funding / silicon-date / paper-acceptance / `1000x` / `4000 TOPS/W` / new-DOI claim) +- **NEW** machine-readable specs: `specs/benchmarks/gf16_bfloat16_nmse.t27` (L4 TESTABILITY: `test` + `invariant` + `bench`), `specs/api/tri_net_api.t27` (L4 TESTABILITY: `test` + `invariant` + `bench`) +- **NEW** JSON schemas: `schemas/nmse-protocol-v1.json` (draft-07, results manifest), `schemas/tri-net-api-v1.json` (draft-07, RepoIdentity / Readiness / ArtefactIndex shapes) +- **P0** GF16 vs bfloat16 NMSE: distribution-explicit (D_NORM, D_LOG, D_RELU, D_PHI, D_DEEP); no silicon number asserted; L5 IDENTITY witness gates every run (`phi^2 + 1/phi^2 = 3` to 1e-15 in f64); BF16 subnormal policy must be declared; seal hash must match `bootstrap/stage0/FROZEN_HASH` or manifest is informational only +- **P1** TRI-NET API: file-based, read-only; explicitly NOT a hosted endpoint; schema MAJOR=1; fail-closed validation; extensions under `x_extension` +- **P1** Whitepaper: position paper only; mirrors `STATUS.md` readiness ladder; no parity claim against commercial NPUs (see `COMPETITORS.md`); cross-links chip repos `tt-trinity-phi`, `tt-trinity-euler`, `tt-trinity-gamma` +- **P2** 22FDX TOPS/W: every row tagged with confidence band C1..C5; C1 rows trace to existing Coq lemmas (W34..W49 in `trios-coq/Physics/`); no measured silicon number; falsification policy enumerated; no tape-out date claimed +- **P2** Zenodo bundles plan: v1 toolchain / v2 silicon-substrate / v3 proofs+conformance; **no DOI quoted before upload**; existing canonical B001..B007 + v5.0 parent (cited in `docs/ZENODO.md`) are predecessor records, not v1/v2/v3 +- **Cross-links** to chip repos: D2D protocol spec is owned by `tt-trinity-euler` / `tt-trinity-gamma`; t27 surfaces only the toolchain-side hooks. Triple-Deck (W47 RBB + W48 FBB-active + W49 CapBoost) Coq lemmas already in `trios-coq/Physics/` per existing NOW entries; chip-side implementation lives in chip repos. +- **L1 TRACEABILITY**: PR cites `Closes #696`. **L2 GENERATION**: zero edits under `gen/`, `coq/`, `trios-coq/`, `proofs/`, `bootstrap/`. **L3 PURITY**: all new files ASCII / English (verifiable via `scripts/check_first_party_doc_language.py`). **L4 TESTABILITY**: both new `.t27` specs contain `test` + `invariant` + `bench`. **L5 IDENTITY**: `phi^2 + 1/phi^2 = 3` cited verbatim in every new doc and witnessed in NMSE protocol. **L6 CEILING**: `FORMAT-SPEC-001.json` + `specs/numeric/gf16.t27` referenced as SSOT; no numeric kernel changes. **L7 UNITY**: zero new `*.sh`. +- **R5-HONEST**: every projection in `docs/22FDX_TOPS_W_PROJECTION.md` labelled "projection, not measured silicon"; every Zenodo row tagged `pending`; whitepaper claims strictly bounded by `STATUS.md` ladder +- Closes #696 + ## ci(notebook-sync) — repair workflow syntax causing instant failures (this PR, #694, Closes #695) - **Fixed**: `.github/workflows/notebook-sync.yml` was failing instantly on every push since #693 merged — runs completed in seconds with `conclusion=failure`, zero jobs dispatched, `gh run view --log-failed` reported *log not found*. diff --git a/docs/README.md b/docs/README.md index a5344ada5..0caf3911b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -49,6 +49,17 @@ TDD, bootstrap/testing plans, math/physics test framework charter, PHI loop, tec |---------|-------------|-------| | **CLARA DARPA PA-25-07-02** | DARPA CLARA submission package (moved 2026-04-15) | [ghashTag/trinity-clara](https://github.com/gHashTag/trinity-clara) | +## TRI-NET cross-line package (docs-only) + +| Path | Role | +|------|------| +| [`TRI_NET_WHITEPAPER.md`](TRI_NET_WHITEPAPER.md) | Position paper -- open high-assurance ternary AI silicon substrate. | +| [`TRI_NET_API.md`](TRI_NET_API.md) | File-based, read-only external integration contract (schema MAJOR=1). | +| [`GF16_BFLOAT16_NMSE_PROTOCOL.md`](GF16_BFLOAT16_NMSE_PROTOCOL.md) | Distribution-explicit NMSE comparison protocol; L5 identity-witness-gated. | +| [`22FDX_TOPS_W_PROJECTION.md`](22FDX_TOPS_W_PROJECTION.md) | Energy projection methodology with C1..C5 confidence bands (projection, not measured). | +| [`ZENODO_BUNDLES.md`](ZENODO_BUNDLES.md) | v1 / v2 / v3 Zenodo bundle plan -- no DOI quoted before upload. | +| [`SCIENTIFIC_IMPROVEMENT_PLAN.md`](SCIENTIFIC_IMPROVEMENT_PLAN.md) | 2026 t27-side roadmap (CL-01..04, EN-01..03, SN-01..03, PUB-01..03, OS-01..03). | + --- **φ² + 1/φ² = 3 | TRINITY** diff --git a/docs/SCIENTIFIC_IMPROVEMENT_PLAN.md b/docs/SCIENTIFIC_IMPROVEMENT_PLAN.md new file mode 100644 index 000000000..eac8f096d --- /dev/null +++ b/docs/SCIENTIFIC_IMPROVEMENT_PLAN.md @@ -0,0 +1,235 @@ +# TRI-NET 2026 Scientific Improvement Plan -- t27 (toolchain side) + +> **Status:** PLAN. This document is the **t27-side projection** of the +> line-level TRI-NET 2026 scientific improvement plan. It enumerates +> what the **toolchain product** of the line (specs, compilers, +> conformance vectors, schemas, Coq export, SDK) is expected to ship +> in 2026 to support the line's DARPA-CLARA-aligned, energy-efficient, +> SNN-fused, peer-reviewed, open-source posture. +> +> **R5-HONEST gating.** Every row in every table below carries one of +> three labels: +> +> - `VERIFY` -- claim sourced from outside this repo; integrator must +> verify before quoting. No funding, no programme date, no paper +> acceptance is asserted as fact in this document. +> - `projection` -- architecture-level estimate, not measured silicon. +> - `target` -- programmatic goal, not an achieved outcome. +> +> Anything that is **measured** in this repo today is in +> `STATUS.md` / `BENCHMARKS.md` instead, and is not duplicated here. + +--- + +## 1. Scope + +This plan covers what **`t27`** ships in 2026: tools, schemas, specs, +conformance, Coq export, and integration surfaces. Per-chip readiness +(GDS / pinout / silicon return) lives in the chip repos +(`tt-trinity-phi`, `tt-trinity-euler`, `tt-trinity-gamma`); their own +SCIENTIFIC_IMPROVEMENT_PLAN documents are the authoritative source +there. This document is the **toolchain mirror** of the line plan. + +Cross-links to companion docs: + +- `docs/TRI_NET_WHITEPAPER.md` -- positioning +- `docs/TRI_NET_API.md` -- external integration contract +- `docs/GF16_BFLOAT16_NMSE_PROTOCOL.md` -- numeric comparison protocol +- `docs/22FDX_TOPS_W_PROJECTION.md` -- energy projection methodology +- `docs/ZENODO_BUNDLES.md` -- DOI bundle plan (v1 / v2 / v3) +- `STATUS.md` -- readiness ladder (authoritative for measured state) +- `BENCHMARKS.md` -- restrained benchmark posture +- `COMPETITORS.md` -- honest positioning + +--- + +## 2. DARPA CLARA alignment (CL-01..CL-04) + +> **No claim is made that CLARA has funded this work; no programme +> date is named.** The rows below are technical alignments visible in +> this repo today, not funding statements. The full assurance +> workflow lives in `clara-bridge/` and `CLARA_TRACEABILITY.md`. + +| ID | Track | t27 deliverable | Label | +|----|-------|------------------|-------| +| CL-01 | Drain-on-restraint semantic surface | Toolchain-side hooks in `docs/TRI_NET_API.md` so chip-repo D2D protocols can be consumed by external auditors without scraping. **D2D protocol itself lives in `tt-trinity-euler` / `tt-trinity-gamma`, not here.** | `target` | +| CL-02 | Assurance bridge (CLARA-style reasoning) | `clara-bridge/` exit-criteria documented; conformance vectors `conformance/ar_*.json` validated against the bridge demo. | `target` | +| CL-03 | Spec-to-RTL traceability | Every `gen/verilog/` artefact traceable to a sealed `.t27` spec; seal-hash field in `schemas/tri-net-api-v1.json#/$defs/RepoIdentity`. | `target` | +| CL-04 | Formal cross-walk | Coq export crate that ingests `.v` files from `coq/` and `trios-coq/` and emits a citation-map JSON consumable by external review tooling. | `target` | + +**Out of scope here:** any statement on whether the chip repos hit +their own CL-01..CL-04 rows. Those are in their SIP documents. + +--- + +## 3. Energy efficiency (EN-01..EN-03) + +> **No `1000x` or `4000 TOPS/W` claim is restated as fact.** Any +> external press figure of that shape is `VERIFY` -- integrator must +> chase the source before quoting. The existing in-repo +> `28-120 TOPS/W` band stays `projection`, with back-links to +> `BENCHMARKS.md` and `docs/22FDX_TOPS_W_PROJECTION.md`. + +| ID | Track | t27 deliverable | Label | +|----|-------|------------------|-------| +| EN-01 | Triple-Deck (RBB + FBB + CapBoost) toolchain support | Coq lemmas already landed in `trios-coq/Physics/CapBoost.v`, `FBBActive2.v`, plus W47 RBB (per `docs/NOW.md`). t27 ships the **citation-map JSON** that lets chip repos point a single artefact at the proofs. Chip-side RTL status (which of RBB / FBB / CapBoost is implemented vs witness-only) is reported in each chip's `TRIPLE_DECK_STATUS.md`. | `projection` (Coq) + `target` (citation export) | +| EN-02 | 22FDX TOPS/W projection methodology | `docs/22FDX_TOPS_W_PROJECTION.md` shipped with C1..C5 confidence bands; falsification policy enumerated. No measured silicon row. | `projection` | +| EN-03 | External press TOPS/W figures | Not restated in this document. If a press release names a figure (`1000x`, `4000 TOPS/W`, etc.), the integrator must `VERIFY` the source before quoting and must label the quoted number `projection` or `target` depending on the source's own framing. | `VERIFY` | + +**Reminder.** `BENCHMARKS.md` is the authoritative restraint policy: +the repo publishes only numbers reproducible from a sealed spec or +generated file. When in doubt, omit the row. + +--- + +## 4. SNN-TRI fusion (SN-01..SN-03) + +> Surface-level only. t27 hosts the **format** and the **NMSE +> comparison protocol**; SNN integration on the silicon side is owned +> by the chip repos. No `Delta_dB` number exists in t27 today; this +> doc forbids quoting one until a `bench/results/nmse-*.json` lands. + +| ID | Track | t27 deliverable | Label | +|----|-------|------------------|-------| +| SN-01 | NMSE harness for SNN-relevant distributions | `specs/benchmarks/gf16_bfloat16_nmse.t27` ships `D_NORM`, `D_LOG`, `D_RELU`, `D_PHI`, `D_DEEP`. SNN-specific tags can be added under `x_extension` (see `schemas/nmse-protocol-v1.json`) without breaking the schema MAJOR. | `target` | +| SN-02 | Theta-gate / StochSkip surface for fusion designs | Coq lemma `StochSkipSafe.v` already landed (hippocampal theta anchor, per `docs/NOW.md`); t27 ships the **lemma index** that chip repos and SNN integrators consume. | `projection` (lemma) + `target` (index export) | +| SN-03 | INT2 codebook for SNN spike weights | `Int2QuantSafe.v` Coq lemma already landed. t27 ships the **codebook description** in `FORMAT_REGISTRY.md` as a planned-bridge row; full `.t27` spec for the codebook is a `target` for 2026. | `projection` (lemma) + `target` (spec) | + +--- + +## 5. Publication path (PUB-01..PUB-03) + +> Framed as "draft and submit", not "accepted at venue X". No paper +> acceptance is asserted as fact. + +| ID | Track | t27 deliverable | Label | +|----|-------|------------------|-------| +| PUB-01 | GoldenFloat family paper | `docs/WHITEPAPER/gf_paper_v3_imrad_draft.md` already exists in the repo. 2026 work: harden citations, run the NMSE protocol from PUB-02 on a fixed seed set, attach the manifest. | `target` | +| PUB-02 | NMSE manifest contributing to a publication | One sealed-toolchain `bench/results/nmse-*.json` produced under `docs/GF16_BFLOAT16_NMSE_PROTOCOL.md`. **No `Delta_dB` figure introduced before this manifest lands.** | `target` | +| PUB-03 | Tooling / spec-first methodology paper | A whitepaper-derivative doc that bundles `docs/TRI_NET_WHITEPAPER.md`, `STATUS.md`, `LINEUP.md`, `COMPETITORS.md` for an external review venue (workshop / preprint server). Draft only; submission is downstream. | `target` | + +--- + +## 6. Open-source community (OS-01..OS-03) + +| ID | Track | t27 deliverable | Label | +|----|-------|------------------|-------| +| OS-01 | TRI-NET API SDK -- Python (read-only) | A `tri-net-py` package (separate repo, name `target`) that consumes `schemas/tri-net-api-v1.json`, `schemas/nmse-protocol-v1.json`, `schemas/numeric-format-v1.json` and produces typed bindings. **Read-only**, file-based, mirroring `docs/TRI_NET_API.md`. No hosted endpoint added. | `target` | +| OS-02 | Coq export | A small crate / script under `tools/` that walks `coq/`, `trios-coq/`, `proofs/` and emits a single manifest JSON enumerating `Theorem` / `Lemma` / `Qed` / `Admitted` counts per file, plus a citation map. Consumed by Zenodo v3 (`docs/ZENODO_BUNDLES.md`). | `target` | +| OS-03 | Conformance vector contribution path | A `CONTRIBUTING.md` addendum that explains how to add a new conformance vector under `conformance/` and route it through `./scripts/tri validate-conformance`. Mirrors the L4 TESTABILITY mandate. | `target` | + +The SDK row (OS-01) is **read-only**. Producer-side mutation of TRI-NET +artefacts is not in scope -- producers are the t27 build itself and the +chip-repo CI jobs, not the Python SDK. + +--- + +## 7. Timeline + +> Quarter labels are **targets**, not commitments. "Open" means no +> date is named because the work depends on artefacts outside t27's +> control (silicon return, external review timelines). + +| Quarter | Theme | t27 deliverables | +|---------|-------|------------------| +| **Q2 2026** | NMSE harness usable end-to-end | `target` PUB-02 first sealed manifest; `target` OS-03 contribution path documented | +| **Q3 2026** | Energy projection auditable | `target` EN-02 22FDX projection table linked from chip-repo SIPs; `target` OS-02 Coq export draft | +| **Q4 2026** | Read-only Python SDK preview | `target` OS-01 SDK preview release; `target` SN-01 SNN-tagged NMSE manifest under `x_extension` | +| **open** | Silicon return for any chip in the line | t27-side: when a chip repo posts a measured TOPS/W or NMSE manifest, t27 wires it into `STATUS.md` and `bench/results/`. No date here. | +| **open** | Paper acceptance | t27-side: PUB-01 / PUB-03 drafts ready; acceptance is venue-controlled and not promised. | +| **open** | Zenodo v1 / v2 / v3 upload | Per `docs/ZENODO_BUNDLES.md` pre-upload gates. No DOI quoted. | + +--- + +## 8. Success metrics + +> The only metrics that count here are **CI-green workflows** and +> **committed artefacts**, both of which are auditable from this repo. +> Throughput / latency / energy metrics live in the chip repos when +> backed by silicon. + +| Metric | Source of truth | Today | Target end of plan | +|--------|------------------|-------|--------------------| +| `.t27` specs that parse via `t27c parse` | README "System Status" + `STATUS.md` | 170+ | `target` 200+ | +| `gen/verilog/` modules that pass simulation | `STATUS.md` 2.1 | 5/5 | `target` 5/5 maintained; new modules tracked | +| Sealed artefacts under `.trinity/seals/` | `STATUS.md` 2.1 | 729 (at audit time) | `target` strictly non-decreasing | +| Coq files with zero `Admitted` cited in line plans | `trios-coq/Physics/`, `coq/` | per `docs/NOW.md` ledger | `target` zero `Admitted` in any file cited by Zenodo v3 manifest | +| Conforming NMSE manifests under `bench/results/` | `docs/GF16_BFLOAT16_NMSE_PROTOCOL.md` | 0 | `target` at least 1 sealed manifest for PUB-02 | +| Schema files validating draft-07 | `schemas/` | 3 (numeric-format / tri-net-api / nmse-protocol) | `target` 3+ maintained; new schemas added only via constitutional / issue review | +| Documents passing `scripts/check_first_party_doc_language.py` | the gate itself | PASS (today) | `target` PASS maintained | + +No silicon-bound metric appears in this table on purpose. When +silicon does land, the metric joins `STATUS.md`, not this plan. + +--- + +## 9. References + +> Repo-internal references are authoritative. External references are +> labelled `VERIFY` and must be checked at the linked source before +> being quoted in derivative work. + +**Repo-internal (authoritative):** + +- `STATUS.md` -- readiness ladder +- `LINEUP.md` -- the four-product map +- `BENCHMARKS.md` -- restrained benchmark posture +- `COMPETITORS.md` -- honest positioning +- `FORMAT_REGISTRY.md` -- numeric SSOT mirror +- `CLARA_TRACEABILITY.md` -- assurance bridge to DARPA CLARA +- `docs/T27-CONSTITUTION.md` -- L1..L7 constitutional stack +- `docs/TRI_NET_WHITEPAPER.md` -- positioning paper +- `docs/TRI_NET_API.md` -- external integration contract +- `docs/GF16_BFLOAT16_NMSE_PROTOCOL.md` -- numeric comparison protocol +- `docs/22FDX_TOPS_W_PROJECTION.md` -- energy projection methodology +- `docs/ZENODO_BUNDLES.md` -- DOI bundle plan +- `docs/ZENODO.md` -- existing canonical DOIs (B001..B007 + v5.0 parent) +- `docs/NOW.md` -- rolling ledger of Coq lemmas and waves +- `trios-coq/Physics/` -- W34..W49 Coq lemmas +- `conformance/FORMAT-SPEC-001.json` -- numeric registry SSOT +- `schemas/numeric-format-v1.json`, `schemas/tri-net-api-v1.json`, + `schemas/nmse-protocol-v1.json` -- public draft-07 schemas +- `CITATION.cff`, `codemeta.json`, `.zenodo.json` -- repo identity + +**External (all `VERIFY` -- not quoted as fact in this doc):** + +- DARPA CLARA program page (darpa.mil; date / wording must be checked + at source before any derivative cites it). +- Any 22FDX vendor brief from GlobalFoundries (vendor page; cite at + use, not pre-cached here). +- Any commercial-NPU TOPS/W figure (Coral / Hailo / Axelera / Qualcomm / + MediaTek). `COMPETITORS.md` already documents the restraint. +- Line-level TRI-NET 2026 plan from coordinator notes outside this + repo. **Authoritative copy is outside `t27`.** This document is + the t27-side projection. + +**Coq references** in `trios-coq/Physics/` cite published prior work +(Rabaey, Tschanz, Mukhopadhyay, Larsson and Svensson, Jiang et al., +Hubara, Gupta) per the existing NOW ledger entries. Those are +secondary to the in-repo Coq lemmas and are not restated here. + +--- + +## 10. What this document is NOT + +- **NOT a funding statement.** No claim is made that DARPA / CLARA / + any other agency has funded this work, contracted it, or + scheduled it. `CL-01..CL-04` are technical alignment rows, not + funding rows. +- **NOT a tape-out commitment.** No silicon arrival date is named. + Chip-repo timelines are owned by chip repos. +- **NOT a paper acceptance claim.** `PUB-01..PUB-03` are + draft-and-submit rows; acceptance is venue-controlled. +- **NOT a `1000x` or `4000 TOPS/W` claim.** Any such figure that + surfaces in derivative work must carry `VERIFY` and a source URL. +- **NOT a new DOI.** Only `10.5281/zenodo.19227877` (existing B007 + record, per `docs/ZENODO.md`) is referenced; v1 / v2 / v3 DOIs do + not exist until upload (see `docs/ZENODO_BUNDLES.md`). +- **NOT a hosted-service announcement.** The TRI-NET API remains + file-based and read-only (see `docs/TRI_NET_API.md`). +- **NOT a NPU parity claim.** `COMPETITORS.md` continues to govern + the line's restraint posture. + +--- + +**phi^2 + 1/phi^2 = 3 | TRINITY** diff --git a/docs/TRI_NET_API.md b/docs/TRI_NET_API.md new file mode 100644 index 000000000..772795786 --- /dev/null +++ b/docs/TRI_NET_API.md @@ -0,0 +1,173 @@ +# TRI-NET API for External Integration + +> **Status:** SPEC (draft). Interface shape only. No runtime endpoint is +> hosted from this repo and none is promised. This document specifies the +> *shape* of an integration interface that external tools may rely on when +> they consume TRI-NET artefacts (specs, conformance vectors, NMSE +> manifests, format registry, seal hashes). +> +> **Source of truth:** `specs/api/tri_net_api.t27` and +> `schemas/tri-net-api-v1.json`. If this Markdown disagrees with either, +> the spec / schema wins. + +--- + +## 1. What this API is, in one paragraph + +TRI-NET exposes a small set of **read-only artefacts** that downstream +tools (chip-repo bring-up scripts, CI gates, third-party auditors) can +consume programmatically. The interface is **file-based, not network-based**: +the canonical "TRI-NET API" is a contract over the JSON files that live in +this repo (and in sibling chip repos that follow the same schema). There is +no proprietary REST surface, no SDK, and no service in scope here. + +This is deliberate. R5-HONEST forbids us from describing a hosted runtime +we do not actually operate. + +--- + +## 2. Versioning + +- Schema version follows semver: `MAJOR.MINOR.PATCH`. +- `MAJOR` change is a breaking change; consumers must opt in. +- A consumer SHOULD reject an artefact whose schema major does not match + what the consumer was written against. +- The current schema is `1.0` (see `schemas/tri-net-api-v1.json`). + +--- + +## 3. Artefact families + +Each family below has a canonical filename pattern and a canonical schema +fragment. A TRI-NET-conforming artefact lives at a path matching the +pattern and validates against the schema. + +### 3.1 Format registry + +- **Path:** `conformance/FORMAT-SPEC-001.json` (this repo is the canonical + host of the registry; chip repos consume, do not republish). +- **Schema:** `schemas/numeric-format-v1.json` (existing, unchanged). +- **Stability:** L6 CEILING -- only changed via constitutional amendment. + +### 3.2 NMSE protocol results + +- **Path pattern:** `bench/results/nmse---.json`. +- **Schema:** `schemas/nmse-protocol-v1.json` (new, see + `docs/GF16_BFLOAT16_NMSE_PROTOCOL.md`). +- **Stability:** SPEC. A new minor field is non-breaking; renaming an + existing field is breaking. + +### 3.3 Toolchain seal hash + +- **Path:** `bootstrap/stage0/FROZEN_HASH` (plain text, single SHA-256 + hex digest). +- **Stability:** GREEN -- defined by the constitutional stack + (`AGENTS.md` section 3, item 6). + +### 3.4 Readiness ladder + +- **Path:** `STATUS.md` (human-readable) with table cells one of + `SPEC`, `RTL`, `SIM`, `SYNTH`, `GDS/TAPEOUT`, `SILICON`. +- **Programmatic mirror:** OPTIONAL `bench/readiness.json` -- when present, + conforms to schema fragment `tri-net-api-v1#/$defs/Readiness`. +- **Stability:** SPEC. Programmatic mirror is opt-in. + +### 3.5 Conformance vectors + +- **Path pattern:** `conformance/*.json`. +- **Schema:** family-specific (existing `gf*_vectors.json`, `ar_*.json`, + `nn_*.json`, `sacred_physics*.json`). +- **Stability:** SPEC for new families; existing families are GREEN. + +### 3.6 Cross-repo identity + +- **Path:** `tri-net-identity.json` (optional, top-level of each repo in + the line, including chip repos). +- **Schema:** `schemas/tri-net-api-v1.json#/$defs/RepoIdentity`. +- **Purpose:** lets a consumer enumerate the four products of the line + without scraping documentation. + +--- + +## 4. Consumer contract + +A consumer that depends on the TRI-NET API: + +1. MUST pin a schema major version. +2. MUST validate every artefact against the relevant schema fragment + before treating its fields as authoritative. +3. MUST fail closed on schema violation; partial parsing is forbidden. +4. SHOULD verify `bootstrap/stage0/FROZEN_HASH` matches the seal recorded + in any artefact whose `seal_hash` field is present. +5. SHOULD log the schema version in any output it produces. + +--- + +## 5. Producer contract + +A producer (e.g. a chip repo's CI job): + +1. MUST emit only artefacts that validate against the active schema. +2. MUST include the schema version field at the artefact root. +3. MUST NOT add undocumented top-level fields; extensions live under a + reserved `x_extension` object. +4. MUST cite the toolchain seal hash if numeric results are reported. +5. SHOULD include a `tri-net-identity.json` at repo root. + +--- + +## 6. What this API is NOT + +- It is not a hosted HTTP service. +- It is not an SDK with bindings shipped from this repo. +- It is not a real-time control plane for any chip. +- It does not expose any silicon-bring-up endpoint. + +If a future hosted endpoint is added, it will be a separate document and a +separate contract. + +--- + +## 7. Worked example: NMSE manifest consumer + +A third-party auditor wants to verify a claimed GF16-vs-BF16 result: + +1. Fetch the manifest at `bench/results/nmse---.json`. +2. Validate against `schemas/nmse-protocol-v1.json`. Reject on failure. +3. Read `seal_hash` and compare against the repo's + `bootstrap/stage0/FROZEN_HASH`. Reject on mismatch. +4. Read `protocol_version`. Reject if outside the accepted major range. +5. Read the per-distribution `nmse_gf16` / `nmse_bf16` pairs. Treat any + distribution not listed in `docs/GF16_BFLOAT16_NMSE_PROTOCOL.md` section 4 as + informational, not certifying. +6. Output is the validated, signed-by-seal table -- no further trust step + needed. + +--- + +## 8. Cross-links + +- Whitepaper: `docs/TRI_NET_WHITEPAPER.md` +- NMSE protocol: `docs/GF16_BFLOAT16_NMSE_PROTOCOL.md` +- Numeric SSOT: `FORMAT_REGISTRY.md`, `conformance/FORMAT-SPEC-001.json` +- Readiness: `STATUS.md` +- Sibling chip repos: `LINEUP.md` (the four-product map) +- Chip-side D2D protocol (out of scope here, handled in + `tt-trinity-euler` / `tt-trinity-gamma`). +- Roadmap: `docs/SCIENTIFIC_IMPROVEMENT_PLAN.md` -- OS-01 names the + Python SDK target that consumes this API's schemas read-only. + +--- + +## 9. R5-HONEST notes + +- The API is file-based today; no hosted endpoint is implied. +- Schemas are conservative -- they describe SHAPE, not semantic guarantees + about silicon behaviour. +- No throughput, latency, or energy field is part of the canonical + surface. Those, if added later, will be under `x_extension` until + promoted by an issue + PR + constitutional review. + +--- + +**phi^2 + 1/phi^2 = 3 | TRINITY** diff --git a/docs/TRI_NET_WHITEPAPER.md b/docs/TRI_NET_WHITEPAPER.md new file mode 100644 index 000000000..1737dbed7 --- /dev/null +++ b/docs/TRI_NET_WHITEPAPER.md @@ -0,0 +1,229 @@ +# TRI-NET Whitepaper -- Open High-Assurance Ternary AI Silicon Substrate + +> **Status:** Position paper. Reflects the current ambition of the TRI-NET +> line and the state of `t27` (the toolchain product of the line). Every +> silicon-readiness statement here is a strict mirror of `STATUS.md` -- +> nothing here outruns that file. +> +> **R5-HONEST:** This document does not promise tape-outs, does not name +> dates, and does not claim parity with any commercial product. + +--- + +## 1. Thesis (one paragraph) + +The AI-accelerator industry optimises for TOPS, TOPS/W, and SDK breadth. +TRI-NET is not optimising for any of those. TRI-NET optimises for a +different vector: **how much of an inference accelerator can be made +inspectable, formal-friendly, and reproducible from a sealed +specification?** The line bets that, for a growing class of users +(scientific compute, safety-critical inference, on-device assurance, +regulated deployments), the answer "all of it, from `.t27` spec through +Verilog RTL through Tiny Tapeout shuttle" is more valuable than a few +percent of TOPS/W. + +--- + +## 2. What we are + +TRI-NET is a **product line of four open artefacts**: + +| Product | Role | Repo (separate) | +|--------------------|-------------------------------------------|-------------------------| +| `t27` | Spec-first toolchain, numeric registry | this repo | +| `tt-trinity-phi` | 1x1 phi-anchor / identity chip | `tt-trinity-phi` | +| `tt-trinity-euler` | 8x2 safety / control engine | `tt-trinity-euler` | +| `tt-trinity-gamma` | 8x4 32-PE ternary mesh | `tt-trinity-gamma` | + +The toolchain product is `t27`. The three chip products use `t27`'s +generators to produce their Verilog from `.t27` specifications, rather than +hand-writing HDL. The numeric kernel -- GoldenFloat GF16 (primary path) and +its family (GF4..GF32) -- lives in `t27` as the L6 CEILING SSOT +(`conformance/FORMAT-SPEC-001.json`). + +See `LINEUP.md` for the full four-product map; this whitepaper does not +duplicate it. + +--- + +## 3. What we are not + +- **Not a TOPS race.** We have not benchmarked against commercial NPUs + (Coral Edge TPU, Hailo-8, Axelera Metis, Qualcomm Cloud AI 100 Ultra, + MediaTek Dimensity 9400+). See `COMPETITORS.md` for the restrained + posture. +- **Not a private fab line.** The silicon target is the **Tiny Tapeout + shuttle** (1x1 / 2x2 / 4x4 / 8x4 tiles). No private mask set is + implied. +- **Not a hosted SDK.** The API surface is **file-based**, not network- + based; see `docs/TRI_NET_API.md`. +- **Not a closed numeric kernel.** GF16 is fully specified in + `specs/numeric/gf16.t27`; its evidence vectors are in + `conformance/gf*_vectors.json`. + +--- + +## 4. Why "high-assurance ternary" + +### 4.1 Ternary + +Ternary inference (weights in `{-1, 0, +1}` or close cousins like INT1.58) +removes the multiplier from the dominant inner loop. R-SI-1, our keystone +constraint, says **the multiplier-free path must remain multiplier-free**. +Coq witnesses for this -- for the LUT-NPU kernel, the AVS-48 voltage +stacking microcode, the AVS-96 dopamine safety gate, the StochRound +operator, the StochSkipSafe gate, the Int2QuantSafe codebook, the RBB / +FBB / CapBoost triple-decker -- already live in `trios-coq/` and +`coq/`. See `NOW.md` for the running ledger. + +### 4.2 High-assurance + +Every block on the critical path is: + +1. authored as a `.t27` spec with `test` / `invariant` / `bench` blocks + (L4 TESTABILITY); +2. compiled by a sealed bootstrap compiler whose hash is recorded at + `bootstrap/stage0/FROZEN_HASH` (L2 GENERATION); +3. emitted to `gen/verilog/` (or `fpga/vivado/`) without hand-edit + (L2); +4. accompanied by conformance vectors under `conformance/` (correctness, + not throughput -- see `BENCHMARKS.md`); +5. cross-checked by Coq lemmas where the operator is sacred (the W34..W49 + ledger). + +This is the assurance posture. It is verifiable today from this repo's +own files; no external trust step is needed. + +### 4.3 Open + +- License: Apache-2.0 (root LICENSE, NOTICE). +- Specs: `specs/` -- all `.t27`. +- Schemas: `schemas/` -- JSON Schema, draft-07. +- Conformance: `conformance/` -- JSON SSOT. +- Coq: `coq/`, `trios-coq/`, `proofs/`. +- Numeric SSOT: `FORMAT_REGISTRY.md` + `conformance/FORMAT-SPEC-001.json`. + +The Tiny Tapeout shuttle target is itself open; the chip repos publish +GDS / pinout / submission per repo when made. + +--- + +## 5. The numeric kernel + +GoldenFloat GF16 is the primary 16-bit format of the line. The bit layout, +decode formula, and identity witnesses live in `FORMAT_REGISTRY.md`. The +canonical Trinity identity holds: + +``` +phi^2 + 1/phi^2 = 3 +``` + +GF16 vs bfloat16 is a recurring question. We standardise that comparison +in `docs/GF16_BFLOAT16_NMSE_PROTOCOL.md` (this package). The protocol is +**distribution-explicit** -- there is no single GF16-vs-BF16 number that +isn't tied to a sampling distribution and a seed. + +The GoldenFloat family also includes GF4, GF8, GF12, GF20, GF24, GF32 +(see `specs/numeric/`). FP8 and the NF4 / INT4 / INT8 bridges are +**planned** but not yet specified. + +--- + +## 6. The four products in detail + +### 6.1 `t27` -- the toolchain + +What `t27` actually ships today (mirrored from `STATUS.md`): + +- Bootstrap Rust compiler (`bootstrap/`) -- SPEC+, sealed. +- `t27c parse` -- 170+ specs parse -- GREEN. +- `t27c gen-verilog` -- 5/5 FPGA modules synthesise -- SIM. +- `t27c gen-zig`, `t27c gen-c` -- RTL-equivalent software backends. +- `t27c seal` -- GREEN, 729 sealed artefacts at audit time. +- `./scripts/tri` -- canonical CLI wrapper -- GREEN. + +### 6.2 `tt-trinity-phi` -- 1x1 phi anchor + +Smallest chip. Witnesses the phi identity in silicon and serves as a +proof-of-life CI gate for the line. Status, pinout, GDS, and Tiny Tapeout +submission live in the chip repo -- not here. + +### 6.3 `tt-trinity-euler` -- 8x2 e-engine + +Mid-tile. Safety / control. Bounded reasoning. Pairs with `clara-bridge/` +in `t27`. 22FDX is a plausible-future PDK target; see +`docs/22FDX_TOPS_W_PROJECTION.md` for the projection methodology. + +### 6.4 `tt-trinity-gamma` -- 8x4 32-PE ternary mesh + +Largest tile. Inference compute volume of the line. Pairs with the +LUT-NPU operator (`OP_LUT_NPU = 0xE3`), the StochSkipSafe theta gate +(`L2_DG_THETA_SKIP_GATE`), and the AVS-48 / AVS-96 voltage stacking +microcode (see `trios-coq/Physics/`). Triple-Deck RBB / FBB / CapBoost is +specified at the Coq level (W47 / W48 / W49). The chip-side Triple-Deck +implementation lives in this repo's chip-sibling tree. + +--- + +## 7. Who is this for + +- **Scientific compute and formal-verification teams** that need a + multiplier-free, inspectable inference path with Coq-backed identities. +- **Regulated-deployment auditors** that need spec-to-RTL traceability + (every Verilog comes from a sealed `.t27`). +- **Open-shuttle researchers** that need a Tiny Tapeout-shaped silicon + target. +- **Educators** that need a small, complete, ternary-AI stack to teach + from. + +It is **not for** users whose primary constraint is TOPS/W or SDK +ergonomics -- see `COMPETITORS.md` for the honest framing. + +--- + +## 8. Roadmap and how it is governed + +Roadmap items live in `docs/ROADMAP.md` and the running PHI-LOOP ledger +in `NOW.md`. Every roadmap item: + +- has a tracking issue (L1 TRACEABILITY); +- is referenced by `Closes #N` in its PR; +- ships as `.t27` spec + generated `gen/` + conformance + Coq lemma + (where applicable); +- enters STATUS.md at the appropriate readiness level only when in-repo + evidence exists. + +22FDX TOPS/W projection: `docs/22FDX_TOPS_W_PROJECTION.md` (this package). +Zenodo bundles plan: `docs/ZENODO_BUNDLES.md` (this package). + +--- + +## 9. Cross-links + +- `LINEUP.md` -- product map +- `STATUS.md` -- readiness ladder +- `BENCHMARKS.md` -- restrained benchmark posture +- `COMPETITORS.md` -- honest positioning +- `FORMAT_REGISTRY.md` -- numeric SSOT mirror +- `CLARA_TRACEABILITY.md` -- assurance bridge to DARPA CLARA +- `docs/T27-CONSTITUTION.md` -- constitutional stack (L1..L7) +- `docs/TRI_NET_API.md` -- API contract for external integrators +- `docs/GF16_BFLOAT16_NMSE_PROTOCOL.md` -- numeric comparison protocol +- `docs/22FDX_TOPS_W_PROJECTION.md` -- silicon energy projection +- `docs/ZENODO_BUNDLES.md` -- DOI bundle plan +- `docs/SCIENTIFIC_IMPROVEMENT_PLAN.md` -- 2026 t27-side roadmap (CL / EN / SN / PUB / OS) + +--- + +## 10. R5-HONEST closing + +This whitepaper is a positioning document, not a marketing document. It +sets out **what TRI-NET is trying to be** and **what TRI-NET is not**. +Every reader should be able to verify the readiness levels claimed by +reading the repo files cited. If any cell of `STATUS.md` and any +sentence of this whitepaper disagree, **`STATUS.md` wins**; open an +issue. + +--- + +**phi^2 + 1/phi^2 = 3 | TRINITY** diff --git a/docs/ZENODO_BUNDLES.md b/docs/ZENODO_BUNDLES.md new file mode 100644 index 000000000..b35b61de6 --- /dev/null +++ b/docs/ZENODO_BUNDLES.md @@ -0,0 +1,209 @@ +# Zenodo Bundles Plan -- TRI-NET v1, v2, v3 + +> **Status:** PLAN. This document is a checklist / manifest for three +> future Zenodo bundles. **No DOI is asserted for v1, v2, or v3 in this +> document.** Zenodo issues DOIs at upload time; quoting one before that +> is not honest. The community page already lists a v0 baseline +> (B001..B007, plus the v5.0 parent record). See `docs/ZENODO.md` for the +> canonical list of *existing* DOIs. + +--- + +## 1. Why three bundles + +The TRI-NET line crosses four artefacts (toolchain + three chip repos) +and several conceptual layers (numeric kernel, generator backends, +formal proofs, conformance, assurance bridge). A single mega-bundle is +unreadable. A per-chip bundle leaks toolchain assumptions into each. +Three line-level bundles -- split by *role*, not by chip -- is the +working plan: + +| Bundle | Working title | Audience | +|--------|----------------------------------------------------------|---------------------------| +| v1 | TRI-NET v1 -- Spec-first toolchain and numeric registry | tool builders, auditors | +| v2 | TRI-NET v2 -- Open ternary silicon substrate | silicon researchers | +| v3 | TRI-NET v3 -- High-assurance proofs and conformance | formal-methods reviewers | + +These three bundles correspond to the three persuasion lanes for the +line: "the toolchain is real", "the silicon is real (Tiny Tapeout shape)", +"the assurance story is real (Coq + conformance)". + +--- + +## 2. v1 manifest -- Spec-first toolchain and numeric registry + +**Inclusion checklist:** + +- [ ] `README.md`, `STATUS.md`, `LINEUP.md`, `FORMAT_REGISTRY.md`, + `COMPETITORS.md`, `BENCHMARKS.md`, `CLARA_TRACEABILITY.md` +- [ ] `docs/T27-CONSTITUTION.md`, `AGENTS.md`, `CLAUDE.md`, `SOUL.md` +- [ ] `docs/TRI_NET_API.md`, `docs/TRI_NET_WHITEPAPER.md`, + `docs/GF16_BFLOAT16_NMSE_PROTOCOL.md`, + `docs/22FDX_TOPS_W_PROJECTION.md` (this package) +- [ ] `specs/` (full tree) +- [ ] `bootstrap/` (Stage-0 Rust source; `FROZEN_HASH` seal verbatim) +- [ ] `schemas/` -- `numeric-format-v1.json`, `tri-net-api-v1.json`, + `nmse-protocol-v1.json` (this package) +- [ ] `conformance/FORMAT-SPEC-001.json` (numeric SSOT) +- [ ] `CITATION.cff`, `codemeta.json`, `.zenodo.json` + +**Exclusion list (do not include in v1):** + +- `gen/` -- generated, reproducible from specs + sealed compiler. +- `coq/`, `trios-coq/`, `proofs/` -- belong in v3. +- Chip-repo content -- belongs in v2 via cross-link. + +**Pre-upload gates:** + +1. `scripts/check_first_party_doc_language.py` passes. +2. `FORMAT-SPEC-001.json` JSON sanity passes. +3. `bootstrap` builds with `cargo build --release`. +4. `./scripts/tri test` clean (or its CI surrogate). +5. `STATUS.md` ladder unchanged or only raised by direct evidence. +6. No `.env` or secret-shaped file under tree (`SECURITY.md` policy). + +**Upload metadata template:** + +```yaml +title: "TRI-NET v1 -- Spec-first Toolchain and Numeric Registry" +upload_type: software +license: Apache-2.0 +communities: + - identifier: trinity-s3ai +related_identifiers: + - relation: isVersionOf + identifier: "10.5281/zenodo.19227879" # v5.0 parent record + - relation: isPartOf + identifier: "https://github.com/gHashTag/t27" +keywords: + - TRI-NET, t27, GoldenFloat, GF16, ternary, spec-first +language: eng +``` + +--- + +## 3. v2 manifest -- Open ternary silicon substrate + +**Inclusion checklist:** + +- [ ] `LINEUP.md` (the four-product map) -- copy for offline reading +- [ ] `docs/TRI_NET_WHITEPAPER.md` +- [ ] `docs/22FDX_TOPS_W_PROJECTION.md` +- [ ] `gen/verilog/` index file (list, not contents -- chip repos are + authoritative for HDL) +- [ ] `fpga/vivado/` build scripts and testbenches (treated as + toolchain-side evidence, not silicon) +- [ ] `STATUS.md` (the readiness ladder) +- [ ] Cross-references to: + - `tt-trinity-phi` GDS / pinout / Tiny Tapeout submission record + - `tt-trinity-euler` GDS / pinout / Tiny Tapeout submission record + - `tt-trinity-gamma` GDS / pinout / Tiny Tapeout submission record +- [ ] D2D protocol spec **pointer** (the protocol lives in + `tt-trinity-euler` / `tt-trinity-gamma`; v2 bundles only the + pointer plus the toolchain-side hooks) +- [ ] Triple-Deck (W47 RBB + W48 FBB-active + W49 CapBoost) **Coq + lemma list** -- full sources go to v3 + +**Exclusion list (do not include in v2):** + +- Raw Verilog (chip-repo authoritative). +- GDS files (chip-repo authoritative). +- Anything that would imply a silicon claim t27 can't back from this + repo's evidence. + +**Pre-upload gates:** + +1. Each chip-repo cross-link resolves at upload time (live URL). +2. `STATUS.md` and `docs/22FDX_TOPS_W_PROJECTION.md` cross-check: no + silicon claim exists in the projection doc that is missing from the + ladder. + +--- + +## 4. v3 manifest -- High-assurance proofs and conformance + +**Inclusion checklist:** + +- [ ] `coq/` (full tree) +- [ ] `trios-coq/` (full tree, incl. Physics/StochRound.v, + AvsStacking.v, SubThreshold.v, StochSkipSafe.v, Int2QuantSafe.v, + Avs96Safe.v, RBB / FBBActive2 / CapBoost) +- [ ] `proofs/` (work-in-progress lemma drawer; clearly labelled) +- [ ] `conformance/` (all vectors; not just numeric) +- [ ] `clara-bridge/` (assurance workflow) +- [ ] `docs/T27_KERNEL_FORMAL_COQ.md` +- [ ] `docs/PHYSICS_REVIEW_PROTOCOL.md` +- [ ] `docs/NUMERICS_VALIDATION.md` +- [ ] `docs/COMPILER_VERIFICATION_*` (the three landscape docs) +- [ ] `CITATION.cff` with `doi:` field populated (PASS-24 gate; currently + open as issue #653 -- must be closed before v3 upload) + +**Pre-upload gates:** + +1. `coqc` clean across `coq/` and `trios-coq/` -- `Admitted` count zero + for everything cited in the manifest. +2. `citation_map.json` consistent with bundled `.v` files. +3. `CITATION.cff` has `doi:` field (gate #653). + +--- + +## 5. Common rules across v1, v2, v3 + +- License: Apache-2.0 (root `LICENSE` and `NOTICE`). +- Language: English / ASCII first-party (L3 PURITY). +- Author block: per `CITATION.cff` at upload time. +- Community: `trinity-s3ai`. +- Anchor identity stated in description: `phi^2 + 1/phi^2 = 3`. + +**DOI policy (this is the heart of the document):** + +> No DOI is issued, reserved, or quoted before the bundle is uploaded. +> Zenodo issues a DOI at first publish; a concept DOI (always-latest) +> appears once a second version is published. Until v1 is actually +> uploaded, the v1 row contains the string `pending`; quoting any other +> placeholder is forbidden. + +The existing canonical Trinity / B-series DOIs (B001..B007 + v5.0 parent, +plus `10.5281/zenodo.19227877` cited in `NOW.md`) are **predecessor +records**, not the v1/v2/v3 line -- see `docs/ZENODO.md`. + +--- + +## 6. Upload order + +1. v1 first (toolchain) -- needed to anchor v2 and v3. +2. v3 second (proofs + conformance) -- read-only relative to specs; + doesn't depend on v2. +3. v2 last -- depends on chip repos' GDS / submission records being + public, which is the riskiest external dependency. + +Each upload is its own issue with `Closes #N` discipline. + +--- + +## 7. Cross-links + +- Existing DOIs: `docs/ZENODO.md` +- Whitepaper: `docs/TRI_NET_WHITEPAPER.md` +- TRI-NET API contract: `docs/TRI_NET_API.md` +- Format registry: `FORMAT_REGISTRY.md` +- Readiness: `STATUS.md` +- Chip repos: `LINEUP.md` (the four-product map) +- `CITATION.cff` DOI gate: issue #653 +- Roadmap: `docs/SCIENTIFIC_IMPROVEMENT_PLAN.md` -- OS-02 names the + Coq export consumed by v3; PUB-02 names the sealed NMSE manifest + whose existence is a v1 / v3 pre-upload signal. + +--- + +## 8. R5-HONEST closing + +This is a plan. None of v1, v2, v3 has a DOI. The plan is auditable +because each manifest is enumerable from this repo today; what it produces +is conditional on each pre-upload gate passing. If a future PR adds a v1 +DOI without an upload behind it, that PR violates this document and +should be rejected. + +--- + +**phi^2 + 1/phi^2 = 3 | TRINITY** diff --git a/schemas/nmse-protocol-v1.json b/schemas/nmse-protocol-v1.json new file mode 100644 index 000000000..42a4d2a3e --- /dev/null +++ b/schemas/nmse-protocol-v1.json @@ -0,0 +1,143 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://github.com/gHashTag/t27/schemas/nmse-protocol-v1.json", + "title": "GF16 vs bfloat16 NMSE protocol results manifest (TRI-NET)", + "description": "Schema for one run of the GF16 vs bfloat16 NMSE comparison protocol. See docs/GF16_BFLOAT16_NMSE_PROTOCOL.md and specs/benchmarks/gf16_bfloat16_nmse.t27. Conservative; describes a results manifest only.", + "type": "object", + "required": [ + "schema_version", + "protocol_version", + "seal_hash", + "rng", + "samples_per_distribution", + "results", + "bf16_subnormal_policy", + "runner", + "timestamp" + ], + "additionalProperties": false, + "properties": { + "schema_version": { + "type": "string", + "pattern": "^1\\.[0-9]+$", + "description": "MAJOR.MINOR. MAJOR must be 1 for this schema file." + }, + "protocol_version": { + "type": "string", + "pattern": "^[0-9]+\\.[0-9]+$", + "description": "Version of the NMSE protocol implementation." + }, + "seal_hash": { + "oneOf": [ + { + "type": "string", + "pattern": "^[0-9a-f]{64}$", + "description": "SHA-256 hex digest matching bootstrap/stage0/FROZEN_HASH." + }, + { + "type": "string", + "const": "unsealed", + "description": "Run was not produced under a sealed toolchain; manifest is informational only." + } + ] + }, + "rng": { + "type": "object", + "required": ["family", "seed"], + "additionalProperties": false, + "properties": { + "family": { + "type": "string", + "enum": ["xoshiro256pp", "pcg64", "splitmix64", "philox4x64"] + }, + "seed": { + "type": "string", + "pattern": "^0x[0-9a-fA-F]{1,16}$" + } + } + }, + "samples_per_distribution": { + "type": "integer", + "minimum": 1000, + "description": "Number of samples drawn per reference distribution. Default 10_000_000." + }, + "bf16_subnormal_policy": { + "type": "string", + "enum": ["ieee", "ftz"], + "description": "IEEE subnormal handling vs flush-to-zero. Required by spec; missing is non-conforming." + }, + "results": { + "type": "object", + "minProperties": 1, + "additionalProperties": false, + "patternProperties": { + "^D_(NORM|LOG|RELU|PHI|DEEP)$": { + "type": "object", + "required": ["nmse_gf16", "nmse_bf16"], + "additionalProperties": false, + "properties": { + "nmse_gf16": { + "oneOf": [ + { "type": "number", "minimum": 0 }, + { "type": "null", "description": "Undefined; baseline mean-square was zero." } + ] + }, + "nmse_bf16": { + "oneOf": [ + { "type": "number", "minimum": 0 }, + { "type": "null" } + ] + }, + "ratio": { + "oneOf": [ + { "type": "number", "exclusiveMinimum": 0 }, + { "type": "null", "description": "Undefined; either numerator or denominator is null." } + ], + "description": "nmse_gf16 / nmse_bf16; meaningful only over the same seed and distribution." + } + } + } + } + }, + "identity_witness": { + "type": "object", + "description": "Optional but recommended. Records the L5 IDENTITY checks performed before measurement.", + "additionalProperties": false, + "properties": { + "phi_squared_residual_f64": { + "type": "number", + "description": "|phi^2 - (phi + 1)| in f64. Must be < 1e-15." + }, + "trinity_residual_f64": { + "type": "number", + "description": "|phi^2 + 1/phi^2 - 3| in f64. Must be < 1e-15." + } + } + }, + "runner": { + "type": "object", + "required": ["host_arch", "compiler"], + "additionalProperties": false, + "properties": { + "host_arch": { + "type": "string", + "examples": ["x86_64-linux", "aarch64-linux", "aarch64-darwin"] + }, + "compiler": { + "type": "string", + "examples": ["rustc 1.79.0", "zig 0.13.0"] + } + } + }, + "timestamp": { + "type": "string", + "format": "date-time", + "description": "RFC 3339 / ISO 8601 timestamp at run start." + }, + "x_extension": { + "type": "object", + "description": "Reserved namespace for producer-specific extensions. Consumers may ignore.", + "additionalProperties": true + } + } +} diff --git a/schemas/tri-net-api-v1.json b/schemas/tri-net-api-v1.json new file mode 100644 index 000000000..b06a1b9d5 --- /dev/null +++ b/schemas/tri-net-api-v1.json @@ -0,0 +1,142 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://github.com/gHashTag/t27/schemas/tri-net-api-v1.json", + "title": "TRI-NET external integration API surface (schema family)", + "description": "Conservative shape schema for TRI-NET API artefacts produced by t27 and its sibling chip repos. File-based, read-only. See docs/TRI_NET_API.md and specs/api/tri_net_api.t27.", + "type": "object", + "required": ["schema_version", "kind"], + "properties": { + "schema_version": { + "type": "string", + "pattern": "^1\\.[0-9]+$" + }, + "kind": { + "type": "string", + "enum": ["RepoIdentity", "Readiness", "ArtefactIndex"] + }, + "x_extension": { + "type": "object", + "additionalProperties": true + } + }, + "oneOf": [ + { "$ref": "#/$defs/RepoIdentity" }, + { "$ref": "#/$defs/Readiness" }, + { "$ref": "#/$defs/ArtefactIndex" } + ], + "$defs": { + "RepoIdentity": { + "type": "object", + "required": ["schema_version", "kind", "tri_net_product", "repo_url"], + "additionalProperties": false, + "properties": { + "schema_version": { "type": "string", "pattern": "^1\\.[0-9]+$" }, + "kind": { "const": "RepoIdentity" }, + "tri_net_product": { + "type": "string", + "enum": ["t27", "tt-trinity-phi", "tt-trinity-euler", "tt-trinity-gamma"] + }, + "role": { + "type": "string", + "enum": ["toolchain", "phi_anchor", "safety_engine", "ternary_mesh"] + }, + "repo_url": { + "type": "string", + "format": "uri" + }, + "tile_size": { + "type": "string", + "enum": ["N/A", "1x1", "2x2", "4x4", "8x2", "8x4"] + }, + "seal_hash": { + "type": "string", + "pattern": "^[0-9a-f]{64}$" + }, + "format_registry_pointer": { + "type": "string", + "description": "Relative path to the canonical numeric registry, or URL to t27 if consuming.", + "examples": ["conformance/FORMAT-SPEC-001.json", "https://github.com/gHashTag/t27/blob/master/conformance/FORMAT-SPEC-001.json"] + }, + "x_extension": { "type": "object", "additionalProperties": true } + } + }, + "Readiness": { + "type": "object", + "required": ["schema_version", "kind", "components"], + "additionalProperties": false, + "properties": { + "schema_version": { "type": "string", "pattern": "^1\\.[0-9]+$" }, + "kind": { "const": "Readiness" }, + "as_of": { + "type": "string", + "format": "date" + }, + "components": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "required": ["name", "level"], + "additionalProperties": false, + "properties": { + "name": { "type": "string" }, + "level": { + "type": "string", + "enum": ["SPEC", "RTL", "SIM", "SYNTH", "GDS_TAPEOUT", "SILICON"] + }, + "evidence": { + "type": "string", + "description": "Repo-relative path or URL to the evidence cited by STATUS.md." + } + } + } + }, + "x_extension": { "type": "object", "additionalProperties": true } + } + }, + "ArtefactIndex": { + "type": "object", + "required": ["schema_version", "kind", "artefacts"], + "additionalProperties": false, + "properties": { + "schema_version": { "type": "string", "pattern": "^1\\.[0-9]+$" }, + "kind": { "const": "ArtefactIndex" }, + "generated_at": { + "type": "string", + "format": "date-time" + }, + "artefacts": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "required": ["family", "path", "schema_ref"], + "additionalProperties": false, + "properties": { + "family": { + "type": "string", + "enum": [ + "format_registry", + "nmse_results", + "seal_hash", + "readiness", + "conformance_vectors", + "repo_identity" + ] + }, + "path": { + "type": "string", + "description": "Repo-relative path." + }, + "schema_ref": { + "type": "string", + "description": "Path or URI of the schema this artefact validates against." + } + } + } + }, + "x_extension": { "type": "object", "additionalProperties": true } + } + } + } +} diff --git a/specs/api/tri_net_api.t27 b/specs/api/tri_net_api.t27 new file mode 100644 index 000000000..38212dec2 --- /dev/null +++ b/specs/api/tri_net_api.t27 @@ -0,0 +1,189 @@ +// SPDX-License-Identifier: Apache-2.0 +# TRI-NET API CONTRACT 0 External Integration Surface + +## Specification + +File-based, read-only API surface that downstream tools (chip-repo CI, +third-party auditors, formal-methods reviewers) consume to interact with +TRI-NET artefacts produced by t27 and its sibling chip repos. There is +no hosted network endpoint in scope. + +Human-readable companion: docs/TRI_NET_API.md +Schema: schemas/tri-net-api-v1.json +Numeric SSOT: conformance/FORMAT-SPEC-001.json + schemas/numeric-format-v1.json + +## Mathematical Foundation + +``` +phi^2 + 1/phi^2 = 3 = TRINITY +``` + +The API has no math content of its own; it merely shapes how TRI-NET +artefacts that *do* carry math content are produced and consumed. + +## Versioning + +``` +schema_version: semver + MAJOR change -> breaking; consumer must opt in + MINOR change -> additive; consumer should ignore unknown fields + PATCH change -> editorial; no semantic change +current: 1.0 +``` + +## Artefact Families + +### Format registry +``` +path: conformance/FORMAT-SPEC-001.json +schema: schemas/numeric-format-v1.json +host: t27 only (chip repos consume; do not republish) +law: L6 CEILING +``` + +### NMSE protocol results +``` +path: bench/results/nmse---.json +schema: schemas/nmse-protocol-v1.json +companion_doc: docs/GF16_BFLOAT16_NMSE_PROTOCOL.md +``` + +### Toolchain seal +``` +path: bootstrap/stage0/FROZEN_HASH +format: single SHA-256 hex digest, trailing newline allowed +law: L2 GENERATION +``` + +### Readiness ladder (programmatic mirror, optional) +``` +path: bench/readiness.json // optional +schema: schemas/tri-net-api-v1.json#/$defs/Readiness +levels: [ SPEC, RTL, SIM, SYNTH, GDS_TAPEOUT, SILICON ] +authority: STATUS.md is human-readable SSOT; programmatic mirror is opt-in +``` + +### Conformance vectors +``` +path_glob: conformance/*.json +families: gf*_vectors, ar_*, nn_*, sacred_physics*, FORMAT-SPEC-001 +``` + +### Cross-repo identity (optional) +``` +path: tri-net-identity.json // top level of any TRI-NET-conforming repo +schema: schemas/tri-net-api-v1.json#/$defs/RepoIdentity +purpose: + lets a consumer enumerate the four products of the line without + scraping documentation +``` + +## Consumer Contract + +``` +must pin a schema MAJOR +must validate every artefact before treating fields as authoritative +must fail closed on schema violation +should verify seal_hash matches bootstrap/stage0/FROZEN_HASH +should log schema_version in any output +``` + +## Producer Contract + +``` +must emit only artefacts that validate against the active schema +must include schema_version at artefact root +must place extensions under reserved x_extension object +must cite seal_hash when numeric results are reported +should publish tri-net-identity.json at repo root +``` + +## Tests + +``` +test "API: format registry validates" { + // conformance/FORMAT-SPEC-001.json validates against + // schemas/numeric-format-v1.json +} + +test "API: schema version present" { + // Every conforming artefact carries a schema_version field at the + // top level; reject otherwise. +} + +test "API: seal hash matches frozen seal" { + // A produced artefact whose seal_hash != contents of + // bootstrap/stage0/FROZEN_HASH is non-conforming. +} + +test "API: fail-closed on undocumented top-level field" { + // Producers cannot add new top-level keys; extensions go under + // x_extension or fail validation. +} +``` + +## Invariants + +``` +invariant "no hosted endpoint claim" { + // No artefact in this API surface claims a hosted runtime exists. +} + +invariant "single source for format registry" { + // FORMAT-SPEC-001.json is hosted in t27 only; chip-repo copies are + // verbatim mirrors with no schema drift. +} + +invariant "extension namespace" { + // Unknown keys must reside under x_extension; otherwise validation + // fails. +} + +invariant "L6 CEILING preserved" { + // The numeric registry is read-only at the API; changing it + // requires a constitutional amendment, not an API change. +} +``` + +## Benchmark + +``` +bench "TRI-NET API schema round-trip" { + procedure: + - for each artefact family above + - produce a minimal valid artefact (golden file under + bench/api_goldens/) and validate against its schema + - mutate one required field; confirm validation fails + output: bench/results/api-roundtrip-.json + success_criterion: 100% of golden files validate, 100% of mutated + golden files fail validation +} +``` + +## What This API Is Not + +``` +- not a hosted HTTP service +- not an SDK +- not a control plane for any chip +- not a place where silicon-bring-up endpoints live +``` + +## Cross-links + +- docs/TRI_NET_API.md (human-readable mirror) +- docs/TRI_NET_WHITEPAPER.md (line positioning) +- schemas/tri-net-api-v1.json (this API's schema) +- schemas/numeric-format-v1.json (numeric SSOT schema) +- schemas/nmse-protocol-v1.json (NMSE manifest schema) +- LINEUP.md (the four-product map) +- STATUS.md (readiness ladder) +- specs/api/c_api_contract.t27 (separate FFI bridge contract) +- specs/api/sdk_contract.t27 (separate SDK contract) + +## R5-HONEST Notes + +- API is file-based today; no network endpoint is implied. +- Schemas describe SHAPE only; they do not promise silicon behaviour. +- No throughput / latency / energy field is part of the canonical + surface today. diff --git a/specs/benchmarks/gf16_bfloat16_nmse.t27 b/specs/benchmarks/gf16_bfloat16_nmse.t27 new file mode 100644 index 000000000..22db88738 --- /dev/null +++ b/specs/benchmarks/gf16_bfloat16_nmse.t27 @@ -0,0 +1,152 @@ +// SPDX-License-Identifier: Apache-2.0 +# GF16 vs bfloat16 NMSE PROTOCOL BENCHMARK 0 TRI-NET + +## Specification + +Standard comparison protocol for GoldenFloat GF16 vs bfloat16 numeric +fidelity, expressed as Normalised Mean Squared Error (NMSE) over named +reference distributions. Protocol-level only; no silicon numbers asserted. + +Human-readable companion: docs/GF16_BFLOAT16_NMSE_PROTOCOL.md +Schema for results manifest: schemas/nmse-protocol-v1.json +Numeric SSOT: conformance/FORMAT-SPEC-001.json + +## Mathematical Foundation + +``` +phi^2 + 1/phi^2 = 3 = TRINITY +NMSE(F) = E[ (x - Q_F(x))^2 ] / E[ x^2 ] +``` + +## Formats Under Test + +### GF16 (GoldenFloat 16-bit, primary path) + +``` +bit_layout: [ S(1) | E(6) | M(9) ] +bias: 31 +value: (-1)^S * 2^(E - 31) * (1 + M / 2^9) +rounding: round_to_nearest_ties_to_even +source: specs/numeric/gf16.t27 +``` + +### bfloat16 (IEEE 754 binary32 truncated) + +``` +bit_layout: [ S(1) | E(8) | M(7) ] +bias: 127 +value: (-1)^S * 2^(E - 127) * (1 + M / 2^7) +rounding: round_to_nearest_ties_to_even +subnormal_policy: { ieee | ftz } // must be declared in manifest +``` + +## Reference Distributions + +``` +D_NORM : x ~ N(0, 1) +D_LOG : log2|x| ~ U(-10, 10) ; sign uniform +D_RELU : x = max(0, N(0, 1)) +D_PHI : x ~ N(phi, 1/phi) ; phi = (1 + sqrt 5) / 2 +D_DEEP : 0.7 D_NORM + 0.3 D_LOG +``` + +Each distribution: 10_000_000 samples per run unless overridden. + +## Identity Witness (L5 IDENTITY) + +``` +witness phi_squared_identity { + require |phi^2 - (phi + 1)| < 1e-15 +} +witness trinity_identity { + require |phi^2 + 1/phi^2 - 3| < 1e-15 +} +``` + +A run aborts before reporting NMSE if either witness fails. + +## Tests + +``` +test "NMSE-Protocol: identity witness gates run" { + // Both witnesses must hold in IEEE f64 before any measurement. +} + +test "NMSE-Protocol: non-negative" { + // For each format and distribution, NMSE >= 0. +} + +test "NMSE-Protocol: deterministic for fixed seed" { + // Two runs with the same seed and same RNG family produce + // bit-identical per-distribution NMSE values. +} +``` + +## Invariants + +``` +invariant "NMSE non-negative" { + forall F, D : NMSE(F, D) >= 0 +} + +invariant "ratio undefined on zero baseline" { + // If E[x^2] == 0 over the sample, NMSE is undefined and the run + // reports null for that distribution. No division-by-zero is + // silently produced. + forall D : if mean_sq_ref(D) == 0 then NMSE(*, D) == null +} + +invariant "subnormal policy is declared" { + // Manifest must state ieee or ftz for BF16; missing => non-conforming. +} + +invariant "seal hash recorded" { + // Every conforming manifest cites the toolchain seal hash matching + // bootstrap/stage0/FROZEN_HASH. +} +``` + +## Benchmark + +``` +bench "GF16 vs BF16 NMSE over D_NORM, D_LOG, D_RELU, D_PHI, D_DEEP" { + seed: declared_in_manifest + samples_per_distribution: 10_000_000 + output: schemas/nmse-protocol-v1.json + reports: + - nmse_gf16[D] + - nmse_bf16[D] + - ratio[D] = nmse_gf16[D] / nmse_bf16[D] + fail_modes: + - identity_witness_fail -> abort, no manifest emitted + - subnormal_policy_missing -> abort, no manifest emitted + - seal_hash_missing -> emit manifest tagged "informational" +} +``` + +## Reporting Rules + +``` +- protocol_version: semver, MAJOR matches schema MAJOR +- ratio: dimensionless; meaningful only when both NMSE values are + non-null over the same seed and the same distribution +- direction: ratio < 1.0 favours GF16 on that distribution; + ratio > 1.0 favours BF16; ratio == 1.0 ties +- never report a ratio without naming the distribution and seed +- never compare against a commercial-NPU number under this protocol +``` + +## Cross-links + +- docs/GF16_BFLOAT16_NMSE_PROTOCOL.md (human-readable mirror) +- docs/TRI_NET_API.md (artefact consumer contract) +- schemas/nmse-protocol-v1.json (manifest schema) +- specs/numeric/gf16.t27 (GF16 SSOT) +- conformance/FORMAT-SPEC-001.json (numeric registry SSOT) +- LINEUP.md (chip-repo cross-links for runners) + +## Non-Claims (R5-HONEST) + +- This spec does not assert a measured NMSE on silicon. +- This spec does not assert GF16 wins or loses over BF16 in general. +- This spec assumes nothing about ratio sign without a distribution and seed.