Skip to content

README.md

Latest commit

 

History

History
272 lines (207 loc) · 9.49 KB

README.md

File metadata and controls

272 lines (207 loc) · 9.49 KB
Raw

t27 — The Spec-First Contract Language for Bit-Exact Silicon

One .t27 specification. Sealed software, tests, Zig, C, and Verilog.
No hand-editing generated code. Ever.

t27 is the source-of-truth toolchain for Trinity S³AI’s open, high-assurance ternary AI silicon. Its primary path is:

.t27 specification
  → conformance vectors
  → SHA-256 seals
  → Zig / C / Verilog artifacts
  → tests and differential verification
  → FPGA synthesis and board receipts
  → Tiny Tapeout reproducibility manifests

φ² + 1/φ² = 3 | TRINITY

The Golden Series

t27 is Article 3 of THE GOLDEN SERIES:

Layer Article What it establishes
Numbers GoldenFloat One phi-derived rule for the GF4–GF1024 floating-point family
Verification Golden Ruler Bit-exact conformance vectors across numeric formats
Execution GOLDEN CHAIN One .t27 contract from source to silicon evidence

The chain is directional:

GoldenFloat → Golden Ruler → GOLDEN CHAIN
   numbers  →   verification  →   silicon evidence

Why t27 Exists

Machine-learning formats diverge across CPU, GPU, FPGA, and ASIC. Golden Ruler addresses numeric divergence with 109 formats, six bit-exact conformance packs, and explicit disclosure of unresolved differences.

t27 extends that principle from numbers to systems:

  • Spec-first: .t27 is the only source of truth.
  • Generated artifacts: Zig, C, and Verilog are outputs, never sources.
  • Sealed evidence: specifications and artifacts carry SHA-256 seals.
  • Bit-exact verification: conformance vectors are language-agnostic.
  • Hardware path: .t27 can become synthesizable Verilog and FPGA evidence.

Core Principle

No hand-editing generated code. Ever.

If a generated artifact is wrong, fix the .t27 specification, the compiler, or the conformance suite—not the generated file.

Quick Start

Requires Rust/Cargo on macOS or Linux.

git clone --recursive https://github.com/Trinity-S-AI-DNA/t27.git
cd t27

make install                        # build tri, t27c and t27b, install them under /usr/local
make -n install                     # print the plan, change nothing
make install PREFIX=$HOME/.local    # install under a directory you own, no sudo
make install CLAW=on                # also install TRI CLAW, the merge and gate agent
make uninstall                      # remove exactly the files the install listed
make help
tri --version                       # with PREFIX/bin on your PATH

A second make install changes nothing. CLAW=on installs TRI CLAW's service spec (specs/claw/service.t27) with its seals and verifies them with t27c seal --verify. No lab node ships in this repository yet, so make install EARN=on stops before it changes anything.

Verify the repository:

./scripts/tri test
./scripts/tri validate-conformance
./scripts/tri validate-gen-headers

Use the toolchain:

# Parse a specification
./scripts/tri parse specs/base/types.t27

# Generate Zig
./scripts/tri gen specs/numeric/gf16.t27

# Generate Verilog
./scripts/tri gen-verilog specs/fpga/mac.t27

# Generate C
./scripts/tri gen-c specs/base/ops.t27

# Verify a seal
./scripts/tri seal specs/numeric/gf16.t27 --verify

Full installation options, including PREFIX, CLAW=on, and EARN=on, are in QUICK_START.md.

The GOLDEN CHAIN

