feat(bench): scaffold ourios-bench crate (PR-H1 of RFC 0006)

[jensholdgaard]

Summary

First half of the RFC 0006 specified → red progression. Lands the ourios-bench crate scaffold so the test stubs in PR-H2 have a public surface to link against; PR-H2 follows with the seven #[ignore]'d acceptance-criterion tests and the frontmatter status bump.

Lands

• crates/ourios-bench/ new crate, wired into the workspace members list (and removed from the "remaining members" comment block).
• src/lib.rs — public surface:
  • BenchConfig / GateSet (the CLI's parsed shape; consumed by run()).
  • ResultsFile + sub-structs (CorpusStats, OuriosStats, ZstdStats, A1Result, C1Result, C2Result, ConvergenceSample). Struct shapes mirror RFC 0006 §3.6 exactly so a future serde_json::from_str(<results-file>) parses against this type without translation. Nullable gate fields (a1, c1, c2: Option<...>) implement the §3.6 nullability rule.
  • BenchError — declared upfront so downstream test code doesn't have to refactor when later variants start firing.
  • run() entry point that returns BenchError::NotImplemented (the Red-gate scaffold).
• src/main.rs — thin binary that prints a scaffold-stage banner to stderr and exits 2. CLI argument parsing follows in PR-H2.
• justfile — new thesis-bench *ARGS recipe per the RFC §3.7 resolution (separate from bench, which still runs cargo bench for the future criterion suite).

What's not in this PR

• The per-module split (corpus.rs / harness.rs / a1.rs / c1.rs / c2.rs / report.rs) — collapsed into lib.rs for now per CLAUDE.md §5.2 "≤ 5 files per phase". The first module to graduate is corpus.rs, in a follow-up.
• Test stubs — PR-H2.
• RFC frontmatter status: specified → red — PR-H2 (after test stubs exist, the maturity model says).

Test plan

• cargo build -p ourios-bench — green.
• cargo fmt --all --check — clean.
• cargo clippy --all-targets --all-features -- -D warnings — clean.
• cargo test --all-features — 225 passed / 18 ignored (unchanged from main; bench has no tests yet).
• Reviewer eyeballs the ResultsFile field shape against RFC 0006 §3.6's JSON example to confirm one-to-one correspondence (the type is the §3.6 contract incarnated; drift here is drift from the RFC).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a benchmarking harness with configuration and structured result output schema.
  • Added a convenient release-mode command to invoke the benchmark; note the CLI is currently a scaffold that reports “not implemented” and exits with a non-zero status.

• Chores

  • Registered the new benchmark component in the workspace configuration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: feed38f1-b46a-492f-90ee-9077dfe469e5

📥 Commits

Reviewing files that changed from the base of the PR and between 4b3dfde and dc81044.

📒 Files selected for processing (1)

• crates/ourios-bench/src/lib.rs

---

📝 Walkthrough

Walkthrough

Adds a new ourios-bench crate to the workspace with a Cargo manifest, library API scaffolding (BenchConfig, GateSet, ResultsFile, BenchError, run placeholder), a stub binary that exits non‑zero, and a justfile recipe to invoke the bench in release mode.

Changes

RFC 0006 Benchmarking Crate Scaffold

Layer / File(s)	Summary
Workspace registration Cargo.toml	crates/ourios-bench is added to [workspace].members and the placeholder comment is removed.
Crate manifest and dependencies crates/ourios-bench/Cargo.toml	Package metadata, binary/library targets, dependencies on workspace crates (ourios-core, ourios-miner, ourios-parquet) and serialization (serde, serde_json), plus tempfile dev-dependency and workspace lints.
Library types and config crates/ourios-bench/src/lib.rs	Crate-level RFC 0006 documentation and #![deny(unsafe_code)]; defines BenchConfig and GateSet (GateSet::all()).
run() entry point placeholder crates/ourios-bench/src/lib.rs	Public run(&BenchConfig) -> Result<ResultsFile, BenchError> implemented as a NotImplemented placeholder.
ResultsFile schema and related structs crates/ourios-bench/src/lib.rs	RFC-pinned ResultsFile with CorpusStats, OuriosStats, ZstdStats, A1Result, C1Result, C2Result, and ConvergenceSample; uses Option for skipped gates and C2 availability.
BenchError and trait impls crates/ourios-bench/src/lib.rs	BenchError enum variants plus Display and Error implementations.
Unit tests crates/ourios-bench/src/lib.rs	Tests for GateSet::all(), run() returning NotImplemented, and ResultsFile serde round-trip.
Binary entry point and build integration crates/ourios-bench/src/main.rs, justfile	Binary main() prints a scaffold-not-implemented message and exits with code 2; thesis-bench recipe runs cargo run -p ourios-bench --release forwarding arguments.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• jensholdgaard/ourios#48: Adds the ourios-bench crate scaffold and RFC 0006 contracts that align with this PR's benchmark API and schema.

Poem

🐰 Hops of code in twilight's den,
A1, C1, C2 — gates for when.
The bench is seeded, scaffolded neat,
Results will dance when runs are complete.
Rabbit applauds this tidy feat.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: adding a scaffold for the ourios-bench crate as the first half of RFC 0006 implementation.
Description check	✅ Passed	The description covers the required template sections: Summary explains the purpose, Related links RFC 0006, and Checklist items are addressed with test verification details.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/ourios-bench-scaffold

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Scaffolds the new ourios-bench crate (RFC 0006 PR-H1) so follow-up Red-gate acceptance tests can link against a stable public surface, and wires a just thesis-bench entry point into the workspace.

Changes:

• Add new crates/ourios-bench crate with initial public API (BenchConfig, GateSet, results JSON structs, BenchError, and a stub run()).
• Add a stub ourios-bench binary that currently prints a scaffold banner and exits non-zero.
• Wire the crate into the workspace and add a just thesis-bench recipe.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
justfile	Adds thesis-bench recipe to run the new bench harness in release mode.
crates/ourios-bench/src/main.rs	Introduces stub CLI/binary entry point (currently banner + exit).
crates/ourios-bench/src/lib.rs	Defines the public surface (config, results schema, error type) and stub run().
crates/ourios-bench/Cargo.toml	Adds crate manifest with workspace lint opt-in and serde/tempfile deps.
Cargo.toml	Adds crates/ourios-bench to workspace members.
Cargo.lock	Records the new workspace package and its dependencies.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/ourios-bench/src/lib.rs`:
- Around line 29-31: This file lacks colocated unit tests for the non-trivial
contract behavior described; add a #[cfg(test)] mod tests block inside
src/lib.rs and implement focused unit tests that exercise the public API used by
main.rs and tests/, e.g. call and assert behaviors of run and any public
structs/enums used by the CLI contract, mock or construct inputs directly
(instead of relying only on tests/ integration tests), and include edge cases
referenced in the module docs so the module’s behavior is validated alongside
the code.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 28b8568e-d8bd-4e27-915e-ec409b3bd0a2

📥 Commits

Reviewing files that changed from the base of the PR and between 7c808c3 and 15fe1ef.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (5)

• Cargo.toml
• crates/ourios-bench/Cargo.toml
• crates/ourios-bench/src/lib.rs
• crates/ourios-bench/src/main.rs
• justfile

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated no new comments.