ReNunney/docs/TRACK2_RUST.md

Track 2 Rust Plan

Updated: 2026-04-12

Purpose

This note defines the initial Rust entry point for Track 2 in renunney.

Track 2 is not a line-by-line translation of Nunney's published threshold heuristic. It is the modern path: explicit threshold definitions, clearer simulation contracts, and a performant kernel.

Why Rust

Rust is the preferred Track 2 kernel language because it directly addresses the main engineering problems revealed by Track 1:

• heavy repeated stochastic simulation,
• threshold sweeps over many independent jobs,
• need for clear data structures and reproducible binaries,
• and a likely future need for Python bindings or service backends.

Initial Scope

The first Rust step is intentionally narrow:

• create a Rust workspace,
• define a Track 2 core crate,
• and encode threshold-centered abstractions rather than immediately porting the entire biological simulator.

This is the correct order because Track 2 should start from a clean statement of what is being estimated.

Current Crate

The active crate is:

• rust/track2-core

It now includes:

• threshold helper types and search scaffolding
• serialization-friendly Track 2 job/result structs
• a simple placeholder kernel for basic trait wiring
• a minimal Nunney-style stochastic kernel for same-parameter smoke checks
• Rust examples for direct kernel use and Python-vs-Rust smoke comparison
• a growing unit-test suite around fecundity, fitness, mutation bounds, inheritance, extinction, and bookkeeping invariants

This is no longer just a threshold-abstraction placeholder. It is now a usable Track 2 kernel development surface with:

• make rust-check
• make rust-test
• make rust-smoke
• make rust-smoke-release
• make compare-track1-rust-smoke

Current Status

What is done now:

1. Core Track 2 data types compile and test cleanly.
2. The Rust kernel can run a one-run smoke simulation directly.
3. A minimal Nunney-style kernel exists for side-by-side comparison work.
4. A multi-seed comparison harness exists in scripts/compare_track1_rust_smoke.py.
5. The Rust library test suite now covers core mechanical invariants instead of relying only on Python comparison.

What is not done yet:

1. The Rust kernel is not a full Track 1 parity implementation.
2. The threshold-search layer is still a scaffold rather than a production estimator.
3. Rust is not yet wired into orchestration as a real worker backend.

Next Rust Steps

1. Reduce systematic divergence from Python in births, survivors, and final N by tightening update-order and RNG-sensitive mechanics.
2. Add more low-level kernel tests for hand-constructed populations: exact tracking_metrics, exact multi-locus fitness values, and tiny deterministic generation updates.
3. Define statistical parity criteria over many seeds rather than using exact-seed agreement as the primary validation standard.
4. Promote the current smoke framework into a real Track 2 execution path with stable CLI contracts and result serialization.
5. Only after that, extend threshold search from scaffold to actual Track 2 estimation workflow.

Operational Targets

The repo Makefile should treat Rust as a first-class build/test surface:

• make rust-test
• make rust-check
• make rust-smoke
• make compare-track1-rust-smoke

That keeps Track 2 visible in daily workflow from the start.