AGENTS.md — strata/kuro

the doctrine of the home is ~/cyber/AGENTS.md; it applies here first. Claude Code receives both files at session start through ~/.config/cyber/agents-md.nu; other agents read them in order.

kuro (黒) — F₂ tower field arithmetic for binary proving.

project structure

kuro/
├── rs/              core library (kuro crate, zero deps, no_std)
│   ├── tower.rs     F₂ through F₂¹²⁸ tower arithmetic
│   ├── packed.rs    Packed128: 128 elements per u128
│   ├── inv.rs       checked inversion utilities
│   ├── batch.rs     Montgomery batch inversion
│   ├── encoding.rs  bytes ↔ tower element conversion
│   ├── vectors.rs   test vectors (77 tests)
│   └── benches/     criterion benchmarks
├── tri/             Trident ZK circuit implementations (.tri)
│   ├── tower.tri    F₂ through F₂¹²⁸ tower (U32 bit-packed)
│   ├── packed.tri   Packed128: 128 elements in 4 × U32
│   ├── inv.tri      checked inversion with zero handling
│   ├── batch.tri    Montgomery batch inversion (fixed-size)
│   └── encoding.tri U32 words ↔ tower element conversion
├── wgsl/            GPU compute shaders (kuro-wgsl crate)
├── cli/             command-line tool (kuro-cli crate)
├── specs/       canonical specifications (9 files)
└── docs/explanation/ educational articles (8 files)

key invariants

• zero production dependencies in the core library
• #![no_std] — embeddable anywhere
• Wiedemann tower construction: α_k = product of all previous generators
  • F₂⁴: α = 0x02, F₂⁸: α = 0x08, F₂¹⁶: α = 0x80, ...
  • pattern: α = 1 << (half_bits - 1) in the sub-field representation
• addition = XOR at every level (characteristic 2)
• multiplication = tower Karatsuba (3 sub-muls per level)
• inversion = tower-recursive via sub-field norm
• squaring = Frobenius endomorphism (linear in char 2)

running

cargo test -p kuro           # 77 tests
cargo bench -p kuro          # criterion benchmarks
cargo run -p kuro-cli -- help # CLI tool

relationship to other repos

writing code

• reference specs in specs/ are the source of truth. code follows spec.
• #[inline] on mul/square/inv (recursive). #[inline(always)] only on add/XOR (1 instruction).
• avoid #[inline(always)] on recursive tower functions — causes extreme compile times.
• all new operations need test vectors in rs/vectors.rs.
• tower levels F₂⁴ through F₂¹²⁸ are generated by a macro. changes to one affect all.