From e7d3d5e362b15aabf0c4364a8db751ccea99d26b Mon Sep 17 00:00:00 2001 From: Adam Getchell Date: Wed, 11 Nov 2026 18:50:41 -0800 Subject: [PATCH] fix(release): repair draft verification and refresh maintainer docs - Verify release evidence with the installed CLI's repository-relative policy path. - Exclude generated performance reports and run records from CodeRabbit review. - Replace obsolete release and tooling guidance with current ownership and recovery steps. - Archive historical benchmark reviews and clarify benchmark and API documentation. --- .coderabbit.yaml | 3 + .github/workflows/prepare-release.yml | 2 +- CONTRIBUTING.md | 42 +- README.md | 18 +- SECURITY.md | 21 +- docs/BENCHMARKING.md | 69 ++-- docs/MEASURING_COVERAGE.md | 2 +- docs/RELEASING.md | 54 +-- docs/archive/development/README.md | 11 + .../benchmark-candidate-review.md | 6 +- .../development}/benchmark-workload-review.md | 13 +- docs/code_organization.md | 34 +- docs/dev/MANAGING_CHANGES.md | 80 ++-- docs/dev/performance-tooling-adoption.md | 197 ---------- docs/dev/release-flow-integration.md | 250 ++++-------- docs/roadmap.md | 371 ++---------------- src/ldlt.rs | 4 +- src/lu.rs | 4 +- src/matrix.rs | 44 +-- tests/tooling/test_release_flow.py | 59 +++ tooling/README.md | 56 +-- 21 files changed, 357 insertions(+), 983 deletions(-) create mode 100644 docs/archive/development/README.md rename docs/{dev => archive/development}/benchmark-candidate-review.md (98%) rename docs/{dev => archive/development}/benchmark-workload-review.md (97%) delete mode 100644 docs/dev/performance-tooling-adoption.md diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 065403b..b888bd6 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -10,6 +10,9 @@ reviews: # Repository-owned checks validate deliberately invalid static-analysis fixtures. path_filters: - "!tests/semgrep/**" + - "!docs/performance.md" + - "!docs/performance-runs/runs/*/report.md" + - "!docs/performance-runs/runs/*/run.json" pre_merge_checks: # Ruff owns docstring policy without treating fixtures as public APIs. docstrings: diff --git a/.github/workflows/prepare-release.yml b/.github/workflows/prepare-release.yml index d122647..db07661 100644 --- a/.github/workflows/prepare-release.yml +++ b/.github/workflows/prepare-release.yml @@ -56,7 +56,7 @@ jobs: python -I -c 'import sys; from research_repo_tools.cli import main; sys.exit(main())') "${runtime[@]}" --root "$GITHUB_WORKSPACE" release check "$RELEASE_TAG" "${runtime[@]}" --root "$GITHUB_WORKSPACE" release evidence verify \ - "$RUNNER_TEMP/handoff/evidence.toml" --checkout "$GITHUB_WORKSPACE" \ + tooling/release-evidence.toml --checkout "$GITHUB_WORKSPACE" \ --commit "$commit" --version "${RELEASE_TAG#v}" \ --output "$RUNNER_TEMP/handoff/selection.json" "${runtime[@]}" --root "$GITHUB_WORKSPACE" changelog notes "$RELEASE_TAG" > "$RUNNER_TEMP/handoff/notes.md" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5449d59..1e75664 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,9 +20,8 @@ clarity, and the fixed-dimension stack-allocation model. ## Getting Started -Reusable Python development tooling has moved into -[`research-repo-tools`](https://github.com/acgetchell/research-repo-tools). -It is a development dependency for this repository's setup, validation, +[`research-repo-tools`](https://github.com/acgetchell/research-repo-tools) +is the shared development dependency for this repository's setup, validation, maintenance, benchmark reporting, and release workflows. Static declarations and native correctness gates retain la-stack's scientific policy; see the [Tooling guide](tooling/README.md) for the ownership boundary. @@ -77,8 +76,7 @@ an unrelated system installation cannot satisfy a managed Cargo pin. Use `just update` for deliberate maintenance. It runs `just update-tools` first: upgrade uv through its installation owner, upgrade declared managed Cargo tools, publish their verified pins, and synchronize setup. Just follows the shared -package's `rust-just` pin. Managed upgrades replace `cargo-update` and the old -Just-variable reconciler; unrelated user-global Cargo installations stay outside +package's `rust-just` pin. Unrelated user-global Cargo installations stay outside this workflow. Then `just update-dependencies` upgrades Cargo requirements and refreshes Cargo's @@ -184,9 +182,8 @@ before a deduplicated `github-actions[bot]` approval. Native squash auto-merge still requires the configured approvals, strict checks (including CodeRabbit's status), resolved threads, and dismissal of stale approvals. -This replaces owner-authored CodeRabbit requests and their personal token. CodeRabbit's successful status on a skipped bot review is not an approval. -The [rollout guide](docs/dev/MANAGING_CHANGES.md#dependabot-approval-rollout) +The [configuration guide](docs/dev/MANAGING_CHANGES.md#dependabot-approval-configuration) owns GitHub settings and post-merge verification. The workflow never executes PR code; dependency eligibility remains in `.github/dependabot.yml`. Dependabot monitors Semgrep through the root Python manifest and lockfile, @@ -200,10 +197,9 @@ global `RUSTFLAGS='-D warnings'`, this denies lint warnings only for local packages without changing rustc arguments and creating separate cache artifacts. Rustdoc has a separate warning contract, so `doc-check` continues to set `RUSTDOCFLAGS='-D warnings'` for the default and `exact` documentation -surfaces. See the [Rust 1.98 release notes](https://doc.rust-lang.org/stable/releases.html#version-1980-2026-08-20) -and [Cargo configuration reference](https://doc.rust-lang.org/cargo/reference/config.html#buildwarnings). +surfaces. See the [Cargo configuration reference](https://doc.rust-lang.org/cargo/reference/config.html#buildwarnings). -Rust 1.98's `f32`/`f64::algebraic_{add,sub,mul,div,rem}` operations are +The `f32`/`f64::algebraic_{add,sub,mul,div,rem}` operations are forbidden in `src/`, examples, and benchmark implementations. They permit real-number transformations such as reassociation with unspecified precision, which can invalidate the crate's documented error bounds and deterministic @@ -222,13 +218,9 @@ manifests and `clippy.toml` match `rust-toolchain.toml`; CI, coverage, and relea setup consume that declaration. Run `just setup-tools` after changing it: managed Cargo tools are installed separately for each compiler version. -The [Rust 1.99 migration study](docs/archive/performance/studies/rust-1.99.md) -records the final release-note audit, numerical validation, and paired LLVM -22/23 measurements. New Clippy diagnostics are addressed with `#[must_use]`, -integer `bit_width`, and diagnostic empty-array assertions. The existing -Linux, macOS, and Windows MSVC CI matrix and strict floating-point policy remain -the support contract. New allocation, raw-pointer, and collection APIs do not -serve an existing library requirement. +The Linux, macOS, and Windows MSVC CI matrix and strict floating-point policy +define the support contract. Historical compiler measurements and migration +evidence belong in the [Rust 1.99 study](docs/archive/performance/studies/rust-1.99.md). ## Contributor Workflow @@ -252,8 +244,9 @@ git switch -c doc/329-branch-guidance Keep each change scoped to one coherent purpose. Update tests and documentation with the behavior they support, avoid unrelated formatting churn, and cite relevant literature for numerical or algorithmic work. Automation and AI -assistants must stop before version-control mutations and release operations; a -human contributor performs and reviews commits, pushes, tags, and releases. +assistants need explicit maintainer authorization for version-control mutations +and release operations. Authorization remains valid within its agreed scope; +required checks and reviews still gate merge and publication. ### Validation Workflow @@ -324,8 +317,8 @@ publication keep caches disabled. The shared local build cache defaults to the tooling home's `cargo-build//`; an absolute `RESEARCH_REPO_TOOLS_CARGO_BUILD_HOME` selects separate compilation storage. This cache does not replace project builds or validation. See the -[integration record](docs/dev/release-flow-integration.md#hosted-ci-stages) for graph ownership, -baseline timings and remaining native/published-package evidence. +[integration reference](docs/dev/release-flow-integration.md#hosted-ci-stages) +for graph ownership and release-evidence boundaries. `la-stack` intentionally has no notebook validation bucket: the repository has no notebooks or supported Python binding surface. Add notebook tooling only @@ -450,10 +443,9 @@ section of [`REFERENCES.md`](REFERENCES.md). Releases are deliberate, maintainer-driven work. Ordinary feature, fix, review, and hygiene changes must not update package versions, version-pinned dependency snippets, citation release dates, generated changelogs, checked-in -release benchmark reports, tags, or other release artifacts. The maintainer -performs every version bump and release manually by -following [`docs/RELEASING.md`](docs/RELEASING.md). Do not substitute an -automated or abbreviated release path. +release benchmark reports, tags, or other release artifacts. Follow +[`docs/RELEASING.md`](docs/RELEASING.md) for explicitly authorized release work, +including its automated workflows, approval boundaries, and recovery procedure. ## Getting Help diff --git a/README.md b/README.md index 1ab05a0..77c5535 100644 --- a/README.md +++ b/README.md @@ -341,11 +341,7 @@ when the norm is finite. Both results remain approximate, without a certified error bound. [Worked example and range contracts][guide-norms]. -**v0.4.6 migration:** `Vector::norm2_sq()` is renamed to `Vector::norm_squared()`, -the unreleased `Vector::norm2()` API is named `Vector::norm()`, and -`Matrix::inf_norm()` is renamed to `Matrix::norm_inf()`. The old method names -are removed; their numerical behavior and error contracts are unchanged by -the renames. `Matrix::norm_inf()` remains the maximum absolute row sum. +`Matrix::norm_inf()` computes the maximum absolute row sum. ### Unsigned vector angles @@ -580,12 +576,12 @@ construction, and release-comparison workflow details, see [docs/BENCHMARKING.md](https://github.com/acgetchell/la-stack/blob/main/docs/BENCHMARKING.md). For the current release-to-release performance snapshot, see [docs/performance.md](https://github.com/acgetchell/la-stack/blob/main/docs/performance.md). -The exact release suite includes the already-exact rational-input groups for -D=2 through D=8. Those rows report `RationalMatrix::det_sign`, `det`, and -`solve` alongside straightforward `BigRational` Gaussian determinant and solve -references. Releases produced with the rational-input harness include Criterion -point estimates and confidence intervals for these rows; comparisons against a -pre-API baseline retain them as explicit current-only measurements. +The exact release selection includes rational-input groups for D=2 through D=8, +covering `RationalMatrix::det_sign`, `det`, and `solve` with Criterion point +estimates and confidence intervals. Comparisons against a pre-API baseline retain +supported new workloads as explicit current-only measurements. The benchmark +target also provides `BigRational` Gaussian references for optional diagnostics; +those reference timings are excluded from required release acquisition. The focused `interval` Criterion suite covers conclusive and inconclusive relative-coordinate lifted determinant signs at D=4 and the maximum supported diff --git a/SECURITY.md b/SECURITY.md index e5df3f1..2847c4f 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -123,17 +123,15 @@ and compatibility overrides live in `pyproject.toml`; `uv.lock` retains patched PyJWT 2.15.1 with its crypto dependencies and Base64URL padding fix. Validate native Semgrep scans when changing the scanner or lock. -Semgrep 1.182.1 pins MCP 1.29.0, which is affected by +The Intel macOS Semgrep pin, 1.182.1, requires MCP 1.29.0, which is affected by [GHSA-84m7-p3x7-pcfv](https://github.com/advisories/GHSA-84m7-p3x7-pcfv). The root environment overrides that pin with `mcp==1.30.0`, retaining the patched 1.x API. Remove the override when a released Semgrep dependency accepts a patched MCP version. Matching OpenTelemetry API, SDK, exporter and instrumentation overrides retain the patched API without breaking scanner startup. -`just audit` and Dependabot use the root Python lockfile. -The [observed dependency graph job](https://github.com/acgetchell/la-stack/actions/runs/38871146224) -rejected Python 3.15, so dependency alerts can be stale; use -`just audit` to check the current inventory until upstream supports Python 3.15. +`just audit` checks the root Python lockfile directly, independently of GitHub's +dependency-graph ingestion and alert state. The root overrides select Python 3.15 Windows wheels. Local and hosted scans cap an unlimited Linux stack until [Semgrep #11979](https://github.com/semgrep/semgrep/issues/11979) is fixed. @@ -145,18 +143,15 @@ potentially sensitive data. Here, `Matrix::certified_error_bound` and the benchmark helper's `certified_bound` refer to numerical rounding-error bounds. They contain no credentials, cryptographic certificates, or personal information. -Alerts #171–#178 were reviewed against commit -`bd80cc05df3ebf409d8db9a471b671a5737bf0c4`: their sinks are assertion or panic -diagnostics for deterministic test and benchmark fixtures. These individual -alerts were dismissed as false positives with that rationale. Keep the query -enabled and preserve diagnostic values needed to investigate numerical failures. +Assertion and panic diagnostics for deterministic numerical fixtures can +therefore produce false positives. Keep the query enabled and preserve +diagnostic values needed to investigate numerical failures. Review new alerts on their own data flow. ### Benchmark dependency maintenance -As of October 16, 2026, `paste` 1.0.15 enters through the development dependency -`faer` 0.24.4, via `gemm` 0.19.0 and `pulp` 0.22.3. Those are the latest -published upstream versions checked on that date. Repository-owned Rust code +In `Cargo.lock`, `paste` 1.0.15 enters through the development dependency +`faer` 0.24.4, via `gemm` 0.19.0 and `pulp` 0.22.3. Repository-owned Rust code already uses `pastey`; changing that direct dependency cannot replace upstream uses of `paste`. diff --git a/docs/BENCHMARKING.md b/docs/BENCHMARKING.md index eaa7ac5..bb73cf4 100644 --- a/docs/BENCHMARKING.md +++ b/docs/BENCHMARKING.md @@ -110,7 +110,7 @@ for diagnostics. ### Release acquisition policy -The `public-release-and-paired-lu-peers-v4` policy extends #301 with column bases, +The `public-release-and-paired-lu-peers-v4` policy includes column bases, interval division/solves, rational dot products, and polynomial determinants. The full la-stack selection has 736 default-feature and 667 exact-feature cases. Local `performance-release`, `performance-local`, and full `performance-measure` @@ -177,7 +177,7 @@ implementation diagnostics and exponent-spread studies remain opt-in. Use Routine release acquisition excludes them. The README retains its existing eight-dimension LU graph; no additional performance page or graph is produced. -The [v0.5.3 workload review](dev/benchmark-workload-review.md) maps required, +The [archived workload review](archive/development/benchmark-workload-review.md) maps required, optional and excluded measurements to caller costs, numerical regimes and oracles. Astra accepted its no-removal conclusion and recommended a paired LU suite with current-phase peer comparisons for the availability migration. @@ -194,10 +194,8 @@ status in ignored `target/bench-reports/full/runtime.txt`, including failures. The timer starts after Just's prerequisite checks. Use `time just performance-release` to include those checks in an end-to-end command measurement. Keep these records and the terminal log with the exact command, revisions, toolchain, dependencies and -host when comparing actual before/after runtime. The former 1,422-case run had -a nominal 189.6-minute budget; that calculation supplies no observed elapsed -time. Expanded public coverage means removing peers alone establishes no overall -speedup. No end-to-end acquisition has been timed for the expanded policy. +host when comparing actual before/after runtime. Nominal budgets are not observed +elapsed times; changing the selection alone establishes no measured speedup. `performance-release` uses the installed shared progress reporter. Its optional arguments select output mode and heartbeat seconds: @@ -215,9 +213,8 @@ diagnostics. Captured logs need no TTY. Counts advance only after phase validati partial output files do not count. ETA stays unknown for unseen work, and neither an estimate nor the nominal budget is a timeout. Scheduled progress reports trial, suite and phase state, with eight nominal seconds per case. -The published v0.2.7 tooling fixes the gate-failure event defect recorded in the -review. Preserve the command's nonzero exit and runtime record when diagnosing -failure. +Preserve the command's nonzero exit, captured logs, and runtime record when +diagnosing failure. Retry a failed report promotion with `just performance-promote`, or README publication with `just performance-readme`. Neither reacquires samples. @@ -385,8 +382,8 @@ just performance-local This compares the current working tree with the latest stable GitHub release. The shared snapshot includes tracked changes and nonignored untracked regular -files, and rechecks them before publishing measurement outputs. This replaces -the former tracked-only snapshot policy. Keep generated files under ignored +files, and rechecks them before publishing measurement outputs. Keep generated +files under ignored `target/`; symlinks, junctions and submodules are outside this snapshot contract. Both sources use the captured current harness, dependency lock and toolchain. @@ -437,10 +434,8 @@ just performance-measure "$CURRENT_TAG" "$PREVIOUS_TAG" non-exact ``` Use `performance-local*` for working-tree changes against the latest release. -The old positional labels on `performance-local-non-exact` and the local -`--suite`/`--scope` adapter flags are retired. Full and non-exact selection now -uses named declarations. To include an open-ended report selection, maintain a -named measurement declaration using the shared `series.select` contract; +Full and non-exact selection uses named declarations. To include an open-ended +report selection, maintain a named declaration using the shared `series.select` contract; selection never weakens complete sampling or the independent required inventory. ### Iterate Against A Local Saved Baseline @@ -519,8 +514,7 @@ The optional non-exact diagnostic supports 32 views: `det_from_lu`, `solve_from_lu`, declared under `tooling/plots/non-exact/`. Scratch views consume the full scratch pair; retained views work after scratch cleanup. Non-exact views consume the non-exact scratch pair and use separate -`vs_linalg_non_exact_*` output paths. The old separate metric/statistic, -`sample=new` and boolean log arguments are replaced by this named view. +`vs_linalg_non_exact_*` output paths. There is no implicit input fallback. Plots preserve scientific coordinates, nanoseconds, the selected statistic @@ -574,20 +568,17 @@ fails `performance-promote`; it never triggers a retained-history fallback. The completed v0.5.1/v0.5.0 run used the former broad-peer declaration. It stays frozen under that identity and needs no rerun. Current renderers reject it as -input to the new acquisition policy; they become available for new matching -complete runs after acquisition and promotion. Removing scratch evidence never +input to the current acquisition policy; rendering requires a matching complete +run after acquisition and promotion. Removing scratch evidence never selects or relabels a historical run automatically. Historical reports, plots, CSV/JSON, indexes and immutable complete runs keep -their original bytes and links during this migration. The existing -v0.5.0/v0.4.6 comparison lacks the newer acquisition declaration and is now a +their original bytes and links. The v0.5.0/v0.4.6 comparison lacks the newer +acquisition declaration and is a frozen record, with no regeneration requirement. Current publication checks must not be relaxed and missing provenance must not be invented to replay it. -Future runs acquired with the current declarations support offline rendering. - -The metadata-free `performance-github-assets` command and historical benchmark -execution compatibility remain retired. Published release assets remain -downloadable as original records. +Runs acquired with the current declarations support offline rendering. +Published release assets remain downloadable as original records. ## Output Locations @@ -758,11 +749,10 @@ The [solve finalization decision](archive/performance/studies/solve-finalization why #234 retained the existing result construction after testing all eight README dimensions. It links the regression tests and current benchmark command. -Release-signal reports compare latest la-stack measurements against a saved -la-stack baseline, and show saved nalgebra/faer baseline timings as context -where a matching peer benchmark exists. That keeps iteration cheap while still -making the release signal auditable. The full `vs_linalg` run remains the source -of README plots and crate-to-crate comparison tables. +Optional saved-baseline reports compare local la-stack measurements against +saved samples and can show saved peer timings as context. They do not satisfy +release acquisition. README plots and comparison tables consume the complete +release plan's paired LU suite, using current-phase nalgebra/faer observations. ## Exact-Arithmetic Notes @@ -839,20 +829,6 @@ cargo test --locked --release --features bench,exact \ The counting allocator is not linked into Criterion timing executables. -The local performance audit on 2026-09-05 retained two exact-arithmetic -optimizations: strict conversion uses the existing proof that rational vectors -are canonical, and dense exact D=4 determinants share six lower-row minors. -Matching before/after runs supported both changes. LU loop-expansion and -combined-check prototypes were removed after failing performance acceptance -across the required dimensions. - -Those experiments used Rust 1.98.0 on an Apple M4 Max / AArch64 with Criterion -0.8.2, 50 samples, one-second warm-up, and three-second measurement. Correctness -gates ran before timing. The benchmarks above remain runnable with the current -toolchain; historical timing estimates, source fingerprints, and discarded -prototypes are optional local analysis artifacts rather than prerequisites for -building, testing, or benchmarking the crate. - The f64-input random-corpus and adversarial groups run the same exact-arithmetic benches (`det_sign_exact`, `det_exact`, `solve_exact`, `solve_exact_f64_result`, `solve_exact_rounded_f64`) so tables are comparable @@ -907,8 +883,7 @@ not have comparable full-corpus rows, so those rows appear once both sides of a comparison provide the stable group. For a current snapshot without a saved baseline, use Criterion’s native reports -under `target/criterion/`. The retired `bench-compare --snapshot` command is no -longer provided. +under `target/criterion/`. ## Release Notes diff --git a/docs/MEASURING_COVERAGE.md b/docs/MEASURING_COVERAGE.md index d7f1d7d..6ef0e54 100644 --- a/docs/MEASURING_COVERAGE.md +++ b/docs/MEASURING_COVERAGE.md @@ -53,7 +53,7 @@ reports, uploads the Cobertura and JUnit files to Codecov, and archives each report directory as a workflow artifact. Local setup via `just setup-tools` installs the same Rust component and cargo subcommands. -## Migration Notes +## Coverage policy - Keep `just coverage-ci` as the single source of truth for CI coverage arguments; workflows should install tools and upload artifacts, not duplicate diff --git a/docs/RELEASING.md b/docs/RELEASING.md index e112c4e..e6052b0 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -115,11 +115,8 @@ constraints used by the installed verifier. See GitHub's The common Step 1/Step 2 flow follows the [research-repo-tools v0.2.8 guide](https://github.com/acgetchell/research-repo-tools/blob/v0.2.8/docs/RELEASING.md). -Draft preparation uses the public capability from upstream -[PR #207](https://github.com/acgetchell/research-repo-tools/pull/207), supplied in -v0.2.7 along with receipt retrieval from -[PR #209](https://github.com/acgetchell/research-repo-tools/pull/209). Published-package release checks and final native adoption -remain required by [#333](https://github.com/acgetchell/la-stack/issues/333). +Draft preparation and authenticated receipt retrieval use the installed shared +API. Release boundaries require published tooling and successful native evidence. | Command | Common behavior and la-stack declaration | | --- | --- | @@ -319,7 +316,7 @@ These commands acquire measurements. Shared status reports the active native stage, validated counts, elapsed time and an ETA only when its observations support one. Five-minute heartbeats do not limit native command runtime. The [benchmark guide](BENCHMARKING.md#release-acquisition-policy) explains -unknown budgets/estimates and the pinned supplier's gate-failure event limitation. +unknown budgets and estimates. The shell runtime record still retains the final duration and exit status. After acquisition succeeds, retry report promotion with `just performance-promote` and README publication separately; neither retry performs measurements. @@ -330,10 +327,9 @@ to refresh tags explicitly. This separate command remains useful for inspecting inputs before acquisition. Restore a lost original preparation from its independent owner record; never derive replacement assertions from a candidate. The shared preparation record also binds the package version and measurement -declaration. If you have an old adapter-format `release-inputs.json`, remove -that ignored scratch file once and prepare again. It is deliberately not -converted from measurement evidence. Moved refs or changed package/declaration -inputs require a new preparation before measurement or README publication. +declaration. Moved refs or changed package/declaration inputs require a new +preparation before measurement or README publication. Preserve the original +owner record and retained evidence when diagnosing a later release-stage failure. Fresh acquisition refuses an existing checkpoint before preparation. Resume explicitly reuses the original preparation and checkpoint: @@ -354,10 +350,8 @@ explicitly use `just performance-capture "$OWNER" --retained-scratch` while you still control the original acquisition. Then retry promotion and README rendering directly. Never treat incoming candidate files as owner assertions. -No shell variables or exports are needed. `performance-prepare` does not set -`PREVIOUS_TAG`, `CURRENT_COMMIT`, or `PREVIOUS_COMMIT` in your shell; those -variables may remain unset. Do not run the old manual `git rev-parse` -assignments or pass those variables to the ordinary README step below. +The ordinary README step consumes the retained preparation; no additional +source-selection shell variables or exports are needed. Review `docs/performance.md` and the complete new run and index changes under `docs/performance-runs/`. Its current/baseline @@ -538,12 +532,10 @@ If main-push evidence needs renewal, rerun every job in the original run and explicitly review a new selection. Manual CI dispatch cannot supply release evidence. Pending, failed, cancelled or expired evidence blocks publication. -### 3. Create and verify the annotated tag +### 3. Create the annotated tag ```bash just tag "$TAG" -git --no-pager tag -l --format='%(contents)' "$TAG" -test "$(git --no-pager rev-parse "$TAG^{commit}")" = "$(git --no-pager rev-parse HEAD)" ``` `just tag` first runs `release-version-check` and revalidates the existing reviewed @@ -553,7 +545,7 @@ section. For a changelog larger than 125 kB, it links that section. ### 4. Push the tag -Only after evidence verification and tag inspection succeed, push the tag. +After `just tag` succeeds, push the tag. This starts `Prepare GitHub release`; pushing does not wait for or verify CI. ```bash @@ -703,8 +695,10 @@ cargo check --locked --manifest-path "$CONSUMER/Cargo.toml" Use a disposable shell for this check. Preserve the output and record the tag, commit, benchmark run, publishing run, registry URL/checksum and consumer results -in the current release's tracking issue or merged release PR. Keep any release -tracking issue open until publication and consumer verification succeed. +in the current release's tracking issue or merged release PR. Close the release +tracker when its agreed validation boundary is satisfied. If a maintainer accepts +an unresolved verification failure, record the failed or unperformed check and +link its follow-up issue explicitly; do not mark it passed or silently drop it. Hosted jobs restore no dependency caches. The checkout verifier has read-only repository permissions. Draft retrieval and attachment require write access @@ -758,6 +752,22 @@ be the same original owner record; do not copy a digest from incoming assets. ### Recovering a failed run +A failed draft, attachment, or upload step does not invalidate completed +benchmark measurements. Preserve the external owner record, preparation, +checkpoint, archive, transfer files, and workflow receipts. Do not run +`just clean` or restart acquisition to troubleshoot those later phases. + +The pinned tooling can still spend substantial time installing tools and +rechecking dependency and candidate evidence. Targeted follow-ups are tracked in +research-repo-tools [#225](https://github.com/acgetchell/research-repo-tools/issues/225), +[#232](https://github.com/acgetchell/research-repo-tools/issues/232), +[#233](https://github.com/acgetchell/research-repo-tools/issues/233), +[#234](https://github.com/acgetchell/research-repo-tools/issues/234), and +[#235](https://github.com/acgetchell/research-repo-tools/issues/235). +These are not capabilities supplied by the current pin. Inspect the failed stage +and its retained records before choosing the specific recovery below. An +unconfirmed write outcome requires provider inspection before retrying. + If HEAD changes, return to Step 2's synchronization and exact-commit verification. If a native run/attempt changes, explicitly review a new named selection as described below. Missing, expired, PR, dispatch or partial-rerun evidence never @@ -870,9 +880,7 @@ automatic approval so these changes require maintainer review. Do not add a long-lived `CARGO_REGISTRY_TOKEN` secret. -Workflow YAML and settings payloads do not apply account configuration. The initial -Trusted Publishing rollout and verified v0.5.0 publication are recorded in -[#259](https://github.com/acgetchell/la-stack/issues/259). Before each release, +Workflow YAML and settings payloads do not apply account configuration. Before each release, verify the actual crates.io publisher identity and GitHub environment reviewers/tag policy, allowlist and permissions. Record that evidence in the current release's tracking issue or release PR. Re-read live settings before changing them. diff --git a/docs/archive/development/README.md b/docs/archive/development/README.md new file mode 100644 index 0000000..c2a47ce --- /dev/null +++ b/docs/archive/development/README.md @@ -0,0 +1,11 @@ +# Development review archive + +These records preserve decisions, source identities, validation results, and +limitations from release-tooling development. Their pending tasks and supplier +pins are historical, not current operating instructions. + +- [Benchmark candidate and resume review](benchmark-candidate-review.md) +- [Release benchmark workload review](benchmark-workload-review.md) + +Use [Benchmarking](../../BENCHMARKING.md), [Releasing](../../RELEASING.md), and +the [tooling guide](../../../tooling/README.md) for current procedures. diff --git a/docs/dev/benchmark-candidate-review.md b/docs/archive/development/benchmark-candidate-review.md similarity index 98% rename from docs/dev/benchmark-candidate-review.md rename to docs/archive/development/benchmark-candidate-review.md index d576f1f..85f4091 100644 --- a/docs/dev/benchmark-candidate-review.md +++ b/docs/archive/development/benchmark-candidate-review.md @@ -1,5 +1,9 @@ # Benchmark candidate and resume review +Historical architecture and validation evidence. Adoption status and remaining +work below describe the reviewed revisions. The current operational procedure +belongs to [Releasing](../../RELEASING.md). + Independent Astra architecture checkpoint on 2026-11-07 for [#325](https://github.com/acgetchell/la-stack/issues/325) and [#323](https://github.com/acgetchell/la-stack/issues/323), requested by the @@ -164,7 +168,7 @@ and example validation, native gates and final package evidence. ## Release ordering and trust The following is the reviewed target design; it is not yet executable guidance. -The [release guide](../RELEASING.md) remains the operational owner. +The [release guide](../../RELEASING.md) remains the operational owner. 1. Finish versions, dependency pins, lockfiles, source, harness, commands and output declarations before Step 1. Any subsequent non-output tree change diff --git a/docs/dev/benchmark-workload-review.md b/docs/archive/development/benchmark-workload-review.md similarity index 97% rename from docs/dev/benchmark-workload-review.md rename to docs/archive/development/benchmark-workload-review.md index 093b4cd..afbfaa2 100644 --- a/docs/dev/benchmark-workload-review.md +++ b/docs/archive/development/benchmark-workload-review.md @@ -1,5 +1,10 @@ # Release benchmark workload review +Historical review and development-pin validation evidence. Pending work and +supplier limitations below describe the reviewed revisions. For current commands +and policy, use [Benchmarking](../../BENCHMARKING.md) and +[Releasing](../../RELEASING.md). + Consumer review for [#322](https://github.com/acgetchell/la-stack/issues/322), with availability and progress integration findings for [#320](https://github.com/acgetchell/la-stack/issues/320) and @@ -24,7 +29,7 @@ Initial review on 2026-11-05 at source Retain all 1,403 current library cases: 736 default and 667 exact. No workload removal or sampling reduction is proposed. The exact required IDs remain in -[`performance-policy.toml`](../../tooling/performance-policy.toml); this review +[`performance-policy.toml`](../../../tooling/performance-policy.toml); this review explains their coverage rather than introducing another selection mechanism. The full native catalog remains available for explicit diagnostics. @@ -40,7 +45,7 @@ That review accepts scientific coverage, not minimality or measured runtime. Each row below is required in the current release selection. Construction and conversion stay timed when they are part of the named public operation. Fixture generation and independent oracle evaluation stay outside timing. The native -targets and filters are owned by [`performance.just`](../../tooling/performance.just). +targets and filters are owned by [`performance.just`](../../../tooling/performance.just). | Native family / feature | Cases | Calling forms, algorithm regimes and dimensions | Independent correctness evidence | | --- | ---: | --- | --- | @@ -116,7 +121,7 @@ The initial review used **research-repo-tools 0.2.6**, resolved from PyPI. The development branch now tests exact upstream commit `055353c630604b1ae3438c1eaf534ba85e067a7e`; its unchanged 0.2.6 version label is not a published-artifact identity. Follow the -[development pin policy](../../tooling/README.md#shared-capability-adoption) +[development pin policy](../../../tooling/README.md#shared-capability-adoption) before release. On 2026-11-05 the [exact-version registry metadata](https://pypi.org/pypi/research-repo-tools/0.2.6/json) reported non-yanked wheel and source artifacts whose SHA-256 hashes match @@ -237,7 +242,7 @@ the preserved prepared-pair and baseline/current schema-5 regressions pass. Keep those regressions and adopt the supplying published release before final publication; do not add consumer event rewriting or relax gate acceptance. -See [the benchmark guide](../BENCHMARKING.md#release-acquisition-policy) for +See [the benchmark guide](../../BENCHMARKING.md#release-acquisition-policy) for commands and retry boundaries. Report/README retries consume retained evidence without measurement. Heartbeats, nominal budgets and estimates never replace raw-file, sampling, correctness or freshness validation. diff --git a/docs/code_organization.md b/docs/code_organization.md index efb29d1..1a56baa 100644 --- a/docs/code_organization.md +++ b/docs/code_organization.md @@ -155,7 +155,7 @@ construction, prepared solves, and full runtime-dispatch adapter costs; `benches/interval_solve.rs` measures 32-system batches and reports certification counts outside timing. Division and solve rows belong to default-feature release acquisition, with `tests/interval_solve.rs` providing the independent rational gate. -`benches/column_basis.rs` and `benches/rational_dot.rs` own the new rectangular +`benches/column_basis.rs` and `benches/rational_dot.rs` own the rectangular selection and exact reduction benchmarks, with analytical fixture checks before timing. Both targets belong to release acquisition in their respective feature selections. `benches/polynomial.rs` measures exact sparse determinants for coincident lifted @@ -188,7 +188,7 @@ The [justfile](../justfile) owns executable development workflows. Shared complete-inventory Python and file runners own discovery and bounded execution; repository lint policy and archive exclusions stay in the recipes and native tool configuration. The [capability inventory](../tooling/README.md#shared-capability-adoption) -records the v0.2.6 development and release-command dependency. The installed +records the shared package's development and release responsibilities. The installed CLI verifies the Semgrep scanner in the locked Python 3.15 environment. `osv-scanner.toml` owns temporary advisory-specific dependency exceptions, and @@ -206,7 +206,7 @@ package and exports verified paths for CI. Release callers disable its caches. `.github/actions-allowlist.json` owns approved action identities for local validation and updates. Historical payloads under `.github/settings/` describe live GitHub settings separately; consult the -[rollout guide](dev/MANAGING_CHANGES.md#dependabot-approval-rollout) before applying them. +[configuration guide](dev/MANAGING_CHANGES.md#dependabot-approval-configuration) before applying them. Release metadata, version checks, Markdown line checks, and Semgrep fixture validation also belong to the shared CLI. Consumer policy stays in @@ -225,7 +225,7 @@ Performance consumers use shared Criterion parsing and estimate/comparison validation, digest verification, archive extraction, byte-preserving document sections, and multi-file transactions. Shared rendering produces complete-run reports, coordinate SVG, timing CSV and document tables. Historical artifact -bytes and fingerprint framing remain frozen and readable directly. Published v0.2.2 +bytes and fingerprint framing remain frozen and readable directly. The shared package owns common-harness orchestration, completeness, worktrees, complete run retention, validated latest selection, and transactional report publication. Its `RunTableStyle` API owns compact README table formatting; the consumer selects @@ -235,7 +235,7 @@ Generic parsing, staging, and rollback tests belong upstream; local tests verify the scientific and retained-artifact integration boundaries. Hosted Dependabot approvals use the pinned shared -GitHub workflow; the [rollout guide](dev/MANAGING_CHANGES.md#dependabot-approval-rollout) +GitHub workflow; the [configuration guide](dev/MANAGING_CHANGES.md#dependabot-approval-configuration) owns settings and deployment verification. `tooling/criterion-inventory.toml` declares optional saved-baseline list commands and @@ -259,10 +259,10 @@ README ratios; the non-exact diagnostic retains broader baseline peers. Runtime commands consume the shared schemas. The root `dependency-sources.toml` declares Python/Cargo release ownership for shared dependency validation and is included in benchmark harness inputs. -The [workload review](dev/benchmark-workload-review.md) records the scientific -selection argument, supplier contract findings and remaining adoption evidence; +The [archived workload review](archive/development/benchmark-workload-review.md) records the scientific +selection argument and historical supplier contract findings; it does not replace the independent case catalog. -The [candidate review](dev/benchmark-candidate-review.md) records the independent +The [archived candidate review](archive/development/benchmark-candidate-review.md) records the independent release-ordering and trust review for resume and acquisition reuse. The release guide owns the implemented operational procedure. @@ -277,9 +277,8 @@ All views require explicit input ownership. `tooling/performance-release.toml` declares independent preparation storage and the measurement, report and README policies. Installed `performance prepare`, `release` and `readme` commands own those separately retriable phases. -The former measurement/publication implementations and root `scripts/` directory are retired. Shared public APIs own acquisition, validation and publication transactions. -`tooling/release_candidate.py` owns thin repository orchestration: immutable +`tooling/release_candidate.py` owns repository orchestration: immutable owner records outside the checkout, pre-promotion capture, named final acceptance, original archive derivation, exact draft staging and authenticated transfer. It does not implement a comparison engine, archive parser or CI verifier. @@ -291,11 +290,9 @@ checks parallel/serial validator ownership, shared setup, failure propagation and the managed compilation-cache boundary. `tests/tooling/test_release_context.py` owns automatic external owner selection, authenticated original draft-receipt retrieval and reviewed publication dispatch. -Working-tree measurements now include nonignored untracked regular files. +Working-tree measurements include nonignored untracked regular files. `tests/tooling/test_performance_workflow.py` exercises actual recipes and -scientific policy. Shared failure matrices remain upstream. The -[adoption record](dev/performance-tooling-adoption.md) records replacement -ownership and native validation gates. +scientific policy. Shared failure matrices remain upstream. Original artifacts, including the v0.5.0/v0.4.6 complete run, remain frozen without regeneration or invented acquisition records. New complete runs @@ -326,8 +323,8 @@ evidence inspection and isolated draft creation. Its authenticated inert handoff and durable journal use the installed draft API; no local creation engine exists. `tooling/draft-receipt.toml` declares the original tag-push workflow and required receipt-producing jobs/steps for the installed retrieval API. -The [integration record](dev/release-flow-integration.md) maps command/validation -ownership and records baseline timings and remaining adoption evidence. +The [integration reference](dev/release-flow-integration.md) maps command/validation +ownership, cache boundaries, and release handoffs. `.github/workflows/publish-crates.yml` consumes a second maintainer dispatch with independent canonical-asset and full acceptance assertions. It owns approval, the immutable approval receipt, explicit native-evidence renewal, revalidation @@ -350,8 +347,9 @@ live in `docs/dev/`; human setup and validation guidance lives in [Measuring coverage](MEASURING_COVERAGE.md) owns local and CI coverage execution. The generated [performance report](performance.md) records measured results; [Benchmarking](BENCHMARKING.md) owns the commands that produce and compare them. -[Local benchmark summaries](performance/README.md) owns complete versioned local -datasets. Completed optimization studies belong under +The [legacy benchmark index](performance/README.md) lists frozen local +datasets. Historical tooling decisions belong in the +[development review archive](archive/development/README.md). Completed optimization studies belong under [archived performance studies](archive/performance/studies/README.md). The [Rust 1.99 study](archive/performance/studies/rust-1.99.md) owns the compiler migration baseline and its retained measurements; it is separate from generated diff --git a/docs/dev/MANAGING_CHANGES.md b/docs/dev/MANAGING_CHANGES.md index e5c3964..4091c53 100644 --- a/docs/dev/MANAGING_CHANGES.md +++ b/docs/dev/MANAGING_CHANGES.md @@ -9,7 +9,7 @@ Operational details for the Git rules in [AGENTS.md](../../AGENTS.md). - [GitHub CLI](#github-cli) - [Issue planning](#issue-planning) - [Issue dependencies](#issue-dependencies) -- [Dependabot approval rollout](#dependabot-approval-rollout) +- [Dependabot approval configuration](#dependabot-approval-configuration) ## Git operations and branch names @@ -118,60 +118,36 @@ gh api repos/acgetchell/la-stack/issues/217/dependencies/blocked_by \ Use `-F` so the resolved numeric ID is encoded as an integer. Keep independent tasks related without inventing a blocking dependency. -## Dependabot approval rollout - -The caller in `.github/workflows/dependabot-auto-merge.yml` pins the reviewed -research-repo-tools approval workflow at -[`b972cbf`](https://github.com/acgetchell/research-repo-tools/commit/b972cbfd717319abaa68d9b1373711ad6f163294). -It replaces the owner-issued CodeRabbit request that left bot PRs without an -approving review (#258). A successful CodeRabbit status on a skipped review does -not supply approval; the provider's underlying failure to process owner commands -remains unconfirmed. The new workflow removes that approval dependency. - -The trusted base branch supplies exact ecosystem/file allowlists, including the -comparison workspace manifest. Signed Dependabot metadata, verified commits and -base merges, complete file inventories, current-head checks, and approval -deduplication belong to the shared workflow. It never checks out PR code or uses -personal tokens. `.github/dependabot.yml` continues to own dependency eligibility. -See the [shared approval contract][shared-approval]. - -[shared-approval]: https://github.com/acgetchell/research-repo-tools/blob/b972cbfd717319abaa68d9b1373711ad6f163294/docs/AUTOMATING_DEPENDABOT.md - -The settings payloads under `.github/settings/` capture the October 1, 2026 -rollout. They enable Actions approvals with read-only default permissions, add -only the metadata action and reusable workflow to the existing selected-action -allowlist, and enable stale-review dismissal in ruleset `11113227`. All six -required checks, one required approval, resolved threads, strict checks, merge -methods, and the existing bypass actor are preserved. Auto-merge and squash -merging are already enabled. Actions approval is an intentional change from the -old #258 criterion, matching the maintainer's requested MCMC approach. - -Before applying payloads later, reread current settings and reconcile intervening -changes; do not overwrite newer checks or allowlist entries with this snapshot. -The settings can then be applied with: - -```bash -gh api repos/acgetchell/la-stack/actions/permissions/workflow \ - --method PUT --input .github/settings/actions-workflow.json -gh api repos/acgetchell/la-stack/actions/permissions/selected-actions \ - --method PUT --input .github/settings/actions-selected.json -gh api repos/acgetchell/la-stack/rulesets/11113227 \ - --method PUT --input .github/settings/main-ruleset.json -``` - -Merge the caller to `main` before expecting `pull_request_target` to use it. -An old workflow rerun retains its original definition; exercise a new eligible -Dependabot event after deployment. Verify an actual `github-actions[bot]` -approval whose commit ID is the current PR head, native squash merge only after -required checks and threads pass, and continued manual review for ineligible -updates. Record PR, head, approval, workflow-run, and merge links. Installing the -Python package does not deploy or configure this GitHub workflow. +## Dependabot approval configuration + +The [caller workflow](../../.github/workflows/dependabot-auto-merge.yml) owns the +reviewed research-repo-tools workflow pin and exact ecosystem/file allowlists. +The shared workflow verifies signed Dependabot metadata, commits, base merges, +complete file inventories, and the current head before approving. It never +checks out PR code or uses personal tokens. +[Dependency configuration](../../.github/dependabot.yml) owns update eligibility. + +GitHub must allow Actions to approve PRs and permit the caller's pinned action +and reusable workflow. Required reviews, status checks, resolved threads, and +stale-review dismissal still gate native auto-merge. A successful CodeRabbit +status on a skipped review does not itself supply an approving review. +Installing the Python package does not deploy or configure this workflow. + +The payloads under `.github/settings/` are historical snapshots, not live state. +Before applying settings, reread the repository's workflow permissions, selected +actions, and active branch rulesets. Reconcile the intended change against those +live responses; preserve newer required checks, allowlist entries, and review +policy. Do not replay a snapshot against a hardcoded ruleset ID. + +After a workflow change reaches `main`, exercise a new eligible Dependabot +event. Rerunning an old job retains its original workflow definition. Verify an +actual `github-actions[bot]` approval at the current PR head and a merge only +after required checks and threads pass. Ineligible updates retain manual review. +Record the PR, head, approval, workflow-run, and merge links. Merges using `GITHUB_TOKEN` may not trigger push workflows. A manual `ci.yml` dispatch against `main` can diagnose the merged commit, but cannot produce release-eligible signed evidence. Before selecting a release commit, require a successful main-push run as described in [Releasing](../RELEASING.md#reusable-ci-evidence). The CI signer and crates.io publishing workflows require manual dependency review. -Remove `CODERABBIT_REVIEW_TOKEN` from Actions -and Dependabot secrets only after the old caller has been replaced and no other -workflow consumes it. Local opt-in CodeRabbit CLI review remains separate. +Local opt-in CodeRabbit CLI review remains separate. diff --git a/docs/dev/performance-tooling-adoption.md b/docs/dev/performance-tooling-adoption.md deleted file mode 100644 index cd4fb7d..0000000 --- a/docs/dev/performance-tooling-adoption.md +++ /dev/null @@ -1,197 +0,0 @@ -# Performance tooling adoption - -[#296](https://github.com/acgetchell/la-stack/issues/296) completes the shared -performance-tooling migration begun in #276 and #285. The consumer retains -scientific declarations, native correctness gates, and installed-package -integration tests. Generic execution, validation, rendering, and publication -belong to research-repo-tools. - -## Publication boundary - -For la-stack v0.5.2, the development and release workflows pinned the -published `research-repo-tools==0.2.4` package. The suite verification, -packaging and assembly commands adopted for -[#316](https://github.com/acgetchell/la-stack/issues/316), targeting v0.5.2, -used that release as well. That adoption used the verified shared tool -updater and a temporary scanner-selection override to keep Semgrep on -Python 3.15. The [current tooling guide](../../tooling/README.md) records the -active pin and scanner setup. -Upstream [#123](https://github.com/acgetchell/research-repo-tools/pull/123) -adds trusted main-validation artifact reuse for release promotion; v0.2.3 -was published from commit `4085125526e21b2855eb7c61a52ee312782ae31a`. -It also refreshes explicitly declared independent Python projects while -preserving their selectors, exact pins, overrides, and separate environments. -The minimum-release acquisition contract introduced by v0.2.2 remains in place: -v0.2.1 could not express the consumer's v0.5.0 measurement floor. - -[PyPI v0.2.4](https://pypi.org/project/research-repo-tools/0.2.4/) supplies both -distributions. Their SHA-256 hashes match the published -[GitHub release assets](https://github.com/acgetchell/research-repo-tools/releases/tag/v0.2.4) -and the exact registry lock entries: - -| Distribution | SHA-256 | -| --- | --- | -| Wheel | `00aaab2b7efd680d79324c6debb64db4d8d1ff076a460ff46e24e0ef1c24bd7d` | -| Source distribution | `30b6d4d2f8d0cb98d5311656928dd65800088b651dd6c0c29f9a02526e9e902a` | - -Runtime imports and acceptance checks used the installed release. Benchmark -execution, validation and publication used the public shared APIs. - -The maintainer approved freezing earlier evidence instead of extending the -shared policy gate to accept missing acquisition declarations. This deliberately -supersedes #296's original v0.5.0/v0.4.6 replay requirement. The minimum release -applies to new acquisition; it does not redefine eligibility of already -declared complete runs. - -## Entry-point replacements - -The root Justfile calls the installed CLI directly. Static TOML describes -measurement and publication; the native Justfile contains Cargo commands. -There are no replacement Python wrappers, runtime configuration generators, -or shell implementations of the shared workflow. - -| Consumer command | Installed owner and declaration | -| --- | --- | -| `performance-local` | `performance measure`, `measurements/full.toml`, current versus latest published release | -| `performance-local-non-exact` | `performance measure`, `measurements/non-exact.toml`, current versus latest published release | -| `performance-measure` | Explicit current/baseline labels and a named full/non-exact declaration | -| `performance-prepare` | `performance prepare` with `performance-release.toml`; independent saved assertions | -| `performance-release` | `performance release` with `performance-release.toml`; measure the prepared pair and promote | -| `performance-promote` | Explicit scratch payload and envelope, checked against `performance-report.toml` | -| `performance-doc` | Offline retained history through `performance promote` and the independent full policy | -| `performance-readme` | `performance readme` with `performance-release.toml`, prepared or explicit independent identities and transactional formatting | -| `plot-vs-linalg` | `performance publish --artifacts-only` with named full scratch, retained, or non-exact scratch views | -| `bench-release-check` | `performance verify-saved` with saved name, Criterion directory and `criterion-saved.toml` | -| `bench-release-check-suite` | `performance verify-saved --suite` with the complete independent policy and selected feature suite | -| Hosted suite packaging and assembly | `performance host`, `pack-suite` and `assemble-suites`; la-stack retains the native commands, matrix, artifact selection and budgets | -| `bench-compare` | Existing installed saved-Criterion comparison CLI | - -Paths in the table are relative to `tooling/`. - -### Release adapter migration - -Published `research-repo-tools==0.2.4` now owns the former -`release_changelog.py`, `release_evidence.py` and `release_performance.py` -adapters. Citation dates are declarative in `pyproject.toml`; evidence, draft -assets and performance phases have dedicated TOML policies. The native Just -launchers observe checkout identity and forward arguments to the installed -commands. Evidence and asset verification use an isolated runtime outside the -checkout. Privileged benchmark jobs retain their existing installed asset -commands and captured target without checking out or executing repository code. - -The upstream installed-consumer suites -[`public_evidence_consumer.py`](https://github.com/acgetchell/research-repo-tools/blob/v0.2.4/tests/releases/public_evidence_consumer.py) -and -[`public_dates_consumer.py`](https://github.com/acgetchell/research-repo-tools/blob/v0.2.4/tests/changelog/public_dates_consumer.py) -own generic output rollback, immutable handoffs, malformed metadata, signature -and date parsing regressions. Local tests retain the actual native/Cargo policy, -workflow approval barriers, real Just output transport, installed runtime -identity, stale preparation rejection and scientific publication fixtures. -The shared downloader's archive bound is 32 MiB; signed manifests remain -bounded at 1 MiB. Recovery uses the shared selection schema; legacy preparation -files must be replaced through a new independent preparation. -[Benchmarking](../BENCHMARKING.md) owns arguments and examples. - -## Consumer contracts - -- Both acquisition labels must be v0.5.0 or newer. The published parser rejects - older labels before Git mutations or measurement output. -- Independent scientific catalogs require 417 full-report IDs. The non-exact - declaration selects the comparison suite. Native discovery may capture - additional diagnostic cases without weakening required coverage. -- Every phase retains 100 samples, mean and median estimates, 95% intervals, - nanoseconds, and the exact discovered inventory. Both native scientific gates - run before collection. -- nalgebra and faer references always originate in the baseline phase. - Compatibility includes host, CPU, architecture, harness, Rust/Cargo/Just, and - dependency identities. -- Measurements use the captured current harness with explicit Rust toolchain, - native host target, compiler/wrapper settings, flags, and isolated output - directories. Ambient code-generation overrides no longer silently change - the measured configuration. -- Snapshots include tracked changes and nonignored untracked regular files. - This intentionally replaces tracked-only snapshots. Source and harness - membership and bytes are checked again before README publication. -- Saved samples require the independent inventory, canonical storage paths, - matching fresh/saved raw files and complete statistical data. The configured - raw inventory remains `benchmark.json`, `estimates.json`, `sample.json`, and - `tukey.json`. -- Scratch and retained inputs are explicit choices. Incomplete scratch never - falls back to an older run. Promotion and document publication validate - independent declarations, not only a payload's self-consistency. -- All eight scientific plot metrics retain mean/median and linear/log choices, - giving 32 named views for each input source. Non-exact scratch views use - separate asset paths; official release promotion requires the full policy. - The README has one canonical - LU-solve median/log view and one shared publication section. -- README publication requires independently supplied releases and full Git - revisions, a retained run, current source/harness freshness, package/report - reference checks, tag checks, and successful formatting before any output - changes. The shared publisher emits full immutable links, so README uses - rumdl's Markdown-aware line policy; the extra raw-character gate continues - to cover other active documents. - -The minimum release, scientific rows, native commands, and publication choices -remain reviewable static consumer data. The shared engine owns their runtime -validation. `tooling/performance-policy.toml` is the independent scientific -catalog used by acceptance tests, not a local production parser. - -## Historical evidence - -Historical reports, plots, CSV/JSON, archives, and complete-run files retain -their original bytes and links. The existing v0.5.0/v0.4.6 complete run -`634bc9527c2caf0a431a9bdfac082c190e1094f0b29eb6e3f28c4b96961cdec5` -is a frozen readable record. It predates acquisition declarations and is no -longer an input for regeneration or current publication. Do not backfill its -provenance or relax the shared eligibility gate. - -New declared complete runs support offline report and plot rendering after -scratch deletion. README publication additionally requires current-source -freshness. New axis-specific plot paths preserve existing historical assets; -release metadata updates exclude immutable archive contents and their README -links. Regression hashes protect both the legacy CSV/JSON evidence and the -frozen complete run. - -## Deletion and test ownership - -The retirement removes `archive_performance.py`, `performance_runs.py`, -their adapter tests, and their obsolete measurement/plot declarations. -Useful non-performance integration tests move from `scripts/tests/` to -`tests/tooling/`. The root `scripts/` directory then has no production or -test owner. Semgrep fixtures under `tests/semgrep/scripts/` and historical -security-exception paths keep their existing identities. - -| Generic behavior | Upstream owner | Consumer evidence retained | -| --- | --- | --- | -| Floors, captured phases, complete samples and independent policy validation | `tests/performance/public_complete_consumer.py` | Actual full/non-exact declarations, release floor, scientific coverage and native commands | -| Transactional publication, formatting and provenance | `tests/publication/public_publication_consumer.py` and complete-run consumer suite | Actual recipes, stale source/harness, partial scratch, formatter failure, immutable links and frozen hashes | -| Saved-sample validation and archive transport | `tests/performance/public_performance_consumer.py` and Criterion baseline tests | Actual workflow archive, required IDs, canonical storage and saved/fresh bytes | -| Changelog, release target capture, toolchains and maintenance | Capability-specific installed-consumer suites | Existing la-stack workflow, package identity, release policy and configuration checks | - -The shared package runs public consumer suites from isolated wheel and sdist -installations. la-stack acceptance imports public APIs only and invokes the -actual Just recipes against bounded synthetic samples. No historic benchmark -reruns or new performance claims are needed. - -## Runtime and validation - -The dependency-only environment remains Python 3.15. Python supports shared -tools and consumer tests; deleting production scripts does not remove it. -Semgrep initially used a separately locked Python 3.14 environment. Following -[MCMC #214](https://github.com/acgetchell/markov-chain-monte-carlo/pull/214), -Semgrep 1.182.1 scans and fixture checks share the root Python 3.15 environment and lockfile. -The root manifest retains its native-wheel requirement, compatibility overrides -and Python 3.15 Windows wheels. Local and hosted scans retain the Linux -stack-limit workaround. Consumer tests now live under `tests/tooling/`. - -Initial migration discovery listed 533 comparison and 354 exact cases while verifying -the independent 417 required IDs. The scientific gates passed 26 exact-input -tests and 42 comparison-input tests. These checks compiled/listed the native -benchmarks without collecting timing measurements. -The expanded v0.5.2 selection and its current correctness gates are documented -in [Benchmarking](../BENCHMARKING.md#release-acquisition-policy). - -Final acceptance also requires focused installed-package tests, `just check`, -`just ci`, Markdown/spelling/docs checks, and Linux/macOS/Windows CI for the -adoption commit. Local macOS validation does not establish other native results. -Release and adoption PRs retain the source-bound validation evidence. diff --git a/docs/dev/release-flow-integration.md b/docs/dev/release-flow-integration.md index b25c73b..66e5f2e 100644 --- a/docs/dev/release-flow-integration.md +++ b/docs/dev/release-flow-integration.md @@ -1,185 +1,87 @@ # Release and validation integration -Historical implementation record for [#326](https://github.com/acgetchell/la-stack/issues/326), -[#330](https://github.com/acgetchell/la-stack/issues/330) -and [#338](https://github.com/acgetchell/la-stack/issues/338). The starting source -is `7c3a3625220773369c089e64e568a979abc0bb7f`. The authorized supplying revision is -research-repo-tools `cd8594f658b5bf3ade063a685834565cc62e0cb3` (PRs #207 and #209). -Its installed metadata remains 0.2.6; the Git commit, manifest, lock and isolated -runtime assertions distinguish this development rehearsal from publication. -The [hosted CI stages](#hosted-ci-stages) section records the subsequent published -v0.2.8 integration and workflow split in PR #343; earlier timings retain their -original source and supplier identities. - -## Workstream readiness - -[PR #335](https://github.com/acgetchell/la-stack/pull/335) merged at the starting -source above. Its Linux, macOS, Windows, Cargo packaging and static checks passed; -all six prerequisites of #326 (#320 through #325) are closed. This integration -completes the remaining #330 command/guide and automatic-draft work, plus #338's -validation graph and cache wiring. Required PR checks and review still gate merge. -Final release validation and published-tooling adoption belong to #333. - -## Release contract - -The [release command comparison](../RELEASING.md#release-command-alignment) -records the v0.2.6 reference revision, common operator commands and Cargo/benchmark -differences. The eligible final-main attempt owns native tests and default/exact -packaging. Step 2 inspects retained evidence before tagging. Tag-triggered draft -preparation uses the supplier's signed-selection and durable intent API; the -read-only job passes inert notes and evidence to an isolated writer through an -authenticated immutable artifact. Initial staging requires the authenticated -preparation target and never discovers a replacement draft. The supplier's -tag-aware receipt retrieval freezes the original provider run/attempt and artifact -before using its target. Step 1 registers one immutable external owner selection -per checkout and tag. Routine commands recover that owner and derive clean HEAD; -explicit owner/target/transfer inputs remain manual recovery options. - -Generic draft lifecycle and retry logic remain upstream. Existing owner records, -scientific workloads, raw measurements, generated reports, archive identity, -publication approval and nonbuilding Cargo upload remain separate responsibilities. -The development-pin gate still prevents acquisition for release, signed evidence -creation and publication until a published supplying package is adopted. - -## Validation graph - -Previously `ci` listed all validators sequentially. The new graph runs shared -`python-sync` and `tools-check`, then `_ci-policy`, then the two dependencies of -`[parallel] _ci-execution`. One Just invocation coalesces shared prerequisites; -there are no nested Just processes for lane orchestration. `just --jobs 1 ci` -serializes the same graph. -This uses [Just's parallel dependency scheduling](https://just.systems/man/en/parallelism.html). - -| Owner | Existing validators retained | -| --- | --- | -| Shared setup | `python-sync`, `tools-check`, their prerequisite checks | -| `_ci-policy` | `action-lint`, `workflow-allowlist-check`, `zizmor`, Markdown/spelling, private nonfinal version check, changelog, TOML, YAML, citation, JSON, Just formatting, Python static checks, Cargo lock/formatting, Semgrep/fixtures, unused dependencies, shell checks | -| `_ci-rust` | `clippy-all-targets`, `doc-check`, `test-rust-ci`, `test-doc`, `test-doc-exact`, `bench-compile`, `test-bench-exact`, `examples` | -| Parallel Python lane | `test-python`, with explicit `--no-sync` after shared setup | -| Separate main-CI packaging job | `publish-check` (formerly recipe `release-package`); hosted job and step names remain unchanged | -| Explicit acquisition | No timing recipe joins validation; benchmark collection remains opt-in and isolated | - -All root Cargo output users stay sequential. Python consumer fixture workspaces -remain isolated. No source, installed-distribution or fresh-setup matrix is -invented for this private dependency-only Python environment. There was no -consumer fresh-install smoke job to remove. Existing native Linux/macOS/Windows -`build` jobs, `Run CI checks`, `release-package`, its packaging step, signer -dependencies and signer steps remain unchanged, so evidence policy and required -check names require no migration. - -`tests/tooling/test_validation_graph.py` executes the real graph with inert -validator bodies. It requires identical complete coverage and one setup in -parallel and serial modes, proves lane overlap, and injects failures before and -inside each lane. The native scientific tests and package checks still run -through the owning recipes; graph fixtures do not replace them. +This reference maps validation, cache, and release-handoff ownership. +[CONTRIBUTING.md](../../CONTRIBUTING.md#validation-workflow) owns validator +selection; [Releasing](../RELEASING.md) owns the operator procedure. +The [justfile](../../justfile) and [CI workflow](../../.github/workflows/ci.yml) +are the executable authorities. -## Managed compilation cache +## Local validation graph -The supplying package owns the local Cargo build-cache implementation and exact -tool installation verification. Ordinary CI's existing setup action now caches -only `RUNNER_TEMP/rrt-cargo-build`, supplied through the documented absolute -`RESEARCH_REPO_TOOLS_CARGO_BUILD_HOME` override. Exact-version installation homes -under `RUNNER_TEMP/rrt` are separate and freshly verified. Cache keys include OS, -architecture, Rust toolchain, Python/tool declarations and both locks, without -broad restore prefixes. GitHub's branch/PR cache scopes remain in force; PR -entries cannot replace protected main entries. No remote cache crosses those -provider boundaries. This is compilation reuse, not validation reuse. +`just ci` runs shared `python-sync` and `tools-check`, then `_ci-policy`, +then the parallel `_ci-rust` and `test-python` lanes. One Just invocation +coalesces shared prerequisites. `just --jobs 1 ci` serializes the same graph. -Release packaging, preparation, evidence signing, benchmark attachment and Cargo -publication keep caches disabled. No compiler flags, scientific inputs or -benchmark directories change. +| Owner | Responsibility | +| --- | --- | +| Shared setup | Locked Python synchronization and declared tool verification | +| `_ci-policy` | Workflow, Markdown/spelling, version/changelog, TOML/YAML/CFF/JSON, Just, Python static, Cargo lock/format, Semgrep/fixtures, unused-dependency and shell checks | +| `_ci-rust` | Clippy, default/exact rustdoc and doctests, native Rust tests, benchmark compilation, exact benchmark test mode and examples | +| `test-python` | Complete Python consumer suite, isolated from root Cargo output | +| `publish-check` | Separate default/exact Cargo package validation | +| Acquisition | Explicit benchmark collection; never a dependency of validation | + +Root Cargo output users remain sequential. Python fixture workspaces use +isolated storage. `tests/tooling/test_validation_graph.py` checks complete +validator coverage, shared setup, lane overlap, and failure propagation in +parallel and serial modes. These graph fixtures do not replace native checks. ## Hosted CI stages -PR #343 separates hosted validation while retaining the complete local `just ci` -graph. Each preparation job installs the declared tools through RRT and completes -the same policy validators. Its successful completion saves managed compilation -outputs. After all three preparation jobs succeed, native jobs start independently -and install verified tools using that compilation cache. Installation homes, -project outputs and validation results are never shared between these jobs. -A cache miss may rebuild tools; it cannot skip checks or satisfy provenance. +Preparation jobs complete policy checks on Linux, macOS, and Windows. After +all preparation jobs succeed, independent native jobs run on each OS. -| Hosted owner, on each native OS | Canonical command and complete responsibility | +| Hosted owner | Canonical command and responsibility | | --- | --- | -| `prepare (OS)` | RRT setup, then `just ci-policy`: every `_ci-policy` validator and shared setup check listed above | -| `native-rust (OS)` | `just ci-rust`: the complete sequential `_ci-rust` lane, including compilation, tests, docs, examples and benchmark validation | -| `native-python (OS)` | `just ci-python`: every Python test without the `release_candidate` marker, using four workers | -| `native-candidate (OS)` | `just ci-candidate`: the complete candidate capture/acceptance regression, using one worker on a dedicated runner | +| `prepare (OS)` | Tool setup, then `just ci-policy` | +| `native-rust (OS)` | `just ci-rust`: the complete sequential Rust lane | +| `native-python (OS)` | `just ci-python`: Python tests without the `release_candidate` marker, using four workers | +| `native-candidate (OS)` | `just ci-candidate`: candidate capture/acceptance tests, using one worker | | `native-dependencies (OS)` | `just ci-dependencies`: locked Cargo fetch, native build receipts and dependency-provenance verification | -| `build (OS)` | Required-check name preserved on a lightweight Linux gate; rejects any failed, skipped, cancelled or absent preparation/native result | -| `release-package` | Independent uncached dependency verification and default/exact Cargo package validation | -| `release-evidence` | Protected main-push signer; requires all aggregate gates and packaging, then verifies every actual native job, required step and OS label | - -`tests/tooling/test_validation_graph.py` collects the real pytest suite under both -hosted selections and requires a disjoint, complete partition. Local `just ci` -still selects the full Python suite once. Gate regressions execute the workflow's -actual shell for success, failure, skipped, cancelled and missing results. -Release-evidence regressions reject incomplete steps in every native stage. -Scientific fixtures, assertions and benchmark sampling policy are unchanged. - -The preceding monolithic run at `1548f59`, -[42858660611](https://github.com/acgetchell/la-stack/actions/runs/42858660611), -passed Linux, macOS and uncached packaging. Windows spent about 51 minutes in -setup and 62 minutes in `just ci`, including 465 passing Python tests, before -its two-hour limit interrupted Cargo provenance verification. Python tests took -3,632.39 seconds; candidate acceptance alone took 1,783.31 seconds plus its fixture -setup. These observations motivate resource separation; they do not establish a -speedup. Native timing and cache-hit evidence for the split workflow must be -reconciled on its final source revision. - -## Timing evidence and limits - -Baseline native data comes from successful main-push -[CI run 42443172694, attempt 1](https://github.com/acgetchell/la-stack/actions/runs/42443172694/attempts/1) -on the starting source. Durations below use API job/step timestamps and are -descriptive wall time, not benchmark results or a cold/warm comparison. - -| Job | Queue from run start | Tool setup | CI or packaging step | Total job wall time | -| --- | --- | --- | --- | --- | -| Linux build | 3 s | 23 m 51 s | 26 m 27 s | 50 m 40 s | -| macOS build | 4 s | 41 m 59 s | 36 m 27 s | 80 m 35 s | -| Windows build | 3 s | 1 m 49 s | 62 m 18 s | 66 m 57 s | -| Release packaging | 3 s | 21 m 23 s | 4 s | 21 m 35 s | -| Evidence job | Waited for native jobs | — | Development-pin signing/upload skipped | 14 s | - -The complete workflow occupied 80 m 56 s from creation to completion. The four -build/package job intervals total 219 m 47 s of runner wall time; this is distinct -from critical-path duration and excludes provider billing/rounding. Setup cache -hit state was not established, so none of these observations is labelled cold -or warm. The evidence job's success does not establish signed release evidence: -its development-pin signing and artifact upload steps were skipped. - -Locally, the original `just check` graph at the new exact supplier pin completed -in 52.67 s elapsed (27.52 s user, 13.11 s system) on the existing macOS environment -before recipe restructuring. This is a warm development environment, not a clean -managed-install experiment. It is not directly comparable to full hosted CI. - -Final local validation at the supplying revision above passed on macOS 27.2, -arm64, Python 3.15 and Rust 1.99.1, using the existing development environment -and four Python test workers: - -| Command | Elapsed | User CPU | System CPU | Python suite | -| --- | --- | --- | --- | --- | -| `just --jobs 1 ci` | 905.35 s | 2,152.17 s | 365.49 s | 438 passed in 676.01 s | -| `just ci` | 736.74 s | 1,640.82 s | 340.51 s | 438 passed in 691.83 s | - -Both runs completed the same validators, including 1,143 Rust tests, default/exact -doctests, benchmark compilation, the exact harness in test mode and examples. -The serial run compiled missing targets; the later parallel run reused them. -These are descriptive observations with different compilation cache states, -not an isolated measurement of parallelism or managed-cache speedup. The long -synthetic acquisition/acceptance consumer is a remaining bottleneck: its call -alone took 525.65 s in the serial run. No scientific measurements were acquired. - -The focused owner/receipt/dispatch and graph regressions passed, including real -Just rejection of publication without prior review. Windows-targeted static -type checking and the exact lock check passed. Astra's source review found no -remaining trust-boundary blocker; it did not substitute for native validation. - -The implementation PR closes #326, #330 and #338 on merge. -[#333](https://github.com/acgetchell/la-stack/issues/333) owns final native -validation, authenticated hosted retained-evidence handoff, matched cold/warm -managed installation timings and published-tooling adoption. No speedup is -claimed from configuration, graph-fixture timing or these unmatched cache -observations. No release, tag or benchmark campaign is run as part of this -integration. +| `build (OS)` | Aggregate required-check gate; rejects failed, skipped, cancelled or missing preparation/native results | +| `release-package` | Uncached `just ci-dependencies` and `just publish-check` | +| `release-evidence` | Protected main-push signer, requiring aggregate gates and packaging and verifying actual native jobs, steps and OS labels | + +The hosted Python selections form a disjoint, complete partition of the local +suite. Required `build (OS)` names are Linux-hosted aggregate gates; native +evidence comes from the actual OS-specific jobs. Manual dispatch can diagnose a +commit but does not satisfy the main-push event requirement for release signing. + +## Managed compilation cache + +Ordinary CI caches managed Cargo compilation outputs through the absolute +`RESEARCH_REPO_TOOLS_CARGO_BUILD_HOME` override. Cache keys include OS, +architecture, Rust toolchain, tool declarations, and both locks. Exact-version +installation homes are separate and freshly verified. GitHub's cache scopes +separate PR entries from protected main entries. + +Preparation populates this cache before native jobs start. Installation homes, +project outputs, and validation results are not shared between jobs. A cache +miss may rebuild tools; a hit cannot skip checks or establish provenance. +Release packaging, evidence signing, draft preparation, benchmark attachment, +and Cargo publication disable caches. Cache configuration alone is not evidence +of a measured speedup. + +## Release handoffs + +Step 1 retains the benchmark acquisition and one immutable external owner +selection per checkout and tag. Final acceptance binds that original evidence +to the reviewed candidate. Routine commands recover the registered owner; +explicit owner, target, and transfer inputs support recovery. + +Tag-triggered preparation verifies native evidence before passing inert notes +and evidence through an authenticated artifact to an isolated draft writer. +Durable receipts identify the original provider run, attempt, artifact, and +draft target. Initial staging uses that target and never discovers a replacement +draft. Attachment consumes retained measurements without collecting new ones. + +Publication is a separate maintainer-approved operation. Its workflow rechecks +the candidate and canonical assets, retains an approval receipt, and performs +nonbuilding Cargo upload using authenticated native validation. Published +supplier tooling is required at release boundaries. + +Generic verification, draft lifecycle, and retry primitives belong to +research-repo-tools. Scientific selection, repository orchestration, and +consumer acceptance remain local. See the [tooling guide](../../tooling/README.md) +for declarations and tests, and the [development review archive](../archive/development/README.md) +for historical design evidence. diff --git a/docs/roadmap.md b/docs/roadmap.md index 10b0e21..ef10a34 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,348 +1,57 @@ # Roadmap -This roadmap records likely directions for the `la-stack` crate. It is not a -stability promise; release scope depends on mathematical correctness, API -maturity, downstream need, and validation quality. Concrete implementation work -is tracked as GitHub issues; keep this document focused on release direction, -ordering, and non-goals. - -Until v1.0, API breaks are acceptable when they improve correctness, -performance, or orthogonality. The `v0.4.x` line stays on stable Rust and includes -focused robustness APIs, downstream ergonomics, API-contract cleanup, -documentation, validation, invariant audits, benchmark coverage, and -release/tooling hardening. The current release is -[`v0.5.0`](https://github.com/acgetchell/la-stack/releases/tag/v0.5.0), published -on 2026-10-17, consolidating the work previously targeted at `v0.4.7`. -It remains on stable Rust and makes the Rust 1.99.1 minimum an -explicit downstream upgrade boundary. -Expanded const-generic work is tracked separately without an assigned release; -it depends on the specific language capabilities required by the proposed API. - -## Scalar Scope - -`la-stack` intentionally supports `f64` for floating-point APIs and exact -rationals behind the optional `"exact"` feature. This is not a temporary -implementation detail: the crate targets small, fixed-size, +This roadmap records directions for `la-stack`, not release promises. Scope +depends on mathematical correctness, API maturity, downstream need, and +validation quality. Use [open issues](https://github.com/acgetchell/la-stack/issues) +and [milestones](https://github.com/acgetchell/la-stack/milestones) for scheduled +work. [CHANGELOG.md](../CHANGELOG.md) and +[GitHub releases](https://github.com/acgetchell/la-stack/releases) own release +history and migration notes. + +Until v1.0, API breaks are acceptable when they materially improve correctness, +performance, or orthogonality. Releases remain on stable Rust; the +[Cargo manifest](../Cargo.toml) owns the minimum supported version. Version +changes and downstream migration belong to dedicated release preparation. + +## Scalar scope + +`la-stack` supports `f64` for floating-point APIs and exact rationals behind the +optional `exact` feature. The crate targets small, fixed-size, robustness-sensitive numerical and computational geometry workloads where -`f64` plus exact arithmetic is the right tradeoff. +these representations fit the required guarantees. -Other scalar families are non-goals. Users who need lower-precision `f32` / -`f16` support, throughput-oriented reduced precision, accelerator-heavy -computation, large dynamic matrices, sparse matrices, or broad decomposition +Other scalar families are non-goals. Users needing reduced precision, +accelerators, large dynamic matrices, sparse matrices, or broad decomposition coverage should use larger linear-algebra ecosystems such as `nalgebra` or `faer`. -## Release History and Next Sequence - -### v0.4.2 Stable Rust Cleanup (released) - -The `v0.4.2` milestone collected work that could be done on stable Rust while -keeping the crate useful to downstream geometry crates: - -Completed foundation work: - -- [#100](https://github.com/acgetchell/la-stack/issues/100) clarified `f64` - as the intended floating-point type in README and other documentation. -- [#109](https://github.com/acgetchell/la-stack/issues/109) added fallible - runtime matrix dispatch and contextual index errors. -- [#83](https://github.com/acgetchell/la-stack/issues/83) changed - `Matrix::set` to return `Option<()>` instead of `bool`. -- [#94](https://github.com/acgetchell/la-stack/issues/94) made tolerance - parsing explicit and consistent across the crate. -- [#82](https://github.com/acgetchell/la-stack/issues/82) unified `det()` - error behavior across all dimensions as far as stable Rust allows. -- [#120](https://github.com/acgetchell/la-stack/issues/120) completed the - parse-don't-validate `NonZero*` audit. -- [#111](https://github.com/acgetchell/la-stack/issues/111), - [#112](https://github.com/acgetchell/la-stack/issues/112), - [#113](https://github.com/acgetchell/la-stack/issues/113), and - [#117](https://github.com/acgetchell/la-stack/issues/117) cleaned up - Markdown/YAML tooling, CI speed, and shared Rust workflow/security checks. - -API-invariant cleanup: - -- [#126](https://github.com/acgetchell/la-stack/issues/126) is resolved as an - internal parse-don't-validate design rather than a public proof-bearing API. - `Matrix` and `Vector` parse raw `f64` storage at construction and then - carry the finite-entry proof directly. Crate-private finite wrappers remain - only as implementation helpers at algorithm boundaries. -- The public prelude stays focused on downstream composition: raw boundary - types, factorization handles, tolerances, crate errors, dispatch helpers, and - common defaults. Advanced determinant error-bound coefficients remain - explicit crate-root exports. Proof-bearing wrappers remain crate-private, - while the exact-arithmetic sign and integer/rational re-exports remain gated - behind the `"exact"` feature. -- Fallible raw boundaries advertise parsing explicitly: `Tolerance::try_new` - constructs validated tolerances, `Matrix::try_get` preserves index context, - and `Matrix::set` validates atomically before mutation. -- Exact determinant signs use `DeterminantSign` rather than an invalidable raw - integer. Because `Matrix` already carries the finite-entry proof and filter - range failures fall back to exact integer arithmetic, `det_sign_exact` returns - `DeterminantSign` infallibly; `as_i8` is reserved for numeric interoperability. -- The public LDLT API remains `Matrix::ldlt`. Symmetry proof storage is kept - internal and `SymmetricMatrix` is not exported. Asymmetric errors retain both - observed entries and their effective bound; negative pivots and zero pivots - with nonzero coupling use distinct `PositiveSemidefiniteViolation` values. -- The public error model keeps semantic categories typed: exact and numerical - singularity use distinct `SingularityReason` values, numerical rejection - retains its factorization/pivot/tolerance, and `NonFiniteOrigin` plus - `NonFiniteLocation` distinguish invalid inputs from arithmetic overflow. -- Strict exact-to-`f64` conversion reports `RequiresRounding` only when an - explicit rounded fallback can return a finite value; values above the - overflow-rounding midpoint report `NotFinite` consistently from strict and - rounded APIs. -- The determinant error-bound constants `ERR_COEFF_2`, `ERR_COEFF_3`, and - `ERR_COEFF_4` are documented as dimension-specific roundoff multipliers over - the absolute Leibniz sum, not caller-tuned tolerances. - -Completed release blockers: - -- [#125](https://github.com/acgetchell/la-stack/issues/125) - Add a Semgrep - guardrail against `unwrap` / `expect` in examples, benches, and doctests. -- [#98](https://github.com/acgetchell/la-stack/issues/98) - Add random-input - percentile benchmarks to the exact arithmetic suite. - -The broad shape is now: document scalar scope, add downstream dispatch -ergonomics, clean up small API contracts, tighten validation, encode reusable -invariants behind the public raw-boundary API, lock examples and benchmarks into -proper error handling, then finish with broader benchmark work. - -### v0.4.3 Benchmark and Tooling Hardening (released) - -This release tightened the benchmark and tooling story so performance claims are -auditable across releases and Python support scripts have a modern typed baseline. - -- [#137](https://github.com/acgetchell/la-stack/issues/137) - Investigate - checked vector kernel performance for v0.4.3. -- [#138](https://github.com/acgetchell/la-stack/issues/138) - Add first-class - cross-release performance comparison tooling. -- [#142](https://github.com/acgetchell/la-stack/issues/142) - Update Python - tooling to 3.13 and parse scripts at boundaries. - -Release outcome: - -- The release-signal comparison against `v0.4.2` showed broad - improvement across LU, solve, determinant-via-LU, and vector helper rows. -- Treat the remaining `D=4` direct determinant regression as a tracked - performance note rather than a release blocker because the LU-backed - determinant and solve paths improved. -- Defer `Matrix::inf_norm` optimization to follow-up work after `v0.4.3`. - Larger-dimension `vs_linalg` measurements suggest it is the most interesting - leaf-kernel target, but it is not required for the release. - -### v0.4.4 Focused Leaf-Kernel Performance (released) - -This release used the improved benchmark workflow to investigate narrow -leaf-kernel performance gaps without broadening the crate's scope or weakening -the small fixed-dimension API model. - -- [#154](https://github.com/acgetchell/la-stack/issues/154) - Investigate - `Matrix::inf_norm` performance against `nalgebra` and `faer`. -- [#155](https://github.com/acgetchell/la-stack/issues/155) - Investigate - `Vector::dot` and `Vector::norm2_sq` performance against `nalgebra` and - `faer`. -- [#174](https://github.com/acgetchell/la-stack/issues/174) - Raise the stable - Rust baseline to 1.97.0 and audit its new bit helpers. Retain the existing - primitive and `num-bigint` operations where the new helpers do not simplify - current hot paths or preserve benchmark performance. - -Release outcome: - -- `Matrix::inf_norm` moved finiteness checks off the ordinary per-cell success - path while replaying only overflowed rows to preserve exact error locations. -- `Vector::dot` and `Vector::norm2_sq` adopted the same success-path reduction - strategy while retaining left-to-right fused accumulation, `const fn` - evaluation, and typed failure metadata. -- The MSRV moved to Rust 1.97.0 after auditing the new integer bit helpers; the - existing exact-arithmetic operations remained where alternatives did not - improve clarity or preserve measured performance. -- Direct and exact determinant hot paths were restored without weakening the - numerical contracts or the fixed-size allocation model. - -### v0.4.5 Rust 1.98 Numerical Policy (released) - -This milestone completed stable-Rust maintenance without broadening the crate's -scalar or algorithm scope. - -- [#208](https://github.com/acgetchell/la-stack/issues/208) raised the MSRV and - pinned contributor/CI toolchain to Rust 1.98, audited the final stable release, - and added a repository guard against the new algebraic floating-point - operations in correctness-sensitive source, examples, and benchmarks. -- Local and release performance workflows were unified around retained, - schema-versioned CSV/JSON inputs, validated rerendering, and transactional - report promotion. -- Dependency, contributor-tool, and GitHub Action maintenance was refreshed - while preserving explicit repository ownership of update scope. +## Longer-term directions -The existing IEEE 754 operations, deterministic accumulation order, error -bounds, exact fallbacks, and typed non-finite behavior remain authoritative. -Any future approximate or fast-math API requires a separate opt-in design and -correctness analysis. - -### v0.4.6 Exact Inputs and Certified Bounds (released) - -This milestone extends robustness-sensitive workflows on stable Rust while -preserving fixed dimensions, `f64` floating-point storage, and feature-isolated -exact arithmetic. - -Completed capability work: - -- Certified dot-product and affine-difference bounds - ([#220](https://github.com/acgetchell/la-stack/issues/220)) support sign and - threshold decisions over stored coordinates, with explicit inconclusive - outcomes when a certificate is unavailable or overlaps the threshold. -- Exact rational matrix and vector inputs - ([#216](https://github.com/acgetchell/la-stack/issues/216)) preserve rational - expressions before `f64` rounding and provide exact determinants and solves - with explicit strict or rounded output conversion. -- Gram matrix construction - ([#219](https://github.com/acgetchell/la-stack/issues/219)) accepts fixed - vectors with independent const-generic input and output dimensions. The - floating-point result is symmetric but is not a definiteness certificate. -- Interval expressions and determinant signs - ([#218](https://github.com/acgetchell/la-stack/issues/218)) preserve outward - bounds through determinant evaluation up to D=7, distinguish exact zero from - inconclusive overlap, and report range exhaustion explicitly. -- Overflow-safe Euclidean norms - ([#217](https://github.com/acgetchell/la-stack/issues/217)) avoid unnecessary - overflow and underflow from squaring coordinates. Norm results remain - approximate, without a certified error bound. - -Performance and tooling outcomes: - -- Benchmark release budgets and baseline validation - ([#224](https://github.com/acgetchell/la-stack/issues/224)), attachment before - immutable publication ([#225](https://github.com/acgetchell/la-stack/issues/225)), - and cache isolation ([#226](https://github.com/acgetchell/la-stack/issues/226)) - now form one documented release workflow. -- Exact rational conversion and dense 4D determinant paths avoid redundant - arithmetic while preserving exact results and typed conversion errors. -- Rational row-clearing measurements - ([#233](https://github.com/acgetchell/la-stack/issues/233)) support retaining - the existing borrowed component access; see the - [allocation study](archive/performance/studies/rational-row-clearing.md). LU/LDLT solve - finalization remains unchanged because its proposed replacement showed no - repeatable speedup ([#234](https://github.com/acgetchell/la-stack/issues/234)); - see the [decision report](archive/performance/studies/solve-finalization.md). -- Tooling uses Rust 1.98.1 and Python 3.14, reconciles managed tool pins, rejects - ambiguous updater output, and verifies the installed Cargo upgrade tool - through its supported version command during setup. - -Intentional compatibility changes include requiring Rust 1.98.1, -`Vector::norm2_sq()` becoming `Vector::norm_squared()`, -`Matrix::inf_norm()` becoming `Matrix::norm_inf()`, -and `Matrix::solve_exact()` returning `RationalVector` instead of a raw -rational array. `Vector::norm()` names the new Euclidean norm; raw exact solution -storage remains available through `as_array()` and `into_array()`. - -Further stable-Rust maintenance can remain in `v0.4.x`; it does not depend on -expanded const-generic support. - -### v0.5.0 Stable Rust APIs and Performance (released) - -The [v0.5.0 milestone](https://github.com/acgetchell/la-stack/milestone/3) -replaced the planned `v0.4.7` release. It combined the completed Rust 1.99 -migration and stable vector-angle API with correctness-preserving performance -improvements and release-tooling adoption. Expanded const-generics stabilization -did not gate this release. - -Completed work included in this release: - -- Certified dot-product and affine-difference reductions - ([#248](https://github.com/acgetchell/la-stack/issues/248)) reduce avoidable - arithmetic and certificate overhead while preserving outward bounds, typed - failures, and exact fallback. -- Interval arithmetic and determinant signs - ([#247](https://github.com/acgetchell/la-stack/issues/247)) avoid redundant work - while retaining containment guarantees and const evaluation. -- Rust 1.99.1 and LLVM 23 - ([#251](https://github.com/acgetchell/la-stack/issues/251)) establish the new - MSRV and strict floating-point baseline, with retained correctness, codegen, - and performance evidence. -- Shared performance orchestration - ([#268](https://github.com/acgetchell/la-stack/issues/268)), complete-run reports - ([#277](https://github.com/acgetchell/la-stack/pull/277)), and opt-in review - recipes ([#253](https://github.com/acgetchell/la-stack/issues/253)) reduce local - tooling duplication while preserving scientific policy and historical evidence. -- Stable unsigned vector angles - ([#249](https://github.com/acgetchell/la-stack/issues/249)) support fixed vectors - and allocation-free borrowed coordinate slices, including extreme magnitudes - and representable subnormal angles. Results remain rounded without a certified - error bound. - -The bounded algebraic floating-point evaluation -([#250](https://github.com/acgetchell/la-stack/issues/250)) concluded with a -**retain-strict** decision on 2026-10-15. The selected matrix-norm reduction -improved local timing at D=4/5 but hid a required overflow error. The maintainer -rejected adoption and ended the remaining prototype investigation; no algebraic -API or feature is planned. The -[validation record](validation/algebraic-floating-point.md) documents the -decision, executed checks, and unperformed native Linux/Windows runs; the -[study](archive/performance/studies/algebraic-float.md) retains the raw evidence. - -The release sequence is complete: - -1. The triangular rational-solve optimization - ([#246](https://github.com/acgetchell/la-stack/issues/246), - [PR #278](https://github.com/acgetchell/la-stack/pull/278)) landed with the - exact general-system fallback and independent regression evidence. -2. The published shared-tooling capabilities were adopted - ([#276](https://github.com/acgetchell/la-stack/issues/276)), preserving the - dimension plot, scientific eligibility rules, and historical artifacts. -3. Release validation and the `v0.4.6` versus `v0.5.0` performance record completed - through the adopted workflow. The crates.io publishing workflow and publisher - settings were verified ([#259](https://github.com/acgetchell/la-stack/issues/259)). -4. The reviewed `v0.5.0` release was published and registry availability verified; - #259 closed after publication on 2026-10-17. - -Consumers using a `0.4` Cargo requirement must explicitly adopt `0.5`. -Downstream adoption retains independent correctness and performance gates. Package versions -and generated release artifacts are updated during dedicated release preparation. - -### v0.5.1 Follow-Up Work (planned) - -The [v0.5.1 milestone](https://github.com/acgetchell/la-stack/milestone/10) -holds compatible follow-up work after `v0.5.0`. The negative #250 decision -does not transfer an algebraic floating-point adoption task to this milestone. -Changes incompatible with a published `v0.5` API require an appropriate later -minor release. - -## Longer-Term Directions - -- Keep the crate focused on fixed small dimensions and stack allocation. +- Grow exact arithmetic where it strengthens robustness-sensitive workflows + without adding dependencies to the default build. +- Keep core operations focused on small fixed dimensions and stack allocation. - Preserve `const fn` surfaces where they make mathematical evaluation compile-time checkable. -- Grow exact-arithmetic support only where it strengthens robustness-sensitive - workflows without making the default build dependency-heavy. -- Use benchmarks to validate performance claims against `nalgebra` and `faer` - within the crate's intended dimensional scope. - -### Expanded Const Generics (unscheduled) +- Validate performance claims against comparable workloads within the crate's + intended dimensional scope, using the [benchmarking policy](BENCHMARKING.md). -[#123](https://github.com/acgetchell/la-stack/issues/123) tracks the determinant -API work in the [Future: expanded const generics milestone](https://github.com/acgetchell/la-stack/milestone/11). -Stable const generics already support the crate's fixed dimensions. The future -work requires richer expressions involving generic parameters and depends on -the exact capabilities needed to express dimension-specific support in types. +### Expanded const generics -The Rust project's [October 2, 2026 update](https://blog.rust-lang.org/inside-rust/2026/10/02/generic-const-args-and-you/) -describes Generic Const Arguments (GCA) as the intended replacement for -`generic_const_exprs`. None of the discussed features were ready for stabilization -at that time, and the post gives no stabilization date. Evaluate the relevant -GCA features or equivalent support independently; do not assume that one -stabilized subset will enable every proposed determinant abstraction. +[#123](https://github.com/acgetchell/la-stack/issues/123) tracks determinant API +work in the [expanded const generics milestone](https://github.com/acgetchell/la-stack/milestone/11). +Stable const generics already support the crate's fixed dimensions. Richer +dimension-specific contracts depend on the particular language capabilities +needed to express them; no stabilization date or release is assumed here. -When sufficient support is stable, revisit determinant APIs to make closed-form -dimension support explicit and reduce runtime `D` branching where that improves -caller usability. Unify direct, LU-backed, error-bound, and exact determinant -internals where justified by correctness, maintainability, and benchmark evidence. -Assign a numbered release after confirming the required capabilities, API design, -MSRV, and downstream migration. This work is not a prerequisite for v0.5.0 or v1.0. -If a redesign breaks an API already published in v1.x, it requires a major release. +Before scheduling this work, confirm that the required capabilities are stable, +evaluate the API and MSRV impact, and establish downstream migration and +benchmark evidence. Unify determinant internals only where correctness, +maintainability, and caller usability justify it. A redesign that breaks an API +published in v1.x requires a major release. -## Non-Goals +## Non-goals -- Dynamic or large matrix dimensions. -- Sparse matrices, parallel solvers, GPU acceleration, or out-of-core storage. - Alternate floating-point scalar families such as `f32` or `f16`. +- Dynamic or large matrix dimensions. - Replacing full-featured linear-algebra libraries. +- Sparse matrices, parallel solvers, GPU acceleration, or out-of-core storage. diff --git a/src/ldlt.rs b/src/ldlt.rs index 62ed057..be451ac 100644 --- a/src/ldlt.rs +++ b/src/ldlt.rs @@ -263,8 +263,8 @@ impl Ldlt { /// /// Diagonal pivots are multiplied directly while each non-zero running /// product remains finite and normal. If direct accumulation detects range - /// loss, all pivots are recomputed with power-of-two scaling before a - /// premature overflow or underflow can affect the returned determinant. + /// loss, the product is recomputed from the stored pivots with power-of-two + /// scaling; the factorization itself is not repeated. /// The final product is rounded to `f64`; a non-zero magnitude below the /// binary64 range may round to zero. No certified absolute error bound is /// provided. diff --git a/src/lu.rs b/src/lu.rs index e24092d..5a2b522 100644 --- a/src/lu.rs +++ b/src/lu.rs @@ -354,8 +354,8 @@ impl Lu { /// /// Diagonal pivots are multiplied directly while each non-zero running /// product remains finite and normal. If direct accumulation detects range - /// loss, all pivots are recomputed with power-of-two scaling before a - /// premature overflow or underflow can affect the returned determinant. + /// loss, the product is recomputed from the stored pivots with power-of-two + /// scaling; the factorization itself is not repeated. /// The final product is rounded to `f64`; a non-zero magnitude below the /// binary64 range may round to zero. No certified absolute error bound is /// provided. diff --git a/src/matrix.rs b/src/matrix.rs index bc05c6c..f5f5b3d 100644 --- a/src/matrix.rs +++ b/src/matrix.rs @@ -900,7 +900,7 @@ impl Matrix { /// /// Returns `Ok(Some(det))` for `D` ∈ {0, 1, 2, 3, 4}, `Ok(None)` for D ≥ 5. /// `D = 0` returns `Ok(Some(1.0))` (empty product). - /// This is a `const fn` (Rust 1.94+) and uses fused multiply-add (`mul_add`) + /// This is a `const fn` and uses fused multiply-add (`mul_add`) /// for improved accuracy and performance. /// /// For a determinant that works for any dimension (falling back to LU for D ≥ 5), @@ -1252,44 +1252,10 @@ impl Matrix { /// ``` /// /// # Adaptive precision pattern (requires `exact` feature) - /// ```ignore - /// use la_stack::prelude::*; - /// - /// fn adaptive_det_sign( - /// matrix: &Matrix, - /// ) -> DeterminantSign { - /// if let Ok(Some(estimate)) = matrix.det_direct_with_errbound() { - /// if estimate.determinant().abs() > estimate.absolute_error_bound() { - /// return if estimate.determinant() > 0.0 { - /// DeterminantSign::Positive - /// } else { - /// DeterminantSign::Negative - /// }; - /// } - /// } - /// - /// matrix.det_sign_exact() - /// } - /// - /// fn main() -> Result<(), LaError> { - /// assert_eq!( - /// adaptive_det_sign(&Matrix::<3>::identity()), - /// DeterminantSign::Positive - /// ); - /// - /// let big = f64::MAX / 2.0; - /// let overflowing = Matrix::<3>::try_from_rows([ - /// [0.0, 0.0, 1.0], - /// [big, 0.0, 1.0], - /// [0.0, big, 1.0], - /// ])?; - /// assert_eq!( - /// adaptive_det_sign(&overflowing), - /// DeterminantSign::Positive - /// ); - /// Ok(()) - /// } - /// ``` + /// See the [executable adaptive-filtering guide](https://docs.rs/la-stack/latest/la_stack/guide/exact/index.html#adaptive-determinant-filtering) + /// for positive, singular, and overflowing filter cases. The guide shows how + /// to retain the paired estimate and fall back to `det_sign_exact()` when + /// the floating-point bound is unavailable or inconclusive. /// /// # Errors /// Propagates [`LaError::NonFinite`] from diff --git a/tests/tooling/test_release_flow.py b/tests/tooling/test_release_flow.py index e15664b..2672d5b 100644 --- a/tests/tooling/test_release_flow.py +++ b/tests/tooling/test_release_flow.py @@ -13,6 +13,7 @@ import pytest import yaml from research_repo_tools import release_assets, release_drafts, release_evidence, release_validation +from research_repo_tools.cli import main as shared_main from research_repo_tools.just_inspect import dry_run from research_repo_tools.process import run_command @@ -24,6 +25,64 @@ WORKFLOW = ROOT / ".github/workflows/prepare-release.yml" +def test_draft_verification_handoff_uses_the_installed_cli_path_contract(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + """Run the workflow shell, then replay its evidence call with the real parser.""" + checkout, runner = tmp_path / "checkout with spaces", tmp_path / "runner temp" + (checkout / "tooling").mkdir(parents=True) + runner.mkdir() + (checkout / "Cargo.toml").write_text('[package]\nname = "la-stack"\nversion = "0.5.42"\n', encoding="utf-8", newline="\n") + policy = (ROOT / "tooling/release-evidence.toml").read_bytes() + (checkout / "tooling/release-evidence.toml").write_bytes(policy) + calls = tmp_path / "calls.jsonl" + recorder = tmp_path / "record.py" + recorder.write_text( + "import json, os, pathlib, sys\n" + 'with pathlib.Path(os.environ["FIXTURE_CALLS"]).open("a", encoding="utf-8", newline="\\n") as stream:\n' + ' stream.write(json.dumps(sys.argv[1:]) + "\\n")\n', + encoding="utf-8", + newline="\n", + ) + workflow = yaml.safe_load(WORKFLOW.read_bytes()) + step = next(step for step in workflow["jobs"]["verify"]["steps"] if step.get("id") == "source") + shell = ( + 'git() { if [[ "$2" == rev-parse ]]; then printf "%s\\n" "$GITHUB_SHA"; ' + 'else [[ "$2" == merge-base && "$3" == --is-ancestor ]]; fi; }\n' + f'uv() {{ {shlex.quote(Path(sys.executable).as_posix())} {shlex.quote(recorder.as_posix())} "$@"; }}\n' + step["run"] + ) + output = runner / "github-output" + result = run_command( + "bash", + ["--noprofile", "--norc", "-euc", shell], + cwd=checkout, + env={ + **{key: value for key, value in os.environ.items() if key not in {"BASH_ENV", "SHELLOPTS", "BASHOPTS"}}, + "GITHUB_WORKSPACE": checkout.as_posix(), + "RUNNER_TEMP": runner.as_posix(), + "RELEASE_TAG": TAG, + "GITHUB_EVENT_NAME": "push", + "GITHUB_REF": f"refs/tags/{TAG}", + "GITHUB_SHA": COMMIT, + "GITHUB_OUTPUT": output.as_posix(), + "FIXTURE_CALLS": calls.as_posix(), + }, + check=False, + ) + assert result.returncode == 0, result.stderr + assert output.read_bytes() == f"commit={COMMIT}\n".encode() + assert (runner / "handoff/evidence.toml").read_bytes() == policy + invocations = [json.loads(line) for line in calls.read_text(encoding="utf-8").splitlines()] + evidence = [args for args in invocations if "evidence" in args] + assert len(invocations) == 3 + assert len(evidence) == 1 + arguments = evidence[0][evidence[0].index("--root") :] + provider = EvidenceProvider(checkout) + provider.install(monkeypatch) + assert shared_main(arguments) == 0 + selected = json.loads((runner / "handoff/selection.json").read_bytes()) + assert selected["run"]["id"] == 101 + assert selected["run"]["head_sha"] == COMMIT + + @pytest.mark.parametrize("outcome", ["success", "automatic", "dispatch-failure", "missing", "wrong-tag", "malformed"]) def test_benchmark_recipe_forwards_one_tag_and_independent_transfer(tmp_path: Path, outcome: str) -> None: transfer = tmp_path / "owner's transfer $literal.json" diff --git a/tooling/README.md b/tooling/README.md index 252e5cb..9bc99d1 100644 --- a/tooling/README.md +++ b/tooling/README.md @@ -81,9 +81,8 @@ Both registry and verified Git selections can run full `just ci`; only the published selection is eligible for release evidence and publication. Before an actual release, replace any override and isolated Git pins with the supplying published version, resolve/sync the lock and revalidate affected -evidence. The configured `release.published-dependencies` policy uses -the shared implementation from -[research-repo-tools#193](https://github.com/acgetchell/research-repo-tools/issues/193). +evidence. The configured `release.published-dependencies` policy requires a +published supplier at each release boundary. `just release-dependencies` checks that transition before release work. It rejects development pins; ordinary checks and bounded acquisition remain available during rehearsal. Release evidence and publication enforce the @@ -114,10 +113,7 @@ or verification still fail. Release jobs with fresh project environments prepare their own receipts before acquisition/acceptance verification. Local `just ci` retains its ordinary validation scope. -Normal `just update` uses the supplier's exact Git-source support from -[research-repo-tools#201](https://github.com/acgetchell/research-repo-tools/pull/201), -which fixes [#200](https://github.com/acgetchell/research-repo-tools/issues/200). -The updater preserves the included tooling group's exact supplier pin, any +Normal `just update` preserves the included tooling group's exact supplier pin, any immutable source commit and inherited tool versions while updating unrelated dependencies. Upgrading a published supplier uses the target release's adopter outside the old project environment. For the current release: @@ -144,9 +140,8 @@ Python and Cargo selections. After applying, sync the environment and reconcile isolated runtime pins and identity tests; the helper does not rewrite workflows or automatically promote a development pin when a release appears. -The root `dependency-sources.toml` declares both dependency graphs for the -shared source-policy validation introduced by -[research-repo-tools#198](https://github.com/acgetchell/research-repo-tools/pull/198). +The root `dependency-sources.toml` declares both dependency graphs for shared +source-policy validation. Cargo release ownership includes `la-stack` and its private comparison member; the Python project is the private tooling environment. Other dependencies must come from their registries for release. The file is retained in source exports @@ -232,7 +227,7 @@ suites run their column-basis, rational-dot, interval-solve or polynomial gate on every supported revision. The non-exact diagnostic retains its original gate and baseline-phase reference libraries. -The expanded #301 policy measures all public la-stack workflows at the current +The release policy measures all public la-stack workflows at the current revision and on supported baselines. Older baselines retain 1,254 shared library cases; the 149 cases introduced in v0.5.2 become required automatically at that boundary. The paired LU suite acquires 16 peer cases on each phase alongside @@ -249,40 +244,20 @@ coverage decisions, feature configurations and runtime estimates. to the installed reporter, defaulting to `human` and `300` seconds. JSON status and `none` are supported without a local progress engine. Consumer fixtures exercise validated totals, unknown ETA, captured logs and early failure; report -and README recipes retain their measurement-free retry boundaries. The -[workload review](../docs/dev/benchmark-workload-review.md) records the availability -decision, preserved coverage and supplier's corrected gate-failure event. - -General workload availability across API revisions is tracked in -[research-repo-tools#166](https://github.com/acgetchell/research-repo-tools/issues/166) -for v0.2.5, with published-package adoption in -[la-stack#320](https://github.com/acgetchell/la-stack/issues/320) for v0.5.3. -The full declaration now uses inclusive `since = "v0.5.2"` suite bounds. -The normally installed 0.2.6 interface was checked against the consumer's peer -comparison contract. Astra recommends retaining its cross-phase different-ID -restriction and migrating to paired LU suites with current-phase peer ratios. -The published v0.2.7 supplier fixes the gate-status defect tracked in -[research-repo-tools#191](https://github.com/acgetchell/research-repo-tools/issues/191); -the preserved schema-2 and schema-5 regressions pass against it. -No permanent baseline exclusion remains; supported missing cases or failed -compilation remain errors. - -The current pin also supplies schema-6 interrupted-trial recovery and -phase-specific sources from [PR #205](https://github.com/acgetchell/research-repo-tools/pull/205). +and README recipes retain their measurement-free retry boundaries. +The full declaration uses inclusive `since = "v0.5.2"` suite bounds; +supported missing cases or failed compilation remain errors. + +Schema-6 interrupted-trial recovery retains phase-specific sources. Baseline sources declare historical README compiler input; current gates prove README is excluded from ordinary debug/release compilation. Current README is one of the precise generated outputs. Historical current revisions that still compile it are rejected by the full candidate plan. -Earlier adopted fixes for -[research-repo-tools#196](https://github.com/acgetchell/research-repo-tools/issues/196) -and [#197](https://github.com/acgetchell/research-repo-tools/issues/197) arrived through -[PR #199](https://github.com/acgetchell/research-repo-tools/pull/199). The paired-suite publisher resolves dependency-version labels from the owning suite observation; preparation checks each available suite's minimum release before -saving a source pair. The preserved public-API reproducers pass without changing -their assertions. The [workload review](../docs/dev/benchmark-workload-review.md#validation-evidence) -records downstream validation and the remaining publication/platform boundary. +saving a source pair. Historical design and validation evidence belongs in the +[workload review](../docs/archive/development/benchmark-workload-review.md). Working-tree measurements include tracked changes and nonignored untracked regular files. Scratch outputs belong under ignored `target/`. @@ -352,7 +327,7 @@ and scientific checks on the exact commit, and requires the durable Criterion release asset. `release-gate`, `release-publish` and `release-verify` use the shared release contract; `publish-check` owns native default/exact Cargo dry-runs. Main CI signs those packaging and native validation identities; -`release-evidence ` binds the original acquisition, precise publisher +`just release-evidence [OWNER] [SELECTION]` binds the original acquisition, precise publisher receipt, final clean commit and signed native acceptance. Named review records are immutable; selecting a later native attempt requires an explicit new name. `release-evidence.toml` owns the package, workflow, native job and signer policy; @@ -383,7 +358,6 @@ need no `OWNER` or `RELEASE_COMMIT` shell variables. `release-upload` dispatches the existing reviewed publication selection without approving deployment. `release-version-check` requires final metadata; ordinary CI retains a private nonfinal metadata check. -There are no `docs-version-check` or `release-package` recipe aliases. `tests/tooling/test_toolchain_integration.py` owns the package-identity check: manifest requirement, registry lock and installed published version, including @@ -393,5 +367,3 @@ lockfile and isolated requirements; no sibling checkout supplies runtime code. Setup, managed execution, dependency updates, Markdown checks, Semgrep, security scans and opt-in CodeRabbit review also use shared commands. -See the [adoption record](../docs/dev/performance-tooling-adoption.md) for -deletion dispositions and release validation evidence.