.t27 specification
  ├── t27c parse          → canonical frontend
  ├── conformance/*.json  → bit-exact expected behavior
  ├── t27c seal           → SHA-256 integrity evidence
  ├── t27c gen            → Zig artifacts
  ├── t27c gen-c          → C artifacts
  ├── t27c gen-verilog    → synthesizable RTL
  ├── t27c test           → reference verification
  └── FPGA flow           → synthesis, board profile, receipts

The repository currently records:

  • 170+ parsing specifications.
  • 170+ seals under .trinity/seals/.
  • 34 conformance-vector JSON files.
  • 5/5 FPGA modules passing gen-verilog.
  • CI gates for conformance vectors, generated headers, seal coverage, and issue traceability.

See CANON.md, SOUL.md, and docs/T27-CONSTITUTION.md.

Primary Numeric Path

The default numeric path is GoldenFloat GF16. The GF4–GF32 family is registered in conformance/FORMAT-SPEC-001.json.

Format Bits Primary use
GF4 4 Binary masks
GF8 8 Weights
GF12 12 Attention
GF16 16 Primary path
GF20 20 Training
GF24 24 Precision
GF32 32 Full precision

FP8 compatibility and NF4 / INT4 / INT8 quantization bridges are planned, not shipped. Details: FORMAT_REGISTRY.md.

Honest Status

Domain Status Evidence
.t27 parsing 🟢 GREEN 170+ specs parse
Verilog generation 🟢 GREEN 5/5 FPGA modules synthesize
Sealing 🟢 GREEN 170+ seals exist
Conformance vectors 🟢 GREEN 34 JSON vector sets validate
FPGA synthesis CI 🔴 RED fpga-synthesis failing; last green 2026-04-14
End-to-end bitstream CI 🔴 RED No .bit artifact uploaded since 2026-04-14
Tiny Tapeout reproducibility 🟡 YELLOW 2/4 tracks complete; no die fabricated

A red status is not hidden: it is part of the chain. The TTSKY26a and TTSKY26b Tiny Tapeout submissions were withdrawn and refunded; no die has been fabricated. See LINEUP.md.

What t27 Generates

specs/*.t27              # source of truth
gen/zig/                 # generated Zig — DO NOT EDIT
gen/c/                   # generated C — DO NOT EDIT
gen/verilog/             # generated Verilog — DO NOT EDIT
conformance/*.json       # language-agnostic expected behavior
.trinity/seals/          # SHA-256 integrity evidence

Repository Map

Path Purpose
specs/ .t27 specifications: the only source of truth
compiler/ Compiler specs: parser, codegen, CLI, runtime
gen/ Generated Zig, C, and Verilog artifacts
conformance/ Bit-exact test vectors
bootstrap/ Stage-0 Rust compiler
architecture/ Dependency graph and ADRs
docs/ First-party documentation and live status
chips/ Tiny Tapeout chip submodules
fpga/ FPGA flows, profiles, and board support

Domain ownership begins at OWNERS.md.

Development Law

Every change follows the PHI LOOP:

tri skill begin <task> --issue <N>
tri spec edit <module>   # NOT BUILT: edit the .t27 spec directly
tri seal <file.t27> --save
tri gen
tri test
tri verdict --toxic
tri experience save
tri skill end
git commit

Repository laws:

  1. .t27 specs are the only source of truth.
  2. Generated Zig, C, and Verilog are never edited by hand.
  3. Every mutation is bound to a GitHub issue and PR with Closes #N.
  4. Every specification carries tests, invariants, or benchmarks.
  5. GoldenFloat is defined in specs and conformance JSON, not backend code.
  6. Evolution follows the architecture graph; circular dependencies are forbidden.

Contributing

  1. Open an issue first—no issue, no work.
  2. Create a branch: ring/<N>-<name>, fix/<name>, or task/<name>.
  3. Edit .t27 specifications only.
  4. Run ./scripts/tri test, validate-conformance, and validate-gen-headers.
  5. Open a PR to master with Closes #N.

See CONTRIBUTING.md.

Documentation

Research

License

Apache License 2.0. See LICENSE and NOTICE.

φ² + 1/φ² = 3 | TRINITY

Moved Material (links to dedicated docs)

The following material was moved out of this README into dedicated documents:

Topic Location
Wave 11–17 plans, Track A–D docs/history/WAVES.md
SEED-RINGS table docs/nona-01-foundation/SEED-RINGS.md
27-agent alphabet docs/agents/AGENTS_ALPHABET.md
Automated Reasoning modules docs/AUTOMATED_REASONING.md
BitNet HLS pipeline docs/BITNET_HLS.md
Tiny Tapeout CLI and mĀnifests docs/TINY_TAPEOUT.md
Sacred Constants docs/SACRED_CONSTANTS.md
GoldenFloat installation packages docs/GOLDEN_FLOAT_INSTALL.md