Repo Structure Redesign

Context

The repo mixes source code, generated artifacts, and dead stubs. 54 .tasm files in vm/, std/, os/ are identical garbage. benches/ conflates three concerns. data/ is a vague name for neural model weights. The structure must scale to multiple target architectures and multiple producers of assembly.

Key Design Constraints

Multiple targets. 20 VM targets defined today (triton, arm64, x86-64, riscv, wasm, evm, cairo, miden, ...). Each target has its own assembly language and file extension. Hand-written assembly will exist for many of them, not just Triton.

Multiple producers. For any given module on any given target, assembly can come from three sources:

• hand — expert-written from first principles (optimization floor)
• neural — neural optimizer output
• formal — formally synthesized (future)

Model weights need a real name. data/ says nothing. The 29MB checkpoint is a trained neural model — call it what it is.

Proposed Layout

trident/
  src/             Rust compiler (unchanged)

  vm/              .tri source + target configs (delete dead .tasm)
  std/             .tri source (delete dead .tasm)
  os/              .tri source + target/state configs (delete dead .tasm)

  baselines/       Hand-written assembly, per target
    triton/                          target = file extension boundary
      vm/core/field.tasm
      std/crypto/poseidon2.tasm
      os/neptune/kernel.tasm
      ...
    arm64/                           (future)
      std/crypto/poseidon2.s
    x86-64/                          (future)
      std/crypto/poseidon2.s
    wasm/                            (future)
      std/crypto/poseidon2.wat
    ...

  benches/         Benchmark infrastructure ONLY
    end_to_end.rs                    Criterion bench (Cargo convention)
    README.md
    harnesses/                       Live execution programs
      std/compiler/lexer.tri
      std/compiler/lexer.inputs
      ...
    references/                      Rust ground truth
      std/crypto/poseidon2.rs
      ...

  model/           Trained model weights (was data/)
    general/                       target-agnostic models
      v2/stage1_best.mpk            current production
      v3/                            next experiment
    triton/                        triton-specific (future)
      v1/
    arm64/                         arm64-specific (future)
      v1/

  reference/       Canonical docs (unchanged)
  docs/            User docs (unchanged)
  editor/          Editor integrations (unchanged)
  tests/           Integration tests (unchanged)
  .claude/         Agent memory (unchanged)

Producer Convention

Each producer gets its own suffix before the extension:

baselines/triton/std/crypto/poseidon2.tasm           # hand (no suffix = hand)
baselines/triton/std/crypto/poseidon2.neural.tasm     # neural (gitignored, cached)
baselines/triton/std/crypto/poseidon2.formal.tasm     # formal (future)

Hand baselines are committed. Neural and formal outputs are gitignored (ephemeral, regenerated by tools). The bare filename is always hand-written — the source of truth floor.

Same pattern scales to other targets:

baselines/arm64/std/crypto/poseidon2.s                # hand
baselines/arm64/std/crypto/poseidon2.neural.s         # neural
baselines/wasm/std/crypto/poseidon2.wat               # hand
baselines/wasm/std/crypto/poseidon2.neural.wat        # neural

What Changes

What Stays The Same

• src/ — Rust compiler
• vm/, std/, os/ — namespace hierarchy, .tri files, target configs
• reference/, docs/, editor/, tests/, .claude/
• Cargo.toml single crate structure

Code Changes Required

1. src/cli/bench.rs

• find_baseline_files(): scan baselines/triton/ for *.tasm
• cmd_bench(): baselines_root = project_root.join("baselines/triton")
• Path mapping: rel_str.replace(".tasm", ".tri") (simpler)
• Reference lookup: project_root.join("benches/references").join(...)
• Harness lookup: project_root.join("benches/harnesses").join(...)
• derive_neural_tasm_path(): write to baselines/triton/
• find_project_root(): look for baselines/ dir
• run_rust_reference(): update path derivation
• BenchArgs default dir: "baselines/triton" instead of "benches"

2. src/neural/checkpoint.rs

• CHECKPOINT_DIR: "data/neural/v2" → "model/general/v2"

3. Cargo.toml

• 14 example paths: benches/references/std/crypto/poseidon2.rs

4. .gitignore

*.tasm
!baselines/**/*.tasm
baselines/**/*.neural.tasm
baselines/**/*.formal.tasm

5. CLAUDE.md — update baseline path references

6. benches/README.md — rewrite

Migration: 4 Atomic Commits

Commit 1: chore: delete dead .tasm stubs from vm/, std/, os/

• git rm all dead .tasm files
• Zero tooling impact

Commit 2: refactor: move baselines to baselines/triton/

• Move 42 .baseline.tasm → baselines/triton/*.tasm
• Update src/cli/bench.rs
• Update .gitignore, CLAUDE.md, benches/README.md

Commit 3: refactor: reorganize bench harnesses and references

• Move harnesses and references into subdirs
• Update Cargo.toml example paths
• Update remaining bench.rs logic

Commit 4: refactor: rename data/ to model/

• git mv data/ model/
• Update src/neural/checkpoint.rs
• Update .gitignore

Verification

After each commit:

• cargo check — zero warnings
• cargo test — all pass
• trident bench — same output as before