Bootstrap hotpath from engineering spec v0.1

Commit the spec and scaffold the system it describes:

- SPEC.md: the full v0.1 engineering spec
- crates/: trust-layer Rust workspace, unit-tested
  - bench-runner: interleaved ABAB scheduling with discarded warm-ups,
    deterministic bootstrap CIs over the ratio of medians,
    CI-lower-bound accept rule, env fingerprinting, and a CLI with
    compare + A/A self-test modes (A/A verified passing end-to-end)
  - diff-test: gate outcome model, sha256 corpus pin verifier that
    refuses on mismatch, per-target equivalence policy parser
    (byte-identical default, explicit fp-tolerance opt-in)
  - ledger: append-only SQLite attempt schema with UPDATE/DELETE
    refused by triggers, anti-double-attempt query
  - report: cores-saved and dollars/yr ROI math over speedup CIs,
    pricing.toml inputs
- playbook/: classes 1-7 with preconditions, procedure, verification
  notes, and known failure modes per class
- agent/: Python package skeleton — six-tool contract and prompting
  spine, harness IPC deferred to Phase 1
- config/: accept.toml (2% threshold, 30 runs/side), pricing.toml
- targets/, corpora/, results/calibration/: layout and policy docs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EcKPWQ3MQD4NdEHwar96u2

crates/report/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "report"
+description = "ROI reports from ledger rows: throughput→cores→dollars with CIs, workload statement, and env fingerprint on every figure"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+anyhow.workspace = true
+ledger = { path = "../ledger" }
+serde.workspace = true
+serde_json.workspace = true
+toml.workspace = true

crates/report/src/lib.rs

@@ -0,0 +1,74 @@
+//! ROI methodology (SPEC §3.6, §9): what did the stopwatch say, and what
+//! does that cost or buy? Every figure carries its CI; the caveats print
+//! on the report, not in an appendix.
+
+pub mod pricing;
+
+/// Cores returned to the fleet by a throughput speedup:
+/// `fleet_cores × (1 − 1/speedup)`.
+pub fn cores_saved(fleet_cores: f64, speedup: f64) -> f64 {
+    assert!(speedup > 0.0, "speedup must be positive");
+    fleet_cores * (1.0 - 1.0 / speedup)
+}
+
+/// Annual dollars from saved cores at a $/core-hour rate.
+pub fn dollars_per_year(cores: f64, dollars_per_core_hour: f64, hours_per_year: f64) -> f64 {
+    cores * dollars_per_core_hour * hours_per_year
+}
+
+/// ROI range induced by a speedup CI — the report quotes the interval,
+/// never just the point estimate.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct RoiRange {
+    pub cores_lo: f64,
+    pub cores_median: f64,
+    pub cores_hi: f64,
+    pub dollars_lo: f64,
+    pub dollars_median: f64,
+    pub dollars_hi: f64,
+}
+
+pub fn roi_from_speedup_ci(
+    fleet_cores: f64,
+    speedup_median: f64,
+    speedup_ci: (f64, f64),
+    dollars_per_core_hour: f64,
+    hours_per_year: f64,
+) -> RoiRange {
+    let (lo, hi) = speedup_ci;
+    let (c_lo, c_med, c_hi) = (
+        cores_saved(fleet_cores, lo),
+        cores_saved(fleet_cores, speedup_median),
+        cores_saved(fleet_cores, hi),
+    );
+    RoiRange {
+        cores_lo: c_lo,
+        cores_median: c_med,
+        cores_hi: c_hi,
+        dollars_lo: dollars_per_year(c_lo, dollars_per_core_hour, hours_per_year),
+        dollars_median: dollars_per_year(c_med, dollars_per_core_hour, hours_per_year),
+        dollars_hi: dollars_per_year(c_hi, dollars_per_core_hour, hours_per_year),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn cores_saved_formula() {
+        // 2x speedup halves the fleet: 100 cores → 50 saved.
+        assert!((cores_saved(100.0, 2.0) - 50.0).abs() < 1e-12);
+        // 1.25x on 1000 cores: 1000 × (1 − 0.8) = 200.
+        assert!((cores_saved(1000.0, 1.25) - 200.0).abs() < 1e-9);
+        // No speedup, no savings.
+        assert_eq!(cores_saved(100.0, 1.0), 0.0);
+    }
+
+    #[test]
+    fn roi_range_is_ordered() {
+        let r = roi_from_speedup_ci(1000.0, 1.10, (1.05, 1.16), 0.04, 8760.0);
+        assert!(r.cores_lo < r.cores_median && r.cores_median < r.cores_hi);
+        assert!(r.dollars_lo < r.dollars_median && r.dollars_median < r.dollars_hi);
+    }
+}

crates/report/src/pricing.rs

@@ -0,0 +1,30 @@
+//! Pricing inputs (`config/pricing.toml`). Rates are engagement inputs,
+//! not constants — public cloud list prices by default, customer's own
+//! numbers when supplied.
+
+use serde::Deserialize;
+use std::path::Path;
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Pricing {
+    /// Dollars per core-hour (e.g. public-cloud on-demand vCPU rate).
+    pub dollars_per_core_hour: f64,
+    /// Fleet hours per year the workload actually runs (8760 for 24/7).
+    pub hours_per_year: f64,
+    /// Where the rate came from — printed on the report.
+    pub rate_source: String,
+}
+
+impl Pricing {
+    pub fn load(path: &Path) -> anyhow::Result<Self> {
+        let raw = std::fs::read_to_string(path)?;
+        let p: Self = toml::from_str(&raw)?;
+        anyhow::ensure!(p.dollars_per_core_hour > 0.0, "rate must be positive");
+        anyhow::ensure!(
+            p.hours_per_year > 0.0 && p.hours_per_year <= 8784.0,
+            "hours_per_year must be in (0, 8784]"
+        );
+        Ok(p)
+    }
+}