# 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.