Module runtime_policy 

Runtime Policy Layer — deterministic thermally-bounded execution policy (thread caps, thermal profiles, batch sizing, audit depth) plus a wall-clock-free energy estimate. The “green compute” control surface. Runtime Policy Layer — deterministic, thermally-bounded execution policy.

This module is the “green compute” control surface for CJC-Lang. It lets a run declare how much machine it is willing to use — thread caps, batch sizing, audit depth — and exposes a deterministic energy estimate so a program can reason about joules-per-result instead of merely wall-clock seconds.

The guiding philosophy: do not let CJC-Lang blindly saturate the CPU. Use deterministic bounded execution. Thermal/energy limits are made explicit and deterministic rather than left to the OS scheduler.

Builtins (registered in crate::builtins)

Policy query / mutate:

• runtime_policy_thermal_mode() -> String
• runtime_policy_set_thermal_mode(mode: String) -> String
• runtime_policy_threads() -> Int (resolved effective cap)
• runtime_policy_set_threads(n: Int) -> Int
• runtime_policy_batch_size() -> Int
• runtime_policy_set_batch_size(n: Int) -> Int
• runtime_policy_audit_mode() -> String
• runtime_policy_set_audit_mode(mode: String) -> String
• runtime_policy_numeric_mode() -> String
• runtime_policy_set_numeric_mode(mode: String) -> String
• runtime_policy_reset() -> Int
• runtime_policy_summary() -> String

Energy model:

• energy_estimate(flops: Int, bytes: Int) -> Float (joules)
• energy_per_flop() -> Float
• energy_per_byte() -> Float

Determinism story

Two invariants make this layer safe under Prime Directive #3 (same seed = bit-identical output):

1. Thread count never changes results. The parallel kernels in crate::tensor reduce with Kahan / crate::accumulator binned summation over a fixed chunk order, so the numeric output is identical regardless of how many rayon workers are live. The thermal mode and thread cap therefore move only the performance/heat axis, never the answer axis. Capping threads is pure “deterministic bounded execution”.

2. Energy is estimated from workload counts, never from wall time. [energy_estimate_joules] is a pure function of integer FLOP and byte counts times fixed documented constants. Wall-clock time is explicitly not an input, because it varies run-to-run and would poison determinism. Same program + same seed → same FLOP count → same joule estimate, bit-for-bit. The two multiplies are kept in separate let bindings so the compiler cannot contract them into a single FMA (the same no-FMA discipline the SIMD kernels follow).

The policy itself lives in a thread-local RefCell<RuntimePolicy>, mirroring the crate::profile counter sink. The interpreter thread reads and writes it; the actual rayon thread cap is applied once per process by [apply_thread_cap] (the CLI calls this at startup) because rayon’s global pool can only be configured once. No RNG is touched. No HashMap is used.

Structs

RuntimePolicy

A fully-resolved runtime execution policy.

Enums

AuditMode

Audit/forensics depth. Controls how much cold-path work (logs, Merkle trees, full lineage) runs alongside the hot numerical path. Deeper modes trade speed and energy for traceability; they never change numeric output.

Determinism

Determinism guarantee level. Strict is the only mode that ships today; Relaxed is reserved so the field exists in the policy surface without implying it weakens any current guarantee.

NumericMode

Floating-point reduction strategy. Maps to the existing accumulator family; every variant preserves determinism (none enables FMA or random ordering).

ThermalMode

Thermal/energy execution profile. This is the headline “green” knob: it bounds how aggressively a run uses the CPU so a laptop does not cook itself sustaining turbo across all cores.

Constants

ENERGY_PER_BYTE_JOULES

Estimated energy cost of moving one byte through the memory hierarchy, in joules (~100 pJ/byte, representative of DRAM traffic). Memory traffic is a dominant energy consumer, which is why TidyView’s sparse/dictionary-encoded layouts matter for the green story. Same caveat as ENERGY_PER_FLOP_JOULES: an estimate for relative comparison, not a calibrated absolute.

ENERGY_PER_FLOP_JOULES

Estimated energy cost of a single double-precision FLOP, in joules.

Functions

apply_thread_cap

Pre-warm the throttle pool for a thread cap. Returns the live worker count.

current_effective_threads

Resolved effective thread cap for the current policy on this machine.

detect_cores

Detected logical core count (>= 1). Falls back to 1 if the platform cannot report parallelism. This is the only place we read machine topology.

effective_threads

Resolve the effective thread cap for a policy given a detected core count.

energy_estimate_joules

Deterministic energy estimate in joules for a workload of flops floating-point operations and bytes of memory traffic.

get

Snapshot the current policy.

reset

Reset to the laptop-safe Balanced default. Tests and the REPL call this to avoid cross-run leakage on a reused thread. Also clears the race-to-idle burst timer so a fresh run starts in the burst regime.

run_parallel

Run work under the active thermal policy, throttling parallelism to the thermal cap only when appropriate.

set_adaptive

Enable/disable race-to-idle adaptive scheduling. false = fixed cap (reproducible schedule); true = burst-then-throttle (the default).

set_audit_mode

Set the audit depth.

set_batch_size

Set the advisory batch size.

set_determinism

Set the determinism level.

set_numeric_mode

Set the numeric reduction mode.

set_thermal_mode

Adopt a thermal profile wholesale: sets the thermal mode plus its preset batch size and audit depth, and resets the thread cap to auto. Explicit per-field setters called after this win (the CLI applies the profile first, then individual --threads / --batch-size / --audit-mode overrides).

set_threads

Set an explicit thread cap (0 = auto).