Align performance command syntax and artifact semantics with la-stack

[acgetchell]

Summary

Align Delaunay's canonical performance commands and artifact lifecycle with the finalized la-stack workflow so related repositories expose the same operator-facing syntax and semantics.

Delaunay-specific performance, topology, geometry, allocation, and large-scale regression helpers remain additive.

Current State

Issue #436 introduced temp-worktree release comparisons, durable Criterion release assets, curated Markdown promotion, and Delaunay-specific release-signal suites.

The remaining cross-repository differences are:

• Public recipes use perf-local, perf-github-assets, and perf-release instead of the canonical performance-* names.
• Delaunay has no performance-doc workflow that promotes a report solely from retained validated artifacts.
• Local and GitHub-assets comparisons retain only rendered Markdown rather than a Markdown/CSV/provenance bundle.
• Release generation renders and promotes directly instead of retaining the measurement bundle, validating a reload, and then promoting atomically.
• bench-compare does not expose the same baseline, suite, and scope positional contract as la-stack.

Full native Criterion .tar.gz GitHub Release assets remain the durable raw-baseline format and should not be replaced.

Shared Command Contract

Expose these canonical workflows with the same high-level behavior as la-stack:

just performance-local
just performance-release [current-tag baseline-tag]
just performance-doc
just performance-github-assets [current-tag baseline-tag]
just bench-compare [baseline] [suite] [scope]
just bench-save-baseline <tag> [suite]
just bench-latest
just bench-latest-vs-last

Tag arguments must follow one rule everywhere: omit both to use discovery/inference, or provide both explicitly; a partial pair fails before fetching, worktree creation, or benchmarking.

Existing perf-* names may remain as compatibility aliases, but documentation and help output should present performance-* as canonical.

Workflow Semantics

• performance-local: measure the current tree against the latest stable release in temporary worktrees; validate and retain target/bench-reports/performance.{md,csv,provenance.json}; never modify committed documentation.
• performance-release: measure the inferred or explicit release pair; retain the same artifact bundle; validate it after reload; then atomically promote docs/PERFORMANCE.md and archive the prior report.
• performance-doc: run no Cargo benchmarks and create no measurement worktrees; validate the retained CSV/provenance and render/promote documentation from those inputs; fail closed for invalid, incomplete, unsupported, or non-distinct release pairs.
• performance-github-assets: compare stored GitHub Release benchmark assets without local Cargo runs; retain target/bench-reports/github-assets-performance.{md,csv,provenance.json}; never promote documentation.
• bench-compare: accept the same positional baseline, suite, and scope shape and forward it to the underlying CLI consistently.

Keep Delaunay-specific helpers such as perf-no-regressions, perf-vs-ref, and perf-large-scale-smoke; they are not part of the shared cross-repository contract.

Artifact Contract

• Use a versioned, deterministic CSV schema for suite, scope, benchmark identity, coverage state, baseline/current estimates, and confidence bounds.
• Store release pair, source revisions/states, benchmark commands, suite/scope, harness/configuration digests, Criterion and Rust versions, host identity, and schema version in adjacent JSON provenance.
• Sort rows deterministically and fail closed on duplicates, unknown coverage states, non-finite timings, invalid intervals, mismatched release pairs, incomplete provenance, or unsupported schemas.
• Publish each scratch bundle transactionally and render Markdown only from a validated artifact reload.
• Preserve native Criterion GitHub Release archives for full raw release baselines.
• Treat target/bench-reports/ as reproducible scratch data that cleanup may remove.

Acceptance Criteria

• The canonical performance-* recipes exist with the same syntax, defaults, tag-pair validation, and promotion boundaries as la-stack.
• bench-compare exposes and tests the shared baseline, suite, and scope positional contract.
• Specialized Delaunay commands remain available and are clearly separated from the shared core.
• Local and GitHub-assets workflows retain validated Markdown, CSV, and JSON provenance bundles without promoting docs.
• performance-release retains a bundle, validates a reload, and only then promotes/archive docs atomically.
• performance-doc reproduces and promotes the report from retained artifacts without Cargo benchmark runs or measurement worktrees.
• Every numeric value and coverage note in rendered Markdown is derivable from the CSV.
• Provenance identifies both measured source states, commands, toolchain, Criterion version, harness/configuration, suite/scope, and host.
• Full Criterion GitHub Release assets remain compatible with performance-github-assets.
• Round-trip and malformed-input tests fail closed and preserve prior valid outputs.
• Benchmark, release, command, and performance documentation uses the canonical names and explains artifact ownership.

Related Work

• Adapt release performance benchmarking workflow from la-stack #436 introduced the current release-performance workflow.
• Harden Python release preflight and local performance feedback #552 contains adjacent release-preflight and live-progress hardening.
• Cross-repository implementation reference: fix(perf)!: unify local and release performance workflows la-stack#210