Persist CSV inputs for release performance rerendering

[acgetchell]

Summary

Make cross-release performance reports robust, auditable, and data-analysis friendly by preserving the exact report inputs as schema-versioned CSV plus a JSON provenance sidecar before temporary benchmark worktrees are removed.

Generate the committed Markdown report by reloading those stored artifacts, and provide a rerender command that does not rerun benchmarks.

Current State

The public vs_linalg README benchmark workflow already publishes timing point estimates and confidence bounds as CSV with a JSON provenance sidecar.

The release-comparison path is different. performance-release measures and renders inside a temporary worktree, returns only Markdown, and then removes the Criterion results and provenance used to create it. Full native Criterion archives are retained later as GitHub Release assets, but there is no retained pre-release, machine-readable comparison dataset.

Consequences:

• Formatting or reporting changes require another lengthy benchmark run or direct Markdown edits.
• The published report cannot be independently regenerated from a retained local dataset.
• Manual corrections can preserve displayed values, but the transformation is not demonstrated by an end-to-end artifact round trip.
• Downstream analysis must parse Markdown instead of consuming a stable tabular schema.

Proposed Changes

• Export the release comparison to a deterministic CSV under target/bench-reports/.
• Include, at minimum, suite, scope, benchmark identifier, coverage status, baseline/current median point estimates, and both confidence-interval bounds in nanoseconds.
• Store the release pair, source revisions and states, benchmark commands, harness/configuration digests, Criterion and Rust versions, host information, and schema version in an adjacent JSON provenance file.
• Publish the CSV and provenance sidecar transactionally after validating the complete dataset.
• Make performance-release reload and validate the stored CSV and provenance before rendering and promoting docs/PERFORMANCE.md.
• Add a performance-rerender command that regenerates the report from the stored artifacts without invoking Cargo or creating Git worktrees.
• Keep the full native Criterion .tar.gz GitHub Release assets; the CSV is the analysis and report-reproduction layer, not a replacement for raw release baselines.
• Document artifact ownership, retention under target/, cleanup behavior, and the distinction between CSV reporting inputs and native Criterion archives.

Benefits

• Provides a direct, auditable path from measurements and provenance to every reported figure.
• Makes benchmark evidence independently analyzable with standard data tools.
• Allows report-format fixes without introducing a second noisy measurement run.
• Aligns release reporting with la-stack's existing CSV-plus-provenance public benchmark pattern.
• Separates compact reporting inputs from complete post-release Criterion archives.

Implementation Notes

• Prefer Python's standard csv and json modules; Parquet is unnecessary for this dataset and Criterion does not consume it directly.
• Use explicit nanosecond column names and a versioned schema.
• Sort rows deterministically and use stable UTF-8/newline handling.
• Reject duplicate benchmark keys, unknown coverage states, non-finite or non-positive timings, invalid confidence intervals, mismatched release pairs, incomplete provenance, and unsupported schema versions.
• Treat target/bench-reports/ as reproducible local scratch data; just clean may remove it.
• Ensure failed serialization, validation, rendering, or promotion preserves the prior valid report and artifact pair.

Acceptance Criteria

• just performance-release writes a CSV and JSON provenance sidecar before temporary measurements are cleaned up.
• The promoted Markdown report is rendered from a validated reload of those files, not directly from in-memory Criterion parsing.
• just performance-rerender reproduces the same Markdown without running Cargo or modifying Git worktrees.
• Every numeric value and coverage note in the Markdown report is derivable from the retained CSV.
• Provenance identifies both measured source states, commands, toolchain, Criterion version, benchmark harness/configuration, and host.
• Round-trip tests cover comparable, current-only, and baseline-only rows.
• Malformed CSV, malformed or mismatched provenance, incomplete confidence intervals, and partial publication fail closed.
• docs/BENCHMARKING.md and docs/RELEASING.md describe the new artifacts and rerender path.

Praxis Relevance

• Affected layer: la-stack shared numerical infrastructure and its performance-evidence pipeline.
• Classification: Category 2 — reproducibility or measurement defect.
• Evidence: The release workflow deletes its machine-readable comparison inputs when its temporary worktree exits, leaving only rendered Markdown.
• Risk if deferred: Release performance claims used as Praxis evidence cannot be independently regenerated or conveniently reanalyzed, and report corrections may require new noisy measurements.
• Smallest intervention: Persist the exact report-level dataset and provenance, validate a serialization round trip, and add a rerender-only path; do not redesign Criterion or the benchmark harness.
• Required validation: Deterministic round-trip tests plus one end-to-end release-report generation that proves the promoted Markdown came from the retained artifacts.
• Condition impact: Shared infrastructure; applies symmetrically to conventional and learned conditions that depend on la-stack.
• Timing: Required before treating these release benchmark reports as final Praxis evidence.
• Recommendation: Required for research-grade performance reporting; bounded to the report artifact pipeline.

Related: #138