Module profile 

Deterministic profile counters (Tier 2 of Chess RL v2.3). Write-only timing sink that does not perturb program state, RNG, or weight hashes. Deterministic profile counters for Tier 2 of the Chess RL v2.3 upgrade.

This module provides a minimal, write-only profiling sink that the CJC-Lang program can use to time named zones inside a hot loop. It is the smallest possible surface that makes the v2.2 bottleneck measurable without perturbing program state.

Builtins

• profile_zone_start(name: String) -> i64
• profile_zone_stop(handle: i64) -> f64
• profile_dump(path: String) -> i64

All three dispatch arms live in crate::builtins; this module owns only the thread-local state and the pure helper functions that operate on it.

Determinism story

The counter state lives in a thread-local RefCell<ProfileState>. The program can observe the identity of a zone handle (to pair start/ stop calls), but the integer value of the handle must not feed into program logic, RNG draws, tensor math, or control flow. The Chess RL v2.3 parity test asserts that an instrumented rollout produces a weight hash identical to an uninstrumented rollout.

No floating-point math is done on the counters until profile_dump renders the CSV, by which point the nanosecond counters are committed. All iteration over zones uses [BTreeMap] ordering so the CSV layout is reproducible across runs.

No RNG is touched. No tensor math is touched. No cross-thread state is accessed. No external crates are pulled in — only std::time::Instant, std::collections::BTreeMap, and std::cell::RefCell.

Structs

ProfileState

Internal profiler state — one instance per thread.

ZoneStats

Per-zone aggregated statistics.

Functions

dump_to_path

Serialize the aggregated zone statistics to CSV, sorted by total_ns descending so the hot zones appear at the top. Returns the number of data rows written (not including the header). Resets the profiler state after writing.

zone_start

Start a zone and return an opaque handle. The handle is monotonically increasing within the current thread.

zone_stop

Stop a zone previously started by zone_start. Updates the aggregated ZoneStats and returns the elapsed seconds as f64. Returns -1.0 for an unknown handle (never panics).