feat(bench): §9 benchmarks.md results appender (PR-J3)

crates/ourios-bench/src/lib.rs

@@ -2,20 +2,24 @@
 //! (A1 compression, C1 reconstruction, C2 template-count
 //! convergence).
 //!
-//! **Implementation status (PR-J2):** all three writer-side
+//! **Implementation status (PR-J3):** all three writer-side
 //! gates — A1 (compression), C1 (reconstruction), C2
 //! (template-count convergence) — are live. [`run`] computes
 //! any combination in a single miner pass and returns a
 //! populated [`ResultsFile`]. The CLI (RFC 0006 §3.7) in
-//! `main.rs` drives `run` and writes the §3.6 JSON results
-//! file via [`write_results_json`]. The remaining piece is the
-//! `docs/benchmarks.md` §9 markdown appender (the
-//! `--update-benchmarks-md` path), which lands in a follow-up.
+//! `main.rs` drives `run`, writes the §3.6 JSON results file
+//! via [`write_results_json`], and — with
+//! `--update-benchmarks-md` — folds the results into the
+//! `docs/benchmarks.md` §9 table via [`update_status_section`].
+//! The bench's measurement + reporting surface is complete;
+//! the only RFC 0006 work left is the RFC0006.7
+//! reproducibility test (still `#[ignore]`'d).
 //!
 //! Per RFC 0006 §3.2 the module layout is `corpus`, `harness`,
 //! `a1`, `c1`, `c2`, `report`. PR-I1 extracted `corpus`,
 //! `harness`, `c1`; PR-I2 added `a1`; PR-J1 added `report`
-//! (JSON half) + the CLI; PR-J2 added `c2`.
+//! (JSON half) + the CLI; PR-J2 added `c2`; PR-J3 added the
+//! §9 appender.
 
 #![deny(unsafe_code)]
 
@@ -29,7 +33,7 @@ mod corpus;
 mod harness;
 mod report;
 
-pub use report::write_results_json;
+pub use report::{update_status_section, write_results_json};
 
 /// Configuration for one bench invocation.
 ///
@@ -85,10 +89,12 @@ impl GateSet {
 /// Top-level entry point. Loads the corpus, drives the miner
 /// and writer pipeline, computes the §3.4 measurements for
 /// every enabled gate, and returns the §3.6 results in
-/// memory; writing the JSON file to `config.results_dir` and
-/// optionally rewriting the `docs/benchmarks.md` §9 sub-heading
-/// per `config.update_benchmarks_md` are the binary's
-/// responsibility (and not yet implemented).
+/// memory. Persisting them — writing the JSON file to
+/// `config.results_dir` and, when `config.update_benchmarks_md`
+/// is set, folding them into the `docs/benchmarks.md` §9 table
+/// — is the binary's responsibility, via
+/// [`write_results_json`] and [`update_status_section`]
+/// respectively.
 ///
 /// All three gates — A1, C1, C2 — are implemented and run in
 /// any combination. At least one gate must be enabled; an

crates/ourios-bench/src/main.rs

@@ -7,16 +7,23 @@
 //! exit code (a C1 reconstruction mismatch is a hard failure
 //! per §3.4.2).
 //!
-//! The `--update-benchmarks-md` §9 markdown appender is not
-//! implemented yet — the flag is accepted (so the surface
-//! matches §3.7) but currently only warns; the JSON results
-//! file is written regardless.
+//! With `--update-benchmarks-md`, it also folds the run's
+//! results into the `docs/benchmarks.md` §9 Results table
+//! (via [`ourios_bench::update_status_section`]); the JSON
+//! results file is written either way.
 
 use std::path::PathBuf;
 use std::process::ExitCode;
 
 use clap::{Parser, ValueEnum};
-use ourios_bench::{BenchConfig, BenchError, GateSet, run, write_results_json};
+use ourios_bench::{
+    BenchConfig, BenchError, GateSet, run, update_status_section, write_results_json,
+};
+
+/// The §9 Results doc the `--update-benchmarks-md` path
+/// rewrites. Relative to the invocation directory (the
+/// maintainer runs `just thesis-bench` from the repo root).
+const BENCHMARKS_MD_PATH: &str = "docs/benchmarks.md";
 
 /// RFC 0006 §1 hardware baseline tag, surfaced in the
 /// `--allow-unknown-hardware` warning so an operator knows
@@ -53,8 +60,9 @@ struct Cli {
     /// requiring `--hardware-kind`.
     #[arg(long)]
     allow_unknown_hardware: bool,
-    /// Append / rewrite the `docs/benchmarks.md` §9 sub-heading
-    /// (not implemented yet — see crate docs).
+    /// Fold this run's results into the `docs/benchmarks.md`
+    /// §9 Results table (rewriting the block for this
+    /// git-sha / hardware-kind in place).
     #[arg(long)]
     update_benchmarks_md: bool,
     /// Comma-separated subset of gates to compute. Default: all.
@@ -144,10 +152,7 @@ fn run_bench(cli: Cli) -> Result<ExitCode, BenchError> {
     }
     print_summary(&results);
     if update_md {
-        eprintln!(
-            "ourios-bench: warning: --update-benchmarks-md is not implemented yet (the §9 \
-             markdown appender lands in a follow-up PR); JSON results written only.",
-        );
+        update_benchmarks_md(&results)?;
     }
 
     // §3.4.2: a non-lossy reconstruction mismatch is a
@@ -171,6 +176,22 @@ fn run_bench(cli: Cli) -> Result<ExitCode, BenchError> {
     Ok(ExitCode::SUCCESS)
 }
 
+/// Read `docs/benchmarks.md`, fold this run's results into its
+/// §9 Results region, and write it back. Thin file I/O around
+/// the pure [`update_status_section`] transform.
+fn update_benchmarks_md(results: &ourios_bench::ResultsFile) -> Result<(), BenchError> {
+    let path = std::path::Path::new(BENCHMARKS_MD_PATH);
+    let md = std::fs::read_to_string(path).map_err(|e| BenchError::Report {
+        detail: format!("read {}: {e} (run from the repo root?)", path.display()),
+    })?;
+    let updated = update_status_section(&md, results)?;
+    std::fs::write(path, updated).map_err(|e| BenchError::Report {
+        detail: format!("write {}: {e}", path.display()),
+    })?;
+    eprintln!("ourios-bench: updated {} §9 Results", path.display());
+    Ok(())
+}
+
 /// Print a one-line-per-gate human summary to stdout. The
 /// machine-readable form is the JSON results file; this is
 /// just operator feedback.