From f5fa847365c151d585a01ac24e032f00d23e4f7b Mon Sep 17 00:00:00 2001 From: doc Date: Fri, 9 Oct 2026 20:43:25 +0000 Subject: [PATCH 01/46] plans(ci): close M003j dispatch input hardening --- architecture/overview.md | 10 +- .../ci-release-orchestration/003j-status.md | 96 +++++++++++++++++++ ...dispatch-tag-shell-injection-corrective.md | 2 +- plans/registry.md | 13 ++- .../ci-release-orchestration-roadmap.md | 4 +- 5 files changed, 116 insertions(+), 9 deletions(-) create mode 100644 plans/closure/ci-release-orchestration/003j-status.md diff --git a/architecture/overview.md b/architecture/overview.md index 9625426..babe091 100644 --- a/architecture/overview.md +++ b/architecture/overview.md @@ -25,7 +25,7 @@ reading instead of the source. Keeping them true is a manual obligation, and it has been missed before, so record what is actually true rather than what was once true. -The last code commit, `61b2c03`, changed five source files +The prior code commit, `61b2c03`, changed five source files (`builder.rs`, `qualification.rs`, `ci/src/lib.rs`, `cli/src/main.rs`, `github/src/lib.rs`). It also edited most of the deep dives, but **did not re-base the line numbers** in six of them, so roughly ninety citations pointed at @@ -73,6 +73,14 @@ whose intent it could not confirm. Treat those as indicative until re-based by symbol name. The rule from the `61b2c03` pass holds: re-base by reading the line and confirming it holds what the sentence claims, never by arithmetic alone. +CI M003j (`559d940`) modified `eggpack-ci/src/lib.rs` and increased its count to +10772 lines. The dispatch-rendering anchors were rechecked by symbol for this +change: workflow trigger/concurrency rendering (`3320-3350`), reusable resolve +(`3388`), write-scoped stage (`3895-3999`), and post-render check (`4003`). The +approximate `ci.md` renderer range and these relevant `ci-rendering.md` anchors +were updated. Other pre-existing `ci-rendering.md` citations were not +blanket-shifted; verify them by symbol before relying on them. + ## How to read this document This file has two jobs, deliberately: diff --git a/plans/closure/ci-release-orchestration/003j-status.md b/plans/closure/ci-release-orchestration/003j-status.md new file mode 100644 index 0000000..81d28b0 --- /dev/null +++ b/plans/closure/ci-release-orchestration/003j-status.md @@ -0,0 +1,96 @@ +# CI M003j Closure — Dispatch-Tag Shell Injection Corrective + +Status: **closed** + +Source plan: `plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md` + +Roadmap: `plans/subsystems/ci-release-orchestration-roadmap.md` + +Reviewed Eggpack baseline: `d61ca71fc0112be63e7e8ba31ba8fa2b1ce5a628`. + +Implementation commit and immutable producer pin: `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce`. + +Reviewed consumer configurations: wg-basic `0b814fe02b5e09654e9363c8f61caf59b25ecc92` (R001 status/registry/roadmap-only update; workflow/config unchanged), Eggsearch `2e876e46724c02c502d78bf968e74a1ad6affb71`, Eggsact `d4e6e5c5cd7e9665373fbe312f4e1fb122fb5729`, and StegoEggo `a01a0222c6a5022a9eb3561f153b1e72b6e6c42a`. The source plan's originally confirmed wg-basic security-review baseline was `dbowm91/wg-basic@ff40f851508ccda52171c27cefdcdaf4ec1da2d5`. No consumer workflow or release-policy configuration was changed. + +Hosted CI: [run 37987890305](https://github.com/eggstack/eggpack/actions/runs/37987890305), push, attempt 1, `head_sha` exactly `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce`, conclusion `success`. Linux stable, Linux 1.89.0, macOS, and Windows portability all passed. + +## Executive finding + +CI M003j is closed. Workflow-dispatch release tags are validated as bounded canonical stable `vX.Y.Z` data before the reusable resolver or write-scoped staging job checks out the selected source. The generated Bash reads the value through the quoted `EGGPACK_RELEASE_TAG` environment variable. The reusable resolver now uses this data path for both mapped and legacy exact-tag identity modes; the legacy mode previously placed the dispatch expression directly in the `_resolve-release` shell argument. A renderer guard rejects dispatch-tag expressions in any generated `run:` script while permitting data use in action inputs such as checkout `with.ref` and in concurrency keys. + +No build/qualification authority, staging permission, manifest schema, publication authority, or signing trust decision changed. No real dispatch, draft creation, signing, or publication occurred. + +## Requirement-to-evidence matrix + +| Requirement | Evidence | Result | +|---|---|---| +| Remove executable interpolation in reusable resolver and stage validation | `dispatch_tag_validation_step` emits an `env` binding and fixed Bash validator; resolve and stage branches place it before checkout. `m003c_tag_source_controls_checkout_input_and_stage_guard` asserts safe `run` bodies, environment binding, and validation-before-checkout ordering. | Pass | +| Route resolver CLI tag argument through data for legacy and mapped modes | Runtime `ResolveRelease` always uses the renderer-only `$release_tag` marker, which renders as the quoted `"$EGGPACK_RELEASE_TAG"`; resolver step binds the tag for both modes. `m003i_mapped_workflow_binds_tag_safely_and_preserves_event_mapping` remains green; M003j reusable render assertions cover dispatch mode. | Pass | +| Reject malformed or injected tags before source checkout | Validator caps input at 64 characters and accepts only canonical stable `vX.Y.Z`. Unix regression covers valid, empty, non-prefixed, leading-zero, prerelease, build suffix, newline, shell substitution, punctuation, and over-bound input. | Pass | +| Prove the test distinguishes the old vulnerable script | The controlled old-template Bash run creates a temporary marker from `$(touch ...)`; the rendered validator rejects the same fixture without creating the marker. No network or credentials are used. | Pass | +| Fail closed if unsafe dispatch expressions return to generated scripts | `contains_unsafe_dispatch_expression_in_run` rejects direct `inputs.release_tag` expressions in scalar and block `run:` forms. Mutation test inserts the old expression and verifies the guard detects it and `check_release_github` reports drift. | Pass | +| Preserve ref-name, mapped identity, staging scope, and release schema | RefName stays push/tag-only; DispatchInput remains dispatch-only; exact-source verification, M003i mapping, permissions and handoff remain unchanged. No schema or CLI document shape changed. Existing M003c/M003i regressions and the full workspace suite pass. | Pass | +| Qualify the exact implementation on required hosted platforms | Hosted run 37987890305 is green on Stable Linux, Rust 1.89.0 Linux, macOS, and Windows. | Pass | +| Re-render the affected consumer configuration without modifying it | From wg-basic's current checked-in workflow shape, contract, and GitHub policy: generation produced 33,370 bytes and `ci check: match`. Diff is exactly the two validation steps: each now has a bounded environment-based validator moved ahead of checkout. No policy key changed; the policy's pinned Eggpack revision remains consumer-owned and must be repinned by its plan. | Pass | +| Identify other adopted DispatchInput consumers | Current Eggsact, StegoEggo, and Eggsearch policies all select `dispatch_input`; their checked-in `release-binaries.yml` / `release-eggpack.yml` contain direct executable interpolation. Fresh render sizes were 56,534 / 56,596 / 76,328 bytes and self-check passed; `ci check` against each checked-in workflow correctly reports drift. Generated diffs replace both validation snippets and, in legacy exact-identity mode, replace the direct `_resolve-release --tag '${{ inputs.release_tag }}'` argument with `"$EGGPACK_RELEASE_TAG"`. | Confirmed; consumer remediation remains open | + +## Production implementation evidence + +- `crates/eggpack-ci/src/lib.rs`: one canonical bounded Bash validator is rendered into reusable `resolve` and `stage`; both run it before checkout. `ResolveRelease` takes the tag from a quoted environment reference in every identity mode. +- The generator scans emitted `run:` scalar and block forms for direct dispatch-tag interpolation and returns a bounded render error if one appears. Dispatch expressions remain permitted in non-executable action inputs and concurrency metadata. +- `crates/eggpack-ci/README.md`, `architecture/ci-rendering.md`, `architecture/ci.md`, and `architecture/overview.md` describe the new behavior and current source line counts/relevant anchors. +- Golden workflows for RefName staging are byte-identical; no golden fixture update was needed because the affected DispatchInput reusable flow is exercised from its actual parsed generated YAML in tests. + +Before/after consumer render: the two old `run: "test -n \"${{ inputs.release_tag }}\""` steps are replaced by a multiline validator using `EGGPACK_RELEASE_TAG`; the new steps precede checkout in both jobs. For legacy exact-identity configurations, `_resolve-release --tag '${{ inputs.release_tag }}'` also becomes `_resolve-release --tag "$EGGPACK_RELEASE_TAG"` with the expression moved into `env`. Other generated workflow sections and consumer policy keys are unchanged by the rerender. + +## Exact verification executed + +| Command/evidence | Result | +|---|---| +| `cargo test -p eggpack-ci --locked m003c_tag_source_controls_checkout_input_and_stage_guard -- --nocapture` | Passed | +| `cargo test -p eggpack-ci --locked m003j_dispatch_tag_validation_treats_values_as_data -- --nocapture` | Passed; controlled shell-substitution marker negative proved | +| `cargo test -p eggpack-ci --locked m003i_mapped_workflow_binds_tag_safely_and_preserves_event_mapping -- --nocapture` | Passed | +| `cargo run -p eggpack-cli --locked -- ci generate --workflow-shape ../wg-basic/release/eggpack/workflow-shape.json --contract ../wg-basic/release/eggpack/distribution.toml --github-policy ../wg-basic/release/eggpack/github-policy.json --output /tmp/eggpack-wg-basic-m003j.yml` | Generated 33,370 bytes | +| `cargo run -p eggpack-cli --locked -- ci check --workflow-shape ../wg-basic/release/eggpack/workflow-shape.json --contract ../wg-basic/release/eggpack/distribution.toml --github-policy ../wg-basic/release/eggpack/github-policy.json --workflow /tmp/eggpack-wg-basic-m003j.yml` | `ci check: match (33370 bytes)` | +| Generate and self-check Eggsact, StegoEggo, and Eggsearch reusable outputs | Passed at 56,534 / 56,596 / 76,328 bytes. Against the checked-in workflows, `ci check` reported expected drift (55,901 / 55,963 / 75,695 actual bytes) pending consumer repin/regeneration. | +| `scripts/check-local.sh` | Passed: format, check, clippy, per-crate tests, workspace tests, docs, dependency trees, package verification, and Rust 1.89.0 check/tests | +| Hosted [run 37987890305](https://github.com/eggstack/eggpack/actions/runs/37987890305) | Passed on exact implementation SHA across Linux stable, Linux 1.89.0, macOS, Windows | +| `git diff --check` | Passed | + +The package phase printed the pre-existing registry warning that locked `yoke-derive v0.8.3` is yanked; every package verification succeeded. No lockfile or dependency was changed. + +## Invariant review + +- **Data/code separation:** dispatch text is passed only as environment data and a quoted variable argument; the finite validator does not evaluate or re-expand it. +- **Validation order:** `resolve` and privileged `stage` validate before checkout. The earlier preflight checkout remains a pinned action input followed only by `cargo --version`; no checked-out workflow source executes there. The actual build graph depends on successful `resolve`. +- **Identity/source authority:** exact-source SHA verification and M003i tag/manifest mapping remain authoritative; canonical tag syntax does not authorize a source revision. +- **Privilege:** only stage retains `contents: write`, after aggregate. No signing secret, OIDC permission, publication step, or new network action was added. +- **Determinism:** canonical helper output is fixed; workflow generation remains byte-stable and consumer regeneration has zero drift. +- **Release evidence:** ReleaseManifest v1 and final-byte meaning are unchanged; no signature or provenance claim was added. + +Nothing was weakened to reach this milestone. + +## Failure, recovery, compatibility, and security review + +Invalid or oversized dispatch values fail before the resolver or stage checks out the requested tag. A failure leaves no build or draft mutation. A valid value proceeds through the existing exact-source checks. Reruns remain concurrency-serialized and staging remains draft-only/no-clobber. + +This changes generated reusable-workflow bytes and requires consumers to repin the immutable producer commit and regenerate their checked-in workflow under their own plan. Exact-tag workflow identities, RefName push behavior, `StagingTagSource`, CLI interfaces, manifest compatibility, and existing handoff documents remain compatible. No consumer workflow or release-policy configuration was edited; wg-basic received only the plan/registry status update cited below. + +Security review found no residual Eggpack dispatch-tag-to-shell path in generated `run:` text. The tag remains visible in YAML data positions (`with.ref`, environment binding, and concurrency group) by design. No live attack, dispatch, credentials, or privileged staging was attempted; only a harmless local marker fixture was executed. + +## Documentation and operations + +Producer pin for wg-basic Release Readiness R001 and other affected consumers: `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce`. Each consumer plan must update its Eggpack tool revision, regenerate its checked-in workflow, and require its own `eggpack ci check` before signing or staging. No consumer key/config changed here. + +## Unresolved findings + +No unresolved producer finding remains. **High residual consumer finding:** wg-basic, Eggsact, StegoEggo, and Eggsearch still have checked-in dispatch workflows that embed `inputs.release_tag` in executable Bash. Their current configs were positively confirmed as `DispatchInput`; until each owner repins and regenerates through its own plan, those checked-in workflows remain exposed to this injection class. wg-basic Release Readiness R001 is now **ready** after a status-only update at `dbowm91/wg-basic@0b814fe02b5e09654e9363c8f61caf59b25ecc92`; workflow regeneration, provenance proof, and strict closure remain outstanding. Eggpack cannot close or silently edit the other external consumer plans. + +## Roadmap disposition and registry updates + +- CI M003j: `ready` → **closed**, this closure is its evidence record. +- The known downstream blocker is discharged: wg-basic Release Readiness R001 may resume using the immutable producer pin above. This is eligibility only; its implementation and closure remain consumer-owned. +- wg-basic updated R001's status to `ready` through its own plan/registry/roadmap in commit `0b814fe02b5e09654e9363c8f61caf59b25ecc92`; no consumer workflow, policy key, or production behavior changed in that commit. +- Eggsact, StegoEggo, and Eggsearch are also confirmed DispatchInput consumers with stale generated workflows. No corresponding corrective plan was found or changed in their repositories during this producer milestone; their maintainers need to register consumer-owned repin/regenerate work before treating those workflows as remediated. +- No other Eggpack implementation plan is promoted by this closure. The registry has no remaining ready Eggpack plan; future Eggpack implementation requires new plan authoring against the then-current evidence. +- CI M003i's historical closure is unchanged. diff --git a/plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md b/plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md index 5c65fb8..c277aec 100644 --- a/plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md +++ b/plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md @@ -1,6 +1,6 @@ # CI/Release M003j — Dispatch-tag Shell Injection Corrective -Status: ready for implementation. +Status: **closed** — strict closure is recorded at `plans/closure/ci-release-orchestration/003j-status.md` (implementation `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce`, hosted run `37987890305`, all four lanes green). Repository baseline: `eggstack/eggpack@d61ca71fc0112be63e7e8ba31ba8fa2b1ce5a628` (2026-10-08). Source roadmap: `plans/subsystems/ci-release-orchestration-roadmap.md`. Primary class: invariant / security corrective. diff --git a/plans/registry.md b/plans/registry.md index 271c2b9..eb073a4 100644 --- a/plans/registry.md +++ b/plans/registry.md @@ -85,7 +85,7 @@ Distribution predecessor evidence: - **Bootstrap M002b CLOSED:** `plans/closure/bootstrap-installers/002b-status.md`; implementation `88ddf2e796ac3674b306b51726c65ed7cc9bd29a`, hosted run `37806244313` green across Linux stable/MSRV, macOS, Windows. - **CI M003i CLOSED:** `plans/closure/ci-release-orchestration/003i-status.md`; implementation `3ddac9d84fc2e10b8451d38672f66b02e06724df`, hosted run `37813044035` green on Linux stable/MSRV, macOS, and Windows. The finite opt-in mapping preserves exact-tag defaults and ReleaseManifest v1; its mapped runtime identity envelope is explicitly versioned. - **Downstream handoff:** wg-basic Distribution M003 may resume against immutable producer SHA `3ddac9d84fc2e10b8451d38672f66b02e06724df`. Its own implementation, native qualification, and closure remain consumer-owned and were not changed in Eggpack. -- **Execution order:** M002b implementation → M002b strict four-platform closure → M003i implementation → M003i strict closure (complete) → separate wg-basic M003 handoff. These additions supersede historical 'no ready' snapshots below; earlier closure records remain unchanged. +- **Execution order:** M002b implementation → M002b strict four-platform closure → M003i implementation/closure → M003j implementation/strict closure (complete) → separate wg-basic Release Readiness R001 repin/rerender under its consumer-owned plan. Earlier closure records remain unchanged. ## Active subsystem roadmaps @@ -96,7 +96,7 @@ Distribution predecessor evidence: | Release manifest | active | `plans/subsystems/release-manifest-roadmap.md` | M002/M003 closed; M003a closed | M003a closed as a docs-only post-publication downstream-closure reconciliation after Eggup M004 closed (`eggstack/eggup@ea1f1c5e29302e5feca4599db9342d3a5ac93915`; formal Eggup status cleanup `eggstack/eggup@3b82d5397e728649a666690868a1e2d0fe42460d`); closure `plans/closure/release-manifest/003a-status.md`; M003 remains closed and no runtime/package requalification was performed or implied | | Build and qualification | active | `plans/subsystems/build-qualification-roadmap.md` | M001-M006 closed | M006 closed on `398cd43` + run 36484758546 under accepted ADR-0005 Option A; the milestone chain is closed and later work needs new evidence | | Bootstrap installers | active; corrective closed | `plans/subsystems/bootstrap-installers-roadmap.md` | M002b closed; prior milestones closed | M002b implementation `88ddf2e`, hosted run `37806244313`; POSIX runtime remains on Unix and Windows PowerShell archive runtime passed. M003 completion definition remains satisfied | -| CI/release orchestration | active; M003i closed, M003j security corrective ready | `plans/subsystems/ci-release-orchestration-roadmap.md` | M003j dispatch-input shell hardening | M003i historical closure retained; two generated `run:` expressions embed `inputs.release_tag` in shell; wg-basic Release R001 blocked on qualified M003j output | +| CI/release orchestration | active; M003i and M003j closed | `plans/subsystems/ci-release-orchestration-roadmap.md` | none ready | Producer fix is qualified; wg-basic R001 is ready at `dbowm91/wg-basic@0b814fe02b5e09654e9363c8f61caf59b25ecc92` with pin `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce`. Eggsact, StegoEggo, and Eggsearch were also verified as DispatchInput consumers with stale generated workflows; their own plans remain required for remediation. | | Eggup interoperability | active | `plans/subsystems/eggup-interoperability-roadmap.md` | Eggpack M001a + Eggup adapter M001/M001a + Eggup M003 real-consumer adoption + Eggup M004 registry promotion all closed | The whole producer/consumer package seam is closed end to end; Release Manifest M003a closed the remaining Eggpack-side planning drift, and no Eggpack work remains on this seam; Eggwork Operations M003 remains producer-only | | Ecosystem adoption | active | `plans/subsystems/ecosystem-adoption-roadmap.md` | M001/M002/M003a/M003b closed | Closure `plans/closure/ecosystem-adoption/003b-status.md`. Paired plans: Eggpack `plans/implementation/ecosystem-adoption/003b-eggsearch-seven-target-eggpack-producer-cutover.md` (`325d44e`); Eggsearch `plans/implementation/eggpack-release-adoption/001-seven-target-eggpack-producer-cutover.md` (`377f9e8`, registry `6767062`). Implementation landed at `eggstack/eggsearch@eabbf80`; hosted run `37531104901` staged eggsearch `v0.4.2` as draft `405157598` with the exact 19-asset inventory, glibc 2.17 re-proven on all three GNU targets, ARMv7 required consumer validator green, Windows ARM64 required and green, and zero OIDC permission in generated jobs. Provenance attested the staged bytes in run `37561960304`; the draft was published 2026-10-07, closing the named condition | | Planning hygiene | active | `plans/subsystems/planning-hygiene-roadmap.md` | M001/M002 closed | M002 closed at `plans/closure/planning-hygiene/002-status.md`: docs/evidence-only post-M003a handoff reconciliation with an empty production/package/workflow diff; stale/duplicated control-surface text removed and the handoff bound to exact paired-plan paths | @@ -105,7 +105,7 @@ Distribution predecessor evidence: ## Dependency-ready implementation work -Planning Hygiene M002, Ecosystem M003b, Bootstrap M002b, and CI M003i are closed. **New dependency-ready CI M003j security corrective:** `plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md`. A wg-basic release-readiness source audit confirmed two `workflow_dispatch.inputs.release_tag` interpolations into generated executable Bash, including the write-scoped staging job, at Eggpack `crates/eggpack-ci/src/lib.rs` around the reusable resolver and stage render. Fix and qualify the producer generator before wg-basic R001 repins/regenerates; no public release or new signing is authorized. +Planning Hygiene M002, Ecosystem M003b, Bootstrap M002b, and CI M003i/M003j are closed. CI M003j's strict closure is `plans/closure/ci-release-orchestration/003j-status.md`; its immutable producer implementation `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce` passed hosted run `37987890305` on Linux stable/MSRV, macOS, and Windows. wg-basic updated Release Readiness R001 to `ready` in its own plan/registry commit `0b814fe02b5e09654e9363c8f61caf59b25ecc92`; consumer workflow changes remain outstanding. No public release or new signing is authorized by this producer closure. The table below is the **milestone-to-closure index plus active ready work**, not an implication that every historical row is executable. @@ -113,7 +113,7 @@ The table below is the **milestone-to-closure index plus active ready work**, no |---|---|---|---|---| | Bootstrap installers | M002b Windows POSIX archive-test portability | **closed** | `plans/implementation/bootstrap-installers/002b-windows-posix-archive-test-portability-corrective.md` | Closure `plans/closure/bootstrap-installers/002b-status.md`; implementation `88ddf2e`; hosted run `37806244313` all lanes green | | CI orchestration | M003i exact tag versus manifest release ID policy | **closed** | `plans/implementation/ci-release-orchestration/003i-explicit-tag-and-manifest-release-identity-corrective.md` | Closure `plans/closure/ci-release-orchestration/003i-status.md`; implementation `3ddac9d84fc2e10b8451d38672f66b02e06724df`; hosted run `37813044035` all four lanes green. wg-basic M003 may resume with this pin | -| CI orchestration | M003j dispatch-tag Bash interpolation corrective | **ready** | `plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md` | Hard: CI M003i closed; generated workflow root cause proven in source; wg-basic Release R001 needs immutable qualified fix | +| CI orchestration | M003j dispatch-tag Bash interpolation corrective | **closed** | `plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md` | Closure `plans/closure/ci-release-orchestration/003j-status.md`; implementation `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce`; hosted run `37987890305` all lanes green; wg-basic R001 unblocked to repin/regenerate | | Planning hygiene | M001 current evidence baseline + blocker reconciliation | closed | `plans/implementation/planning-hygiene/001-current-evidence-baseline-and-blocker-reconciliation.md` | Closure `plans/closure/planning-hygiene/001-status.md`; discharged CI M003b (eggsact `685fa373` + run `36886042696`) and closed Ecosystem M002 on stegoeggo `v0.5.0` (run `37181914252`); docs-only, zero production/package/workflow delta | | Planning hygiene | M002 post-M003a cross-repository handoff reconciliation | closed | `plans/implementation/planning-hygiene/002-post-m003a-cross-repository-handoff-reconciliation.md` | Closure `plans/closure/planning-hygiene/002-status.md`; docs/evidence-only; stale M003/M003a/M003b control-surface text reconciled against exact paired-plan paths; empty production/package/workflow diff | | Contract and conformance | M003 bounded direct-contract expansion CLI | closed | `plans/implementation/contract-conformance/003-bounded-direct-contract-expansion-cli.md` | Closure `plans/closure/contract-conformance/003-status.md`; implemented on `43fa2d7`; local-only scalar projection delegating to `DistributionContract`; `ci` family unchanged byte-for-byte; no new dependency, serialized schema, discovery, or framework | @@ -161,6 +161,7 @@ were removed rather than left to mislead. | Ecosystem adoption | M006 Egress archive pair | blocked | Remains after prior native adoption evidence; requires explicit archive/Python boundary review | | Provenance/authenticity | future | planned | Researchable but not implementation-ready: requires a dedicated trust ADR. Eggsearch's existing GitHub Artifact Attestation release is prior art only and does not select Eggpack's trust model | | Python/wheel adapters | future | planned | Remains behind broader native adoption (Phase 13); separate package-adapter planning, registry publication explicit | +| Adopted dispatch-workflow consumers | Eggsact, StegoEggo, Eggsearch | consumer-owned follow-up required | Their checked-in DispatchInput workflows still contain executable `inputs.release_tag` interpolation. M003j qualified producer pin `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce` is available; each consumer needs its own registered repin/regenerate plan before its workflow is considered remediated. | Build/Qualification M002a/M003/M004/M005 remain closed with hosted cross-platform evidence. CI M002 and Bootstrap M002 retain their historical implementation/closure records. Both M002a correctives are closed on implementation `4d2270a` with hosted run 36154905956 green. CI M003a retains its historical evidence (`36f1cc1`/36180399698); M003c corrected M003a/M003b's post-closure source-integrity and transfer findings in `5c28099`, qualified by hosted run 36213316240 (all four lanes green). CI M003d then closed the reusable consumer-composition/runtime-identity seam, and Build M005 closed deterministic cross-tool provisioning on `7a206ba` with hosted run 36256831000 green. @@ -281,7 +282,9 @@ External dist 0.33 spike [CLOSED, disposition C] --> prior art only ## Next handoff -Every closed milestone retains its closure record, so do not read this section as a shortlist: Contract M001/M002, Release Manifest M001/M001a/M002/M003/M003a, Build/Qualification M001–M006, CI M001/M002/M002a/M003a–M003h, Bootstrap M001/M002/M002a, Eggup Interoperability M001/M001a, Ecosystem M001/M002, External backend evaluation M001, and Planning Hygiene M001 all have accepted closure records under `plans/closure/`. Eggup Interoperability M003 is additionally closed downstream on the real Eggsact consumer. Per-subsystem detail is in `plans/subsystems/*-roadmap.md`; the milestone-to-closure index is the table above. +Every closed milestone retains its closure record, so do not read this section as a shortlist: Contract M001/M002, Release Manifest M001/M001a/M002/M003/M003a, Build/Qualification M001–M006, CI M001/M002/M002a/M003a–M003j, Bootstrap M001/M002/M002a, Eggup Interoperability M001/M001a, Ecosystem M001/M002, External backend evaluation M001, and Planning Hygiene M001 all have accepted closure records under `plans/closure/`. Eggup Interoperability M003 is additionally closed downstream on the real Eggsact consumer. Per-subsystem detail is in `plans/subsystems/*-roadmap.md`; the milestone-to-closure index is the table above. + +**CI M003j is closed** at `plans/closure/ci-release-orchestration/003j-status.md`; implementation `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce` passed hosted run `37987890305` on all four required lanes. The producer dependency is discharged for wg-basic Release Readiness R001, which may repin this SHA and regenerate/check its workflow under its separate plan. No Eggpack implementation plan is currently ready; the next Eggpack implementation action is plan authoring if new producer work is identified. M003h is closed on the synchronized, verified candidate. **Ecosystem M002 stegoeggo is closed** at `plans/closure/ecosystem-adoption/002-status.md` §9: consumer implementation `3b96fae` and closure `c75132a` prove the second-repo cutover without a new Eggpack producer primitive, and the live evidence arrived as stegoeggo `v0.5.0` — Eggpack run `37181914252`, published 2026-10-04T06:34:19Z from source `57ca94c9…`, exact 15-asset inventory, manual publication, real public `0.4.2 -> 0.5.0` updater transition. The `0.4.3` milestone earlier planning anticipated was stopped pre-publication by the consumer on semver grounds and superseded by `0.5.0`. diff --git a/plans/subsystems/ci-release-orchestration-roadmap.md b/plans/subsystems/ci-release-orchestration-roadmap.md index 38bf53b..bd40430 100644 --- a/plans/subsystems/ci-release-orchestration-roadmap.md +++ b/plans/subsystems/ci-release-orchestration-roadmap.md @@ -100,7 +100,7 @@ M003h status-reconciliation/main-integration corrective plan: `plans/implementat M003i identity-separation corrective: `plans/implementation/ci-release-orchestration/003i-explicit-tag-and-manifest-release-identity-corrective.md` (**closed** at `plans/closure/ci-release-orchestration/003i-status.md`; implementation `3ddac9d84fc2e10b8451d38672f66b02e06724df`, hosted run `37813044035`, all four lanes green). The immutable producer pin unblocked the separate wg-basic Distribution M003 for its consumer-owned implementation and qualification. -M003j dispatch-tag shell-injection corrective: `plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md` (**ready**). A 2026-10-09 wg-basic first-public-release security review found `workflow_dispatch.inputs.release_tag` interpolated directly into executable Bash at two generator sites (resolve and write-scoped stage). Preserve M003i's source identity and fix unsafe render with env/data handling, deterministic negative tests, and a fresh immutable producer pin for wg-basic Release Readiness R001. +M003j dispatch-tag shell-injection corrective: `plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md` (**closed** at `plans/closure/ci-release-orchestration/003j-status.md`; implementation `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce`, hosted run `37987890305`, all four lanes green). Dispatch tags are bounded canonical data validated before resolver/stage checkout; direct dispatch-tag expressions in `run:` are rejected. wg-basic Release Readiness R001 is unblocked to repin/regenerate under its own plan. ## 8. Cross-cutting requirements @@ -142,7 +142,7 @@ Build/Qualification M001-M006 and CI M001/M002/M002a/M003c-M003g are closed on t | M003g live qualification failures corrective | closed | `plans/implementation/ci-release-orchestration/003g-live-qualification-corrective.md` | `plans/closure/ci-release-orchestration/003g-status.md`; implementations `5acda73`/`4b28820`/`5ac5b83`/`e5c81f2`; hosted runs 36638321253, 36642184204, 36646814734, 36652203168 all lanes | cross-tool PATH, invalid zigbuild check, artifact exec-bit stripping, consumer validation against failed evidence, stage arity, swallowed staging error, and boolean `make_latest` all corrected; live run 36652731202 staged a complete 15-asset draft for eggsact `v1.2.7`, which the maintainer then published | | M003h live qualification status reconciliation + main integration | closed | `plans/implementation/ci-release-orchestration/003h-live-qualification-status-reconciliation-and-main-integration.md` | `plans/closure/ci-release-orchestration/003h-status.md` | current `main@404f63ec` was merged by `609d5fb`; status reconciled, full verification passed, and `main` fast-forwarded without force | | M003i explicit tag and manifest release identity corrective | closed | `plans/implementation/ci-release-orchestration/003i-explicit-tag-and-manifest-release-identity-corrective.md` | `plans/closure/ci-release-orchestration/003i-status.md`; implementation `3ddac9d84fc2e10b8451d38672f66b02e06724df`; hosted run `37813044035` passed all four lanes | Finite checked-in opt-in stable-tag mapping with explicitly versioned runtime envelope; legacy exact-tag workflow bytes and ReleaseManifest v1 remain unchanged; wg-basic M003 may resume against the immutable producer SHA | -| M003j dispatch tag shell-injection corrective | ready | `plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md` | none (new corrective plan) | Two unsafe `run:` expression interpolations in runtime resolve and write-scoped stage; fix generator and prove no shell execution from dispatch input; wg-basic Release R001 waits on qualified producer pin | +| M003j dispatch tag shell-injection corrective | closed | `plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md` | `plans/closure/ci-release-orchestration/003j-status.md`; implementation `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce`; hosted run `37987890305` passed Linux stable/MSRV, macOS, and Windows | wg-basic Release Readiness R001 may resume with this producer pin; consumer regeneration and authorization remain separate | ## 13. 2026-10-08 corrective addendum — M003i From 57587b34011f8c647a90ec70468fe21e4f23853e Mon Sep 17 00:00:00 2001 From: doc Date: Fri, 23 Oct 2026 14:32:38 +0000 Subject: [PATCH 02/46] plans: register producer convergence corrective chain Register the corrective chain produced by the 2026-10-23 post-implementation review of feature overlap, maintenance quality, and underdeveloped operator surface. Added: - plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md (proposed) - plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md - plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md - plans/implementation/build-qualification/009-local-producer-operator-commands.md - plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md - plans/implementation/ci-release-orchestration/003m-bounded-process-execution-convergence-corrective.md - plans/implementation/ci-release-orchestration/003n-producer-implementation-consolidation-corrective.md - plans/implementation/planning-hygiene/003-post-implementation-review-baseline-reconciliation.md Updated: - plans/registry.md (roadmap table, milestone index, planned/blocked table, execution graph, next-handoff paragraph) - plans/subsystems/{build-qualification,ci-release-orchestration,planning-hygiene}-roadmap.md - plans/adrs/README.md - AGENTS.md (current-handoff paragraph, which contradicted the registry it points at) No production code is changed by this commit. --- AGENTS.md | 2 +- ...-release-evidence-digest-acceptance-set.md | 245 ++++++++++ plans/adrs/README.md | 6 +- ...-evidence-digest-unification-corrective.md | 286 +++++++++++ ...atibility-floor-verification-corrective.md | 433 +++++++++++++++++ .../009-local-producer-operator-commands.md | 423 +++++++++++++++++ ...r-rule-authority-convergence-corrective.md | 443 ++++++++++++++++++ ...rocess-execution-convergence-corrective.md | 438 +++++++++++++++++ ...implementation-consolidation-corrective.md | 438 +++++++++++++++++ ...entation-review-baseline-reconciliation.md | 438 +++++++++++++++++ plans/registry.md | 44 +- .../subsystems/build-qualification-roadmap.md | 7 +- .../ci-release-orchestration-roadmap.md | 5 + plans/subsystems/planning-hygiene-roadmap.md | 17 +- 14 files changed, 3218 insertions(+), 7 deletions(-) create mode 100644 plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md create mode 100644 plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md create mode 100644 plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md create mode 100644 plans/implementation/build-qualification/009-local-producer-operator-commands.md create mode 100644 plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md create mode 100644 plans/implementation/ci-release-orchestration/003m-bounded-process-execution-convergence-corrective.md create mode 100644 plans/implementation/ci-release-orchestration/003n-producer-implementation-consolidation-corrective.md create mode 100644 plans/implementation/planning-hygiene/003-post-implementation-review-baseline-reconciliation.md diff --git a/AGENTS.md b/AGENTS.md index c8b4001..aba12e2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -89,4 +89,4 @@ Read the index in `overview.md` and follow one link. Grouped by what they cover: ## Planning conventions - Closure discipline: `plans/closure//NNN-status.md`. Compilation ≠ closure. History never rewritten — correctives are new `NNNa` plans; superseded material goes to `plans/archive/`. -- Current handoff (per `plans/registry.md`): no Eggpack plan is `ready`. Contract M003, Bootstrap M003, and Ecosystem M003a are all closed, so the contract-conformance and bootstrap-installers subsystems have no open work. Ecosystem M003b is **closed** at `plans/closure/ecosystem-adoption/003b-status.md`: the implementation landed in `eggstack/eggsearch`, staging evidence came from run `37531104901` (draft `405157598`, exact 19-asset inventory), provenance attested the staged bytes in run `37561960304`, and the draft was published as eggsearch `v0.4.2` on 2026-10-07. Planning Hygiene M002 is closed at `plans/closure/planning-hygiene/002-status.md` (docs/evidence-only). The next Eggpack line is whatever the registry lists as `ready`; if that table is empty, the next action is plan authoring, not implementation. +- Current handoff (per `plans/registry.md`): CI M003k is **in progress** (PR `eggstack/eggpack#1`; independent review/merge and downstream qualification pending). The 2026-10-23 post-implementation review registered a corrective chain that rewrites no closure record: **ready** are Build/Qualification M007 (evidence digest unification, `crates/eggpack-core/**` only), Build/Qualification M009 (local producer operator commands, `crates/eggpack-cli/**` only), and Planning Hygiene M003 (docs/evidence-only baseline reconciliation); **blocked** are Build/Qualification M008 (on M007), CI M003l (on the M003k merge, M007, and ADR-0006), CI M003m (on M003l), and CI M003n (on M003m); **ADR-0006 is proposed**, not accepted, and gates CI M003l's digest-acceptance work package only. Contract M003, Bootstrap M003, and Ecosystem M003a/M003b are closed, so the contract-conformance and bootstrap-installers subsystems have no open work. The next Eggpack line is whatever the registry lists as `ready`; if that table is empty, the next action is plan authoring, not implementation. diff --git a/plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md b/plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md new file mode 100644 index 0000000..a074288 --- /dev/null +++ b/plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md @@ -0,0 +1,245 @@ +# ADR-0006: Release Evidence Digest Acceptance Set + +Status: **proposed** + +Date: 2026-10-23 + +Decision owners: project maintainers + +Related specification sections: + +- plans/000-long-term-specification.md#11-artifact-finalization-and-checksums +- plans/000-long-term-specification.md#12-concrete-release-manifest +- plans/000-long-term-specification.md#19-security-model +- plans/000-long-term-specification.md#20-determinism-and-reproducibility + +Related decisions: + +- ADR-0002 (contract / plan / manifest separation); +- ADR-0005 (native qualification is independent of build strategy). + +Affected subsystem roadmaps: + +- build and qualification; +- release manifest; +- CI/release orchestration. + +## 1. Status note + +This record is **proposed**, not accepted. It exists because a post-implementation +review found that Eggpack carries **three different SHA-256 acceptance rules** for +the same concept, and because the choice between them is a public compatibility +decision rather than an internal refactor. + +Accepting this ADR authorizes +`plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md` +to implement the selected rule set. Until it is accepted, M003l's digest-validator +work package is **blocked**, and every other milestone in this review chain stays +independently implementable. + +## 2. Context + +`ReleaseManifest v1` records SHA-256 digests of final bytes. Three independent +validators exist in the workspace, and they do not agree: + +| Validator | Location | Rule | +|---|---|---| +| `ByteEvidence::validate` | `crates/eggpack-manifest/src/lib.rs:307-322` | exactly 64 lowercase hex characters | +| `validate_sha256` | `crates/eggpack-github/src/lib.rs:567-576` | exactly 64 lowercase hex characters | +| `validate_sha256_hex` | `crates/eggpack-ci/src/lib.rs:632-642` | exactly 64 lowercase hex characters **and not the all-zeros digest** | + +The divergence is not cosmetic. The all-zeros string `"0" * 64` is a +syntactically valid 64-character lowercase hex digest that no real file can +produce, because SHA-256 of any byte sequence is astronomically unlikely to be +the all-zero value. It is therefore a natural sentinel for "digest not computed", +"digest placeholder", or "digest defaulted". Today: + +- the CI crate **rejects** it; +- the GitHub staging crate, which is the component that actually computes and + compares digests over staged bytes, **accepts** it; +- the manifest crate, whose documents are published, **accepts** it. + +Two distinct problems follow. + +### 2.1 The producer's own evidence rules disagree + +A rule that is enforced in one crate and not in another is not a rule. The +crate that stages bytes to a draft release (`eggpack-github`) is the one place +where an all-zeros digest could be persisted into a published asset record, and +it is the one place that does not currently reject the sentinel. This is an +internal consistency defect, and it is fixable without any public contract +change. + +### 2.2 The published manifest's acceptance set is a public compatibility contract + +`eggpack-manifest 0.1.0` is published on crates.io and is consumed downstream by +`eggup-eggpack`. Tightening what `ReleaseManifest v1` accepts — even for a +value that no legitimate producer emits — changes the acceptance set of a +published schema-v1 document. `plans/003-planning-process.md` §4 names exactly +this as an ADR trigger: *"establish a public schema/manifest compatibility +contract"*. + +Therefore the choice cannot be made silently inside a refactor. It must be made +explicitly, with a compatibility handling decision, and recorded. + +## 3. Decision drivers + +- **Fail-closed validation.** The workspace's stated validation model + (`architecture/validation-model.md`, `plans/000-long-term-specification.md` + §19) requires that invalid evidence be refused rather than normalized or + tolerated. An all-zeros digest is a value that can only mean "no digest". +- **No in-tree producer emits it.** Every in-tree manifest is produced by + Eggpack's own finalization path, which computes digests from real bytes. The + sentinel has no legitimate producer. +- **Downstream compatibility must not break silently.** `eggup-eggpack` parses + published manifests. If the acceptance set tightens, that consumer must be + told, and the compatibility window must be explicit. +- **Schema version discipline.** `ReleaseManifest` is `schema_version: 1`. + Tightening a v1 acceptance rule without a version marker would make two + documents with the same `schema_version` mean different things. + +## 4. Considered options + +### Option A — reject the all-zeros digest everywhere, keep `ReleaseManifest v1` at `schema_version: 1` (recommended) + +Every SHA-256 validator in the workspace — producer-internal and published — +refuses the all-zeros sentinel. The published acceptance set tightens. + +Strengths: + +- one rule, one meaning, across the whole workspace; +- the published manifest stops accepting a value no legitimate producer emits; +- no new schema version, no new field, no wire change; the document shape is + identical and the previously-accepted subset remains valid; +- the "digest was never computed" sentinel can no longer reach a published + asset record. + +Costs and risks: + +- it **is** a narrowing of a published crate's acceptance set, so it is a + compatibility event that must be announced, not a pure refactor; +- a downstream consumer that currently persists an all-zeros digest — for + example as a placeholder during a two-phase upload — would now fail closed. + This is the desired behavior, but it must be surfaced rather than assumed + away. + +### Option B — reject the all-zeros digest in producer-internal paths only; leave the published manifest permissive + +`eggpack-core`, `eggpack-ci`, and `eggpack-github` refuse the sentinel. The +published `ReleaseManifest v1` acceptance set is unchanged, and the divergence +is recorded as a known, documented manifest-side gap. + +Strengths: zero downstream compatibility impact; the defect that can actually +persist bad evidence (the staging crate) is closed. + +Costs: the published schema continues to accept a value that no producer can +emit; the workspace keeps two acceptance sets; the gap survives and must be +re-discovered later. This trades a documented, cheap-to-explain asymmetry for +the disappearance of an asymmetry. + +### Option C — keep all three validators as they are and document the divergence + +Strengths: zero code change, zero compatibility impact. + +Costs: the rule that governs producer evidence remains unenforced in the crate +that publishes it. This is not acceptable under the fail-closed validation model +and is not recommended. + +### Option D — reject the all-zeros digest everywhere and bump `ReleaseManifest` to `schema_version: 2` + +Strengths: the acceptance change is machine-visible rather than implicit. + +Costs: `eggup-eggpack` consumes `schema_version: 1`. A version bump is a +hard breaking change for that consumer and requires coordinated work in the +Eggup repository, which this ADR cannot authorize. The narrowing here does not +justify that cost: every manifest a real producer emits remains valid, so the +version-1 documents in the field continue to parse under a tightened rule. + +## 5. Decision + +**Recommended: Option A — reject the all-zeros digest everywhere, keeping +`ReleaseManifest` at `schema_version: 1`.** + +Concretely, on acceptance: + +1. One shared SHA-256 hex validator is defined in `eggpack-manifest`, which owns + the evidence schema, and is consumed by `eggpack-core`, `eggpack-ci`, and + `eggpack-github`. It accepts exactly 64 lowercase hex characters and rejects + the all-zeros digest. +2. `eggpack-manifest` publishes a new patch release (`0.1.1`) carrying that + rule. The `ReleaseManifest` document shape, field set, and `schema_version` + are unchanged; only the acceptance set tightens. +3. `eggpack-github` and `eggpack-ci` stop carrying private copies of the rule + and delegate to the shared validator. +4. The narrowing is recorded as a compatibility event in the release-manifest + closure record and in `architecture/manifest.md`, naming `eggup-eggpack` as + the affected downstream consumer. +5. `eggup-eggpack` is informed and given the opportunity to pin the new + `eggpack-manifest` patch release. Any change inside the Eggup repository is + authorized by a plan registered **there**, not by this ADR. + +If the maintainers prefer zero downstream compatibility impact, Option B is the +acceptable fallback and is recorded as a known residual gap with a named +follow-on. Option C is rejected. Option D is rejected as disproportionate. + +## 6. Consequences + +- The workspace gains exactly one SHA-256 hex acceptance rule, owned by the + crate that owns the evidence schema, and consumed by every crate that + validates or records a digest. +- `eggpack-github` can no longer persist an all-zeros digest into a staged + asset record. +- The published `ReleaseManifest v1` acceptance set narrows. No document shape, + field, or `schema_version` changes, so no consumer that only reads real + producer output is affected. +- `eggpack-manifest` gains a patch release obligation. It is the only published + crate in the workspace, so this ADR creates the first crate-release event + driven by a producer-internal correctness finding. +- This ADR resolves **only** the digest acceptance set. It does not authorize + any change to the digest *computation* path, the file-digest implementations, + or the release manifest's field set. + +## 7. Compatibility and migration + +- No `ReleaseManifest` document produced by any Eggpack version is affected: + the tightened rule rejects a value no producer emits. +- `eggup-eggpack` is the only known downstream consumer of + `eggpack-manifest 0.1.0`. It must be notified and given the new patch + version; its own repository's planning system authorizes any change there. +- `eggpack-manifest 0.1.0` remains published and resolvable. The change ships + as `0.1.1`. `Cargo.lock` in this workspace is updated by the implementing + milestone, not by this ADR. +- Existing generated workflows are unaffected: no workflow bytes change, so + `eggpack ci check` drift status is unchanged. + +## 8. Security and reliability implications + +- The change strictly narrows what is accepted. It cannot cause a previously + valid real-world document to be rejected, because the rejected value is not a + digest of any byte sequence. +- The residual risk is a consumer that used the all-zeros value as a + placeholder. For that consumer the change turns a silent placeholder into a + fail-closed error, which is the intended direction. The affected consumer is + named in §7 so the transition is announced rather than discovered. +- No new network, credential, archive, publication, or privilege surface is + introduced. No signature, attestation, or provenance claim is made or implied. + +## 9. Verification required for implementation closure + +- a shared validator rejects the all-zeros digest, uppercase hex, wrong length, + non-hex characters, and an empty string; +- the shared validator accepts a real SHA-256 digest of known bytes; +- `eggpack-manifest` rejects an all-zeros digest in `ByteEvidence::validate`; +- `eggpack-github` rejects an all-zeros digest on a staged asset path; +- `eggpack-ci` continues to reject an all-zeros digest; +- every previously valid in-tree manifest fixture still validates; +- `eggpack-manifest` packages and publishes as a patch release; +- full workspace `cargo fmt`, `cargo clippy -- -D warnings`, + `cargo test --workspace --all-targets --all-features --locked`, + `cargo doc --workspace --no-deps --locked`, and `./scripts/check-local.sh` + green; +- hosted CI green on all lanes. + +## 10. Supersession + +Superseded only by a later accepted ADR. diff --git a/plans/adrs/README.md b/plans/adrs/README.md index 09e2cb7..663443a 100644 --- a/plans/adrs/README.md +++ b/plans/adrs/README.md @@ -37,7 +37,11 @@ Use an ADR when a decision establishes ownership, a public compatibility contrac ## Proposed records -None. +- ADR-0006 — release evidence digest acceptance set. Decides whether the + all-zeros SHA-256 sentinel is refused by every producer path and whether the + published `ReleaseManifest` acceptance set narrows, which is a compatibility + change to the published `eggpack-manifest` crate. Gates the + digest-acceptance work package of CI M003l only. ## Accepted records diff --git a/plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md b/plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md new file mode 100644 index 0000000..245ddd8 --- /dev/null +++ b/plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md @@ -0,0 +1,286 @@ +# Build/Qualification M007 — Evidence Digest Unification Corrective + +Status: **ready for implementation**. + +Repository baseline: `eggstack/eggpack@fb81aa1400e1f333f6500075f78d944a9242b673` (2026-10-23). +Source roadmap: `plans/subsystems/build-qualification-roadmap.md`. +Primary class: invariant / integrity-evidence corrective. +Historical upstream authority: ADR-0002 contract/plan/manifest separation; ADR-0005 §9 compatibility-floor evidence boundary (the rule that a digest must describe the bytes it claims to describe). +Affected closed milestones: Build/Qualification M001 (implementation `4eba6ec9422ab01a675ef34cdfc2b9d6f9c0944d`, introduced `crates/eggpack-core/src/lib.rs:291`), Build/Qualification M004 (implementation `661288cee39df3aa81ed5d8a5c3b530ced64788e`, introduced `crates/eggpack-core/src/finalization.rs:482`). Both closures remain historical and are not rewritten. +Dependency: none. This milestone is confined to `crates/eggpack-core/**` and does not touch `crates/eggpack-ci/**`, so it does not contend with CI M003k (in flight, PR `eggstack/eggpack#1`). + +## 1. Objective + +Replace `eggpack-core`'s two divergent file-digest implementations with **one** +canonical bounded digest helper that has exactly one defined behaviour for +symlink rejection, empty-file rejection, size arithmetic, and post-read +stability, and make every core digest call site use it. + +The milestone establishes the canonical helper that +`plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md` +later consumes from `eggpack-ci` and `eggpack-github`. It does **not** itself +change any other crate. + +## 2. Current evidence and the defect + +`eggpack-core` contains two file-digest helpers that were written for different +milestones and never reconciled. + +| | `digest_file` | `digest_regular` | +|---|---|---| +| Location | `crates/eggpack-core/src/lib.rs:291-324` | `crates/eggpack-core/src/finalization.rs:482-512` | +| Introduced by | Build M001, `4eba6ec` | Build M004, `661288c` | +| Symlink rejected before open | yes | yes | +| Empty file rejected **before** reading | no — rejected after reading, at `:319-321` | yes, at `:484` | +| Post-read stability re-check | **no** | yes, at `:503-506` | +| Size arithmetic | `checked_add` | `checked_add` | +| Error type | `CoreError` | `CoreError` | + +The post-read re-check is the material difference. `digest_regular` re-stats the +path after the read and refuses the file if it became a symlink, stopped being a +regular file, or changed length while being read. `digest_file` does not, so a +path replaced between the pre-open `symlink_metadata` check and the open can +produce a digest that describes bytes other than the file that was inspected — +the exact TOCTOU hazard that `digest_file`'s own comment at +`crates/eggpack-core/src/lib.rs:292-296` claims to guard against. + +Two consequences: + +- The manifest that `build_manifest` aggregates at + `crates/eggpack-core/src/lib.rs:181` is built from `digest_file` results, so + the final-bytes evidence record is produced by the weaker of the two helpers. +- The stronger helper already exists in the same crate, so this is a divergence + to be closed, not a new capability to be built. + +## 3. Invariants + +- A recorded digest MUST describe the bytes of the exact regular file that was + inspected. The recorded size and digest MUST be mutually consistent. +- A symlink MUST never be followed, and a file that becomes a symlink, changes + type, or changes length during the read MUST be refused, not digested. +- An empty file MUST be refused before it is read, so a zero-length input can + never produce a digest record. +- Size accumulation MUST be overflow-checked; a size overflow is an error, never + a wrap. +- Digest computation MUST stream through a fixed-size buffer and MUST NOT hold + the whole artifact in memory. A finalized release bundle can be far larger + than the process should grow to accommodate. +- The digest helper MUST NOT change what bytes are hashed. This milestone + changes only *which* helper is used and *what it refuses*, never the hash + function, the encoding, or the lowercase hex representation. +- Determinism is preserved: identical bytes MUST produce an identical digest + and size record, and no error message may embed artifact content. + +## 4. Scope / non-goals + +**In scope:** `crates/eggpack-core/**` only. The canonical helper, the two +retirements, the call sites, and the tests. + +**Out of scope:** + +- the SHA-256 *hex acceptance set* (the validator rule, not the digest + implementation). That is decided by + `plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md` and + implemented by CI M003l. M007 changes **no** acceptance set. +- `crates/eggpack-ci/src/lib.rs:4663` `hash_candidate_file` and + `crates/eggpack-github/src/lib.rs:597` `digest_file`. These are consumers of + the canonical helper and are converged by CI M003l. +- Any change to `ReleaseManifest` v1's fields, `schema_version`, or the + published `eggpack-manifest` crate. +- Any change to archive assembly, sidecar content, or the finalization order. + +## 5. Required production changes + +1. Define one canonical bounded file-digest helper in `eggpack-core`, carrying + the **stricter** of the two current semantics: + - `symlink_metadata` before open; refuse anything that is not a regular + non-symlink file; + - refuse an empty file **before** reading; + - read through a fixed-size buffer; accumulate size with `checked_add`; + - `symlink_metadata` again after the read; refuse if the path became a + symlink, stopped being a regular file, or its length differs from the + number of bytes read; + - return the size and the lowercase hex SHA-256 digest. + + The helper MUST be `pub` so that `eggpack-ci` and `eggpack-github` can + consume it in CI M003l, and MUST return a typed error rather than a + sentinel value. + +2. Retire `crates/eggpack-core/src/lib.rs:291` `digest_file` and + `crates/eggpack-core/src/finalization.rs:482` `digest_regular`. Every core + call site routes to the canonical helper. + +3. The canonical helper's error type MUST distinguish the refusal reasons the + current helpers distinguish, so that no diagnostic becomes vaguer than it + is today. Diagnostics remain single-line and bounded, per the workspace's + diagnostic discipline. + +4. The helper MUST be documented with the TOCTOU rationale that + `crates/eggpack-core/src/lib.rs:292-296` currently carries, so the + protection survives the move. + +## 6. Ordered work packages + +### WP1 — Failing discriminating tests first + +Add tests that fail against the current tree and pass after the change: + +- **Post-read replacement is refused.** Build a file, digest it with the + canonical helper, and prove that the helper's post-read re-check is what + refuses a path that changed length during the read. On platforms where the + race cannot be staged deterministically, assert the *presence* of the + re-check by unit-testing the post-read comparison directly rather than by + racing a thread, and say so in the test comment. +- **A symlink is refused** for both the digest path and the finalization path. +- **An empty file is refused before any read occurs.** +- **Size overflow is an error**, not a wrapped value. +- **Identical bytes produce identical digests** and different bytes produce + different digests, proving the helper did not change the hash semantics. + +Each test MUST fail against the pre-change tree for the reason it exists, not +for an incidental reason. + +### WP2 — Canonical helper + +Implement the canonical helper with the semantics in §5. Keep it in a location +that makes the ownership explicit to `eggpack-ci` and `eggpack-github`, and +document it as the **single** producer-side file-digest authority. + +### WP3 — Retire the duplicates + +Replace both call sites. Grep for remaining uses of the retired names and +confirm zero remain. Confirm no second file-digest implementation survives +inside `eggpack-core`. + +### WP4 — Verification and documentation + +Run the full gate. Update `architecture/core-finalization.md`, +`architecture/core.md`, and `crates/eggpack-core/README.md` to name the +canonical helper and to state the TOCTOU rule once, instead of describing it +in two places. + +## 7. Failure, restart and contention semantics + +- A refused digest is a **hard failure** of the enclosing operation. It is + never downgraded to a warning, never retried against the same path, and + never recorded as an empty digest. +- No partial or placeholder digest is ever emitted. There is no sentinel + success value. +- The helper performs no writes and holds no locks, so concurrent callers are + independent. Two callers digesting the same path concurrently may observe + different results if the file legitimately changes between them; each + observes a self-consistent (size, digest) pair or an error. +- Restarting a failed finalization re-runs the digest from the beginning. There + is no resumable state to corrupt. + +## 8. Compatibility and migration + +- No schema change. `ReleaseManifest` v1 fields, `schema_version`, and the + published `eggpack-manifest` crate are untouched. +- No checked-in document changes meaning. A manifest produced before this + milestone still validates, because the tightened behaviour refuses only + inputs that were previously refused by one of the two helpers anyway. +- The only behavioural narrowing is: a file that changes during the read is now + refused by `build_manifest`'s path as well as by the finalization path. + That is the intended correction and it fails closed. +- No new dependency. `sha2` is already a `eggpack-core` dependency. +- No public binary or library API break beyond the removal of two private + helpers. `eggpack-core` is not published. + +## 9. Required tests + +- unit tests for the canonical helper: regular file, empty file, symlink, + directory, missing path, post-read length change, post-read type change; +- a regression test proving `build_manifest` refuses a finalized file that + changes during the read, where the platform allows deterministic staging; +- a regression test proving the finalization path still produces the same + digest and size for unchanged bytes as before the change — the golden + digests already present in the finalization fixtures MUST be unchanged; +- an explicit test that the digest and size records agree for every artifact in + an aggregated manifest. + +## 10. Verification commands + +```text +cargo fmt --all -- --check +cargo check --workspace --all-targets --all-features --locked +cargo clippy --workspace --all-targets --all-features --locked -- -D warnings +cargo test -p eggpack-core --all-targets --all-features --locked +cargo test --workspace --all-targets --all-features --locked +cargo doc --workspace --no-deps --locked +cargo +1.89.0 check --workspace --all-targets --locked +cargo +1.89.0 test -p eggpack-core --all-targets --locked +./scripts/check-local.sh +``` + +Add a direct narrowed run for the new tests, e.g. +`cargo test -p eggpack-core --all-targets --all-features --locked -- --nocapture`. +On Windows, append `-- --test-threads=1` when diagnosing serialization. + +## 11. Documentation updates + +- `architecture/core-finalization.md` — name the canonical helper and the + TOCTOU rule. +- `architecture/core.md` — update the file/crate line counts if they move. +- `crates/eggpack-core/README.md` — record that core owns the single + producer-side file-digest authority. +- `architecture/overview.md` — its line counts and baseline SHA are already + stale; **do not** re-base them here. Planning Hygiene M003 performs the full + re-base against a measured baseline; this milestone re-verifies the + citations in the sections it touches, by symbol name. See + `plans/implementation/planning-hygiene/003-post-implementation-review-baseline-reconciliation.md`. +## 12. Acceptance criteria + +1. Exactly one file-digest implementation exists in `eggpack-core`, and it is + the one used by `build_manifest` and by finalization. +2. That helper refuses symlinks, empty files, non-regular files, and files that + change during the read; accumulates size with overflow checking; streams + through a fixed-size buffer; and returns a typed error rather than a + sentinel. +3. Every in-tree golden digest in the existing fixtures is unchanged. +4. The regression tests in WP1 fail against the pre-change tree for the reason + they exist, and pass after the change. +5. No acceptance set, schema field, `schema_version`, or published crate + changed. +6. The full workspace gate and `./scripts/check-local.sh` are green, and hosted + CI is green on all lanes. +7. `git diff --check` is clean. + +## 13. Stop conditions + +Stop and re-plan if: + +- unifying the helpers would change any recorded digest or size for unchanged + bytes; +- the post-read re-check proves unstably racy on a supported platform, such + that the helper would refuse a file that did not actually change; +- the canonical helper cannot be exposed to `eggpack-ci` and `eggpack-github` + without changing a published contract; +- any change to `ReleaseManifest` v1, the `eggpack-manifest` crate, or the + archive/sidecar formats appears to be required; +- the work would require touching `crates/eggpack-ci/**` or + `crates/eggpack-github/**`, which belong to CI M003l. + +## 14. Closure evidence + +Write `plans/closure/build-qualification/007-status.md` with: the reviewed +baseline and implementation SHA; the before/after helper inventory; the +regression evidence with exact test names and commands; the golden-digest +unchanged proof; the verification commands executed and their actual results; +hosted CI run IDs and the lane matrix spelled out; an invariant review against +§3; an explicit statement that no acceptance set, schema field, or published +artifact changed; unresolved findings by severity; and the CI M003l unblock. + +The M001 and M004 closure records remain historical and unchanged. + +## 15. Handoff notes + +- Start from `fb81aa1400e1f333f6500075f78d944a9242b673`. +- This milestone is **independent of CI M003k** and may be executed while the + M003k PR is open, because it does not touch `crates/eggpack-ci/**`. +- The canonical helper's public surface is the contract that CI M003l consumes. + Land it with that in mind: name it, document it, and make it the obvious + thing for a downstream crate to call. +- The digest **acceptance set** is not decided here. If ADR-0006 is accepted + before this milestone lands, do **not** implement its rule here; CI M003l + owns it. diff --git a/plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md b/plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md new file mode 100644 index 0000000..aadf9b3 --- /dev/null +++ b/plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md @@ -0,0 +1,433 @@ +# Build/Qualification M008 — Compatibility Floor Verification Corrective + +Status: **blocked** on Build/Qualification M007. + +Repository baseline: `eggstack/eggpack@fb81aa1400e1f333f6500075f78d944a9242b673` (2026-10-23). +Source roadmap: `plans/subsystems/build-qualification-roadmap.md`. +Primary class: capability / evidence-corrective. +Historical upstream authority: ADR-0005 §9 *"Compatibility-floor evidence boundary"* +(`plans/adrs/ADR-0005-native-qualification-for-cross-tool-builds.md:276-286`), +which states that Eggpack's glibc floor is a build-policy input and that +independently verifying the final ELF's required GLIBC symbol versions "is +separate qualification hardening and must be planned independently before +Eggpack claims direct evidence for the floor itself". +Affected closed milestones: Build/Qualification M001 (introduced the +`CompatibilityFloor` policy surface and `validate_policy`), Build/Qualification +M005 (extended the floor semantics to the `CargoZigbuild` triple rewrite), +Build/Qualification M006 (established that native execution is not floor +proof). All three closures remain historical and are not rewritten. +Dependency: **Build/Qualification M007** (`plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md`) +must be closed first, because M008 reuses the canonical file-digest helper M007 +establishes when it records the inspected bytes of a candidate. + +## 1. Objective + +Make the declared compatibility floor a **verified or explicitly unverified +fact** rather than a silently dropped policy input, and implement the +independent verification that ADR-0005 §9 requires before Eggpack claims direct +evidence for a floor. + +Concretely: + +1. Every target that declares a `CompatibilityFloor` MUST carry a + machine-readable **floor verification status** in the producer's own + evidence, distinguishing "the toolchain was bound to this floor" from + "the produced bytes were independently inspected against this floor" from + "this floor was declared and is not independently verified". +2. A declared floor MUST never be silently discarded. Under + `BuildStrategy::NativeCargo` the floor is currently accepted by + `validate_policy` and then has no effect at all; that MUST become visible. +3. Independent verification MUST be implemented where it is technically + possible: a GNU/Linux ELF candidate's required `GLIBC_x.y` symbol versions + are read from the binary and compared against the declared floor. + +## 2. Current evidence and the defect + +### 2.1 The floor is a declared policy surface + +`CompatibilityFloor` (`crates/eggpack-core/src/lib.rs:419-436`) has three +variants: `None`, `Glibc { major, minor }`, and `Macos { major, minor }`. It is +carried on `TargetPolicy.floor` (`crates/eggpack-core/src/lib.rs:454-460`) and +is part of `PackConfig` v1. + +### 2.2 It is enforced in exactly one place + +`validate_policy` (`crates/eggpack-core/src/lib.rs:157-165`) checks only that +the floor is *shape-compatible* with the target triple: + +- `Glibc` requires a `-linux-gnu` triple; +- `Macos` requires an `-apple-darwin` triple. + +The floor is *honored* in exactly one place, `cargo_command` +(`crates/eggpack-core/src/builder.rs:357-367`), and only under +`BuildStrategy::CargoZigbuild`, where the target triple is rewritten to +`..` — the cargo-zigbuild glibc-version-suffix +convention. A `Macos` floor under `CargoZigbuild` is refused outright +(`crates/eggpack-core/src/builder.rs:362-364`). + +**Under `BuildStrategy::NativeCargo`, a declared floor is accepted and then has +no effect whatsoever.** No error, no flag, no check, no record. The floor +survives into the `ReleasePlan` as intent and stops there. + +The workspace already states this boundary correctly in the `TargetPolicy.floor` +doc comment (`crates/eggpack-core/src/lib.rs:456-459`): *"Native qualification +evidence proves that the exact candidate executes on the qualifying native +host; it is not independent proof that the produced binary honours this declared +minimum runtime."* M008 does not contradict that statement — it makes the +unproven floor visible instead of leaving it implicit. + +### 2.3 Nothing records that it went unverified + +- `QualificationEvidence` (`crates/eggpack-core/src/qualification.rs:290-315`) + has no floor field. +- `ReleaseManifest`'s `TargetRecord` + (`crates/eggpack-manifest/src/lib.rs:78-83`) is `{ target, form }` only — no + floor, no qualification method, no toolchain. + +The manifest is final-bytes-only *by design* (ADR-0002), so its silence about +the floor is correct. The problem is that the **plan** carries the declaration +and no artifact anywhere records whether the floor was honored, so "declared +glibc 2.17" and "glibc 2.17 verified" are indistinguishable in every producer +output. + +### 2.4 The repository already names this gap + +`plans/subsystems/build-qualification-roadmap.md:177` states: *"Independent +verification that a produced binary honours a declared glibc/macOS floor remains +unplanned and is not claimed by M006."* ADR-0005 §9 says the same and requires +it to be planned independently. This milestone is that plan. + +### 2.5 The structural reader exists but does not read far enough + +`inspect_candidate` (`crates/eggpack-core/src/qualification.rs:1090-1245`) +reads ELF magic and `e_machine`, PE/COFF headers, and the Mach-O header. It +does **not** read program headers, the dynamic segment, or symbol version +requirements. Independent floor verification therefore requires extending the +reader, not starting one. + +## 3. Invariants + +- A declared compatibility floor is **never silently dropped**. It is either + honored by the toolchain, independently verified against the produced bytes, + or explicitly recorded as unverified. +- Native execution evidence is **never** floor proof. A candidate that runs on + a modern matching host proves execution, not a deployment floor. This is + ADR-0005 §9 and it is restated here because M008 touches exactly this + boundary. +- Floor verification describes **the exact produced bytes**. A verification + result is bound to the candidate's digest and size, so it cannot be carried + across a byte-changing transformation. +- Verification is **fail-closed**: an unreadable, malformed, or ambiguous + binary yields `Unverified` with a reason, never `Verified` and never a + silent pass. +- A verification result MUST NOT claim more than it checked. An ELF with no + `GLIBC_x.y` symbol version requirements is compatible with any floor, and + MUST be recorded as such rather than as "floor 2.17 confirmed". +- The published `ReleaseManifest` v1 is **unchanged**. Publishing floor + evidence to consumers is explicitly out of scope and would need its own ADR. +- A floor declaration remains producer policy. It is never inferred from a + contract, a consumer, or an ambient host. + +## 4. Scope / non-goals + +**In scope:** `crates/eggpack-core/**` and the producer-internal evidence +documents it writes (`ReleasePlan`, qualification evidence). A new floor +verification status, the independent ELF inspection, and the plan/evidence +plumbing that carries it. + +**Out of scope:** + +- any change to `ReleaseManifest` v1, its fields, its `schema_version`, or the + published `eggpack-manifest` crate. Publishing the floor to consumers is a + separate compatibility decision and requires its own ADR. +- Windows/PE/COFF floor verification. PE/COFF has no libc floor concept; + `CompatibilityFloor::Glibc` is already refused for non-GNU/Linux triples and + `Macos` is Darwin-only, so no PE/COFF work is implied. +- macOS Mach-O deployment-target verification. The Mach-O `minos` field is the + natural source, but the first milestone establishes the status model and the + ELF path; Mach-O verification is named as a follow-on, not silently included. +- Changing which floors are *admissible* under `NativeCargo`. See §5 WP2 for + the recommended handling. +- Any change to qualification execution, smoke bindings, host matching, or the + `Qualification` / `QualificationMethod` enums. +- Any consumer-side or product-side change. + +## 5. Required production changes + +### 5.1 A floor verification status + +Introduce a finite, serializable status with at least these meanings: + +| Status | Meaning | +|---|---| +| `NotDeclared` | the target declares `CompatibilityFloor::None` | +| `ToolchainBound` | the floor was bound into the build toolchain (the `CargoZigbuild` triple rewrite) and the toolchain is trusted to honor it | +| `Verified` | the produced bytes were independently inspected and satisfy the declared floor | +| `Unverified` | a floor was declared but could not be independently verified, with a bounded reason | + +The status is finite and closed. It is **not** a free-form string, and it is +not `Option`. + +### 5.2 Where the status lives + +- On `PlannedTarget` / `ReleasePlan`, so the declared floor and its status are + visible in the producer's intent artifact. +- On `QualificationEvidence`, so the produced bytes' floor status is bound to + the evidence for that exact candidate. +- **Not** on `ReleaseManifest`. + +A `ReleasePlan` that declares a floor and does not state a status for it is +invalid. A `QualificationEvidence` whose floor status does not agree with the +plan's declared floor is invalid. + +### 5.3 Independent ELF floor verification + +Extend the existing structural reader to compute, for a GNU/Linux ELF +candidate, the **maximum `GLIBC_x.y` symbol version requirement** present in +the binary's version requirements, and compare it against the declared floor. + +The check must: + +- read the program headers to locate `PT_DYNAMIC`; +- read the dynamic entries for the version-requirement structures; +- collect the `GLIBC_` symbol version names and take the highest `major.minor`; +- treat a candidate with **no** `GLIBC_` version requirement as compatible with + any declared floor, and record that specifically rather than as a generic + pass; +- treat a malformed, truncated, non-ELF, or unreadable binary as + `Unverified` with a reason; +- compare `required_glibc <= declared_floor`, so that a binary requiring a + *newer* glibc than declared **fails** the declared floor. + +The comparison direction matters and must be asserted by a test: a binary +requiring `GLIBC_2.34` does **not** satisfy a declared `2.17` floor. + +All parsing is bounded: fixed maximum header, program-header, and +dynamic-table sizes; every offset is checked against the file length; every +read is exact-length. This matches the existing `MAX_BINARY_HEADER` discipline +at `crates/eggpack-core/src/qualification.rs:1206`. + +### 5.4 The `NativeCargo` case — recommended handling + +Under `BuildStrategy::NativeCargo` the floor cannot be bound into the +toolchain, but it **can** be independently verified from the produced ELF. The +recommended handling is therefore: + +- a declared glibc floor under `NativeCargo` is **accepted**, and the + candidate's floor status is computed by independent inspection; +- the result is `Verified` when the bytes satisfy the floor and `Unverified` + (with a reason) otherwise; +- **a floor that is declared and cannot be verified is not an error** by + itself, because a native build on a floor-matching host legitimately + produces floor-compatible bytes — but the status says so explicitly, and no + downstream artifact may describe it as verified. + +The alternative — refusing a glibc floor under `NativeCargo` outright — is +**not recommended**, because it would reject a legitimate producer +configuration and would break the eggsact-shaped five-target shape already +registered in this repository, where the two GNU/Linux targets declare glibc +2.17 floors. If the maintainers prefer refusal, that is a producer-contract +change and must be recorded as such in the closure record rather than folded +silently into this milestone. + +### 5.5 The floor must be carried, not dropped + +`cargo_command` (`crates/eggpack-core/src/builder.rs:357-367`) continues to +bind the floor into the `CargoZigbuild` triple exactly as it does today, and +continues to refuse a `Macos` floor under `CargoZigbuild` exactly as it does +today. **No existing floor behaviour changes.** What changes is that the +resulting status is now recorded rather than implied. + +## 6. Ordered work packages + +### WP1 — Failing discriminating tests first + +- A `GLIBC_2.34`-requiring ELF against a declared `2.17` floor yields + `Unverified`/floor-not-satisfied, not `Verified`. +- A `GLIBC_2.17`-requiring ELF against a declared `2.17` floor yields + `Verified`. +- An ELF with no `GLIBC_` version requirement against a declared `2.17` floor + yields a distinct "no version requirement" result, not a generic `Verified` + and not an error. +- A truncated, malformed, or non-ELF file yields `Unverified` with a reason, + never `Verified`. +- A `ReleasePlan` that declares a floor but omits a status is rejected. +- A `QualificationEvidence` whose floor status contradicts the plan's declared + floor is rejected. +- A `NativeCargo` target that declares a glibc floor produces a plan that + *records* the floor rather than dropping it — the test asserts the floor is + present in the plan and that a status accompanies it. + +### WP2 — Status model and plumbing + +Define the status type, carry it on the plan and the evidence, and add the +cross-checks that make a missing or contradictory status an error. Validate +that every in-tree `PackConfig`/`ReleasePlan` fixture still resolves. + +### WP3 — ELF floor inspection + +Extend the structural reader to compute the maximum required `GLIBC_x.y` +version. Reuse the existing bounded-header discipline and the existing +`CandidateFormat::Elf` path. The inspection runs against the exact candidate +bytes, and its result is bound to the candidate's digest and size. + +### WP4 — Wiring the status through qualification + +`qualify_target` records the floor status for the candidate it inspected. The +status is computed from the bytes actually qualified, so it cannot be carried +across a byte-changing transformation. + +### WP5 — Verification and documentation + +Run the full gate. Update `architecture/core-qualification.md`, +`architecture/core-planning.md`, `architecture/core-build.md`, +`crates/eggpack-core/README.md`, the build/qualification roadmap, and the +registry. State the ADR-0005 §9 boundary explicitly in the new documentation +rather than leaving it implied. + +## 7. Failure, restart and contention semantics + +- An unverifiable floor is a **recorded status**, not a hard failure of the + release. A hard failure here would break every producer that declares a + floor without an inspectable binary, which is a wider behavioural change + than this milestone authorizes. +- A floor that is declared and **contradicted** by the bytes — the binary + requires a newer glibc than declared — is a hard failure of the + qualification for that target, because the declared floor is then false. + This case MUST fail closed and MUST NOT be reported as `Unverified`. +- The inspection is read-only and holds no lock. Two concurrent inspections of + the same candidate observe the same bytes or a changed-file error; each + observation is self-consistent. +- Restarting re-inspects from the beginning. No resumable state exists. + +## 8. Compatibility and migration + +- No change to `ReleaseManifest` v1: no field added, no field removed, no + `schema_version` bump. The published `eggpack-manifest` crate is untouched + and needs no new release. +- `PackConfig` v1 accepts the same documents it accepts today. A target that + declares a glibc floor under `NativeCargo` still resolves; it now carries a + status. +- No checked-in workflow changes, so `eggpack ci check` drift status is + unchanged for existing consumers. Consumers that adopt the new plan or + evidence shape must re-render and re-pin, which the closure record must + state. +- No new dependency. ELF parsing is done with the existing standard-library + and `sha2` surface; no external ELF crate is introduced, to keep the + dependency and supply-chain footprint unchanged. +- `eggup-eggpack` is unaffected: it reads `ReleaseManifest`, which does not + change. + +## 9. Required tests + +- unit tests for the version-requirement reader: minimal valid ELF, ELF with + multiple `GLIBC_` versions, ELF with no version requirements, truncated + dynamic table, truncated program headers, out-of-range offsets, 32-bit and + 64-bit endianness, non-ELF input; +- comparison-direction tests: required newer than declared fails; required equal + to declared passes; required older than declared passes; +- bound tests: an oversized program-header count or dynamic-entry count is + refused rather than parsed; +- plan and evidence validation tests for a missing, contradictory, or + impossible status; +- a regression test that a `NativeCargo` target with a declared glibc floor + still resolves and still produces a valid plan; +- a regression test that the `CargoZigbuild` triple rewrite at + `crates/eggpack-core/src/builder.rs:358-367` is byte-unchanged, and that the + `Macos`-under-zigbuild refusal is unchanged. + +## 10. Verification commands + +```text +cargo fmt --all -- --check +cargo check --workspace --all-targets --all-features --locked +cargo clippy --workspace --all-targets --all-features --locked -- -D warnings +cargo test -p eggpack-core --all-targets --all-features --locked +cargo test --workspace --all-targets --all-features --locked +cargo doc --workspace --no-deps --locked +cargo +1.89.0 check --workspace --all-targets --locked +cargo +1.89.0 test -p eggpack-core --all-targets --locked +./scripts/check-local.sh +``` + +Add a direct narrowed run for the new tests, e.g. +`cargo test -p eggpack-core --all-targets --all-features --locked -- --nocapture`. +Append `-- --test-threads=1` when diagnosing Windows serialization. + +## 11. Documentation updates + +- `architecture/core-qualification.md` — the floor status in evidence, and the + ADR-0005 §9 boundary restated. +- `architecture/core-planning.md` — the floor status on the plan. +- `architecture/core-build.md` — the toolchain-bound case. +- `architecture/overview.md` — line counts and baseline SHA are already stale + and are **not** re-based here; see + `plans/implementation/planning-hygiene/003-post-implementation-review-baseline-reconciliation.md`. +- `crates/eggpack-core/README.md` — the floor status model. +- `plans/subsystems/build-qualification-roadmap.md` — the M008 row and the + removal of the "remains unplanned" sentence at `:177`. + +## 12. Acceptance criteria + +1. Every target that declares a `CompatibilityFloor` carries a finite, + machine-readable floor status on the plan and on the qualification evidence, + and a missing or contradictory status is a validation error. +2. The floor is no longer silently dropped under `NativeCargo`; the declared + floor and its status are both present in the producer's artifacts. +3. A GNU/Linux ELF candidate's maximum required `GLIBC_x.y` version is computed + by bounded inspection, and compared against the declared floor in the + correct direction, with a binary requiring a newer glibc than declared + failing closed. +4. A malformed or unreadable binary yields `Unverified` with a reason, never + `Verified`. +5. `ReleaseManifest` v1 and the published `eggpack-manifest` crate are + unchanged: no field, no `schema_version`, no release. +6. The `CargoZigbuild` triple rewrite and the `Macos`-under-zigbuild refusal + are byte-unchanged. +7. The full workspace gate and `./scripts/check-local.sh` are green, and hosted + CI is green on all lanes. +8. `git diff --check` is clean. + +## 13. Stop conditions + +Stop and re-plan if: + +- independent floor verification would require publishing the floor in + `ReleaseManifest` (that is an ADR-triggering compatibility decision, not + this milestone); +- the ELF inspection cannot be made bounded and fail-closed; +- the status model would have to become a free-form string or an open enum; +- a `NativeCargo` glibc floor must be **refused** rather than recorded + unverified, because that is a producer-contract change that needs its own + decision; +- the work would require a new external dependency; +- any change to qualification execution, host matching, or the + `Qualification`/`QualificationMethod` enums appears to be required. + +## 14. Closure evidence + +Write `plans/closure/build-qualification/008-status.md` with: the reviewed +baseline and implementation SHA; the exact status model and its mapping from +the four statuses to concrete binary observations; the inspection evidence with +exact test names and commands; the bound-proving evidence for the ELF reader; +the regression proof that the zigbuild triple rewrite and the macOS refusal are +unchanged; the explicit statement that `ReleaseManifest` v1 and the published +crate are unchanged; verification commands executed and their actual results; +hosted CI run IDs and the lane matrix; an invariant review against §3; the +disposition of the §5.4 alternative if the maintainers chose refusal rather +than recording; unresolved findings by severity — including the named Mach-O +and PE/COFF follow-ons; and the roadmap and registry updates. + +The M001, M005, and M006 closure records remain historical and unchanged. + +## 15. Handoff notes + +- Start from the M007 closure SHA, not from `fb81aa1400e1f333f6500075f78d944a9242b673`. + M008 reuses M007's canonical digest helper to bind the inspected bytes. +- The Mach-O deployment-target verification is a **named follow-on**, not an + implicit omission. Record it as such in the closure record's unresolved + findings. +- Publishing floor evidence to consumers is a **named follow-on** requiring its + own ADR. Do not add a floor field to `ReleaseManifest` under this plan. +- This milestone changes what Eggpack can *prove*, not what it produces. A + release produced before it remains valid and unchanged. diff --git a/plans/implementation/build-qualification/009-local-producer-operator-commands.md b/plans/implementation/build-qualification/009-local-producer-operator-commands.md new file mode 100644 index 0000000..a150022 --- /dev/null +++ b/plans/implementation/build-qualification/009-local-producer-operator-commands.md @@ -0,0 +1,423 @@ +# Build/Qualification M009 — Local Producer Operator Commands + +Status: **ready for implementation**. + +Repository baseline: `eggstack/eggpack@fb81aa1400e1f333f6500075f78d944a9242b673` (2026-10-23). +Source roadmap: `plans/subsystems/build-qualification-roadmap.md`. +Primary class: capability / specification-gap corrective. +Historical upstream authority: `plans/000-long-term-specification.md` §5.4 +`eggpack-cli` (`:171-185`), which names the intended operator surface and +requires that *"CLI commands MUST distinguish validation, build, staging, and +publication. A command that mutates a public release MUST be explicit."* +Also `plans/subsystems/build-qualification-roadmap.md` §11 completion +definition: *"Eggpack can construct and qualify real direct/bundle/archive +native releases **locally** or via accepted backend with accurate evidence +classification."* +Dependency: none that blocks execution. Contract M001/M002/M003, Release +Manifest M001/M001a/M002/M003a, and Build/Qualification M001–M006 are all +closed, so the underlying APIs are stable. This milestone does not touch +`crates/eggpack-ci/**`, so it does not contend with CI M003k (in flight). + +## 1. Objective + +Restore the operator surface the canonical specification names, so a producer +can construct, qualify, finalize, and aggregate a real release **on a +workstation**, without a GitHub Actions run and without the `ci _*` internal +runner family. + +Specifically, add six top-level local commands: + +| Command | Class | Produces | +|---|---|---| +| `eggpack check` | validation | a validation verdict over contract, policy, and bindings | +| `eggpack plan` | validation | a `ReleasePlan` (intent) | +| `eggpack package` | build | build candidates | +| `eggpack qualify` | build | qualification evidence | +| `eggpack collect` | release aggregation | a finalized release tree | +| `eggpack manifest` | final-bytes evidence | a `ReleaseManifest` v1 | + +Each command is deterministic wiring over an already-closed `eggpack-core` API. +None adds a schema, a template grammar, a discovery mechanism, a network call, +or a release-selection policy. + +## 2. Current evidence and the gap + +### 2.1 The specification names nine commands; seven do not exist + +`plans/000-long-term-specification.md:171-185` gives the operator surface as: + +```text +check +plan +package +qualify +collect / release aggregation +manifest +installer generate/check +ci generate/check +staging/draft-release commands when later enabled +``` + +The CLI's actual top-level dispatch (`crates/eggpack-cli/src/main.rs:35-41`) +accepts exactly two families — `ci` and `contract`: + +```rust +match args[0].as_str() { + "ci" => ci_dispatch(&args[1..]), + "contract" => contract_dispatch(&args[1..]), + other => Err(format!("unknown command {other:?}: expected 'ci' or 'contract'\n{USAGE}\n{CTRACT_USAGE}")), +} +``` + +`ci generate` and `ci check` exist. `ci` also carries the nine internal +`ci _*` runners (`crates/eggpack-cli/src/main.rs:52-71`). `contract expand` +exists (Contract M003). **`check`, `plan`, `package`, `qualify`, `collect`, and +`manifest` do not exist at all**, and `installer generate/check` does not exist. + +### 2.2 The pipeline stages are reachable only through internal runners + +`crates/eggpack-cli/src/main.rs` exposes the build, qualification, and +aggregation stages solely as `ci _capture-build`, `ci _qualify-target`, +`ci _evaluate-gate`, `ci _aggregate`, and their siblings. Those are, by the +repo's own definition, *"file-in/file-out wrappers, not a scripting interface"* +(`AGENTS.md`, and `crates/eggpack-cli/README.md:8`). + +That design is correct for what it is: the generated workflow needs a +deterministic, file-in/file-out step protocol that a YAML runner can invoke. +It is the wrong surface for a human operator, because: + +- the caller must hand-assemble a specific directory layout and a specific set + of intermediate files for each stage, with no command that validates the + layout or reports what is missing; +- the stages are named after their *workflow step*, not after what they do, and + the naming leaks the internal protocol into the operator's vocabulary; +- the workflow steps and the operator actions cannot share an implementation, + so the operator path would be a second, divergent implementation of the same + pipeline — precisely the class of duplication CI M003l/M003n are removing + elsewhere. + +### 2.3 The documented local path stops before the pipeline + +`docs/quickstart.md` walks resolve → generate → check and then states at +`:216-217`: *"After planning come build → qualify → finalize → stage; the +generated workflow replays exactly these steps in CI."* There is no documented +way to run those steps locally. A producer cannot rehearse a release on a +workstation, cannot reproduce a CI failure locally, and cannot inspect a +finalized tree without a hosted run. + +### 2.4 The specification's command-class requirement is not yet met + +`plans/000-long-term-specification.md:185` requires that CLI commands +distinguish **validation, build, staging, and publication**, and that a command +mutating a public release be explicit. Today the `ci _*` family collapses +build, qualification, aggregation, and staging into one flat namespace of +underscore-prefixed names. The taxonomy the specification asks for does not +exist in the command surface. + +## 3. Invariants + +- The CLI remains **deterministic wiring only**. No new dependency, no `clap`, + no template grammar, no serialized model, no repository discovery, no + network, no release selection, no consumer policy. +- Each new command is **deterministic**: identical inputs produce byte-identical + outputs, and the same bounded-reader/bounded-writer helpers the existing + commands use are reused unchanged. +- The command taxonomy maps onto the specification's four classes — + validation, build, staging, publication — and each command declares its + class in `--help`. **No new command in this milestone performs staging or + publication**, so no command in this milestone can mutate a public release. +- The `ci _*` runner family keeps working **byte-for-byte**. Generated + workflows depend on its exact argument surface and exit discipline, and this + milestone must not perturb a single generated byte. +- The new commands are **thin**: they select and validate inputs, call one + `eggpack-core` API, and write one artifact. They contain no pipeline logic of + their own. The pipeline logic lives in `eggpack-core`, which owns it. +- Failure is fail-closed and single-line: exit non-zero with one + `eggpack: ` diagnostic on stderr, and nothing on stdout. +- Every new command is **local-only**: it reads and writes local paths, spawns + no network activity, and performs no repository discovery beyond the + explicit `--source-root`/`--source-revision` binding that already exists. +- Producer/consumer ownership is preserved: this milestone adds producer + operations. It does not add installation, update, rollback, receipt, or + latest/exact selection semantics, which remain Eggup's and the product's. + +## 4. Scope / non-goals + +**In scope:** `crates/eggpack-cli/**` — the six new top-level commands, their +argument parsing, their `--help` text, their tests, and the CLI README. Plus +the minimal `eggpack-core` API surface changes needed to let a caller perform +each stage from the command line (for example, exposing a stage that is today +only reachable through a CI runner's file protocol). + +**Out of scope:** + +- `installer generate/check`. The Bootstrap subsystem owns installer + rendering; a separate Bootstrap milestone must own that command. This + milestone must not render installers. +- `eggpack stage` and any staging/draft-release command. Staging writes to + GitHub, and publication authority is gated by ADR-0003. The staging + capability exists today as `ci _prepare-stage` and `ci _stage-github-draft`; + exposing a user-facing staging command is a separate decision with its own + evidence bar, because it is the first operator command with a credential and + a network effect. +- Any change to the `ci _*` runners' behaviour, arguments, or output bytes. +- Any change to `ReleaseManifest` v1, `PackConfig` v1, `CIPlan` v1, or any other + schema. +- Any change to `eggpack-core`'s pipeline semantics, evidence semantics, or + validation rules. This milestone adds an *entry point*, not behaviour. +- Release selection, "latest" resolution, version comparison, Cargo fallback, + or any other consumer policy. +- A general configuration or workflow language. + +## 5. Required production changes + +### 5.1 The command set and its classes + +Each command is specified by behaviour, not by an exact flag list. The +following names and classes are required; the flag surface follows the +existing convention of `--flag value` and `--flag=value`, each flag required +exactly once, with unknown flags, duplicate flags, empty values, and +positional arguments rejected. + +| Command | Class | Primary inputs | Primary output | +|---|---|---|---| +| `eggpack check` | validation | contract, pack-config, build bindings, qualification bindings | a verdict; non-zero on any violation | +| `eggpack plan` | validation | contract, pack-config, bindings, selected targets, release id, source revision | `ReleasePlan` JSON | +| `eggpack package` | build | plan, bindings, source root | build candidates under a caller-named output root | +| `eggpack qualify` | build | plan, bindings, candidates, host | qualification evidence JSON | +| `eggpack collect` | release aggregation | plan, qualified candidates | a finalized release tree | +| `eggpack manifest` | final-bytes evidence | contract, finalized tree | `release-manifest.json` | + +`eggpack plan` and `eggpack collect` are the two commands that must reflect +the existing `_resolve-release` and `_aggregate` behaviour closely enough that +the same inputs yield the same artifacts. Where a `ci _*` runner already +performs a stage, the new command and the runner MUST call the **same** +`eggpack-core` function. Two implementations of a stage is exactly the +duplication this milestone exists to prevent. + +### 5.2 Reuse, not reimplementation + +- The bounded non-symlink reader (`crates/eggpack-cli/src/main.rs:553` + `read_bounded`), the symlink-rejecting output writer (`:581` + `reject_symlink_output`, `:617` `atomic_write`), and the single-line failure + discipline are reused unchanged. +- The `eggpack ci generate` / `ci check` / `contract expand` paths are + untouched. +- Where `eggpack-core` currently exposes a stage only as an internal or + CI-shaped function, the minimal public surface is added so both the `ci _*` + runner and the new operator command call it. This is a visibility change, not + a behaviour change. + +### 5.3 Command-class visibility + +`--help` states each command's class (validation / build / release +aggregation / final-bytes evidence) and states plainly that no command in this +set stages or publishes. This is the specification's `:185` requirement +expressed at the surface where an operator reads it. + +### 5.4 Exit discipline + +Every command exits `0` on success and `1` on failure with exactly one +`eggpack: ` line on stderr and an empty stdout. No command may print +a partial artifact before failing. + +## 6. Ordered work packages + +### WP1 — Failing discriminating tests first + +Integration tests that fail against the current tree: + +- `eggpack check` on a valid contract/policy/binding set exits `0`; on a + contract with an unknown field, a wrong `schema_version`, an uncovered + target, or an extra binding, it exits non-zero with one bounded diagnostic + and an empty stdout; +- `eggpack plan` on the same inputs produces a `ReleasePlan` that is + **byte-identical** to the plan the existing `ci _resolve-release` produces + from the same inputs; +- `eggpack package` → `eggpack qualify` → `eggpack collect` → `eggpack + manifest` produces a `release-manifest.json` that is byte-identical to the + one the existing `ci _aggregate` produces from the same inputs; +- every command rejects an unknown flag, a duplicate flag, an empty value, a + positional argument, a symlinked output path, and an oversized input; +- every command writes nothing to stdout on failure; +- `--help` names each command and states its class. + +### WP2 — Minimal `eggpack-core` surface + +Expose, or add thin wrappers for, the core functions the six commands need so +that the `ci _*` runners and the new commands call the same code. No pipeline +logic is written in the CLI. + +### WP3 — Command implementations + +Implement the six commands as thin, deterministic wiring. Each parses and +validates its arguments, calls one core API, and writes one artifact through +the existing bounded writer. + +### WP4 — Command taxonomy in `--help` + +Restructure `USAGE` (`crates/eggpack-cli/src/main.rs:45`) to show the command +families and their classes, while keeping the existing `ci` and `contract` +usage text intact so no documented invocation changes meaning. + +### WP5 — Documentation + +Rewrite `docs/quickstart.md` to walk the **local** path end to end — +`check` → `plan` → `package` → `qualify` → `collect` → `manifest` — with every +command and its expected output run verbatim, per the quickstart's existing +contract. Keep the existing CI rendering and drift-check sections. Update +`crates/eggpack-cli/README.md` to become the actual full command reference +that `docs/quickstart.md:212` already promises, including the `ci _*` runner +flag surface. Update `architecture/cli.md`. + +## 7. Failure, restart and contention semantics + +- Every command is fail-closed: on any validation failure it writes no + artifact and exits non-zero. +- A command that writes an artifact writes it atomically through the existing + `atomic_write`, so a failed run never leaves a partial file where a + complete one is expected. +- A command never overwrites an existing artifact silently. It either refuses + or replaces atomically, matching the existing `ci generate` behaviour + explicitly, and the choice is documented per command. +- Local outputs are written under a caller-named root. The caller owns that + root; Eggpack does not create or delete it outside the explicit output + paths. +- Restarting a failed stage re-runs it from its inputs. There is no resumable + state. +- Two concurrent runs against different output roots are independent. Two + concurrent runs against the same output root are the caller's responsibility, + and the atomic writer is the only guarantee offered. + +## 8. Compatibility and migration + +- **No generated workflow byte changes.** The `ci _*` runner arguments, exit + discipline, and diagnostics are unchanged, so `eggpack ci check` drift status + is unchanged for every existing consumer. +- No schema change of any kind: `ReleasePlan`, `CIPlan`, `PackConfig`, + `DistributionContract`, and `ReleaseManifest` v1 are unchanged. +- No new dependency. `eggpack-cli` already depends on `eggpack-core`, + `eggpack-contract`, `eggpack-manifest`, and `serde_json`. +- The `eggpack` binary's existing invocations keep working unchanged. The + error text for an unknown top-level command changes, because the set of + known commands changes; that message is a diagnostic, not a contract, and the + change is recorded here. +- `eggup-eggpack` and every consumer are unaffected: no manifest changes. + +## 9. Required tests + +- per-command argument validation tests: missing flag, duplicate flag, unknown + flag, empty value, positional argument, `--flag=value` form; +- per-command symlink and oversized-input refusal tests; +- the byte-identity tests from WP1 against the corresponding `ci _*` runner + outputs; +- a process-boundary test that each command's stdout on success is exactly + what is documented, and is empty on failure; +- a test that `eggpack ci generate`, `eggpack ci check`, and `eggpack contract + expand` still behave exactly as before, including their documented outputs; +- an exit-code test asserting `0` on success and `1` on failure for every + command. + +## 10. Verification commands + +```text +cargo fmt --all -- --check +cargo check --workspace --all-targets --all-features --locked +cargo clippy --workspace --all-targets --all-features --locked -- -D warnings +cargo test -p eggpack-cli --all-targets --all-features --locked +cargo test --workspace --all-targets --all-features --locked +cargo doc --workspace --no-deps --locked +cargo +1.89.0 check --workspace --all-targets --locked +cargo +1.89.0 test -p eggpack-cli --all-targets --locked +./scripts/check-local.sh +``` + +Add a direct narrowed run for the new tests, e.g. +`cargo test -p eggpack-cli --all-targets --all-features --locked -- --nocapture`. + +The closure record must additionally record the **verbatim** quickstart +walkthrough, with the actual observed output of every command, since +`docs/quickstart.md` is contractually a document of verified commands. + +## 11. Documentation updates + +- `docs/quickstart.md` — the local end-to-end path, with every command run + verbatim and its real output quoted. +- `crates/eggpack-cli/README.md` — the actual full command reference, + including the `ci _*` runner flag surface it currently only summarizes in + prose. +- `architecture/cli.md` — the new operator surface, the command taxonomy, and + the explicit statement that this milestone adds no staging or publication + command. +- `architecture/overview.md` — line counts and baseline SHA are already stale + and are **not** re-based here; see + `plans/implementation/planning-hygiene/003-post-implementation-review-baseline-reconciliation.md`. +- `plans/subsystems/build-qualification-roadmap.md` — the M009 row. + +## 12. Acceptance criteria + +1. Six new top-level commands exist: `check`, `plan`, `package`, `qualify`, + `collect`, `manifest`. Each is documented in `--help` with its class. +2. `eggpack plan` and `eggpack collect` produce byte-identical artifacts to + the existing `ci _resolve-release` and `ci _aggregate` for identical inputs, + and this is proven by test, not by assertion. +3. The `ci _*` runner family is unchanged in behaviour, arguments, and output + bytes; no generated workflow changes; `eggpack ci check` drift status is + unchanged. +4. Every command exits `0` on success and `1` on failure with exactly one + `eggpack: ` line on stderr and an empty stdout on failure. +5. Every command refuses a symlinked output path and an oversized input, using + the existing bounded helpers. +6. No new dependency, no `clap`, no schema change, no template grammar, no + network, no discovery, no release selection. +7. `docs/quickstart.md` documents the local path end to end with verbatim + verified commands and outputs, and `crates/eggpack-cli/README.md` is a + complete command reference. +8. The full workspace gate and `./scripts/check-local.sh` are green, and hosted + CI is green on all lanes. +9. `git diff --check` is clean. + +## 13. Stop conditions + +Stop and re-plan if: + +- any existing `ci _*` runner's behaviour, arguments, diagnostics, or output + bytes would change; +- any generated workflow byte would change; +- a new command would require a schema change, a new dependency, a network + call, repository discovery, or release-selection policy; +- a new command would stage or publish anything; +- the six commands cannot be implemented as thin wrappers over already-closed + `eggpack-core` APIs, because that would mean duplicating pipeline logic in + the CLI; +- the quickstart's documented outputs cannot be produced verbatim on all four + supported platforms, because the quickstart is a verified document and a + platform-specific variant would require a separate decision. + +## 14. Closure evidence + +Write `plans/closure/build-qualification/009-status.md` with: the reviewed +baseline and implementation SHA; the command inventory with each command's +class; the byte-identity evidence between the new commands and the `ci _*` +runners, with exact test names; the verbatim quickstart walkthrough with the +actual observed output of every command on every supported platform; the +verification commands executed and their actual results; hosted CI run IDs and +the lane matrix; the explicit statement that no generated workflow byte and no +schema changed; an invariant review against §3; unresolved findings by +severity; and the named follow-ons — Bootstrap installer commands, the +user-facing staging command, and the ADR-0003 publication gate. + +## 15. Handoff notes + +- Start from `fb81aa1400e1f333f6500075f78d944a9242b673`. +- This milestone is independent of CI M003k and of the CI M003l/M003m/M003n + chain. It does not touch `crates/eggpack-ci/**`. +- If CI M003l lands first and moves pipeline stages into `eggpack-core` + behind shared functions, this milestone should consume those shared + functions rather than re-exposing them. Re-baseline before implementing if + the core surface moved. +- The `installer generate/check` and staging commands named by + `plans/000-long-term-specification.md:175-183` remain **unimplemented** + after this milestone. Record that explicitly in the closure record's + unresolved findings rather than leaving it implicit — the specification + names nine commands and this milestone delivers six of the nine. diff --git a/plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md b/plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md new file mode 100644 index 0000000..dbb3479 --- /dev/null +++ b/plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md @@ -0,0 +1,443 @@ +# CI/Release M003l — Producer Rule Authority Convergence Corrective + +Status: **blocked** on CI M003k merge, and on ADR-0006 for the digest-validator work package. + +Repository baseline: `eggstack/eggpack@fb81aa1400e1f333f6500075f78d944a9242b673` (2026-10-23). +Source roadmap: `plans/subsystems/ci-release-orchestration-roadmap.md`. +Primary class: invariant / correctness corrective. +Historical upstream authority: ADR-0002 contract/plan/manifest separation (no layer redefines another's rules); ADR-0003 checked-in generated CI and publication gate. +Affected closed milestones: CI M001 (implementation `5e79f0b91b478f766124224c1e9c6382778fef14`, introduced the CI-side host-match rule), Build/Qualification M001 (introduced core's `validate_policy`), Build/Qualification M005 (implementation `7a206ba73e986352410f94b34c7c616c1ea26019`, introduced the CI-side SHA-256 hex validator), CI M003a (implementation `36f1cc1c96cf72511bbdadc2c480cdd0934a4fc9`, introduced the GitHub-side SHA-256 hex validator and the GitHub-side file digest), CI M003d (implementation `946dd7a827fcbf7552721ed162972ae5ae78b5f2`, introduced the CI-side file digest and the CI-side exact-tag validator), CI M003i (implementation `3ddac9d84fc2e10b8451d38672f66b02e06724df`, introduced core's git tag path validation). All closures remain historical and are not rewritten. +Dependency: **CI M003k** must be merged first — it is in flight (PR `eggstack/eggpack#1`) and modifies `crates/eggpack-ci/src/lib.rs`. This milestone also requires **Build/Qualification M007** for the canonical file-digest helper that `eggpack-ci` and `eggpack-github` consume. + +## 1. Objective + +Make `eggpack-core` the single authority for the producer rules that +`eggpack-ci` currently re-derives, and remove the divergent second definitions +of those rules. + +After this milestone: + +- host/target matching has one implementation; +- compatibility-floor applicability has one implementation; +- exact-tag safety has one implementation, whose rule set is the union of the + safety concerns that today exist in two partial forms; +- the SHA-256 hex acceptance set has one implementation, per ADR-0006; +- the file digest has one implementation, per Build/Qualification M007. + +## 2. Current evidence and the defects + +### 2.1 Host/target matching is implemented twice + +| Site | Location | Visibility | +|---|---|---| +| core | `crates/eggpack-core/src/lib.rs:84-96` `host_matches_target` | private | +| ci | `crates/eggpack-ci/src/lib.rs:423-435` `host_matches_target` | private | + +The two are semantically identical — same architecture prefixes +(`x86_64-`, `aarch64-`, `armv7-`), same OS predicates (`-linux-`, +`-apple-darwin`, `-windows-`) — and differ only in local variable names. The CI +copy exists because the core copy is private. + +This rule is the **host-matched native qualification** gate that ADR-0005 +established. It now has two implementations, one of which is a copy. The CI +copy is the one that gates the generated workflow, so a future change to the +core copy would leave the workflow gating on the stale rule. + +### 2.2 Compatibility-floor applicability is implemented twice + +| Site | Location | +|---|---| +| core | `crates/eggpack-core/src/lib.rs:157-165`, inside `validate_policy` | +| ci | `crates/eggpack-ci/src/lib.rs:316-320` and `:337-338`, inside `CIPlan::validate` | + +Both derive the same rule: `Glibc` requires a `-linux-gnu` triple, `Macos` +requires an `-apple-darwin` triple, and a `Macos` floor is incompatible with +`CargoZigbuild`. The CI copy additionally re-derives the toolchain-validity +predicate and the native-qualification host check at +`crates/eggpack-ci/src/lib.rs:299-331`. + +`CIPlan::validate` is a *second* policy validator, not an independent +opinion. It exists because `validate_policy` is private. + +### 2.3 Exact-tag safety has two partial, non-overlapping rule sets + +| | core | ci | +|---|---|---| +| Site | `crates/eggpack-core/src/builder.rs:427-441` | `crates/eggpack-ci/src/lib.rs:4940-4954` | +| Introduced by | CI M003i (`7c20b68`) | CI M003d (`946dd7a`) | +| Empty / > 128 / control char | rejected | rejected | +| `?`, space, `\` | rejected | rejected | +| `..` | rejected | rejected | +| Leading / trailing `/` | rejected | rejected | +| `#`, `@`, `'`, `"`, `` ` ``, `$` | **allowed** | rejected | +| trailing `.`, `@{`, `^`, `:`, `*`, `[`, `~` | rejected | **allowed** | +| empty, `.`-leading, or `.lock` path component | rejected | **allowed** | + +**Neither rule set is a superset of the other.** A tag containing `$` or `#` +is refused by the CI path and accepted by the core git-resolution path. A tag +containing `~` or a `.lock` component is refused by the core path and accepted +by the CI path. + +The two rules were written for **different concerns**, and both concerns are +legitimate: + +- core's rule guards a tag used as a **git ref path** in + `git rev-parse --verify refs/tags/^{commit}` + (`crates/eggpack-core/src/builder.rs:442-451`); +- ci's rule guards a tag arriving from a **workflow dispatch input**, which + M003j made a data value in a shell environment + (`plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md`). + +The defect is not that the concerns differ. It is that neither component holds +the **union**, so a tag safe under one concern is accepted without the other +concern's checks. The correct outcome is one canonical *safety* validator +carrying the union of both concern sets, applied wherever an exact tag is +handled, with the separate *canonical-format* check (M003j's `vX.Y.Z` form) +kept as a distinct, named concern layered on top. + +### 2.4 The SHA-256 hex acceptance set has three implementations + +| Site | Location | Rule | +|---|---|---| +| manifest | `crates/eggpack-manifest/src/lib.rs:307-322` | 64 lowercase hex | +| github | `crates/eggpack-github/src/lib.rs:567-576` | 64 lowercase hex | +| ci | `crates/eggpack-ci/src/lib.rs:632-642` | 64 lowercase hex, and not all-zeros | + +The all-zeros digest is refused by CI and accepted by the manifest and by +`eggpack-github` — the crate that computes and records digests over the bytes +actually staged into a draft release. The decision on which rule wins is +**ADR-0006**, which is proposed, not accepted. + +### 2.5 The file digest has four implementations + +| Site | Location | Notable | +|---|---|---| +| core | `crates/eggpack-core/src/lib.rs:291-324` | no post-read re-check | +| core | `crates/eggpack-core/src/finalization.rs:482-512` | post-read re-check | +| github | `crates/eggpack-github/src/lib.rs:597-628` | post-read re-check | +| ci | `crates/eggpack-ci/src/lib.rs:4663-4695` | returns `(0, String::new())` on error; unchecked `size +=` | + +The CI copy is the weakest: it converts every failure — unreadable file, +symlink, empty file, read error — into `(0, String::new())`, and a caller +comparing against the empty string cannot distinguish "no digest" from "no +file". It is also the only one using unchecked size accumulation. + +Build/Qualification M007 establishes the canonical helper in core; this +milestone makes CI and GitHub consume it. + +## 3. Invariants + +- **One rule, one owner.** A producer rule has exactly one implementation. A + downstream crate that needs the rule calls the owner's function; it does not + restate the rule. +- `eggpack-core` owns producer policy validation. `eggpack-ci` owns workflow + projection and rendering. `eggpack-ci` validates a `CIPlan` against the + producer's own rules by **calling** those rules, not by re-deriving them. +- Exact-tag handling is **fail-closed**: a tag is accepted only if it passes + every applicable safety concern. The canonical safety validator carries the + union of the git-ref-path concerns and the shell-metacharacter concerns. +- The canonical **format** check (M003j's `vX.Y.Z` form) remains a separate, + named concern, distinct from safety. A tag that is safe but not canonical is + rejected by the format check, not by the safety check, and the diagnostic + says which one failed. +- The generated workflow's behaviour is **unchanged** by this milestone. Every + tag the current pipeline accepts is still accepted, and every tag it refuses + is still refused, with the same pass/fail outcome. Only the *rule location* + changes. The one intended difference is that a tag now satisfies the union + of both safety concerns in both places — this can only refuse more, never + accept more. +- No public schema changes. `ReleaseManifest` v1, `CIPlan` v1, `PackConfig` + v1, and `DistributionContract` v1 are unchanged, except where ADR-0006 + explicitly authorizes a change to the manifest's digest acceptance set. +- The CI crate's process execution is **not** changed by this milestone. That + is CI M003m. +- No new dependency. `eggpack-ci` already depends on `eggpack-core`, and + `eggpack-github` already depends on `eggpack-core`. + +## 4. Scope / non-goals + +**In scope:** `crates/eggpack-ci/src/lib.rs`, `crates/eggpack-github/src/lib.rs`, +and the minimal `crates/eggpack-core/**` visibility changes needed to expose +the canonical rules. + +**Out of scope:** + +- CI M003m (process execution and bounded reads) and CI M003n (drift-check and + staging-payload duplication). Those are separate milestones in this chain. +- Build/Qualification M007's implementation of the canonical digest helper + and Build/Qualification M008's floor verification. This milestone only + *consumes* them. +- Any change to the generated workflow's bytes, job graph, permissions, or + trigger handling. +- Any change to `ReleaseManifest` v1's fields or `schema_version`. +- Any change to the M003j canonical-stable-tag format rule, beyond separating + it from safety. +- Any new dependency, any new schema, any new command. + +## 5. Required production changes + +### 5.1 Expose the canonical rules from core + +Make the following callable from `eggpack-ci` and `eggpack-github`: + +1. the host/target match predicate (currently + `crates/eggpack-core/src/lib.rs:84`), exposed so `CIPlan::validate` can call + it instead of using its private copy; +2. the policy validation predicate (currently `validate_policy`, + `crates/eggpack-core/src/lib.rs:118`), exposed in a form that `CIPlan::validate` + can apply to a `TargetPolicy` and target triple; +3. the canonical exact-tag **safety** validator — new in core, carrying the + union of the two existing concern sets; +4. the canonical SHA-256 hex validator — new or shared, per ADR-0006; +5. the canonical file-digest helper — delivered by Build/Qualification M007. + +The exposed API must be small and named for what it owns. It is not a general +"validation" entry point. + +### 5.2 Replace the CI copies + +- `crates/eggpack-ci/src/lib.rs:423-435` is deleted; `CIPlan::validate` calls + the core predicate. +- `crates/eggpack-ci/src/lib.rs:316-320` and `:337-338` are deleted; the floor + and strategy rules come from the core policy validation. +- `crates/eggpack-ci/src/lib.rs:4663-4695` is deleted; candidate hashing uses + the canonical helper and returns a typed error instead of `(0, String::new())`. +- `crates/eggpack-ci/src/lib.rs:632-642` is deleted or reduced to a + re-export, per ADR-0006's decision. +- `crates/eggpack-github/src/lib.rs:597-628` is deleted; the staging digest uses + the canonical helper. +- `crates/eggpack-github/src/lib.rs:567-576` is deleted or reduced to a + re-export, per ADR-0006's decision. + +Every one of these deletions must be verified by grep: no second +implementation of the rule remains in the workspace. + +### 5.3 The canonical exact-tag safety validator + +The union of the two existing concern sets, as one function: + +- empty; length bound; control characters — from both; +- `?`, space, `\` — from both; +- `..`; leading and trailing `/` — from both; +- `#`, `@`, `'`, `"`, `` ` ``, `$` — from the CI concern; +- trailing `.`; `@{`; `^`, `:`, `*`, `[`, `~` — from the core concern; +- path components that are empty, begin with `.`, or end with `.lock` — from + the core concern. + +The validator is **safety only**. The M003j canonical-format check remains a +separate function with a separate diagnostic. + +One consequence must be stated explicitly rather than discovered later: the +core git-resolution path will now refuse tags containing `#`, `@`, `'`, `"`, +`` ` ``, or `$` that it previously accepted. This is fail-closed and correct — +those characters are special to git and to shells — but it is a behaviour +change on a path that is currently exercised by live consumer releases. The +closure record must list it and confirm that no in-tree tag, workflow input, +or consumer configuration uses such a tag. + +### 5.4 Diagnostic compatibility + +Diagnostics are single-line and bounded. Where a rule moves from one crate to +another, the **message text** should be preserved where it is already relied +on, and any change must be listed in the closure record. The `ci _*` runner +protocol carries messages to CI logs that consumers may match on; this +milestone must not silently change a message a consumer could be grepping. + +## 6. Ordered work packages + +### WP1 — Failing discriminating tests first + +- **Rule identity:** for a matrix of target triples and host requirements, the + core predicate and the CI predicate must agree on every case. Write the + matrix test against the *core* predicate only, so that deleting the CI copy + is proven not to change any outcome. +- **Floor applicability:** a `Glibc` floor on a non-GNU/Linux triple, a + `Macos` floor on a non-Darwin triple, and a `Macos` floor under + `CargoZigbuild` are each still refused, with the same pass/fail outcome. +- **Tag safety union:** a table-driven test asserting that every character set + refused by either current validator is refused by the canonical validator, + and that the canonical validator's acceptance set is a **subset** of the + union of the two current acceptance sets — that is, it accepts nothing that + either current validator refused. +- **Digest error typing:** the CI candidate-hashing path now returns a typed + error for a missing file, a symlink, an empty file, and an unreadable file. + The test asserts no path yields an empty digest string. +- **SHA acceptance:** per ADR-0006's decision, the shared validator's + acceptance set is asserted identically from all three call sites. + +### WP2 — Expose the canonical rules from core + +Add the small public surface in §5.1, with doc comments naming the owner and +the rule each function owns. + +### WP3 — Replace the CI copies + +Delete the five CI-side implementations and route the call sites to core. +Update `CIPlan::validate` to apply the core policy validation rather than +re-deriving it. + +### WP4 — Replace the GitHub copies + +Delete the GitHub-side digest and SHA validator and route to core. + +### WP5 — Verification and documentation + +Run the full gate. Update `architecture/ci.md`, `architecture/github.md`, +`architecture/core.md`, `architecture/validation-model.md`, +`crates/eggpack-ci/README.md`, `crates/eggpack-github/README.md`, the CI and +build/qualification roadmaps, and the registry. The validation-model document +in particular must state, once, where each producer rule lives. + +## 7. Failure, restart and contention semantics + +- Every rule change fails closed. If the canonical validator cannot be reached + or returns an error, the enclosing operation fails; it never degrades to a + permissive path. +- The canonical candidate digest returns a typed error. There is no sentinel + success value, no empty digest, and no zero-size placeholder. +- These validators are pure functions over their inputs. They hold no lock and + perform no I/O, so concurrent callers are independent and deterministic. +- A partially-applied change is detectable: the workspace grep for each + retired symbol must return zero matches. The closure record must include + that grep's output as evidence. +- Restarting is free: the rules are pure. + +## 8. Compatibility and migration + +- **No generated workflow byte changes.** The rules now live in a different + crate, but their outcomes are identical, so the rendered YAML is identical + and `eggpack ci check` drift status is unchanged for every consumer. +- The one intended behaviour change is the exact-tag safety union described in + §5.3, which can only refuse more. The closure record must confirm that no + in-tree tag, dispatch input, or consumer configuration uses a character in + the newly-refused set. +- No schema change, except the ADR-0006-authorized narrowing of the manifest's + digest acceptance set, which ships as a `eggpack-manifest` patch release. +- No new dependency. `eggpack-ci` and `eggpack-github` already depend on + `eggpack-core`. +- `eggpack-core` is not published, so widening its public surface has no + external compatibility consequence. +- `eggup-eggpack` is affected only by ADR-0006's manifest narrowing, and only + if it persists a placeholder digest. + +## 9. Required tests + +- the rule-identity matrix described in WP1, over a representative set of + triples, hosts, floors, and strategies; +- the floor applicability negatives; +- the tag-safety union table, including every character class named in §5.3; +- a positive test that a canonical `v1.2.3` tag and a multi-segment tag such + as `release/v1.2.3` are still accepted, so the union is not over-tight; +- typed-error tests for the candidate digest path; +- the SHA acceptance tests, per ADR-0006; +- the full existing CI and GitHub suites, unchanged, proving no behavioural + regression; +- a golden-workflow test proving the rendered YAML is byte-identical before and + after the change. + +## 10. Verification commands + +```text +cargo fmt --all -- --check +cargo check --workspace --all-targets --all-features --locked +cargo clippy --workspace --all-targets --all-features --locked -- -D warnings +cargo test -p eggpack-ci --all-targets --all-features --locked +cargo test -p eggpack-github --all-targets --all-features --locked +cargo test --workspace --all-targets --all-features --locked +cargo doc --workspace --no-deps --locked +cargo +1.89.0 check --workspace --all-targets --locked +cargo +1.89.0 test -p eggpack-ci --all-targets --locked +cargo +1.89.0 test -p eggpack-github --all-targets --locked +./scripts/check-local.sh +``` + +Add a direct narrowed run for the new tests, e.g. +`cargo test -p eggpack-ci --all-targets --all-features --locked -- --nocapture`. +Append `-- --test-threads=1` when diagnosing Windows serialization. + +Additionally, the closure record must include the grep output proving each +retired symbol has zero remaining definitions. + +## 11. Documentation updates + +- `architecture/ci.md` — the CI crate consumes core's rules; the retired + copies are gone. +- `architecture/github.md` — the staging digest uses the canonical helper. +- `architecture/core.md` — the canonical rule surface. +- `architecture/validation-model.md` — a single statement of where each + producer rule lives. +- `crates/eggpack-ci/README.md`, `crates/eggpack-github/README.md`. +- `architecture/overview.md` — line counts and baseline SHA are already stale + and are **not** re-based here; see + `plans/implementation/planning-hygiene/003-post-implementation-review-baseline-reconciliation.md`. +- `plans/subsystems/ci-release-orchestration-roadmap.md` and + `plans/subsystems/build-qualification-roadmap.md` — the M003l row. + +## 12. Acceptance criteria + +1. Exactly one implementation of each of the five rules exists in the + workspace: host/target match, floor applicability, exact-tag safety, SHA-256 + hex acceptance, and file digest. Grep evidence is in the closure record. +2. `CIPlan::validate` applies the core policy validation rather than + re-deriving it. +3. The canonical exact-tag safety validator refuses every character class that + either current validator refused, and accepts nothing that either refused. +4. The CI candidate-digest path returns a typed error and never an empty + digest string; it uses overflow-checked size accumulation. +5. The rendered workflow YAML is byte-identical before and after the change, + proven by a golden test. +6. The SHA-256 acceptance set is identical at all three call sites, as decided + by ADR-0006. +7. No schema change beyond what ADR-0006 authorizes; no new dependency; no + change to the CI crate's process execution. +8. The full workspace gate and `./scripts/check-local.sh` are green, and hosted + CI is green on all lanes. +9. `git diff --check` is clean. + +## 13. Stop conditions + +Stop and re-plan if: + +- unifying the rules changes any tag acceptance outcome other than the + intended fail-closed narrowing in §5.3; +- any rendered workflow byte changes; +- the core predicates cannot be exposed without widening `eggpack-core`'s + public surface in a way that would become a new public contract; +- ADR-0006 is not accepted — the SHA-acceptance work package must be dropped + and the milestone re-scoped, not guessed at; +- Build/Qualification M007 is not closed, since the digest consolidation + depends on the canonical helper it delivers; +- a diagnostic message that a consumer could be grepping would change without + that change being explicitly recorded and accepted; +- the change would require a new dependency, a new schema, or a new command. + +## 14. Closure evidence + +Write `plans/closure/ci-release-orchestration/003l-status.md` with: the +reviewed baseline and implementation SHA; the rule-ownership table before and +after; the rule-identity matrix results; the tag-safety union table and the +explicit list of newly-refused character classes with confirmation that no +in-tree or consumer tag uses them; the typed-error evidence for the digest +path; the golden-workflow byte-identity proof; the grep output proving each +retired symbol is gone; the verification commands executed and their actual +results; hosted CI run IDs and the lane matrix; the ADR-0006 disposition and +the `eggpack-manifest` release, if applicable; an invariant review against §3; +unresolved findings by severity; and the CI M003m and M003n unblock. + +Prior CI M001, M003a, M003d, and M003i closure records remain historical and +unchanged. + +## 15. Handoff notes + +- Start from the CI M003k merge SHA and the Build/Qualification M007 closure + SHA. **Do not** implement against `fb81aa1400e1f333f6500075f78d944a9242b673` + while the M003k PR is open. +- ADR-0006 must be accepted before the SHA-acceptance work package starts. + If it is accepted with Option B rather than Option A, the manifest's + acceptance set stays permissive and the shared validator is used only on the + producer-internal paths — do not assume Option A. +- The canonical exact-tag **safety** validator is a new artifact. Give it a + name that says "safety", not "tag validation", so that M003j's canonical + *format* check stays visibly separate. +- This milestone does not touch process execution. CI M003m does, and it + depends on this milestone landing first. diff --git a/plans/implementation/ci-release-orchestration/003m-bounded-process-execution-convergence-corrective.md b/plans/implementation/ci-release-orchestration/003m-bounded-process-execution-convergence-corrective.md new file mode 100644 index 0000000..78fd258 --- /dev/null +++ b/plans/implementation/ci-release-orchestration/003m-bounded-process-execution-convergence-corrective.md @@ -0,0 +1,438 @@ +# CI/Release M003m — Bounded Process Execution Convergence Corrective + +Status: **blocked** on CI M003l. + +Repository baseline: `eggstack/eggpack@fb81aa1400e1f333f6500075f78d944a9242b673` (2026-10-23). +Source roadmap: `plans/subsystems/ci-release-orchestration-roadmap.md`. +Primary class: invariant / reliability and isolation corrective. +Historical upstream authority: `architecture/process-execution.md` and +`architecture/overview.md:326-328`, which record the workspace rule that process +execution is *"bounded time/output, `command-group` process groups/jobs, +cleared env except small toolchain/path allowlist"* — and which already name +the defect this milestone corrects: *"`ci`'s independent reimplementation is the +only site without process-group kill."* +Affected closed milestones: CI M003d (implementation `946dd7a827fcbf7552721ed162972ae5ae78b5f2`, +introduced the CI-side consumer-validator runner and the CI-side bounded +readers). The closure remains historical and is not rewritten. +Dependency: **CI M003l** must be closed first, so that the rule surface is +settled before the execution surface is changed. + +## 1. Objective + +Make `eggpack-ci`'s consumer-validator execution use the workspace's single +bounded process runner, so that it inherits the same guarantees the build and +git paths already have: + +- the supervised process is terminated as a **process group**, so no descendant + outlives the run; +- the reader-thread joins are **bounded**, so a descendant that inherited a + pipe cannot park the run past its deadline; +- the environment allowlist and the output bounds follow one definition. + +The milestone removes the CI crate's independent process-execution +reimplementation rather than adjusting it in place. + +## 2. Current evidence and the defects + +`eggpack-core` and `eggpack-cli` already share one bounded runner: +`crates/eggpack-cli/src/main.rs:365` and `:384` call +`eggpack_core::run_git_tag_bounded` and `eggpack_core::run_git_bounded`, which +route into the shared runner at `crates/eggpack-core/src/builder.rs:596-692`. + +`eggpack-ci` does not use it. The CI crate has its own implementation, with two +spawn sites: + +| Site | Location | Purpose | +|---|---|---| +| `run_interpreter_preflight` | `crates/eggpack-ci/src/lib.rs:4733-4774` | probe an interpreter for `Python 3` | +| `run_validator_process` | `crates/eggpack-ci/src/lib.rs:5030-5104` | run the consumer validator script against a candidate | + +Both use `crates/eggpack-ci/src/lib.rs:4696-4731` `validator_command` to build a +`std::process::Command`, and both read through the CI-local bounded readers +`read_limited` (`:4457-4481`) and `read_limited_stderr` (`:4483`). + +### 2.1 Defect A — the reader-thread join is unbounded, and the run can hang + +`crates/eggpack-ci/src/lib.rs:4783-4795`: + +```rust +fn drain_readers( + stdout: &mut Option, bool)>>, + stderr: &mut Option, bool)>>, +) -> bool { + let mut over = false; + if let Some(handle) = stdout.take() { + over |= handle.join().unwrap_or_default().1; + } + if let Some(handle) = stderr.take() { + over |= handle.join().unwrap_or_default().1; + } + over +} +``` + +Both `join()` calls are **unbounded**. The function's own doc comment at +`:4779-4782` states the assumption it rests on: + +> *"The child is killed first, so its pipes close and these joins return; +> leaving the handles to drop detaches threads that still hold a pipe no one +> drains, and their completion is part of the run's time bound."* + +That assumption holds only when the killed child was the **only** writer to the +pipe. `run_interpreter_preflight` has the same unbounded join at +`:4763-4764`. + +The core runner already solved exactly this problem, and its comment names the +hazard verbatim (`crates/eggpack-core/src/builder.rs:642-651`): + +> *"a drain thread returns only at pipe EOF, which needs every write end +> closed, so a descendant that inherited stdout and outlived the child would +> park the join for that descendant's entire lifetime. The joins therefore get a +> bounded budget taken from what is left of the caller's own deadline, and a +> reader still parked at it is detached and failed closed below."* + +Core implements this with `join_drained` (`crates/eggpack-core/src/builder.rs:700-…`) +and the `MIN_DRAIN_GRACE` / `MAX_DRAIN_GRACE` budget at `:649-651`. + +**Consequence.** A consumer validator script that spawns a descendant which +inherits stdout or stderr leaves that pipe's write end open. When the CI runner +kills the direct child on timeout, cancellation, or output limit, the reader +thread never observes EOF, and the unbounded `join()` blocks forever. The +timeout, the cancellation flag, and the output bound — all three of which this +function implements — are defeated, and the CI job hangs indefinitely instead of +failing closed. A product-supplied validator script therefore has a path to +wedge the pipeline with no bound. + +### 2.2 Defect B — only the direct child is killed + +Both CI spawn sites call `child.kill()` (`:4754`, `:5068`, `:5074`, `:5083`, +`:5091`), which terminates the **direct child only**. The core runner uses +`command_group::CommandGroup` (`crates/eggpack-core/src/builder.rs:4`, `:596`), +whose `kill()` terminates the whole process group or job object. + +A validator that spawns a long-lived descendant therefore leaves that +descendant running after the run has been declared failed, cancelled, or +timed out. On a CI runner that may be a process that survives the job step. + +### 2.3 Defect C — the environment allowlist and output bounds are defined twice + +The CI runner clears the environment and restores only `PATH`, plus +`SYSTEMROOT` on Windows (`crates/eggpack-ci/src/lib.rs:4708-4715`). The core +runner defines a per-allowance allowlist (`crates/eggpack-core/src/builder.rs:533-572`) +that additionally preserves `HOME`/`USERPROFILE` for git, the MSVC variables +for the builder, and `CARGO_HOME`/`RUSTUP_HOME`. The CI allowlist is not +wrong — it is stricter — but it is a second, separately-maintained definition +of the workspace's environment rule, and the two are not obviously related to a +reader. + +The output bound is likewise defined twice: core caps `stdout_limit` and +`stderr_limit` at `MAX_OUTPUT` and refuses a zero limit +(`crates/eggpack-core/src/builder.rs:510-512`); the CI runner accepts the +request's limits and bounds them elsewhere. + +### 2.4 The asymmetry that must not be lost + +The CI runner has one behaviour core does **not** have: it detects an +over-limit stream **promptly** and kills the child immediately +(`crates/eggpack-ci/src/lib.rs:5073-5078`). The core runner detects over-limit +only after the process ends (`:659-661`, checked at `:678`), so a chatty +process runs until its deadline. + +Converging CI onto core's runner without porting this behaviour would be a +**regression** in output-limit responsiveness. The prompt detection is +therefore carried into the shared runner as part of this milestone, not +discarded. + +## 3. Invariants + +- Every spawned process is terminated as a **process group**, so that no + descendant outlives the run. There is no path in which a supervised run ends + with a live descendant. +- Every reader-thread join is **bounded** by a budget derived from the run's own + remaining deadline. A reader still parked at its budget is detached and the + run is **failed closed**. The run's wall-clock time is bounded by its + deadline regardless of what any descendant does. +- The timeout, the cancellation flag, and the output bound are **effective**: + each must be able to end a run that ignores it, and each must end the run + promptly rather than at some later point. +- The environment is **cleared** except for a documented, minimal allowlist. + The allowlist is defined **once**, in one place, and the CI crate does not + restate it. +- Output limits are enforced on both streams, and exceeding either is a + distinguishable failure from a non-zero exit. +- Process execution never returns captured output **contents** to the caller; + it returns bounded sizes, statuses, and the specific failure reason. +- The build and git paths keep their current behaviour exactly. This milestone + changes the CI crate's execution path; it does not change what a build does. +- No new dependency in `eggpack-ci`. `command-group` is already a dependency of + `eggpack-core`; if the shared runner is used, `eggpack-ci` needs none. + +## 4. Scope / non-goals + +**In scope:** `crates/eggpack-ci/src/lib.rs`, and the minimal +`crates/eggpack-core/src/builder.rs` changes needed to (a) offer the shared +runner to the CI crate and (b) carry CI's prompt over-limit detection into it. + +**Out of scope:** + +- CI M003l's rule convergence and CI M003n's duplication removal. +- Any change to the **build** or **git** execution paths' behaviour. The core + runner's existing semantics are preserved. +- Any change to the consumer validator's contract: the request shape, the + outcome enum, the failure reasons, and the evidence recorded all stay as they + are. +- Any change to the generated workflow bytes. +- Any change to the product-side smoke-hook contract. +- Any new dependency in any crate. +- Any change to `ReleaseManifest` v1 or any other schema. + +## 5. Required production changes + +### 5.1 One shared runner + +The CI crate's consumer-validator execution routes through the shared bounded +runner in `eggpack-core`, with an executable allowance that fits a +consumer-supplied interpreter and script. The shared runner must be usable for +this case without weakening the build or git allowances. + +The runner's existing guarantees carry over unchanged: cleared environment with +the documented allowlist, null stdin, piped stdout and stderr, bounded output, +bounded deadline, bounded drain join, group termination. + +### 5.2 Prompt over-limit detection in the shared runner + +The shared runner gains the behaviour CI has and core lacks: when either +stream's bound is exceeded, the process group is terminated promptly and the +run is reported as an output-limit failure rather than waiting for the +deadline. + +This is a **strict improvement** for the build and git paths too, and it is +recorded as such. It does not change any outcome for a process that stays +within its bounds. + +### 5.3 The CI-local runner is removed + +`crates/eggpack-ci/src/lib.rs`: + +- `validator_command` (`:4696-4731`) is removed or reduced to argument + construction that the shared runner accepts; +- `run_interpreter_preflight` (`:4733-4774`) routes through the shared runner; +- `run_validator_process` (`:5030-5104`) routes through the shared runner; +- `read_limited` (`:4457-4481`), `read_limited_stderr` (`:4483`…), and + `drain_readers` (`:4783-4795`) are removed; +- `take_finished_over` (`:4797-4804`) is removed or subsumed. + +Every removal is verified by grep: no second process runner and no second +bounded reader remain in the CI crate. + +### 5.4 Outcome mapping is preserved + +`ConsumerValidationOutcome` and `ConsumerValidationFailure` keep their current +variants and their current meanings. The mapping from runner outcomes to +consumer-validation outcomes is: + +| Runner outcome | Consumer validation outcome | +|---|---| +| success | `Passed` | +| non-zero exit | `Failed(NonZeroExit)` | +| deadline exceeded | `Failed(Timeout)` | +| output bound exceeded | `Failed(OutputLimit)` | +| cancellation observed | `Failed(Cancelled)` | +| interpreter not launchable | `Failed(InterpreterUnavailable)` | + +The mapping is asserted by test, so the shared runner's richer outcome set does +not silently change what a consumer validator reports. + +### 5.5 Diagnostic compatibility + +`ConsumerValidationFailure`'s rendered diagnostics stay as they are. A consumer +that matches on a CI log line must not see it change. The closure record lists +any diagnostic change explicitly. + +## 6. Ordered work packages + +### WP1 — Failing discriminating tests first + +- **Group termination:** a supervised script that spawns a descendant which + outlives it is terminated such that the descendant does not survive the run. + The test must observe the descendant's absence, not merely the direct child's + exit. +- **Bounded join:** a supervised script that spawns a descendant which holds + stdout open past the deadline causes the run to **return** — with a + fail-closed outcome — within a bounded time, rather than blocking. The test + asserts the run completes and that its outcome is a failure, not a hang. + **This test must fail against the current tree by hanging**, so it is written + with an explicit outer timeout and a diagnostic that distinguishes "hung" from + "failed closed". +- **Prompt output limit:** a script that writes past its output bound is + terminated promptly — measurably before its deadline — and reports the + output-limit failure. +- **Cancellation:** a cancelled run terminates the group and reports + `Cancelled`. +- **Outcome mapping:** every row of the §5.4 table is asserted. + +### WP2 — Shared runner extension + +Extend the shared runner with the CI use case and with prompt over-limit +detection. Prove the build and git paths' existing tests still pass unchanged. + +### WP3 — CI migration + +Route both CI spawn sites through the shared runner and delete the CI-local +runner, readers, and drain helpers. + +### WP4 — Verification and documentation + +Run the full gate. Update `architecture/process-execution.md`, +`architecture/ci.md`, `architecture/core-build.md`, +`crates/eggpack-ci/README.md`, `crates/eggpack-core/README.md`, the CI +roadmap, and the registry. `architecture/overview.md:326-328` carries the +sentence naming CI as the only site without process-group kill — that sentence +must be corrected in the same change. + +## 7. Failure, restart and contention semantics + +- Every termination path terminates the **whole group**. There is no path that + kills only the direct child. +- Every reader join is bounded. A parked reader is detached, and the run is + reported as failed closed. +- A run's wall-clock time is bounded by its deadline, independent of any + descendant's behaviour. The deadline is the only bound that matters and it + is always in force. +- The runner is stateless between runs. There is no shared mutable state and no + lock, so concurrent runs are independent. +- A failed run leaves no process group behind. Reaping is attempted on every + path, including the error paths. +- Restarting a failed run re-runs it from its inputs; there is no resumable + state. + +## 8. Compatibility and migration + +- **No generated workflow byte changes.** The consumer-validator step is + invoked the same way; only its internals change. +- No schema change. `ConsumerValidationOutcome` and + `ConsumerValidationFailure` keep their variants and meanings. +- No new dependency. `eggpack-ci` reaches the shared runner through + `eggpack-core`, which it already depends on, and `command-group` is already + a dependency of `eggpack-core`. +- The prompt output-limit change **does** alter behaviour for the build and git + paths: a process that exceeds its output bound is now killed at the moment of + excess rather than at its deadline. The observable outcome + (`OutputLimitExceeded`) is unchanged; only the moment of termination moves + earlier, and no test asserted the old timing. The closure record states this + explicitly. +- `eggup-eggpack` and every consumer are unaffected. +- No consumer configuration change is required. + +## 9. Required tests + +- the group-termination test from WP1; +- the bounded-join test from WP1, with an explicit outer timeout so a + regression is reported as a hang rather than a silent timeout; +- the prompt output-limit test from WP1, asserting the run ends materially + before its deadline; +- the cancellation test from WP1; +- the outcome-mapping tests from WP1; +- the full existing `eggpack-ci` and `eggpack-core` suites, unchanged; +- the existing build and git process tests, proving the shared runner's new + prompt-detection behaviour did not change their outcomes; +- a Windows-lane test for group/job-object termination, in the same spirit as + the existing Windows process-group test. + +## 10. Verification commands + +```text +cargo fmt --all -- --check +cargo check --workspace --all-targets --all-features --locked +cargo clippy --workspace --all-targets --all-features --locked -- -D warnings +cargo test -p eggpack-ci --all-targets --all-features --locked +cargo test -p eggpack-core --all-targets --all-features --locked +cargo test --workspace --all-targets --all-features --locked +cargo doc --workspace --no-deps --locked +cargo +1.89.0 check --workspace --all-targets --locked +cargo +1.89.0 test -p eggpack-ci --all-targets --locked +cargo +1.89.0 test -p eggpack-core --all-targets --locked +./scripts/check-local.sh +``` + +Add a direct narrowed run for the new tests, e.g. +`cargo test -p eggpack-ci --all-targets --all-features --locked -- --nocapture`. +Append `-- --test-threads=1` when diagnosing Windows serialization. + +## 11. Documentation updates + +- `architecture/process-execution.md` — one runner, one environment allowlist, + one bound set; the CI crate is no longer an exception. +- `architecture/ci.md` — the consumer-validator execution path. +- `architecture/core-build.md` — the shared runner's prompt output-limit + detection. +- `architecture/overview.md:326-328` — **remove the sentence naming CI as the + only site without process-group kill**, because it becomes false. This + correction is in scope for this milestone and is not deferred to the + Planning Hygiene reconciliation. +- `crates/eggpack-ci/README.md`, `crates/eggpack-core/README.md`. +- `plans/subsystems/ci-release-orchestration-roadmap.md` — the M003m row. + +## 12. Acceptance criteria + +1. `eggpack-ci` contains no independent process runner, no independent bounded + reader, and no unbounded reader-thread join. Grep evidence is in the closure + record. +2. A supervised consumer validator that spawns a descendant leaves no live + descendant after the run, proven by test. +3. A supervised consumer validator whose descendant holds a pipe open past the + deadline **returns** within a bounded time with a fail-closed outcome. This + is proven by a test that fails against the pre-change tree. +4. The timeout, cancellation, and output-limit bounds are each effective and + prompt. +5. The environment allowlist and the output bounds are defined once. +6. `ConsumerValidationOutcome` and `ConsumerValidationFailure` keep their + variants and meanings; the mapping is asserted by test. +7. No generated workflow byte changes; no schema changes; no new dependency. +8. The full workspace gate and `./scripts/check-local.sh` are green, and hosted + CI is green on all lanes, including the Windows portability lane. +9. `git diff --check` is clean. + +## 13. Stop conditions + +Stop and re-plan if: + +- the shared runner cannot express the consumer-validator case without + weakening the build or git allowances; +- prompt over-limit detection cannot be added without changing an existing + build or git outcome; +- the bounded-join fix would require detaching a reader in a way that could + report a run as passed when it was not; +- any `ConsumerValidationOutcome` or `ConsumerValidationFailure` variant would + need to change meaning; +- the change would require a new dependency, a new schema, or a new command; +- the CI crate's consumer-validator step would require a changed invocation + from the generated workflow. + +## 14. Closure evidence + +Write `plans/closure/ci-release-orchestration/003m-status.md` with: the +reviewed baseline and implementation SHA; the before/after runner inventory; +the group-termination evidence; the bounded-join evidence, explicitly stating +that the test hangs against the pre-change tree and returns against the +post-change tree; the prompt output-limit evidence with the measured +termination time against the deadline; the outcome-mapping evidence; the grep +output proving the CI-local runner, readers, and drain helpers are gone; the +verification commands executed and their actual results; hosted CI run IDs and +the lane matrix including the Windows portability lane; an invariant review +against §3; the explicit statement of the build/git prompt-detection behaviour +change; unresolved findings by severity; and the CI M003n unblock. + +The CI M003d closure record remains historical and unchanged. + +## 15. Handoff notes + +- Start from the CI M003l closure SHA. +- Write WP1's bounded-join test **first** and confirm it hangs against the + current tree. That hang is the evidence that the defect is real; a test that + merely passes before the change proves nothing. +- The prompt output-limit behaviour is CI's existing strength. Port it into the + shared runner; do not let the convergence lose it. +- `architecture/overview.md:326-328` must be corrected in this change, not + left to a later reconciliation. Leaving a false statement in the architecture + index after fixing the code it describes would create a new drift. diff --git a/plans/implementation/ci-release-orchestration/003n-producer-implementation-consolidation-corrective.md b/plans/implementation/ci-release-orchestration/003n-producer-implementation-consolidation-corrective.md new file mode 100644 index 0000000..eab2570 --- /dev/null +++ b/plans/implementation/ci-release-orchestration/003n-producer-implementation-consolidation-corrective.md @@ -0,0 +1,438 @@ +# CI/Release M003n — Producer Implementation Consolidation Corrective + +Status: **blocked** on CI M003m. + +Repository baseline: `eggstack/eggpack@fb81aa1400e1f333f6500075f78d944a9242b673` (2026-10-23). +Source roadmap: `plans/subsystems/ci-release-orchestration-roadmap.md`. +Primary class: maintainability corrective (no behaviour change intended). +Historical upstream authority: `architecture/determinism.md` and +`architecture/overview.md`, both of which require byte-identical renders and a +single canonical implementation of each rendered artifact. +Affected closed milestones: CI M001 (introduced `check_github`), CI M002 +(introduced the release renderers and `check_release_github`), CI M003a +(implementation `36f1cc1c96cf72511bbdadc2c480cdd0934a4fc9`, introduced +`prepare_staging_payload`), CI M003d (implementation +`946dd7a827fcbf7552721ed162972ae5ae78b5f2`, introduced +`prepare_staging_payload_with_presentation` and +`check_reusable_release_github`). The closures remain historical and are not +rewritten. +Dependency: **CI M003m** must be closed first. This milestone reorganises the +CI crate's module structure, and doing that while the execution path is still +being changed would make the diff unreviewable. + +## 1. Objective + +Remove the duplicated producer implementations that a post-implementation +review found, and bring the two largest source files in the workspace back to a +reviewable structure — **without changing a single byte of any output**. + +Specifically: + +1. The drift-comparison logic exists three times in `eggpack-ci`; it becomes + one function. +2. The staging-payload builder exists twice in `eggpack-github`, with 301 of + 352 lines identical; it becomes one function. +3. `render_release_github_inner` is an 845-line function; it becomes a set of + named private helpers. +4. `crates/eggpack-ci/src/lib.rs` is 11,044 lines in one file; it becomes a + module tree. + +Every one of these is a pure consolidation. The milestone's evidence bar is +therefore simple and strict: **the outputs are byte-identical before and +after.** + +## 2. Current evidence and the defects + +### 2.1 The drift comparison is written three times + +`crates/eggpack-ci/src/lib.rs` contains three public check functions: + +| Function | Location | Renders | +|---|---|---| +| `check_github` | `:1906-1936` | `render_github` | +| `check_reusable_release_github` | `:3270-3300` | `render_reusable_release_github` | +| `check_release_github` | `:4149-4179` | `render_release_github` | + +After the first line — which differs only in which renderer is called — the +bodies are **byte-identical text**: the `MAX_WORKFLOW_BYTES` bound, the +`normalize_newlines` CRLF-to-LF normalization of both sides, the equality +comparison, the first-difference byte offset computation, and the +`DriftReport` construction. + +That is roughly 25 duplicated lines in three places. Drift checking is the +mechanism that guarantees a checked-in workflow matches its inputs, so it is +the last place where three copies of the same comparison should sit. + +### 2.2 The staging-payload builder is written twice, 85.5% identically + +`crates/eggpack-github/src/lib.rs` contains: + +| Function | Location | Lines | +|---|---|---| +| `prepare_staging_payload` | `:665-1024` | 360 | +| `prepare_staging_payload_with_presentation_inner` | `:1360-…` | 409 | + +A line-level diff of the two bodies: **301 of 352 lines are identical +(85.5%)**. The differing ~50 lines are the presentation-specific branch. The +identical part includes the manifest and contract validation, the product-id +cross-check, the release-identity check, the source-revision check, the +`reject_symlink_dir` call, the entire expected-inventory construction +(`expected: BTreeMap`), the sidecar-shape checks, +the installer writes, the digest loop, the canonical sort, and the payload +assembly. + +The doc comment at `crates/eggpack-github/src/lib.rs:1026-1029` claims the +`GeneratedDefault` presentation *"delegates to `prepare_staging_payload` with +byte-identical behavior."* The outer function does delegate. The inner function +does not — it duplicates. So the file simultaneously asserts and denies the +property, and the assertion is not enforced by anything. + +This is the highest-risk duplication in the workspace, because a staging payload +is byte-sensitive release evidence: a future change applied to one copy and not +the other would produce two different staging payloads for the same inputs, +with no test necessarily detecting it. + +### 2.3 The largest function in the workspace + +`render_release_github_inner` (`crates/eggpack-ci/src/lib.rs:3302-4146`) is +**845 lines**. It performs policy validation, identity-mode resolution, +trigger cross-checks, tool-pin validation, emulated-runtime checks, and the +complete YAML emission, in one body. A change to any one of those concerns +requires reading all 845 lines to establish what else is affected. + +### 2.4 The largest file in the workspace + +`crates/eggpack-ci/src/lib.rs` is **11,044 lines** — 31% of the workspace's +35,383 Rust lines — holding 164 functions: the CIPlan projection, three +renderers, drift checking, Zig provisioning, consumer-validator execution, +release-identity resolution, and the entire test suite (tests begin at line +5,107). + +For comparison, the other crates' largest files are `eggpack-cli/src/main.rs` +at 4,441 lines and `eggpack-github/src/lib.rs` at 3,268. + +The CI crate's internal section banners (`crates/eggpack-ci/src/lib.rs:4806-4808`, +for example) already delimit logical sections, so the module boundaries are +indicated by the code itself. + +## 3. Invariants + +- **No output changes.** Every rendered workflow, every `DriftReport`, every + staging payload, and every CLI output is byte-identical before and after this + milestone. This is the milestone's primary invariant and its primary + evidence. +- **No public API change** beyond additive internal restructuring. The + `eggpack-ci` and `eggpack-github` public surfaces are unchanged, except + where CI M003l already changed them. +- **No schema change.** `CIPlan` v1, `ReleaseCIPlanV1`, `ReleaseWorkflowShapeV1`, + `GitHubPolicy`, `PackConfig` v1, and `ReleaseManifest` v1 are untouched. +- **No new dependency.** +- **Determinism is preserved.** The canonical sort, the stable serialization, + and the byte-identical renders are unaffected. The consolidation moves code; + it does not reorder a collection or change a format. +- The staging payload's **byte-identical equivalence** between the two + presentations is preserved, and it becomes **enforced by construction** — + one implementation, so there is no second copy to drift. +- The drift comparison's **CRLF-to-LF-only** normalization semantics are + preserved exactly. This is a documented, deliberate behaviour + (`architecture/ci-rendering.md`) and must not become a general whitespace + tolerance. +- The `MAX_WORKFLOW_BYTES` bound is preserved in the shared comparison, so the + bound applies uniformly to all three check functions. +- Source reorganization must not change the crate's public API, its feature + flags, or its MSRV behaviour. `rust-version = 1.89` still holds. + +## 4. Scope / non-goals + +**In scope:** + +- `crates/eggpack-ci/src/lib.rs` — the shared drift comparison, the + decomposition of `render_release_github_inner`, and the split of the crate + into modules. +- `crates/eggpack-github/src/lib.rs` — the shared staging-payload builder. +- the tests that prove byte-identity before and after. + +**Out of scope:** + +- CI M003l's rule convergence and CI M003m's process-execution convergence. +- Merging the three **renderers** (`render_github`, + `render_reusable_release_github`, `render_release_github`). These produce + genuinely different artifacts — a build workflow, a reusable release + workflow, and a mapped release workflow — and were delivered by distinct + milestones. **They are not duplicates and must not be merged.** Only their + *comparison* is shared. +- Any change to what a rendered workflow contains. +- Any change to the staging payload's contents, ordering, or redaction. +- Moving code between crates. +- Any change to `eggpack-core`, `eggpack-contract`, `eggpack-manifest`, + `eggpack-bootstrap`, or `eggpack-cli`. +- Any change to the generated workflow bytes or to the `ci _*` runner protocol. + +## 5. Required production changes + +### 5.1 One drift comparison + +Extract the shared body of the three check functions into one private function +that takes the **already-rendered** expected bytes and the existing bytes, and +returns a `DriftReport`. The three public functions become one-liners that +render and then delegate. + +The shared function keeps, in this order and unchanged: + +1. the `MAX_WORKFLOW_BYTES` bound on the existing bytes; +2. `normalize_newlines` applied to **both** the expected and the existing bytes + (CRLF to LF only); +3. the equality comparison; +4. the first-difference byte offset, computed over the normalized bytes, with + the shorter length as the fallback; +5. the `DriftReport` construction with `expected_bytes`, `actual_bytes`, and + `first_difference`. + +Because the bound and the normalization are now applied once, all three check +functions are guaranteed to behave identically on identical inputs. + +### 5.2 One staging-payload builder + +Restructure `prepare_staging_payload_with_presentation_inner` so that the +shared algorithm is one function taking the presentation as a parameter, and +`prepare_staging_payload` calls it with the `GeneratedDefault` presentation. + +The presentation parameter selects only the presentation-specific work. Every +other step — validation, inventory construction, sidecars, installers, digest +loop, canonical sort, payload assembly — exists once. + +The doc comment at `crates/eggpack-github/src/lib.rs:1026-1029` is updated +from a claim about delegation to a statement about a single implementation. + +### 5.3 Decompose `render_release_github_inner` + +Split the 845-line function into named private helpers, one per concern it +currently interleaves: + +- policy and shape validation; +- release-identity mode resolution; +- trigger and input cross-checks; +- tool-pin and emulated-runtime validation; +- workflow header and permission emission; +- job emission; +- step emission. + +The helpers are private. The public `render_release_github` and +`render_reusable_release_github` signatures are unchanged, and the rendered +bytes are byte-identical. + +### 5.4 Modularize the CI crate + +Split `crates/eggpack-ci/src/lib.rs` into a module tree, using the crate's +existing section banners as the boundaries. The crate's public API is +re-exported identically from the crate root, so **no consumer of +`eggpack-ci` changes a single import**. + +The split must keep the test module reachable in the same way it is today — the +crate's tests currently live inside `src/lib.rs` from line 5,107 onward, and +the `eggpack-github` crate's precedent of a separate `src/tests.rs` module +(`crates/eggpack-github/src/lib.rs:3268`, `crates/eggpack-github/src/tests.rs`) +is the model to follow. + +### 5.5 No behaviour change + +Every change in this milestone is a move. The closure record must show, for +each moved region, that the text is unchanged apart from the module boundary. + +## 6. Ordered work packages + +### WP1 — Capture the before-state as golden evidence + +Before any edit, capture: + +- the rendered output of `render_github`, `render_reusable_release_github`, and + `render_release_github` for the existing fixtures, as byte-exact baselines; +- the `DriftReport` for a matching workflow, a CRLF-variant workflow, a + workflow differing at the first byte, at the last byte, and beyond the end, + and for an over-size workflow; +- the staging payload produced by both presentations for the existing fixtures, + as byte-exact baselines. + +These baselines become the milestone's evidence and are kept in the closure +record. + +### WP2 — Failing discriminating tests first + +- a test asserting that the two staging presentations produce byte-identical + payloads. Today this passes only by coincidence of the two copies; the test + must be written so that it would catch a divergence, and the closure record + must show it passing **after** the consolidation. +- a test asserting that all three check functions return identical + `DriftReport`s for identical (rendered, existing) byte pairs, across the + CRLF, first-byte, last-byte, length-mismatch, and over-size cases. +- a test asserting that the drift comparison rejects an over-size existing + workflow for all three functions, not only one. + +### WP3 — Shared drift comparison + +Extract the shared comparison and reduce the three public functions to +render-then-delegate. Verify byte-identity against WP1's baselines. + +### WP4 — Shared staging-payload builder + +Restructure the GitHub crate's builder. Verify byte-identity against WP1's +baselines for both presentations, and verify that the two presentations remain +byte-identical to each other. + +### WP5 — Decompose `render_release_github_inner` + +Extract the named private helpers. Verify byte-identity against WP1's +baselines. + +### WP6 — Modularize the CI crate + +Split the source file into modules, re-exporting the public API unchanged from +the crate root. Verify that `eggpack-cli`, `eggpack-github`, and the CI +crate's own tests compile and pass with **no import changes** — proven by +grepping the workspace for `eggpack_ci::` and confirming the consumer +imports are untouched by this milestone. + +### WP7 — Verification and documentation + +Run the full gate. Update `architecture/ci.md`, `architecture/ci-rendering.md`, +`architecture/github.md`, `architecture/overview.md` (the module map and the +line counts for the CI and GitHub crates), `crates/eggpack-ci/README.md`, and +`crates/eggpack-github/README.md`. + +## 7. Failure, restart and contention semantics + +- This milestone introduces no runtime behaviour, so it has no new failure + modes. The existing failure semantics of every touched path are unchanged. +- Every consolidation step is independently revertible: each is a pure code + move, and WP1's baselines make a bad move immediately detectable. +- A milestone that is interrupted mid-way leaves the workspace in a state where + the baseline comparison fails loudly. It never leaves a workspace where a + changed output is silently accepted. +- The consolidation touches no lock, no process, and no shared state. + +## 8. Compatibility and migration + +- **No output changes at all.** This is the milestone's defining constraint. + Every rendered workflow, drift report, and staging payload is byte-identical. +- **No public API break.** `eggpack-ci`'s and `eggpack-github`'s public items + are re-exported unchanged. `eggpack-ci` is not published on crates.io; + `eggpack-github` is not published either. Both are workspace-internal. +- No schema change. No new dependency. No change to `Cargo.toml`. +- No change to `Cargo.lock`. +- `eggup-eggpack` and every consumer are unaffected. +- The `eggpack-cli` and `eggpack-github` crates' imports of `eggpack_ci` are + unchanged; the closure record includes the grep evidence. + +## 9. Required tests + +- the byte-identity golden tests from WP1, for all three renderers, both + staging presentations, and every `DriftReport` case; +- the staging-presentation equivalence test from WP2; +- the three-way drift-report equivalence test from WP2; +- the over-size bound test across all three check functions; +- the full existing `eggpack-ci` and `eggpack-github` suites, unchanged; +- a workspace-wide compile check proving no consumer import changed. + +## 10. Verification commands + +```text +cargo fmt --all -- --check +cargo check --workspace --all-targets --locked +cargo clippy --workspace --all-targets --all-features --locked -- -D warnings +cargo test -p eggpack-ci --all-targets --all-features --locked +cargo test -p eggpack-github --all-targets --all-features --locked +cargo test --workspace --all-targets --all-features --locked +cargo doc --workspace --no-deps --locked +cargo +1.89.0 check --workspace --all-targets --locked +cargo +1.89.0 test -p eggpack-ci --all-targets --locked +cargo +1.89.0 test -p eggpack-github --all-targets --locked +./scripts/check-local.sh +``` + +Add a direct narrowed run for the new tests, e.g. +`cargo test -p eggpack-ci --all-targets --all-features --locked -- --nocapture`. +Append `-- --test-threads=1` when diagnosing Windows serialization. + +## 11. Documentation updates + +- `architecture/ci.md` — the CI crate's module map. +- `architecture/ci-rendering.md` — one drift comparison; the three renderers + remain three renderers, and that distinction is now explicit. +- `architecture/github.md` — one staging-payload builder. +- `architecture/overview.md` — the module map and the CI and GitHub line + counts. Note that `architecture/overview.md`'s existing line counts and + baseline SHA are already stale; this milestone updates only the counts for + the crates it actually changes, and the full re-base remains the + responsibility of + `plans/implementation/planning-hygiene/003-post-implementation-review-baseline-reconciliation.md`. + This milestone re-verifies the citations in the sections it touches, by + symbol name. +- `crates/eggpack-ci/README.md`, `crates/eggpack-github/README.md`. + +## 12. Acceptance criteria + +1. Exactly one drift-comparison implementation exists in `eggpack-ci`, used by + all three check functions. Grep evidence is in the closure record. +2. Exactly one staging-payload builder exists in `eggpack-github`, used by + both presentations. +3. `render_release_github_inner` is decomposed into named private helpers, each + with a single concern. +4. `crates/eggpack-ci/src/lib.rs` is reduced to a crate root that re-exports + its public API and contains no implementation body beyond the re-exports. +5. **Every rendered workflow, `DriftReport`, and staging payload is + byte-identical** to the WP1 baselines. This is proven by test, and the + baselines are reproduced in the closure record. +6. The public API of `eggpack-ci` and `eggpack-github` is unchanged; no + consumer import changed. +7. No schema change, no dependency change, no `Cargo.lock` change. +8. The full workspace gate and `./scripts/check-local.sh` are green, and hosted + CI is green on all lanes. +9. `git diff --check` is clean. + +## 13. Stop conditions + +Stop and re-plan if: + +- any output byte changes; +- the two staging presentations are found to be **intentionally** different in + more than the presentation-specific region — that would mean the two + functions encode different policies, not two renderings of one policy, and + it must be understood before consolidating; +- the public API of either crate would change; +- the module split would require a consumer import change; +- the decomposition of `render_release_github_inner` would require changing + the emitted YAML; +- a new dependency, a new schema, or a new command would be required. + +## 14. Closure evidence + +Write `plans/closure/ci-release-orchestration/003n-status.md` with: the +reviewed baseline and implementation SHA; the before/after duplication +inventory with the measured identical-line ratios; the WP1 golden baselines +reproduced in full; the byte-identity proof for every renderer, drift report, +and staging payload; the staging-presentation equivalence proof; the before and +after line counts for `crates/eggpack-ci/src/lib.rs` and +`crates/eggpack-github/src/lib.rs`; the grep output proving each retired +duplicate is gone; the grep output proving no consumer import changed; the +verification commands executed and their actual results; hosted CI run IDs and +the lane matrix; an invariant review against §3; unresolved findings by +severity; and the residual size of `crates/eggpack-cli/src/main.rs`, which this +milestone does **not** address and which the closure record names as a +remaining item. + +The CI M001, M002, M003a, and M003d closure records remain historical and +unchanged. + +## 15. Handoff notes + +- Start from the CI M003m closure SHA. +- Capture WP1's baselines **before** the first edit and keep them out of the + working tree if they would otherwise be picked up by `cargo fmt` or the + linters. The closure record is where they belong. +- The three renderers are **not** duplicates. Do not merge them. The milestone + shares their comparison, not their output. +- `crates/eggpack-cli/src/main.rs` (4,441 lines) and + `crates/eggpack-core/src/qualification.rs` (2,621 lines, with a 372-line + `qualify_target_for_host_with_runner`) remain unaddressed by this chain. + Name them in the closure record's unresolved findings so the next planning + pass sees them. diff --git a/plans/implementation/planning-hygiene/003-post-implementation-review-baseline-reconciliation.md b/plans/implementation/planning-hygiene/003-post-implementation-review-baseline-reconciliation.md new file mode 100644 index 0000000..ced8e51 --- /dev/null +++ b/plans/implementation/planning-hygiene/003-post-implementation-review-baseline-reconciliation.md @@ -0,0 +1,438 @@ +# Planning Hygiene M003 — Post-Implementation Review Baseline Reconciliation + +Status: **ready for implementation**. + +Repository baseline: `eggstack/eggpack@fb81aa1400e1f333f6500075f78d944a9242b673` (2026-10-23). +Source roadmap: `plans/subsystems/planning-hygiene-roadmap.md`. +Primary class: documentation and evidence only. **No production change.** +Historical upstream authority: `AGENTS.md` §Quirks, which requires that +architecture citations be re-based **by symbol name, never by arithmetic**, and +that the current state and the outstanding gap be recorded in +`architecture/overview.md` §Citation-verification state. +Affected closed milestones: none. This milestone records and reconciles state; +it does not correct a closed milestone's behaviour and rewrites no closure +record. +Dependency: none. This milestone does not touch `crates/**` and does not +contend with CI M003k (in flight) or with any production milestone in the +review chain. + +## 1. Objective + +Reconcile the workspace's documentation and evidence surfaces with the code +they describe, after the post-implementation review that produced the corrective +chain registered alongside this milestone. + +Four things are wrong today, all of them the same kind of thing — **the +documents state what was true at an earlier baseline, and the baseline moved**: + +1. `architecture/overview.md` pins code baseline `61b2c03` and a per-crate + line-count table measured against it. **All seven crates have drifted**, and + the pinned baseline is 13 commits behind `HEAD`. +2. `architecture/overview.md` §Citation-verification state records a known + outstanding gap — `ci-consumer-seam.md`'s stale anchors, and the residual + `cli.md` drift — that has not been closed. +3. `AGENTS.md`'s current-handoff paragraph describes a state that predates CI + M003j, M003k, and this entire review chain. +4. `docs/README.md` and `docs/quickstart.md` both promise that + `crates/eggpack-cli/README.md` is the **full command reference**. It is 65 + lines and documents three commands; the nine `ci _*` runners' flag surface + is described only in prose. + +This milestone closes all four, and registers the review chain in the registry +and the subsystem roadmaps. + +## 2. Current evidence and the gaps + +### 2.1 The pinned baseline is stale + +`architecture/overview.md:12-15`: + +> *Code baseline `61b2c03` (the commit that bounds the `git` verification path +> recorded in [process-execution.md](process-execution.md)). Line counts below +> are measured against that baseline and were re-verified when this index was +> last touched — re-verify them against the workspace if you edit the overview +> again.* + +`HEAD` is `fb81aa1400e1f333f6500075f78d944a9242b673`. `61b2c03` is +`61b2c0381494968aad441a82bbf7daa9e916d9fa`. + +### 2.2 Every line count in the table has drifted + +`architecture/overview.md:150-158` carries a per-crate line-count table. +Measured against `fb81aa1400e1f333f6500075f78d944a9242b673`: + +| Crate | Table says | Actual | Drift | +|---|---|---|---| +| eggpack-contract | 2302 | 2449 | +147 | +| eggpack-manifest | 1354 | 1429 | +75 | +| eggpack-core | 5998 | 6237 | +239 | +| eggpack-bootstrap | 3436 | 3587 | +151 | +| eggpack-ci | 10772 | 11044 | +272 | +| eggpack-github | 4873 | 5327 | +454 | +| eggpack-cli | 3803 | 4441 | **+638** | + +The `eggpack-github` and `eggpack-cli` figures are the most misleading: they +were measured before the CI M003d and Contract M003 changes respectively, and +both are now wrong by enough to mislead a reader who uses them to size a change. + +### 2.3 The citation gap is recorded but not closed + +`architecture/overview.md:53-58` states that `ci-consumer-seam.md` *"still +carries a known set of stale anchors into `cli/main.rs` and `core/builder.rs`, +both of which moved substantially in `61b2c03`. Treat its line references as +indicative until they are re-based."* + +`architecture/overview.md:60-74` records that Contract M003 moved +`cli/src/main.rs` again, that `cli.md` was re-based for it, and that a +**residual set of pre-existing drift remains in `cli.md`** in sections M003 did +not touch — the aggregate-sidecar, `release-manifest.json` placement, +path-absolutization call-site, and end-to-end-orchestration (`1754`) +sub-anchors — which *"resolve to unrelated lines in the pre-M003 file as well, +so M003 carried them forward faithfully rather than inventing new numbers whose +intent it could not confirm."* + +Those anchors are still wrong today. + +### 2.4 The current handoff predates the in-flight milestone + +`AGENTS.md:92` states that no Eggpack plan is `ready` and describes the state +through Ecosystem M003b (published as eggsearch `v0.4.2` on 2026-10-07) and +Planning Hygiene M002. Since then: + +- CI M003j was closed (`plans/closure/ci-release-orchestration/003j-status.md`); +- CI M003k moved to **in progress** with PR `eggstack/eggpack#1` open + (`plans/registry.md:99`, `:117`); +- ADR-0006 and the seven review-chain milestones in this pass were registered. + +A grep across every `*.md` in the repository for `M003k` and `M003j` returns +hits **only under `plans/`**. Neither `AGENTS.md` nor `architecture/overview.md` +mentions either milestone. The document that agents are told to read first +describes a state that is three milestones out of date. + +### 2.5 The "full command reference" is not one + +`docs/README.md:29` describes `crates/eggpack-cli/README.md` as *"the full +command reference"*, and `docs/quickstart.md:212` says *"Full command +reference: `../crates/eggpack-cli/README.md`"*. + +The file is 65 lines. It documents `eggpack ci generate`, `eggpack ci check`, +and `eggpack contract expand`, with one prose paragraph covering the nine +`ci _*` runners. The runners' actual flags — which are the workflow's entire +invocation protocol — are not written down anywhere. + +## 3. Invariants + +- **This milestone changes no production code.** No file under `crates/**` is + modified. No behaviour, output, or test result changes. +- **Citations are re-based by symbol name, never by arithmetic.** Every + `file:line` citation is verified by **reading the line and confirming it + holds what the sentence claims**. A citation whose intent cannot be + confirmed is marked indicative with a reason, or removed — it is never + replaced by a guessed number. +- **The citation-verification section is append-only.** It is a running + account of what was checked and when. Earlier entries stay; a new entry is + added. +- **History is not rewritten.** No closure record is edited, reworded, or + deleted. A closed milestone's record stays as it was written. +- Line counts are **measured**, not estimated, and the measurement is recorded + with the tree SHA it was taken against. +- The registry remains the **single compact control surface** for milestone + status. `AGENTS.md` points at it rather than restating it. +- Every command in the completed command reference is **run verbatim** before + it is documented, and its real output is quoted. +- No plan, closure record, or ADR is created by this milestone beyond the + registration it performs. + +## 4. Scope / non-goals + +**In scope:** `architecture/`, `AGENTS.md`, `docs/`, +`crates/eggpack-cli/README.md`, `plans/registry.md`, +`plans/subsystems/*-roadmap.md`, `plans/adrs/README.md`. + +**Out of scope:** + +- Any file under `crates/*/src/**` and any crate `Cargo.toml`. +- Any closure record, past plan, or accepted ADR. +- Any change to a document's **substance** — this milestone corrects what a + document *says about the code*, not what it *decides*. Where a document's + substance is wrong, the milestone records the discrepancy as a finding for a + follow-up plan rather than rewriting the decision. +- The `ci-consumer-seam.md` **prose** and the constants it names. Only its + line anchors are re-based. +- The `architecture/` documents' authority structure, the module map's + substance, or the invariant list. Only factual claims about the code are + corrected. +- Any new plan beyond the registration of the already-written review chain. + +## 5. Required changes + +### 5.1 Re-base the architecture baseline and line counts + +- Set `architecture/overview.md:12` to the tree SHA the counts were measured + against, and state plainly that it is the SHA the citations were verified + against. +- Re-measure every line count in the `architecture/overview.md:150-158` table + against that SHA and update it. +- Re-verify every `file:line` citation across every document in + `architecture/`, **by symbol name**. Record the method and the result. +- Re-base `ci-consumer-seam.md`'s stale anchors. +- Re-base the residual drift in `cli.md` named at `architecture/overview.md:67-71`. +- For any citation whose intent cannot be confirmed: replace it with a + **symbol name reference** rather than a line number, or mark it indicative + with the reason. Do not invent a number. + +### 5.2 Append to the citation-verification state + +Add a new entry to `architecture/overview.md` §Citation-verification state +describing this pass: the baseline, the method, the number of anchors checked, +the number corrected, the number replaced with symbol names, and the number +left indicative with a reason. Leave the earlier entries intact. + +### 5.3 Correct the false statement that M003m will falsify + +`architecture/overview.md:326-328` states that *"`ci`'s independent +reimplementation is the only site without process-group kill."* CI M003m +corrects the code. This milestone updates the sentence **only after** M003m has +landed, or — if M003m has not landed — leaves it in place and records the +pending dependency in the entry added by §5.2. + +The statement must never be left describing code that no longer exists, and it +must not be changed to describe code that does not exist yet. + +### 5.4 Rewrite the current handoff + +Rewrite `AGENTS.md:92` so that it is a **single statement sourced from the +registry**, in the style Planning Hygiene M002 established. It must name: + +- the one milestone in progress (CI M003k) and its blocking relationship; +- the milestones that are ready; +- the milestones that are blocked, and on what; +- the ADR that is proposed and gates a specific milestone. + +It must **not** restate milestone evidence, closure detail, or dates — those +belong to `plans/registry.md`. The paragraph must not claim that no plan is +ready if the registry lists any. + +### 5.5 Complete the command reference + +Rewrite `crates/eggpack-cli/README.md` as an actual full command reference: + +- every command, with its class (validation / build / staging / publication / + internal runner); +- every flag, its arity, and whether it is required; +- the exit-code discipline; +- one worked example per command family, with **real** output. + +Every example is produced by **running the command** and quoting its actual +output. Nothing is written from intent. + +The nine `ci _*` runners are documented with their **exact** flag surface, +because that surface is the generated workflow's invocation protocol and is +currently undocumented. + +If Build/Qualification M009 has landed before this milestone, the six new +operator commands are documented here too, from their real behaviour. If it has +not, this milestone records their absence explicitly rather than leaving the +"full command reference" claim quietly false. + +### 5.6 Register the review chain + +Update `plans/registry.md`: + +- add a row per new milestone with its status, its blockers, and its + dependency; +- add ADR-0006 to the ADR list; +- update the dependency-ready table; +- update the planned/blocked table so the review chain is visible as a chain. + +Update the affected subsystem roadmaps: + +- `plans/subsystems/build-qualification-roadmap.md` — M007, M008, M009; +- `plans/subsystems/ci-release-orchestration-roadmap.md` — M003l, M003m, M003n; +- `plans/subsystems/planning-hygiene-roadmap.md` — M003. + +Update `plans/adrs/README.md` to list ADR-0006. + +Each roadmap row states the milestone's status and its blocker. No roadmap +narrative is rewritten. + +## 6. Ordered work packages + +### WP1 — Register first, so the documents describe a settled state + +Register ADR-0006 and the seven review-chain milestones in the registry, the +roadmaps, and the ADR index, and rewrite `AGENTS.md:92`. Doing this first +means every later document edit is made against a registry that already +reflects the chain. + +### WP2 — Re-base the architecture citations + +Re-verify every citation across `architecture/` by symbol name. Update the +counts and the baseline. Append the citation-verification entry. + +### WP3 — Re-base `ci-consumer-seam.md` and the residual `cli.md` drift + +Close the two gaps the overview already names. + +### WP4 — Complete the command reference + +Rewrite the CLI README as a real full command reference, with every example run +verbatim and its real output quoted. + +### WP5 — Verify and record + +Confirm that `crates/**` is untouched, that no closure record changed, and +that every registered plan and ADR referenced from a document exists at the +path the document names. + +## 7. Failure, restart and contention semantics + +- Not applicable in the usual sense: this milestone changes no runtime + behaviour and has no failure modes of its own. +- The milestone's own failure mode is a **wrong re-base**: a citation moved to + a line that does not hold what the sentence claims. The defence is the + by-symbol-name rule and the rule that an unconfirmable citation becomes a + symbol reference or is marked indicative, never a guessed number. +- The milestone is idempotent: re-running it against an unchanged tree changes + nothing. +- It does not contend with CI M003k, because it touches no file under + `crates/**`. If a production milestone lands while this one is in flight, + the counts and citations it verified must be re-verified against the new + tree — which is the standing rule `architecture/overview.md:14-15` already + states. + +## 8. Compatibility and migration + +- **No production change.** No crate is affected. No test result changes. No + output changes. +- No schema change. No dependency change. No `Cargo.lock` change. +- The CI workflow is unaffected: this milestone edits no file the workflow + reads. +- `AGENTS.md`'s handoff paragraph changes, and `AGENTS.md` is an agent-facing + contract rather than a published artifact. The change makes it accurate + rather than altering any commitment it makes. +- `crates/eggpack-cli/README.md` changes, and it is rendered on crates.io only + for the published `eggpack-manifest` crate. `eggpack-cli` is not published, + so the change has no downstream effect. +- The review-chain plans reference `plans/implementation/...` paths. This + milestone confirms that every path they name exists. + +## 9. Required checks + +Because this milestone changes no code, the required checks are documentary: + +- `git diff --stat` shows **no** change under `crates/*/src/**` and **no** + change to any `crates/*/Cargo.toml`; +- `git diff` over `plans/closure/**` is **empty** — no closure record is + rewritten; +- every `file:line` citation in `architecture/` is confirmed by reading the + line, and the confirmation method is recorded; +- every plan and ADR path referenced from any updated document exists; +- every command example in the rewritten CLI README was produced by running + the command, and the quoted output matches what the command actually prints; +- `cargo test --workspace --all-targets --all-features --locked` is unchanged + and green, proving the milestone did not touch code. + +## 10. Verification commands + +```text +cargo fmt --all -- --check +cargo clippy --workspace --all-targets --all-features --locked -- -D warnings +cargo test --workspace --all-targets --all-features --locked +cargo doc --workspace --no-deps --locked +./scripts/check-local.sh +``` + +Plus the documentary checks in §9. + +## 11. Documentation updates + +This milestone **is** the documentation update. The documents it touches: + +- `architecture/overview.md` — baseline, counts, citation-verification entry; +- `architecture/ci-consumer-seam.md` — anchors only; +- `architecture/cli.md` — the residual drift named at + `architecture/overview.md:67-71`; +- `AGENTS.md` — the current-handoff paragraph; +- `docs/README.md` — the "full command reference" description, if the + reference is now genuinely full; +- `docs/quickstart.md` — the "Full command reference" pointer, if it moves; +- `crates/eggpack-cli/README.md` — the full command reference; +- `plans/registry.md`, `plans/subsystems/*-roadmap.md`, + `plans/adrs/README.md` — the registration. + +## 12. Acceptance criteria + +1. `architecture/overview.md`'s pinned baseline names a tree SHA that is the + SHA the citations and counts were verified against, and every line count in + its table matches the tree at that SHA. +2. Every `file:line` citation in `architecture/` has been verified by reading + the line. Corrections, symbol-name replacements, and indicative markings are + each counted in the appended citation-verification entry. +3. `ci-consumer-seam.md`'s known stale anchors and the residual `cli.md` drift + named at `architecture/overview.md:53-58` and `:67-71` are closed, or — if + an anchor's intent cannot be confirmed — replaced with a symbol-name + reference with the reason recorded. +4. The citation-verification section contains a new entry for this pass, and + every earlier entry is unchanged. +5. `AGENTS.md`'s current-handoff paragraph is a single statement sourced from + the registry, naming the in-progress milestone, the ready milestones, the + blocked milestones and their blockers, and the proposed ADR. It does not + restate evidence or dates, and it does not contradict the registry. +6. `crates/eggpack-cli/README.md` documents every command and flag, with real + output quoted from actual runs, including the `ci _*` runners' exact flag + surface. The "full command reference" description is accurate. +7. ADR-0006 and all seven review-chain milestones are registered in + `plans/registry.md`, the three affected subsystem roadmaps, and + `plans/adrs/README.md`, with statuses and blockers. +8. `git diff --stat` shows no change under `crates/*/src/**`, no change to any + `Cargo.toml`, and no change under `plans/closure/**`. +9. The full workspace gate and `./scripts/check-local.sh` are green. +10. `git diff --check` is clean. + +## 13. Stop conditions + +Stop and re-plan if: + +- re-basing a citation would require changing the **substance** of a document — + record it as a finding instead; +- a citation's intent cannot be confirmed and no symbol-name reference is + available — record it as indicative with a reason, and do not guess; +- the review-chain milestones it must register are changed by another + concurrent plan — re-read the registry before registering; +- registering the chain would require editing a closure record — it must not; +- a command example cannot be produced on all four supported platforms — the + quickstart's verified-command contract applies to `docs/quickstart.md`, and + the CLI README must either show a platform-qualified example or record the + platform difference explicitly. + +## 14. Closure evidence + +Write `plans/closure/planning-hygiene/003-status.md` with: the reviewed +baseline; the measurement method for the line counts and the SHA they were +taken against; the per-crate count table before and after; the citation +audit — how many citations were checked, corrected, replaced with symbol +names, and left indicative with reasons; the closed `ci-consumer-seam.md` and +`cli.md` gaps; the new citation-verification entry as written; the `AGENTS.md` +handoff before and after; the command-reference before and after and the +verbatim evidence that each example was run; the registry and roadmap diff; +the `git diff --stat` evidence that no code changed; the verification commands +executed and their actual results; an invariant review against §3; and +unresolved findings by severity — in particular, any citation that had to be +left indicative, and the standing obligation that any later milestone which +changes a cited file re-verifies the citations in the sections it touches. + +## 15. Handoff notes + +- Start from `fb81aa1400e1f333f6500075f78d944a9242b673`. +- Register first (WP1), then re-base (WP2, WP3). The registry should describe + the chain before the documents that mention it. +- **Re-base by symbol name.** Read the line, confirm the sentence is true of + it, and only then write the number. A blanket arithmetic shift across the + deep dives is exactly what corrupted them the last time; the `61b2c03` pass + recorded at `architecture/overview.md:28-33` is the precedent, and its method + — verified anchor by anchor by name — is the method to repeat. +- The counts will drift again as the review chain lands. That is the standing + condition, not a failure of this milestone; it is recorded in the appended + citation-verification entry and repeated in the closure record's unresolved + findings. diff --git a/plans/registry.md b/plans/registry.md index 89a4111..aa3abd1 100644 --- a/plans/registry.md +++ b/plans/registry.md @@ -94,12 +94,12 @@ Distribution predecessor evidence: | Contract and conformance | **complete** | `plans/subsystems/contract-conformance-roadmap.md` | M001-M003 closed | M003 closed on `43fa2d7`; closure `plans/closure/contract-conformance/003-status.md`: additive local `eggpack contract expand` scalar projection over existing schema-v1 semantics, 18 new tests including a process-boundary stdout contract, parity proven against eggsact `d4e6e5c` and stegoeggo `v0.5.0` for every target/alias/field. Roadmap §11 completion definition fully met; no contract milestone remains registered | | External backend evaluation | closed | `plans/subsystems/external-backend-evaluation-roadmap.md` | M001 closed (C) | no production backend adopted; new evidence/plan required to reopen | | Release manifest | active | `plans/subsystems/release-manifest-roadmap.md` | M002/M003 closed; M003a closed | M003a closed as a docs-only post-publication downstream-closure reconciliation after Eggup M004 closed (`eggstack/eggup@ea1f1c5e29302e5feca4599db9342d3a5ac93915`; formal Eggup status cleanup `eggstack/eggup@3b82d5397e728649a666690868a1e2d0fe42460d`); closure `plans/closure/release-manifest/003a-status.md`; M003 remains closed and no runtime/package requalification was performed or implied | -| Build and qualification | active | `plans/subsystems/build-qualification-roadmap.md` | M001-M006 closed | M006 closed on `398cd43` + run 36484758546 under accepted ADR-0005 Option A; the milestone chain is closed and later work needs new evidence | +| Build and qualification | active | `plans/subsystems/build-qualification-roadmap.md` | M001-M006 closed; M007 and M009 ready; M008 blocked on M007 | M006 closed on `398cd43` + run 36484758546 under accepted ADR-0005 Option A. The 2026-10-23 post-implementation review registered M007 (evidence digest unification), M008 (compatibility floor verification), and M009 (local producer operator commands) | | Bootstrap installers | active; corrective closed | `plans/subsystems/bootstrap-installers-roadmap.md` | M002b closed; prior milestones closed | M002b implementation `88ddf2e`, hosted run `37806244313`; POSIX runtime remains on Unix and Windows PowerShell archive runtime passed. M003 completion definition remains satisfied | -| CI/release orchestration | active; M003j closed, M003k in progress | `plans/subsystems/ci-release-orchestration-roadmap.md` | M003k pre-checkout tag resolution + stage environment | Local gates pass; hosted matrix, producer PR review, and downstream pin/qualification remain | +| CI/release orchestration | active; M003j closed, M003k in progress | `plans/subsystems/ci-release-orchestration-roadmap.md` | M003k pre-checkout tag resolution + stage environment | Local gates pass; hosted matrix, producer PR review, and downstream pin/qualification remain. The 2026-10-23 post-implementation review registered M003l (producer rule authority convergence), M003m (bounded process execution convergence), and M003n (producer implementation consolidation), chained behind M003k | | Eggup interoperability | active | `plans/subsystems/eggup-interoperability-roadmap.md` | Eggpack M001a + Eggup adapter M001/M001a + Eggup M003 real-consumer adoption + Eggup M004 registry promotion all closed | The whole producer/consumer package seam is closed end to end; Release Manifest M003a closed the remaining Eggpack-side planning drift, and no Eggpack work remains on this seam; Eggwork Operations M003 remains producer-only | | Ecosystem adoption | active | `plans/subsystems/ecosystem-adoption-roadmap.md` | M001/M002/M003a/M003b closed | Closure `plans/closure/ecosystem-adoption/003b-status.md`. Paired plans: Eggpack `plans/implementation/ecosystem-adoption/003b-eggsearch-seven-target-eggpack-producer-cutover.md` (`325d44e`); Eggsearch `plans/implementation/eggpack-release-adoption/001-seven-target-eggpack-producer-cutover.md` (`377f9e8`, registry `6767062`). Implementation landed at `eggstack/eggsearch@eabbf80`; hosted run `37531104901` staged eggsearch `v0.4.2` as draft `405157598` with the exact 19-asset inventory, glibc 2.17 re-proven on all three GNU targets, ARMv7 required consumer validator green, Windows ARM64 required and green, and zero OIDC permission in generated jobs. Provenance attested the staged bytes in run `37561960304`; the draft was published 2026-10-07, closing the named condition | -| Planning hygiene | active | `plans/subsystems/planning-hygiene-roadmap.md` | M001/M002 closed | M002 closed at `plans/closure/planning-hygiene/002-status.md`: docs/evidence-only post-M003a handoff reconciliation with an empty production/package/workflow diff; stale/duplicated control-surface text removed and the handoff bound to exact paired-plan paths | +| Planning hygiene | active | `plans/subsystems/planning-hygiene-roadmap.md` | M001/M002 closed; M003 ready | M002 closed at `plans/closure/planning-hygiene/002-status.md`: docs/evidence-only post-M003a handoff reconciliation with an empty production/package/workflow diff; stale/duplicated control-surface text removed and the handoff bound to exact paired-plan paths. M003 ready: docs/evidence-only post-implementation-review baseline reconciliation (architecture citation re-base by symbol name, `AGENTS.md` handoff rewrite, full CLI command reference, review-chain registration) | **Cross-repo M003 mapping:** Eggpack interoperability M003 is the producer/interface view of Eggup's `plans/implementation/eggpack-manifest-interoperability/003-eggsact-real-consumer-manifest-adoption.md`, and that consumer milestone is now closed (`eggstack/eggup@538e3e5`, `eggstack/eggsact@65c916b`, hosted CI `36902758482` + drift `36902758396`). Ecosystem M001 / Eggsact M005 established the live producer contract and published `release-manifest.json`; runtime manifest acquisition/projection and update semantics remain Eggup/Eggsact-owned. Eggup M004a moved the active producer prerequisite to Release Manifest M003: publish the already-qualified leaf crate `eggpack-manifest 0.1.0` under `plans/implementation/release-manifest/003-eggpack-manifest-0.1.0-publication-and-compatibility-baseline.md`. That publication is now closed: `eggpack-manifest 0.1.0` is live on crates.io, and the published `src/lib.rs` is byte-identical to the consumer-qualified pin `678bbf04`, so the Eggpack-owned prerequisite Eggup M004a identified is satisfied. That Eggup-owned chain has also completed: Eggup M004 published `eggup-acquisition 0.1.2` -> `eggup-eggfetch 0.1.2` -> `eggup-eggpack 0.1.2` in dependency order from publication source `eggstack/eggup@02a1d32931be29cc3d8980833643b2cd822f2d28` (hosted run `37090397398` green on Stable, MSRV, macOS, and Windows) and closed at `eggstack/eggup@ea1f1c5e29302e5feca4599db9342d3a5ac93915`, with Eggup's own stale blocked-state prose formally reconciled at `eggstack/eggup@3b82d5397e728649a666690868a1e2d0fe42460d`. The producer/consumer registry seam is therefore closed end to end, and Release Manifest M003a closed the remaining Eggpack-side planning drift against that downstream truth. No Eggpack implementation work is unlocked by it; the next downstream action is Eggsact's own Git-to-registry migration, owned and authorized in `eggstack/eggsact`. @@ -107,6 +107,8 @@ Distribution predecessor evidence: Planning Hygiene M002, Ecosystem M003b, Bootstrap M002b, CI M003i, and CI M003j are closed. **Dependency-ready CI M003k:** `plans/implementation/ci-release-orchestration/003k-precheckout-tag-resolution-and-stage-environment.md`. It resolves the downstream wg-basic R001 pre-checkout and stage-environment gates while preserving M003j's safe dispatch handling. +The post-implementation review of 2026-10-23 registered three further dependency-ready milestones. None contends with CI M003k, because each is confined to a crate CI M003k does not touch: **Build/Qualification M007** (evidence digest unification, `crates/eggpack-core/**` only), **Build/Qualification M009** (local producer operator commands, `crates/eggpack-cli/**` only), and **Planning Hygiene M003** (docs/evidence-only). The review chain continues behind them: Build/Qualification M008, then CI M003l, CI M003m, and CI M003n. **ADR-0006 is proposed, not accepted**; it gates the digest-acceptance work package of CI M003l only. + The table below is the **milestone-to-closure index plus active ready work**, not an implication that every historical row is executable. | Subsystem | Milestone | Status | Plan | Dependencies | @@ -115,8 +117,10 @@ The table below is the **milestone-to-closure index plus active ready work**, no | CI orchestration | M003i exact tag versus manifest release ID policy | **closed** | `plans/implementation/ci-release-orchestration/003i-explicit-tag-and-manifest-release-identity-corrective.md` | Closure `plans/closure/ci-release-orchestration/003i-status.md`; implementation `3ddac9d84fc2e10b8451d38672f66b02e06724df`; hosted run `37813044035` all four lanes green. wg-basic M003 may resume with this pin | | CI orchestration | M003j dispatch-tag Bash interpolation corrective | closed | `plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md` | Closure `plans/closure/ci-release-orchestration/003j-status.md`; implementation `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce`; hosted run `37987890305` all four lanes green | | CI orchestration | M003k pre-checkout tag resolution and stage approval gate | **in progress** | `plans/implementation/ci-release-orchestration/003k-precheckout-tag-resolution-and-stage-environment.md` | PR `eggstack/eggpack#1` at `23d9f0347d89fd6ecd916692c145152e39de687f`; local gate and hosted run `38027143275` passed; independent review/merge and downstream qualification pending | +| CI orchestration | M003l producer rule authority convergence corrective | **blocked** | `plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md` | Blocked on CI M003k merge, Build/Qualification M007, and ADR-0006 acceptance. Removes the duplicate host-match, floor-applicability, exact-tag, SHA-256 acceptance, and file-digest rules; the two exact-tag rule sets are disjoint in both directions and their union becomes canonical | | Planning hygiene | M001 current evidence baseline + blocker reconciliation | closed | `plans/implementation/planning-hygiene/001-current-evidence-baseline-and-blocker-reconciliation.md` | Closure `plans/closure/planning-hygiene/001-status.md`; discharged CI M003b (eggsact `685fa373` + run `36886042696`) and closed Ecosystem M002 on stegoeggo `v0.5.0` (run `37181914252`); docs-only, zero production/package/workflow delta | | Planning hygiene | M002 post-M003a cross-repository handoff reconciliation | closed | `plans/implementation/planning-hygiene/002-post-m003a-cross-repository-handoff-reconciliation.md` | Closure `plans/closure/planning-hygiene/002-status.md`; docs/evidence-only; stale M003/M003a/M003b control-surface text reconciled against exact paired-plan paths; empty production/package/workflow diff | +| Planning hygiene | M003 post-implementation-review baseline reconciliation | **ready** | `plans/implementation/planning-hygiene/003-post-implementation-review-baseline-reconciliation.md` | Docs/evidence-only. Re-bases the `architecture/` citation set and line counts by symbol name against a measured baseline, closes the `ci-consumer-seam.md` and residual `cli.md` drift, rewrites the `AGENTS.md` current handoff, completes the CLI command reference, and registers the review chain. Zero production diff required | | Contract and conformance | M003 bounded direct-contract expansion CLI | closed | `plans/implementation/contract-conformance/003-bounded-direct-contract-expansion-cli.md` | Closure `plans/closure/contract-conformance/003-status.md`; implemented on `43fa2d7`; local-only scalar projection delegating to `DistributionContract`; `ci` family unchanged byte-for-byte; no new dependency, serialized schema, discovery, or framework | | Bootstrap installers | M003 two-consumer adoption/receipt decision | closed | `plans/implementation/bootstrap-installers/003-two-consumer-adoption-and-receipt-boundary-decision.md` | Closure `plans/closure/bootstrap-installers/003-status.md`; zero production delta on Eggpack `013e091`; live installer/manifest parity proven for both releases; wrapper delegation declined (no stable failure/outcome protocol exists to preserve 404-only fallback), Eggup receipt handoff rejected, roadmap §11 completion definition satisfied; optional consumer-side asset-name cleanup only | | Ecosystem adoption | M003a Eggsearch seven-target compatibility preflight + migration design | closed | `plans/implementation/ecosystem-adoption/003a-eggsearch-seven-target-compatibility-preflight-and-migration-design.md` | Closure `plans/closure/ecosystem-adoption/003a-status.md`; read-only/scratch against `eggstack/eggsearch@ec437cb`, zero production delta; all seven targets rendered and `ci check: match`; G1-G4 all selected Option A; no producer prerequisite registered | @@ -131,6 +135,9 @@ The table below is the **milestone-to-closure index plus active ready work**, no | Build and qualification | M004 finalization/aggregation | closed | `plans/implementation/build-qualification/004-finalization-and-local-aggregation.md` | Closure `plans/closure/build-qualification/004-status.md`; hosted run 36098072913 | | Build and qualification | M005 deterministic cross-tool provisioning | closed | `plans/implementation/build-qualification/005-deterministic-cross-tool-provisioning.md` | Closure `plans/closure/build-qualification/005-status.md`; implementation `7a206ba`; hosted run 36256831000 green; exact Zig 0.14.1 / cargo-zigbuild 0.23.3 provisioning, verified Zig path binding, private cargo-zigbuild cache | | Build and qualification | M006 native qualification for cross-tool builds | closed | `plans/implementation/build-qualification/006-native-qualification-for-cross-tool-builds.md` | Closure `plans/closure/build-qualification/006-status.md`; implementation `398cd43`; hosted run 36484758546 green; host-matched native qualification is now independent of the builder, with split-host qualification and eggsact-shaped five-target render evidence | +| Build and qualification | M007 evidence digest unification corrective | **ready** | `plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md` | Confined to `crates/eggpack-core/**`. Replaces core's two divergent file-digest helpers with one canonical helper carrying the stricter TOCTOU, empty-file, and overflow-checked semantics; delivers the helper CI M003l consumes | +| Build and qualification | M008 compatibility floor verification corrective | **blocked** | `plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md` | Blocked on Build/Qualification M007. A declared glibc floor is currently accepted and silently dropped under `NativeCargo`; M008 adds an explicit floor verification status and independent bounded ELF `GLIBC_x.y` inspection. `ReleaseManifest` v1 unchanged | +| Build and qualification | M009 local producer operator commands | **ready** | `plans/implementation/build-qualification/009-local-producer-operator-commands.md` | Confined to `crates/eggpack-cli/**`. Restores six of the nine operator commands named by `plans/000-long-term-specification.md` §5.4 (`check`, `plan`, `package`, `qualify`, `collect`, `manifest`); the `ci _*` runner family stays byte-for-byte unchanged | | Bootstrap installers | M001 generator/direct fixtures | closed | `plans/implementation/bootstrap-installers/001-direct-installer-generator.md` | Closure `plans/closure/bootstrap-installers/001-status.md` | | CI orchestration | M001 CIPlan/GitHub renderer | closed | `plans/implementation/ci-release-orchestration/001-ci-plan-and-github-renderer.md` | Closure `plans/closure/ci-release-orchestration/001-status.md`; hosted run 36040032768 passes all lanes | | CI orchestration | M002 qualification/aggregation gates + drift CLI | closed historically; corrective closed | `plans/implementation/ci-release-orchestration/002-qualification-aggregation-gates-and-drift-cli.md` | Historical closure retained; executable generated-workflow defect corrected and qualified by M002a (`plans/closure/ci-release-orchestration/002a-status.md`) | @@ -147,6 +154,8 @@ The table below is the **milestone-to-closure index plus active ready work**, no | Bootstrap installers | M002a PowerShell archive runtime evidence | closed | `plans/implementation/bootstrap-installers/002a-powershell-archive-runtime-evidence-corrective.md` | Closure `plans/closure/bootstrap-installers/002a-status.md`; implementation `4d2270a`; hosted run 36154905956 (attempt 1, all lanes green) | | Eggup interoperability | M001 Eggpack interface/fixtures | closed (historical) | `plans/implementation/eggup-interoperability/001-manifest-consumer-contract-and-fixtures.md` | Closure `plans/closure/eggup-interoperability/001-status.md`; post-closure projection defect tracked by M001a | | Eggup interoperability | M001a projection fixture consistency corrective | closed | `plans/implementation/eggup-interoperability/001a-projection-fixture-consistency-corrective.md` | Closure `plans/closure/eggup-interoperability/001a-status.md`; corrected pairwise fixture baseline | +| CI orchestration | M003m bounded process execution convergence corrective | **blocked** | `plans/implementation/ci-release-orchestration/003m-bounded-process-execution-convergence-corrective.md` | Blocked on CI M003l. The CI consumer-validator runner kills only the direct child and joins its reader threads without a bound, so a descendant holding a pipe can wedge a CI job past its timeout; converges on core's process-group runner and carries CI's prompt output-limit detection into it | +| CI orchestration | M003n producer implementation consolidation corrective | **blocked** | `plans/implementation/ci-release-orchestration/003n-producer-implementation-consolidation-corrective.md` | Blocked on CI M003m. One drift comparison replaces three byte-identical copies; one staging-payload builder replaces two copies that are 85.5% identical (301 of 352 lines); `render_release_github_inner` (845 lines) is decomposed; the CI crate's 11,044-line source file becomes a module tree. Byte-identical outputs required | ## Planned / blocked work @@ -157,6 +166,11 @@ were removed rather than left to mislead. | Subsystem | Milestone | State | Blocker | |---|---|---|---| +| Architecture decision | ADR-0006 release evidence digest acceptance set | proposed | `plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md`. Awaiting maintainer acceptance. Decides whether the all-zeros SHA-256 sentinel is refused everywhere, and whether the published `ReleaseManifest` acceptance set narrows — a compatibility change to the published `eggpack-manifest` crate. Gates the digest-acceptance work package of CI M003l only; every other milestone in the review chain is independently implementable | +| Build and qualification | M008 compatibility floor verification corrective | blocked | Build/Qualification M007. A declared glibc floor is accepted and silently dropped under `NativeCargo`, and no artifact records that it went unverified; ADR-0005 §9 requires this verification to be planned independently | +| CI orchestration | M003l producer rule authority convergence corrective | blocked | CI M003k merge (PR `eggstack/eggpack#1`, touches `crates/eggpack-ci/src/lib.rs`), Build/Qualification M007, and ADR-0006 acceptance. The two exact-tag rule sets are disjoint in both directions: neither is a superset of the other, so the union becomes canonical | +| CI orchestration | M003m bounded process execution convergence corrective | blocked | CI M003l. The CI consumer-validator runner kills only the direct child and joins its reader threads without a bound, so a descendant holding an inherited pipe can wedge a CI job past its timeout | +| CI orchestration | M003n producer implementation consolidation corrective | blocked | CI M003m. One drift comparison replaces three byte-identical copies; one staging-payload builder replaces two copies that are 85.5% identical; `render_release_github_inner` is 845 lines; the CI crate's source file is 11,044 lines | | Ecosystem adoption | M004 Gregg sibling bundle | blocked | Remains after Eggsearch target-diversity evidence; prior adoption evidence + Gregg bundle/service review | | Ecosystem adoption | M005 CodeGG runfile bundle | blocked | Remains after a qualified sibling-bundle consumer; prior bundle evidence + CodeGG runfile review | | Ecosystem adoption | M006 Egress archive pair | blocked | Remains after prior native adoption evidence; requires explicit archive/Python boundary review | @@ -266,6 +280,28 @@ Manifest M001a corrective [CLOSED: target-local installs, global artifact filena `--> Release Manifest M003a status/closure reconciliation [CLOSED: DOCS ONLY] External dist 0.33 spike [CLOSED, disposition C] --> prior art only + +Post-implementation review chain [2026-10-23] (independent of the closed +history above; it corrects rules and structure that the closed milestones +introduced, and rewrites no closure record): + +ADR-0006 [PROPOSED: digest acceptance set] + | + +--> CI M003l producer rule authority convergence [BLOCKED: M003k merge + M007 + ADR-0006] + | + +--> CI M003m bounded process execution convergence [BLOCKED: M003l] + | + +--> CI M003n producer implementation consolidation [BLOCKED: M003m] + +Build/Qualification M007 evidence digest unification [READY: core only] + | + +--> Build/Qualification M008 compatibility floor verification [BLOCKED: M007] + | + +--> CI M003l (also depends on M007) + +Build/Qualification M009 local producer operator commands [READY: cli only] + +Planning Hygiene M003 baseline reconciliation [READY: docs only] ``` ## Initial architecture constraints @@ -304,6 +340,8 @@ Eggsearch **M003b passed implementation and is conditionally closed.** M003a set Longer-horizon lines stay as recorded: Ecosystem M004-M007 behind completed Eggsearch adoption, Phase 12 provenance behind a dedicated trust ADR, Phase 13 package adapters behind broader native adoption, Phase 14 stabilization premature. Eggsact's Git-to-registry migration remains separately owned downstream. +**The 2026-10-23 post-implementation review registered a corrective chain.** It found that the workspace carries several rules and structures in more than one place, and that the two copies do not always agree: four file-digest implementations with different TOCTOU behaviour, three SHA-256 acceptance rules where the crate that stages bytes accepts a digest the CI crate refuses, two exact-tag rule sets that are disjoint in both directions, a CI process runner that kills only the direct child and joins its reader threads without a bound, and a drift comparison and a staging-payload builder that each exist in duplicate. It also found a declared-but-unenforced compatibility floor, and a CLI that exposes two of the nine operator commands the canonical specification names. The chain is registered above; it corrects closed milestones' behaviour without rewriting any closure record. Three milestones are dependency-ready now and none contends with CI M003k: Build/Qualification M007, Build/Qualification M009, and Planning Hygiene M003. The rest follow behind M007, M003k, and ADR-0006. + ## Downstream unblock disposition The live evidence closes Ecosystem M001 and M002, discharges CI M003b, and satisfies Phase 8. Closing M003e alone only removed the execution-wiring blocker; later evidence resolved the remaining M001 dependencies, and consumer-side evidence resolved M003b and M002. diff --git a/plans/subsystems/build-qualification-roadmap.md b/plans/subsystems/build-qualification-roadmap.md index c360721..4c07643 100644 --- a/plans/subsystems/build-qualification-roadmap.md +++ b/plans/subsystems/build-qualification-roadmap.md @@ -174,7 +174,9 @@ Eggpack can construct and qualify real direct/bundle/archive native releases loc ## 12. Milestone status -M001 PackConfig and ReleasePlan is closed. Release Manifest M001/M001a and Contract M001/M002 are closed. Backend-evaluation evidence is closed with disposition C, which does not authorize a backend. M005 closed the provisioning prerequisite; M006 then closed the producer-policy gap that first-consumer review exposed, so `Qualification::Native` is now admissible for a `CargoZigbuild` candidate on a matching host. The build/qualification milestone chain through M006 is closed. Ecosystem M001 is unblocked and must re-review the current eggsact baseline and re-pin `eggpack_tool.revision` at the M006 implementation before it implements. Independent verification that a produced binary honours a declared glibc/macOS floor remains unplanned and is not claimed by M006. +M001 PackConfig and ReleasePlan is closed. Release Manifest M001/M001a and Contract M001/M002 are closed. Backend-evaluation evidence is closed with disposition C, which does not authorize a backend. M005 closed the provisioning prerequisite; M006 then closed the producer-policy gap that first-consumer review exposed, so `Qualification::Native` is now admissible for a `CargoZigbuild` candidate on a matching host. The build/qualification milestone chain through M006 is closed. Ecosystem M001 is unblocked and must re-review the current eggsact baseline and re-pin `eggpack_tool.revision` at the M006 implementation before it implements. + +The 2026-10-23 post-implementation review registered three further milestones against this subsystem. **M007** unifies core's two divergent file-digest helpers into one canonical helper, because the weaker copy is the one that produces the aggregated manifest evidence. **M008** plans the independent verification that a produced binary honours a declared glibc/macOS floor, which ADR-0005 §9 requires and which remains unplanned and unclaimed by M006; it adds an explicit floor verification status to the plan and the qualification evidence, because a floor declared under `NativeCargo` is currently accepted and then silently dropped, and nothing downstream records that it went unverified. **M009** restores six of the nine operator commands named by `plans/000-long-term-specification.md` §5.4, so a producer can construct, qualify, finalize, and aggregate a release on a workstation rather than only through a hosted workflow run. M007 and M009 are dependency-ready; M008 follows M007. | Milestone | Status | Implementation plan | Closure record | Blockers / sequencing | |---|---|---|---|---| @@ -185,3 +187,6 @@ M001 PackConfig and ReleasePlan is closed. Release Manifest M001/M001a and Contr | M004 finalization/aggregation | closed | `plans/implementation/build-qualification/004-finalization-and-local-aggregation.md` | `plans/closure/build-qualification/004-status.md` | Local and hosted verification passed | | M005 deterministic cross-tool provisioning | closed | `plans/implementation/build-qualification/005-deterministic-cross-tool-provisioning.md` | `plans/closure/build-qualification/005-status.md`; implementation `7a206ba`; hosted run 36256831000 green | exact Zig 0.14.1/cargo-zigbuild 0.23.3 provisioning, explicit verified-Zig binding/private cache | | M006 native qualification for cross-tool builds | closed | `plans/implementation/build-qualification/006-native-qualification-for-cross-tool-builds.md` | `plans/closure/build-qualification/006-status.md`; implementation `398cd43`; hosted run 36484758546 green | ADR-0005 Option A implemented; host-matched native qualification is independent of builder, including split-host qualification; Ecosystem M001 unblocked | +| M007 evidence digest unification corrective | ready | `plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md` | — | Confined to `crates/eggpack-core/**`. One canonical file-digest helper replaces core's two divergent copies; delivers the helper CI M003l consumes. No acceptance-set change | +| M008 compatibility floor verification corrective | blocked | `plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md` | — | Blocked on M007. Plans the independent floor verification ADR-0005 §9 requires; adds a floor verification status to the plan and qualification evidence. `ReleaseManifest` v1 unchanged | +| M009 local producer operator commands | ready | `plans/implementation/build-qualification/009-local-producer-operator-commands.md` | — | Confined to `crates/eggpack-cli/**`. Restores six of the nine operator commands named by `plans/000-long-term-specification.md` §5.4; the `ci _*` runner family stays byte-for-byte unchanged | diff --git a/plans/subsystems/ci-release-orchestration-roadmap.md b/plans/subsystems/ci-release-orchestration-roadmap.md index f92aa62..bc7308b 100644 --- a/plans/subsystems/ci-release-orchestration-roadmap.md +++ b/plans/subsystems/ci-release-orchestration-roadmap.md @@ -104,6 +104,8 @@ M003j dispatch-tag shell-injection corrective: `plans/implementation/ci-release- M003k pre-checkout tag resolution and stage-environment support: `plans/implementation/ci-release-orchestration/003k-precheckout-tag-resolution-and-stage-environment.md` (**in progress**; PR `eggstack/eggpack#1`, producer head `23d9f0347d89fd6ecd916692c145152e39de687f`, local gate and hosted run `38027143275` passed; independent review/merge and downstream qualification remain). +The 2026-10-23 post-implementation review registered three further corrective milestones against this subsystem, chained behind M003k because each modifies `crates/eggpack-ci/src/lib.rs`. **M003l** converges the producer rules the CI crate re-derives — host/target matching, compatibility-floor applicability, exact-tag safety, the SHA-256 hex acceptance set, and the file digest — onto single owners in `eggpack-core`; the two exact-tag rule sets are disjoint in both directions, so neither is currently a superset of the other and their union becomes canonical. **M003m** converges the CI consumer-validator execution onto the workspace's single bounded process runner, which kills the whole process group and bounds its reader-thread joins; today the CI runner kills only the direct child and can therefore block indefinitely when a descendant holds an inherited pipe, defeating the timeout, cancellation, and output bounds the same function implements. **M003n** removes the duplicated drift comparison and staging-payload builder, decomposes the 845-line `render_release_github_inner`, and turns the 11,044-line CI source file into a module tree, with byte-identical outputs required throughout. ADR-0006 is proposed and gates M003l's digest-acceptance work package only. + ## 8. Cross-cutting requirements Least privilege, pinned actions, explicit timeouts, concurrency controls, artifact provenance, no secret leakage in generated summaries. @@ -146,6 +148,9 @@ Build/Qualification M001-M006 and CI M001/M002/M002a/M003c-M003g are closed on t | M003i explicit tag and manifest release identity corrective | closed | `plans/implementation/ci-release-orchestration/003i-explicit-tag-and-manifest-release-identity-corrective.md` | `plans/closure/ci-release-orchestration/003i-status.md`; implementation `3ddac9d84fc2e10b8451d38672f66b02e06724df`; hosted run `37813044035` passed all four lanes | Finite checked-in opt-in stable-tag mapping with explicitly versioned runtime envelope; legacy exact-tag workflow bytes and ReleaseManifest v1 remain unchanged; wg-basic M003 may resume against the immutable producer SHA | | M003j dispatch tag shell-injection corrective | closed | `plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md` | `plans/closure/ci-release-orchestration/003j-status.md`; implementation `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce`; hosted run `37987890305` all four lanes green | Injection is fixed; pre-checkout ordering and stage environment remain M003k requirements | | M003k pre-checkout tag resolution + stage approval gate | in progress | `plans/implementation/ci-release-orchestration/003k-precheckout-tag-resolution-and-stage-environment.md` | PR `eggstack/eggpack#1` at `23d9f0347d89fd6ecd916692c145152e39de687f`; run `38027143275` all four lanes green; independent review/merge and downstream `dbowm91/wg-basic` qualification pending | +| M003l producer rule authority convergence corrective | blocked | `plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md` | — | Blocked on M003k merge, Build/Qualification M007, and ADR-0006 acceptance. One owner each for host/target match, floor applicability, exact-tag safety, SHA-256 acceptance, and the file digest; the two exact-tag rule sets are disjoint in both directions, so their union becomes canonical | +| M003m bounded process execution convergence corrective | blocked | `plans/implementation/ci-release-orchestration/003m-bounded-process-execution-convergence-corrective.md` | — | Blocked on M003l. The CI consumer-validator runner kills only the direct child and joins its reader threads without a bound; converges on core's process-group runner and carries CI's prompt output-limit detection into it | +| M003n producer implementation consolidation corrective | blocked | `plans/implementation/ci-release-orchestration/003n-producer-implementation-consolidation-corrective.md` | — | Blocked on M003m. One drift comparison replaces three byte-identical copies; one staging-payload builder replaces two copies that are 85.5% identical; `render_release_github_inner` (845 lines) is decomposed; the 11,044-line CI source file becomes a module tree. Byte-identical outputs required | ## 13. 2026-10-08 corrective addendum — M003i diff --git a/plans/subsystems/planning-hygiene-roadmap.md b/plans/subsystems/planning-hygiene-roadmap.md index 870af8f..7545588 100644 --- a/plans/subsystems/planning-hygiene-roadmap.md +++ b/plans/subsystems/planning-hygiene-roadmap.md @@ -66,9 +66,23 @@ Closure record: `plans/closure/planning-hygiene/002-status.md`. Outcome: docs/evidence-only. It removed the stale post-closure M003/M003a/M003b control-surface text, collapsed the duplicated and self-contradicting `AGENTS.md` current-handoff paragraph into one statement sourced from the registry, and bound the handoff to the exact registered paired-plan paths. The production/package/workflow diff is empty. +### M003 — Post-implementation-review baseline reconciliation + +Class: planning / documentation hygiene / architecture-citation reconciliation + +Implementation plan: + +`plans/implementation/planning-hygiene/003-post-implementation-review-baseline-reconciliation.md` + +Status: ready. + +Closure record: — (to be written at `plans/closure/planning-hygiene/003-status.md`). + +Outcome: docs/evidence-only. It re-bases the `architecture/` citation set and the per-crate line-count table **by symbol name**, against a measured baseline, closing the `ci-consumer-seam.md` stale anchors and the residual `cli.md` drift that `architecture/overview.md` already names as outstanding. It rewrites the `AGENTS.md` current-handoff paragraph so it names CI M003k as the in-progress milestone and the review chain registered alongside it, completes `crates/eggpack-cli/README.md` into the full command reference that `docs/README.md` and `docs/quickstart.md` already promise, and registers ADR-0006 and the seven review-chain milestones in the registry, the ADR index, and the affected subsystem roadmaps. It changes no file under `crates/**` and rewrites no closure record. + ## 5. Completion definition -The planning-hygiene line is complete when active control surfaces no longer contradict reviewed evidence and each blocked/future line has an exact disposition without inventing implementation work. M001 met that condition for its evidence set on 2026-10-04; M002 met it for the later Contract M003, Bootstrap M003, and Ecosystem M003a closures, so the planning-hygiene line has no open work. +The planning-hygiene line is complete when active control surfaces no longer contradict reviewed evidence and each blocked/future line has an exact disposition without inventing implementation work. M001 met that condition for its evidence set on 2026-10-04; M002 met it for the later Contract M003, Bootstrap M003, and Ecosystem M003a closures. M003 reopens the line because the 2026-10-23 post-implementation review found that the architecture index, the `AGENTS.md` handoff, and the CLI command reference had all drifted from the code they describe, and because the review chain it registers must appear in the registry and the affected roadmaps. ## 6. Milestone status @@ -76,3 +90,4 @@ The planning-hygiene line is complete when active control surfaces no longer con |---|---|---|---|---| | M001 current evidence baseline + blocker reconciliation | closed | `plans/implementation/planning-hygiene/001-current-evidence-baseline-and-blocker-reconciliation.md` | `plans/closure/planning-hygiene/001-status.md` | none; docs/evidence-only, zero production/package/workflow delta | | M002 post-M003a cross-repository handoff reconciliation | closed | `plans/implementation/planning-hygiene/002-post-m003a-cross-repository-handoff-reconciliation.md` | `plans/closure/planning-hygiene/002-status.md` | none; docs/evidence-only, empty production/package/workflow diff, handoff bound to exact paired-plan paths | +| M003 post-implementation-review baseline reconciliation | ready | `plans/implementation/planning-hygiene/003-post-implementation-review-baseline-reconciliation.md` | — | none; docs/evidence-only. Re-bases `architecture/` citations by symbol name, rewrites the `AGENTS.md` handoff, completes the CLI command reference, and registers the review chain | From e3c6192b3b0e405a0cfe46e5025f31a185881f7e Mon Sep 17 00:00:00 2001 From: doc Date: Fri, 23 Oct 2026 14:43:53 +0000 Subject: [PATCH 03/46] fix(core): unify producer file-digest authority Add one canonical bounded file-digest helper and retire the two divergent implementations it replaces. `file_digest` (crates/eggpack-core/src/digest.rs) is now the only file-digest implementation in `eggpack-core`. It carries the stricter of the two previous semantics: `symlink_metadata` before the open, refusal of anything that is not a regular non-symlink file, refusal of an empty file before it is read, a fixed 64 KiB streaming buffer, `checked_add` size accumulation, and a post-read `symlink_metadata` re-check that refuses a path which became a symlink, stopped being a regular file, or changed length while it was read. Refusals are typed (`DigestError`) instead of opaque strings, and the hashed bytes are unchanged: same hash function, same encoding, same lowercase hex. `digest_file` (lib.rs) and `digest_regular` (finalization.rs) are retired. Manifest aggregation, finalization, and candidate qualification all route through the shared helper, so the manifest is now produced by the stronger of the two, and `eggpack-ci` / `eggpack-github` can consume the same public helper instead of re-implementing one. No acceptance set, schema field, `schema_version`, or published crate changed, and the in-tree golden digests are unchanged. --- architecture/core-finalization.md | 214 ++++++++++------- architecture/core.md | 21 +- crates/eggpack-core/README.md | 2 + crates/eggpack-core/src/digest.rs | 294 +++++++++++++++++++++++ crates/eggpack-core/src/finalization.rs | 146 +++++++---- crates/eggpack-core/src/lib.rs | 132 ++++++---- crates/eggpack-core/src/qualification.rs | 35 +-- 7 files changed, 637 insertions(+), 207 deletions(-) create mode 100644 crates/eggpack-core/src/digest.rs diff --git a/architecture/core-finalization.md b/architecture/core-finalization.md index 7833d45..6619dcf 100644 --- a/architecture/core-finalization.md +++ b/architecture/core-finalization.md @@ -4,7 +4,7 @@ Qualification-gated **local** release construction: the last of four producer stages turns build attempts plus `QualificationEvidence` into a new output root of contract-named artifacts and a `ReleaseManifest v1` over the FINAL bytes. File owns exactly one public entry point, `finalize_release` -(`crates/eggpack-core/src/finalization.rs:68`), plus its four public data types; +(`crates/eggpack-core/src/finalization.rs:67`), plus its four public data types; everything else is private. This is one of four `eggpack-core` stage deep dives (planning, build, qualification, finalization); it contains no planning, no compilation, and no execution. @@ -13,17 +13,17 @@ compilation, and no execution. | Direction | Item | Source | | --- | --- | --- | -| in | `&DistributionContract` (layout authority) | `finalization.rs:69` | -| in | `&ReleasePlan` (intent: selected targets, policy, `artifact_form`) | `finalization.rs:70` | -| in | `&FinalizationRequest` (identity + per-target evidence) | `finalization.rs:71` | -| in | `&Path` output root, must be absolute and absent | `finalization.rs:72` | -| out | `FinalizedRelease { root: PathBuf, manifest: ReleaseManifest }` | `finalization.rs:53-59` | - -`FinalizationRequest` (`:36-50`) carries opaque `product_id` / `release_id` / -`source_revision`, a bounded `Vec` (`:26-33`: contract +| in | `&DistributionContract` (layout authority) | `finalization.rs:68` | +| in | `&ReleasePlan` (intent: selected targets, policy, `artifact_form`) | `finalization.rs:69` | +| in | `&FinalizationRequest` (identity + per-target evidence) | `finalization.rs:70` | +| in | `&Path` output root, must be absolute and absent | `finalization.rs:71` | +| out | `FinalizedRelease { root: PathBuf, manifest: ReleaseManifest }` | `finalization.rs:52-58` | + +`FinalizationRequest` (`:35-49`) carries opaque `product_id` / `release_id` / +`source_revision`, a bounded `Vec` (`:25-32`: contract triple-or-alias, the producing `BuildAttempt`, the M003 `QualificationEvidence`), bounded `evidence_references`, and an `Option` that must be -present exactly when some selected target expands to an archive (`:154-165`). +present exactly when some selected target expands to an archive (`:153-164`). The function performs no I/O outside the output root and its parent, opens no network connection, spawns no process, and mutates no tag or branch. @@ -32,69 +32,69 @@ network connection, spawns no process, and mutates no tag or branch. Required targets may not be finalized without passing evidence. -- Per-target status gate (`:196-200`): `QualificationStatus::Passed` is accepted; +- Per-target status gate (`:195-199`): `QualificationStatus::Passed` is accepted; `Deferred` is accepted **only** when `planned.policy.support != SupportTier::Required` (`NonGating` / `Experimental`); everything else — including `Failed(QualificationFailure)` and `Deferred` on a `Required` target — returns `target qualification does not permit finalization`. - Evidence must already match the build: `QualificationEvidence::validate_for` - (`:192-195`, implemented in `qualification.rs:319`) rejects mismatched + (`:191-194`, implemented in `qualification.rs:318`) rejects mismatched `release_id`/`source_revision`/target/classification/support, selector mismatch, unsorted evidence, and `Passed` without a smoke selector for `Native | DeferredNative | Emulated`. -- The build attempt must be identity-exact and successful (`:183-191`): same +- The build attempt must be identity-exact and successful (`:182-190`): same canonical target, `release_id`, `source_revision`, `strategy`, and `CommandOutcome::Success`. Duplicate targets are rejected here. - Every selected target is mandatory. `expected_targets` from the plan must - equal `actual_targets` collected from the request (`:167-168`, `:294-296`). + equal `actual_targets` collected from the request (`:166-167`, `:293-295`). - Deferred non-required targets are not "skipped": they still need complete - candidate byte evidence (`validated_candidates`, `:316-349`) and a full - contract-named file set (`:278-287`). + candidate byte evidence (`validated_candidates`, `:325-357`) and a full + contract-named file set (`:277-286`). Fail-closed shape: there is no partial-release path. Any rejection unwinds to `finalize_release`, which removes the root it created and returns `Err` with no -`FinalizedRelease` (`:142-145`). Every `CoreError` payload is a fixed string +`FinalizedRelease` (`:141-144`). Every `CoreError` payload is a fixed string (`err(...)`); paths, digests, and file contents never appear in errors -(`lib.rs:72-83`). +(`lib.rs:69-80`). ## Output-root safety rules The root is the finalizer's entire write surface, and the rules are enforced here, in this file: -- Absolute path required (`:82`); no `CurDir` / `ParentDir` components - (`:88-95`). +- Absolute path required (`:81`); no `CurDir` / `ParentDir` components + (`:87-94`). - The parent must exist, be a directory, and not be a symlink - (`symlink_metadata` + `file_type().is_symlink()`, `:114-121`). -- The root's own file name must be present and non-empty (`:122-125`). + (`symlink_metadata` + `file_type().is_symlink()`, `:113-120`). +- The root's own file name must be present and non-empty (`:121-124`). - The parent is canonicalized and the root is rebuilt from that canonical parent - plus the literal file name (`:126-128`). Consequence: `FinalizedRelease.root` + plus the literal file name (`:125-127`). Consequence: `FinalizedRelease.root` is the canonical-parent path, which may differ textually from the caller's argument when the parent chain contains symlinks. - The root must be **absent** — `symlink_metadata` on the root must fail - (`:129-131`). An existing populated root, an existing empty root, and a + (`:128-130`). An existing populated root, an existing empty root, and a pre-existing symlink at that path are all refused; nothing is clobbered and - no existing content is read or deleted. Test `finalization.rs:773-774` asserts + no existing content is read or deleted. Test `finalization.rs:840-841` asserts a sentinel file inside an existing root survives the rejection. -- Root creation is a single `create_dir` (`:132`); every artifact and sidecar is - then created with `create_new(true)` (`:400-404`, `:418-422`, `:459-463`), so +- Root creation is a single `create_dir` (`:131`); every artifact and sidecar is + then created with `create_new(true)` (`:409-413`, `:427-431`, `:475-479`), so intra-root name reuse fails instead of overwriting. -- On Unix the root is restricted to mode `0700` (`:134-139`). -- On Windows nothing is set or checked here: the doc comment (`:61-67`) states +- On Unix the root is restricted to mode `0700` (`:133-138`). +- On Windows nothing is set or checked here: the doc comment (`:60-66`) states the parent must be caller-secured/private because the ACL is inherited. That is an explicit caller obligation, not code enforcement. -- On error only the root created by this invocation is removed (`:143`); - candidate sources and the parent are untouched (test `:788-789`). +- On error only the root created by this invocation is removed (`:142`); + candidate sources and the parent are untouched (test `:855-856`). -Temporary archive-member staging uses `root/.eggpack-members` (`:170`, -`:237-241`), i.e. inside the owned root, and is removed before returning -(`:306-309`). A staging-cleanup failure is an error, which in turn removes the +Temporary archive-member staging uses `root/.eggpack-members` (`:169`, +`:236-240`), i.e. inside the owned root, and is removed before returning +(`:305-308`). A staging-cleanup failure is an error, which in turn removes the whole root. `.eggpack-members` is not a contract release file and the exact -inventory check (`:278-287`) only inspects the `release_files` map, so the +inventory check (`:277-286`) only inspects the `release_files` map, so the staging directory never enters the manifest. `release-manifest.json` is **not** written by this file — the manifest is -returned in memory as a value (`:310-313`). Serialization to a file beside the +returned in memory as a value (`:309-312`). Serialization to a file beside the finalized root happens in `eggpack-cli` (`crates/eggpack-cli/src/main.rs983-988` and the M003a handoff at `:1674-1686`, which asserts the file is absent inside the root) and, for staging, in `eggpack-github` @@ -104,89 +104,126 @@ the root) and, for staging, in `eggpack-github` ## Archive assembly - Encoding is `TarGzip` only. `ArchiveEncoding` has exactly one variant and no - other encodings (`:17-22`), so no other encoding is even expressible; a + other encodings (`:16-21`), so no other encoding is even expressible; a request whose encoding presence does not match the selected layouts, or which - is present without being `TarGzip`, is rejected (`:159-165`) rather than + is present without being `TarGzip`, is rejected (`:158-164`) rather than coerced. -- The contract archive filename must end in `.tar.gz` (`:232-236`). +- The contract archive filename must end in `.tar.gz` (`:231-235`). - Members are the contract's `members` in declaration order, zipped with the - staged candidates in the same order (`:262-268`); the tar entry path is the + staged candidates in the same order (`:261-267`); the tar entry path is the contract `source`, never the staging file name `member-{index}` - (`:243-261`). The exact member set is additionally enforced by - `validate_layout_selectors` (`:361-384`) against the layout and by - `build_manifest` (`lib.rs:232-234`). -- Determinism: `GzBuilder::new().mtime(0)` (`:423-425`), - `tar::HeaderMode::Deterministic` (`:427`), `Header::new_gnu()` with entry type + (`:242-260`). The exact member set is additionally enforced by + `validate_layout_selectors` (`:370-393`) against the layout and by + `build_manifest` (`lib.rs:245-247`). +- Determinism: `GzBuilder::new().mtime(0)` (`:432-434`), + `tar::HeaderMode::Deterministic` (`:436`), `Header::new_gnu()` with entry type `Regular`, mode `0o755`, `uid 0`, `gid 0`, `mtime 0`, and `set_cksum()` - (`:432-442`). Member size comes from a fresh digest pass over the staged copy - (`:429`). Byte-identical archives and equal manifests across two independent - roots are asserted in `finalization.rs:726-757`. -- The archive is written with `create_new(true)` (`:418-422`). + (`:441-458`). Member size comes from a fresh digest pass over the staged copy + (`:438`). Byte-identical archives and equal manifests across two independent + roots are asserted in `finalization.rs:710-751`. +- The archive is written with `create_new(true)` (`:427-431`). + +## File-digest authority + +`eggpack-core` has exactly **one** file-digest implementation: `file_digest` +(`crates/eggpack-core/src/digest.rs:102-114`), with a typed refusal reason for +every way a digest can be refused (`DigestError`, `digest.rs:31-46`). Manifest +aggregation (`lib.rs:209-210`, `lib.rs:256-257`), finalization +(`:316-323`), and candidate qualification (`qualification.rs:1138-1141`) all +route through it, and `eggpack-ci` / `eggpack-github` consume the same public +helper rather than re-implementing one. This section states the rule once; the +other sections of this document only name the helper. + +The rule: a recorded digest MUST describe the bytes of the exact regular file +that was inspected, and the recorded size and digest MUST be mutually +consistent. Concretely, the path is inspected with `symlink_metadata` before +the open and refused unless it is a regular non-symlink file; an empty file is +refused **before** it is read, so a zero-length input can never produce a +digest record; the bytes are streamed through a fixed 64 KiB buffer +(`digest.rs:117-136`) and the byte count is accumulated with overflow checking +(`digest.rs:139-141`); and the path is inspected again after the read +(`digest.rs:144-150`), refusing a path that became a symlink, stopped being a +regular file, or changed length while it was read. + +That last step is the time-of-check/time-of-use guard. The symlink rejection is +a property of the path policy, so it stays a path observation; the read then +happens through the handle that was opened, and the evidence recorded is of +those bytes. Without the post-read re-check, a path replaced between the check +and the open could make the digest describe some other file than the one that +was inspected, and a file rewritten mid-read could produce a size and a digest +that disagree with each other. + +The helper changes no hash semantics: the hash function, the encoding, and the +lowercase hex representation are exactly what the producer has always recorded, +so identical bytes still produce an identical digest and size. A refused digest +is a hard failure of the enclosing operation — never a warning, never a retry +against the same path, never an empty or placeholder digest. ## Checksum sidecars -`write_checksum` (`:456-473`) re-hashes the just-written final file and writes -one line: `" \n"` (two spaces, GNU-style), using +`write_checksum` (`:472-489`) re-hashes the just-written final file through the +file-digest authority above and writes one line: +`" \n"` (two spaces, GNU-style), using `artifact.file_name()` — the final on-disk name, not a candidate path. The sidecar filename always comes from the contract (`direct.sidecar_file`, -`entry.sidecar_file`, `archive.sidecar_file`; `:215`, `:225`, `:270`), and the -sidecar is itself registered in `release_files` (`:217`, `:228`, `:272-275`) so -it must appear in `expected_release_files` or the exact-inventory check fails -(`:278-287`). Sidecars are written for direct assets, every bundle entry, and +`entry.sidecar_file`, `archive.sidecar_file`; `:214`, `:224`, `:269`), and the +sidecar is itself registered in `release_files` (`:216`, `:226-227`, `:271-274`) +so it must appear in `expected_release_files` or the exact-inventory check fails +(`:277-286`). Sidecars are written for direct assets, every bundle entry, and the archive — never for archive members. `size` + `SHA-256` are integrity facts about bytes only. Nothing in this file produces or asserts a signature, a provenance chain, a publisher identity, or authenticity, and `evidence_references` are opaque bounded strings copied into -the manifest (`:303`) with no trust meaning. +the manifest (`:302`) with no trust meaning. ## Manifest aggregation -`build_manifest` (`lib.rs:166-274`) is called with the finalized file map per -target (`:298-305`). The manifest is a value at this point, and the caller +`build_manifest` (`lib.rs:178-288`) is called with the finalized file map per +target (`:297-304`). The manifest is a value at this point, and the caller decides whether to serialize it. - Digests are re-computed at this stage, not copied from candidate or - qualification claims: `digest_file` over the finalized paths - (`lib.rs:192-203`, `:243`) after `copy_verified` has already re-verified each - copy against evidence (`finalization.rs:410-413`). `digest_regular` - (`:475-505`) additionally re-`symlink_metadata`s the path after reading and - rejects a non-regular, symlinked, or zero-length file, so a file swapped - mid-read fails. -- Targets are sorted by canonical triple (`:297`) and the whole document is - re-validated against schema-v1 bounds before return (`lib.rs:270-272`). + qualification claims: the file-digest authority over the finalized paths + (`lib.rs:209-210`, `lib.rs:256-257`) after `copy_verified` has already + re-verified each copy against evidence (`:419-422`). The same authority + re-inspects each path after the read, so a file swapped mid-read fails + instead of being recorded. +- Targets are sorted by canonical triple (`:296`) and the whole document is + re-validated against schema-v1 bounds before return (`lib.rs:284-286`). - Bounds come from `eggpack-manifest`: `MAX_TARGETS = 256`, `MAX_RECORDS = 256`, `MAX_EVIDENCE_REFERENCES = 64`, `MAX_DOCUMENT_BYTES = 1_048_576` (`crates/eggpack-manifest/src/lib.rs:12-16`); `finalization.rs` independently - caps plan and request target counts at 256 (`:78-81`). + caps plan and request target counts at 256 (`:77-80`). - Collision rules: release-artifact filename uniqueness is **manifest-global** (enforced by `ReleaseManifest::validate`; also reflected here by `create_new` on the shared root), while `install` name uniqueness is **target-local** (`manifest.md`, "Namespace rule"). This file never computes install names — they come from contract expansion inside `build_manifest` - (`lib.rs:211`, `:225`, `:246`). + (`lib.rs:224`, `lib.rs:238`, `lib.rs:260`). - `release_files` for a direct/bundle target must be empty of archive members - (`lib.rs:206-208`, `:215-217`), and an archive target's member map must match - the contract member count exactly (`lib.rs:232-234`). + (`lib.rs:219-221`, `lib.rs:228-230`), and an archive target's member map must + match the contract member count exactly (`lib.rs:245-247`). ## Key types / functions (with `file:line`) | Item | Location | Note | | --- | --- | --- | -| `ArchiveEncoding::TarGzip` | `:17-22` | sole variant | -| `FinalizationTargetInput` | `:26-33` | target + attempt + qualification | -| `FinalizationRequest` | `:36-50` | identity, targets, evidence refs, encoding | -| `FinalizedRelease` | `:53-59` | `root` + `eggpack_manifest::ReleaseManifest` | -| `finalize_release` | `:68-146` | public entry point; root safety, cleanup | -| `finalize_into` | `:148-314` | per-target copy/archive/manifest work | -| `validated_candidates` | `:316-349` | re-hash candidates vs qualification evidence | -| `get_candidate` | `:351-359` | exact selector lookup | -| `validate_layout_selectors` | `:361-384` | candidate set == contract layout set | -| `copy_verified` | `:386-415` | `create_new` copy + post-copy digest re-check | -| `create_tar_gzip` | `:417-454` | deterministic tar+gzip assembly | -| `write_checksum` | `:456-473` | `{digest} {name}` sidecar from final bytes | -| `digest_regular` | `:475-505` | 64 KiB streaming SHA-256 + pre/post stat | -| inline tests | `:507-860` | direct/bundle inventory, archive determinism, negative cases, concurrency | +| `ArchiveEncoding::TarGzip` | `:16-21` | sole variant | +| `FinalizationTargetInput` | `:25-32` | target + attempt + qualification | +| `FinalizationRequest` | `:35-49` | identity, targets, evidence refs, encoding | +| `FinalizedRelease` | `:52-58` | `root` + `eggpack_manifest::ReleaseManifest` | +| `finalize_release` | `:67-145` | public entry point; root safety, cleanup | +| `finalize_into` | `:147-313` | per-target copy/archive/manifest work | +| `digest_candidate_bytes` / `digest_finalized_bytes` | `:316-323` | diagnostic subjects over the shared authority | +| `validated_candidates` | `:325-357` | re-hash candidates vs qualification evidence | +| `get_candidate` | `:360-368` | exact selector lookup | +| `validate_layout_selectors` | `:370-393` | candidate set == contract layout set | +| `copy_verified` | `:395-423` | `create_new` copy + post-copy digest re-check | +| `create_tar_gzip` | `:426-470` | deterministic tar+gzip assembly | +| `write_checksum` | `:472-489` | `{digest} {name}` sidecar from final bytes | +| `file_digest` | `digest.rs:102-114` | the single producer file-digest authority | +| inline tests | `:492-927` | direct/bundle inventory, archive determinism, negative cases, concurrency | ## Boundaries / non-goals @@ -204,10 +241,11 @@ decides whether to serialize it. - Own deps used by this file (`crates/eggpack-core/Cargo.toml:14-23`): `eggpack-contract` (`expected_release_files`, `DistributionContract`, - `ExpandedAssets`, `:7`), `eggpack-manifest` (returned document type, `:58`), - `sha2` (`:9`), `flate2` (`:8`), `tar` (`:426`, `:432`), plus `std::fs` / - `std::io`. `serde` / `serde_json` / `toml` / `command-group` are crate-level and - unused here. + `ExpandedAssets`, `:7`), `eggpack-manifest` (returned document type, `:57`), + `flate2` (`:8`), `tar` (`:436`, `:442`), plus `std::fs` / `std::io`. The + SHA-256 digest authority is `sha2`, but it is used by `digest.rs`, not here: + this file only calls the shared helper. `serde` / `serde_json` / `toml` / + `command-group` are crate-level and unused here. - Dependents: `eggpack-ci` (`aggregate_finalize`, `aggregate_finalize_with_consumer`), `eggpack-cli` (aggregation + sidecar manifest write), `eggpack-github` (`prepare_staging_payload`, which re-validates the finalized root against diff --git a/architecture/core.md b/architecture/core.md index 34d1dd6..06bc154 100644 --- a/architecture/core.md +++ b/architecture/core.md @@ -1,7 +1,7 @@ # `eggpack-core` — Deep Dive Crate-level orientation for `eggpack-core`: the producer pipeline. This file -explains how the four source files divide the work and what flows between them. +explains how the five source files divide the work and what flows between them. It does not restate the per-file detail — each stage has its own deep dive. `eggpack-core` is the only crate that writes **release artifacts** (finalized @@ -22,16 +22,17 @@ instead of owning a second, weaker spawn path. See `bootstrap` and `ci` derive documents from core's outputs, `github` consumes core's finalized release, and `cli` wires all of it. -Code baseline `fc072af`; 5827 lines across four files. +Code baseline `fc072af`; the working tree measures 6618 lines across five files. ## File map | File | Lines | Owns | Deep dive | |---|---|---|---| -| `src/lib.rs` | 1056 | policy vocabulary, `PackConfig` -> `ReleasePlan`, `build_manifest` | [core-planning.md](core-planning.md) | -| `src/builder.rs` | 1301 | build bindings, command construction, bounded execution, candidate discovery | [core-build.md](core-build.md) | -| `src/qualification.rs` | 2610 | qualification bindings, method taxonomy, host matching, evidence | [core-qualification.md](core-qualification.md) | -| `src/finalization.rs` | 860 | qualification gate, output root, archives, sidecars, manifest | [core-finalization.md](core-finalization.md) | +| `src/lib.rs` | 1128 | policy vocabulary, `PackConfig` -> `ReleasePlan`, `build_manifest` | [core-planning.md](core-planning.md) | +| `src/builder.rs` | 1663 | build bindings, command construction, bounded execution, candidate discovery | [core-build.md](core-build.md) | +| `src/qualification.rs` | 2606 | qualification bindings, method taxonomy, host matching, evidence | [core-qualification.md](core-qualification.md) | +| `src/finalization.rs` | 927 | qualification gate, output root, archives, sidecars, manifest | [core-finalization.md](core-finalization.md) | +| `src/digest.rs` | 294 | the single producer-side file-digest authority | [core-finalization.md](core-finalization.md) | Read them in pipeline order. The rough size split is itself informative: qualification is the most intricate part of the producer, and finalization is @@ -102,6 +103,14 @@ the reason the stages cannot be collapsed: - **Fail-closed everywhere.** A missing input, an unknown field, an out-of-bounds count, or an unmatched identity is an error. There is no tolerant or best-effort path in this crate. +- **One file-digest authority.** `file_digest` (`src/digest.rs`) is the only + file-digest implementation in the crate: manifest aggregation, finalization, + and candidate qualification all route through it, and `eggpack-ci` / + `eggpack-github` consume the same public helper instead of re-implementing + one. A refused digest is a hard failure of the enclosing operation, never a + warning and never a placeholder record. The refusal rules — symlinks, empty + and non-regular files, and files that change while they are read — are stated + once in [core-finalization.md](core-finalization.md). ## Boundaries diff --git a/crates/eggpack-core/README.md b/crates/eggpack-core/README.md index 7a7eb29..cd94851 100644 --- a/crates/eggpack-core/README.md +++ b/crates/eggpack-core/README.md @@ -4,6 +4,8 @@ Producer-side planning, bounded Cargo building and qualification, local finaliza `finalize_release` accepts identity-matched build and qualification evidence for the exact planned target set, enforces required-target qualification gates, copies direct and bundle candidates under contract names, and creates SHA-256 sidecars from final bytes. Archive output currently accepts only an explicit `ArchiveEncoding::TarGzip`; the contract archive asset filename must end in `.tar.gz`. Archive member names come from contract member paths, while tar/gzip timestamps and ownership metadata are normalized for deterministic output. Manifest v1 is constructed only after all artifacts and sidecars are complete, so its artifact digests cover final release bytes and its member digests cover the bytes written into the archive. The finalizer writes only into a new output root beneath a caller-secured parent (mode 0700 on Unix; Windows inherits the parent ACL) and returns no successful aggregate on failure. This remains producer-side file construction: no extraction, installation, publication, or authenticity claim is performed. +`eggpack-core` owns the single producer-side file-digest authority: `file_digest` (`src/digest.rs`) is the only way a file becomes a byte count and a lowercase hex SHA-256. It refuses symlinks, empty files, and non-regular files, streams the bytes through a fixed 64 KiB buffer, accumulates the size with overflow checking, and re-inspects the path after the read so a file that changed while it was read is refused instead of recorded. Manifest aggregation, finalization, and candidate qualification all route through it, and `eggpack-ci` and `eggpack-github` consume the same public helper. A refused digest is a hard failure of the enclosing operation: never a warning, never a retry against the same path, never an empty or placeholder digest. The helper changes no hash semantics — identical bytes still produce an identical digest and size. + `BuildStrategy` and `Qualification` are independent producer axes. `Qualification::Native` is admissible for a `NativeCargo` **or** `CargoZigbuild` target, and requires the effective qualification host (`qualification_host`, else the build host) to match the target OS/architecture. This is what lets a cross-built candidate for a compatibility floor be proven by execution on a matching native host, including a separate qualification host for a cross-built candidate; a cross-tool-built candidate never earns native qualification merely by compiling, and a non-matching host records a failed `HostMismatch` outcome rather than a pass or a skip. A declared `CompatibilityFloor` remains a build-policy input carried into the cross-tool build command: native execution on a matching host proves the candidate runs there, and is not by itself independent proof that the produced binary honours the declared minimum glibc/macOS runtime. `cargo_command` exposes typed shell-free Cargo/CargoZigbuild intent for provider renderers. `execute_target` uses a caller-owned absolute repository root and a pre-existing private work root; each invocation/target gets a new Cargo target directory. The local process runner only launches Cargo, rustc, or Zig, clears inherited environment state except a small toolchain/path allowlist, and never returns captured output contents. Process-tree timeout cleanup uses `command-group` process groups/jobs. diff --git a/crates/eggpack-core/src/digest.rs b/crates/eggpack-core/src/digest.rs new file mode 100644 index 0000000..b49ab87 --- /dev/null +++ b/crates/eggpack-core/src/digest.rs @@ -0,0 +1,294 @@ +//! The single producer-side file-digest authority. +//! +//! `eggpack-core` owns exactly one way to turn a file into a byte count and a +//! lowercase hex SHA-256 digest. Manifest aggregation, local finalization, and +//! candidate qualification all route through [`file_digest`], so a recorded +//! digest always describes the bytes of the exact regular file that was +//! inspected. `eggpack-ci` and `eggpack-github` consume the same helper rather +//! than re-implementing one. +//! +//! A digest is an integrity fact about bytes only. Nothing here produces or +//! asserts a signature, a provenance chain, or a publisher identity. + +use sha2::{Digest, Sha256}; +use std::{ + fs::{self, File}, + io::Read, + path::Path, +}; + +/// Fixed streaming buffer size for file digests. +/// +/// The digest never holds a whole artifact in memory: a finalized release +/// bundle can be far larger than the process should grow to accommodate. +const DIGEST_BUFFER_BYTES: usize = 64 * 1024; + +/// Why a file digest was refused. +/// +/// Every variant is a hard failure of the enclosing operation. There is no +/// sentinel digest, no partial record, and no retry against the same path. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum DigestError { + /// The path could not be inspected. + Unavailable, + /// The path is not a regular non-symlink file. + NotRegularFile, + /// The file is empty; a zero-length input never produces a digest record. + Empty, + /// The file could not be opened for reading. + OpenFailed, + /// The file could not be read to its end. + ReadFailed, + /// The accumulated byte count overflowed `u64`. + SizeOverflow, + /// The path changed while it was being read. + ChangedDuringRead, +} + +impl DigestError { + /// Bounded, single-line reason phrase for this refusal. + /// + /// The phrase is a fragment: a caller prefixes the subject it was + /// digesting, so no diagnostic loses the context it had before the + /// producer converged on one helper. + pub fn reason(self) -> &'static str { + match self { + Self::Unavailable => "is unavailable", + Self::NotRegularFile => "is not a regular non-symlink file", + Self::Empty => "must be non-empty", + Self::OpenFailed => "cannot be opened", + Self::ReadFailed => "read failed", + Self::SizeOverflow => "size overflow", + Self::ChangedDuringRead => "changed during read", + } + } +} + +impl std::fmt::Display for DigestError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(f, "digest input {}", self.reason()) + } +} + +impl std::error::Error for DigestError {} + +/// Digest one regular file into its byte count and its lowercase hex SHA-256. +/// +/// This is the **single** producer-side file-digest authority. It refuses, in +/// this order: +/// +/// 1. the path is inspected with `symlink_metadata`, so a symlink is never +/// followed and a non-regular file is refused; +/// 2. an empty file is refused **before** it is read, so a zero-length input +/// can never produce a digest record; +/// 3. the bytes are streamed through a fixed 64 KiB buffer and the byte count +/// is accumulated with overflow checking, so a large artifact never grows +/// the process to accommodate it; +/// 4. the path is inspected again with `symlink_metadata` after the read, and +/// the digest is refused if the path became a symlink, stopped being a +/// regular file, or changed length while it was read. +/// +/// Step 4 is the time-of-check/time-of-use guard. The symlink rejection in +/// step 1 is a property of the path policy, so it stays a path observation; +/// the read then happens through the handle that was opened, and the evidence +/// recorded is of those bytes. Without the post-read re-check, a path +/// replaced between the check and the open could make the digest describe +/// some other file than the one that was inspected, and a file rewritten +/// mid-read could produce a size and a digest that disagree with each other. +/// +/// The hashed bytes are unchanged by this helper: the hash function, the +/// encoding, and the lowercase hex representation are exactly what the +/// producer has always recorded. +pub fn file_digest(path: &Path) -> Result<(u64, String), DigestError> { + let before = fs::symlink_metadata(path).map_err(|_| DigestError::Unavailable)?; + if before.file_type().is_symlink() || !before.is_file() { + return Err(DigestError::NotRegularFile); + } + if before.len() == 0 { + return Err(DigestError::Empty); + } + let mut file = File::open(path).map_err(|_| DigestError::OpenFailed)?; + let (size, digest) = hash_stream(&mut file)?; + post_read_check(path, size)?; + Ok((size, digest)) +} + +/// Stream one open file through the digest, accumulating the byte count. +fn hash_stream(file: &mut File) -> Result<(u64, String), DigestError> { + let mut hasher = Sha256::new(); + let mut size = 0u64; + let mut buffer = [0u8; DIGEST_BUFFER_BYTES]; + loop { + let count = file + .read(&mut buffer) + .map_err(|_| DigestError::ReadFailed)?; + if count == 0 { + break; + } + size = add_size(size, count as u64)?; + hasher.update(&buffer[..count]); + } + let digest = hasher.finalize(); + Ok(( + size, + digest.iter().map(|byte| format!("{byte:02x}")).collect(), + )) +} + +/// Accumulate the byte count without wrapping. +fn add_size(size: u64, count: u64) -> Result { + size.checked_add(count).ok_or(DigestError::SizeOverflow) +} + +/// Re-inspect the path after the read and refuse a path that changed. +fn post_read_check(path: &Path, size: u64) -> Result<(), DigestError> { + let after = fs::symlink_metadata(path).map_err(|_| DigestError::ChangedDuringRead)?; + if !post_read_stable(&after, size) { + return Err(DigestError::ChangedDuringRead); + } + Ok(()) +} + +/// The post-read stability rule: the same kind of regular file, same length. +fn post_read_stable(after: &fs::Metadata, size: u64) -> bool { + !after.file_type().is_symlink() && after.is_file() && after.len() == size +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::test_temp_dir; + use std::path::PathBuf; + + fn write_file(root: &Path, name: &str, bytes: &[u8]) -> PathBuf { + let path = root.join(name); + fs::write(&path, bytes).unwrap(); + path + } + + #[test] + fn regular_file_digest_is_the_lowercase_hex_sha256_of_its_bytes() { + let root = test_temp_dir("digest-regular"); + let path = write_file(&root, "artifact", b"abc"); + let (size, sha256) = file_digest(&path).unwrap(); + assert_eq!(size, 3); + assert_eq!( + sha256, + "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad" + ); + assert_eq!(sha256.len(), 64); + assert_eq!(sha256, sha256.to_lowercase()); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn identical_bytes_digest_identically_and_different_bytes_differ() { + let root = test_temp_dir("digest-determinism"); + let first = write_file(&root, "first", b"payload"); + let second = write_file(&root, "second", b"payload"); + let third = write_file(&root, "third", b"payload!"); + let first_digest = file_digest(&first).unwrap(); + let second_digest = file_digest(&second).unwrap(); + let third_digest = file_digest(&third).unwrap(); + assert_eq!(first_digest, second_digest); + assert_ne!(first_digest, third_digest); + assert_ne!(first_digest.0, third_digest.0); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn empty_file_is_refused_before_it_is_read() { + let root = test_temp_dir("digest-empty"); + let path = write_file(&root, "empty", b""); + assert_eq!(file_digest(&path).unwrap_err(), DigestError::Empty); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn directory_is_refused() { + let root = test_temp_dir("digest-directory"); + assert_eq!(file_digest(&root).unwrap_err(), DigestError::NotRegularFile); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn missing_path_is_refused() { + let root = test_temp_dir("digest-missing"); + let path = root.join("absent"); + assert_eq!(file_digest(&path).unwrap_err(), DigestError::Unavailable); + fs::remove_dir_all(root).unwrap(); + } + + #[cfg(unix)] + #[test] + fn symlink_is_refused() { + let root = test_temp_dir("digest-symlink"); + let target = write_file(&root, "target", b"payload"); + let link = root.join("link"); + std::os::unix::fs::symlink(&target, &link).unwrap(); + assert_eq!(file_digest(&link).unwrap_err(), DigestError::NotRegularFile); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn post_read_length_change_is_refused() { + // The read race cannot be staged deterministically on the supported + // platforms: nothing guarantees that a path changes between the + // helper's read and its post-read re-check. The plan therefore allows + // asserting the post-read comparison directly instead of racing a + // thread, and `post_read_check` is the helper's own post-read step, + // exercised here on real files. + let root = test_temp_dir("digest-length-change"); + let path = write_file(&root, "artifact", b"0123456789"); + let (size, _) = hash_stream(&mut File::open(&path).unwrap()).unwrap(); + assert_eq!(size, 10); + fs::write(&path, b"0123456789abcd").unwrap(); + assert_eq!( + post_read_check(&path, size).unwrap_err(), + DigestError::ChangedDuringRead + ); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn post_read_type_change_is_refused() { + // Same deterministic-staging note as the length-change test: the + // helper's post-read step is asserted directly on real files. + let root = test_temp_dir("digest-type-change"); + let path = write_file(&root, "artifact", b"0123456789"); + let (size, _) = hash_stream(&mut File::open(&path).unwrap()).unwrap(); + fs::remove_file(&path).unwrap(); + fs::create_dir(&path).unwrap(); + assert_eq!( + post_read_check(&path, size).unwrap_err(), + DigestError::ChangedDuringRead + ); + fs::remove_dir_all(root).unwrap(); + } + + #[cfg(unix)] + #[test] + fn post_read_symlink_change_is_refused() { + // Same deterministic-staging note as the length-change test. + let root = test_temp_dir("digest-symlink-change"); + let path = write_file(&root, "artifact", b"0123456789"); + let (size, _) = hash_stream(&mut File::open(&path).unwrap()).unwrap(); + fs::remove_file(&path).unwrap(); + let target = write_file(&root, "target", b"0123456789"); + std::os::unix::fs::symlink(&target, &path).unwrap(); + assert_eq!( + post_read_check(&path, size).unwrap_err(), + DigestError::ChangedDuringRead + ); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn size_overflow_is_an_error_not_a_wrapped_value() { + assert_eq!( + add_size(u64::MAX, 1).unwrap_err(), + DigestError::SizeOverflow + ); + assert_eq!(add_size(10, 5).unwrap(), 15); + } +} diff --git a/crates/eggpack-core/src/finalization.rs b/crates/eggpack-core/src/finalization.rs index bb1ccf6..c4a4ca9 100644 --- a/crates/eggpack-core/src/finalization.rs +++ b/crates/eggpack-core/src/finalization.rs @@ -1,16 +1,15 @@ //! Qualification-gated local finalization and manifest aggregation. use crate::{ - build_manifest, err, BuildAttempt, CandidateArtifact, CoreError, LogicalOutputSelector, - QualificationEvidence, QualificationStatus, ReleasePlan, SupportTier, + build_manifest, err, file_digest, BuildAttempt, CandidateArtifact, CoreError, + LogicalOutputSelector, QualificationEvidence, QualificationStatus, ReleasePlan, SupportTier, }; use eggpack_contract::{expected_release_files, DistributionContract, ExpandedAssets}; use flate2::{Compression, GzBuilder}; -use sha2::Digest; use std::{ collections::{BTreeMap, BTreeSet}, fs::{self, File, OpenOptions}, - io::{Read, Write}, + io::Write, path::{Path, PathBuf}, }; @@ -313,6 +312,16 @@ fn finalize_into( }) } +/// Digest candidate bytes with the candidate-file diagnostic subject. +fn digest_candidate_bytes(path: &Path) -> Result<(u64, String), CoreError> { + file_digest(path).map_err(|error| err(format!("candidate file {}", error.reason()))) +} + +/// Digest finalized bytes with the finalized-file diagnostic subject. +fn digest_finalized_bytes(path: &Path) -> Result<(u64, String), CoreError> { + file_digest(path).map_err(|error| err(format!("finalized file {}", error.reason()))) +} + fn validated_candidates<'a>( attempt: &'a BuildAttempt, qualification: &crate::QualificationEvidence, @@ -330,7 +339,7 @@ fn validated_candidates<'a>( let evidence = qualified .get(&candidate.selector) .ok_or_else(|| err("candidate has no qualification byte evidence"))?; - let (size, digest) = digest_regular(&candidate.path)?; + let (size, digest) = digest_candidate_bytes(&candidate.path)?; if evidence.package != candidate.package || evidence.binary != candidate.binary || evidence.size != candidate.size @@ -407,7 +416,7 @@ fn copy_verified( .flush() .map_err(|_| err("finalized file flush failed"))?; drop(target); - let (size, digest) = digest_regular(&destination)?; + let (size, digest) = digest_finalized_bytes(&destination)?; if size != evidence.size || digest != evidence.sha256 { return Err(err("candidate changed while being finalized")); } @@ -426,7 +435,7 @@ fn create_tar_gzip(path: &Path, members: &[(&str, &CandidateArtifact)]) -> Resul let mut archive = tar::Builder::new(encoder); archive.mode(tar::HeaderMode::Deterministic); for (member_name, candidate) in members { - let (size, _) = digest_regular(&candidate.path)?; + let (size, _) = digest_candidate_bytes(&candidate.path)?; let mut source = File::open(&candidate.path) .map_err(|_| err("archive member candidate could not be opened"))?; let mut header = tar::Header::new_gnu(); @@ -461,7 +470,7 @@ fn create_tar_gzip(path: &Path, members: &[(&str, &CandidateArtifact)]) -> Resul } fn write_checksum(artifact: &Path, filename: &str, root: &Path) -> Result<(), CoreError> { - let (_, digest) = digest_regular(artifact)?; + let (_, digest) = digest_finalized_bytes(artifact)?; let sidecar = root.join(filename); let mut file = OpenOptions::new() .write(true) @@ -479,49 +488,18 @@ fn write_checksum(artifact: &Path, filename: &str, root: &Path) -> Result<(), Co Ok(()) } -fn digest_regular(path: &Path) -> Result<(u64, String), CoreError> { - let metadata = fs::symlink_metadata(path).map_err(|_| err("candidate file is unavailable"))?; - if !metadata.is_file() || metadata.file_type().is_symlink() || metadata.len() == 0 { - return Err(err("candidate must be a non-empty regular file")); - } - let mut file = File::open(path).map_err(|_| err("candidate file cannot be opened"))?; - let mut size = 0u64; - let mut hasher = sha2::Sha256::new(); - let mut buffer = [0u8; 65536]; - loop { - let count = file - .read(&mut buffer) - .map_err(|_| err("candidate file read failed"))?; - if count == 0 { - break; - } - size = size - .checked_add(count as u64) - .ok_or_else(|| err("candidate size overflow"))?; - hasher.update(&buffer[..count]); - } - let after = fs::symlink_metadata(path).map_err(|_| err("candidate changed during read"))?; - if after.file_type().is_symlink() || !after.is_file() || after.len() != size { - return Err(err("candidate changed during read")); - } - let digest = hasher.finalize(); - Ok(( - size, - digest.iter().map(|byte| format!("{byte:02x}")).collect(), - )) -} - #[cfg(test)] mod tests { use super::*; use crate::{ - ArtifactForm, BuildStrategy, CandidateArchitecture, CandidateFormat, CommandOutcome, - CompatibilityFloor, HostArch, HostOs, HostRequirement, PackConfig, Qualification, - QualificationMethod, QualifiedCandidateEvidence, SupportTier, TargetPolicy, + ArtifactForm, ArtifactRecord, BuildStrategy, CandidateArchitecture, CandidateFormat, + CommandOutcome, CompatibilityFloor, HostArch, HostOs, HostRequirement, PackConfig, + Qualification, QualificationMethod, QualifiedCandidateEvidence, SupportTier, TargetPolicy, ToolchainRequirement, }; use eggpack_contract::DistributionContract; use sha2::Digest; + use std::io::Read; fn elf() -> Vec { let mut bytes = vec![0; 64]; @@ -539,6 +517,13 @@ mod tests { .collect() } + /// The manifest record must describe the bytes that are on disk. + fn assert_artifact_bytes(root: &Path, artifact: &ArtifactRecord) { + let bytes = fs::read(root.join(&artifact.name)).unwrap(); + assert_eq!(artifact.size, bytes.len() as u64); + assert_eq!(artifact.sha256, digest(&bytes)); + } + fn fixture( contract_text: &str, target_alias: &str, @@ -765,6 +750,81 @@ mod tests { fs::remove_dir_all(parent).unwrap(); } + #[cfg(unix)] + #[test] + fn finalization_refuses_a_symlinked_candidate() { + let parent = crate::test_temp_dir("finalize-symlink"); + let (contract, plan, request, source_root) = fixture( + include_str!("../../eggpack-contract/tests/fixtures/simple-direct.toml"), + "linux-x64", + "1.2.6", + &parent, + ); + let candidate = request.targets[0].attempt.candidates[0].path.clone(); + let real = candidate.with_extension("real"); + fs::rename(&candidate, &real).unwrap(); + std::os::unix::fs::symlink(&real, &candidate).unwrap(); + let output = parent.join("release"); + let error = finalize_release(&contract, &plan, &request, &output).unwrap_err(); + assert!(error.to_string().contains("non-symlink"), "{error}"); + assert!(!output.exists()); + assert!(source_root.exists()); + fs::remove_dir_all(parent).unwrap(); + } + + #[test] + fn manifest_records_agree_with_the_finalized_bytes_for_every_artifact() { + for (name, fixture_text, target, release) in [ + ( + "direct", + include_str!("../../eggpack-contract/tests/fixtures/simple-direct.toml"), + "linux-x64", + "1.2.6", + ), + ( + "bundle", + include_str!("../../eggpack-contract/tests/fixtures/codegg-bundle.toml"), + "linux-x64", + "2.4.0", + ), + ( + "archive", + include_str!("../../eggpack-contract/tests/fixtures/egress-archive.toml"), + "linux-x64", + "3.1.0", + ), + ] { + let parent = crate::test_temp_dir(name); + let (contract, plan, request, _) = fixture(fixture_text, target, release, &parent); + let output = parent.join("release"); + let finalized = finalize_release(&contract, &plan, &request, &output).unwrap(); + let mut checked = 0usize; + match &finalized.manifest.targets[0].form { + ArtifactForm::Direct { artifact, .. } => { + assert_artifact_bytes(&finalized.root, artifact); + checked += 1; + } + ArtifactForm::Bundle { entries } => { + for entry in entries { + assert_artifact_bytes(&finalized.root, &entry.artifact); + checked += 1; + } + } + ArtifactForm::Archive { artifact, members } => { + assert_artifact_bytes(&finalized.root, artifact); + checked += 1; + for member in members { + assert_eq!(member.bytes.size, elf().len() as u64); + assert_eq!(member.bytes.sha256, digest(&elf())); + checked += 1; + } + } + } + assert!(checked > 0); + fs::remove_dir_all(parent).unwrap(); + } + } + #[test] fn incomplete_qualification_tampering_and_existing_roots_fail_without_partial_success() { let parent = crate::test_temp_dir("finalize-negative"); diff --git a/crates/eggpack-core/src/lib.rs b/crates/eggpack-core/src/lib.rs index 53cbdb4..02e9b91 100644 --- a/crates/eggpack-core/src/lib.rs +++ b/crates/eggpack-core/src/lib.rs @@ -3,9 +3,11 @@ //! Producer-side release planning and finalized artifact evidence. mod builder; +pub mod digest; mod finalization; mod qualification; pub use builder::*; +pub use digest::*; pub use finalization::*; pub use qualification::*; @@ -18,14 +20,9 @@ use eggpack_manifest::{ TargetRecord, }; use serde::{Deserialize, Serialize}; -use sha2::{Digest, Sha256}; -use std::{ - collections::BTreeMap, - fmt, - fs::{self, File}, - io::{BufReader, Read}, - path::{Path, PathBuf}, -}; +#[cfg(test)] +use std::fs; +use std::{collections::BTreeMap, fmt, path::PathBuf}; #[cfg(test)] pub(crate) fn test_temp_dir(label: &str) -> PathBuf { @@ -209,7 +206,8 @@ pub fn build_manifest( .release_files .get(name) .ok_or_else(|| err("required artifact path missing"))?; - let (size, sha256) = digest_file(path)?; + let (size, sha256) = file_digest(path) + .map_err(|error| err(format!("finalized file {}", error.reason())))?; Ok(ArtifactRecord { name: name.to_string(), size, @@ -255,7 +253,8 @@ pub fn build_manifest( .archive_members .get(&m.source) .ok_or_else(|| err("required archive member path missing"))?; - let (size, sha256) = digest_file(p)?; + let (size, sha256) = file_digest(p) + .map_err(|error| err(format!("finalized file {}", error.reason())))?; Ok(ArchiveMemberRecord { source: m.source.clone(), install: m.install_name.clone(), @@ -288,41 +287,6 @@ pub fn build_manifest( Ok(manifest) } -fn digest_file(path: &Path) -> Result<(u64, String), CoreError> { - // The symlink rejection is a property of the path policy, so it stays a - // path observation. The read then happens through the handle that was - // opened, and the evidence recorded is of those bytes: a path replaced - // between the check and the open can no longer make the digest describe - // some other file than the one that was inspected. - let link_metadata = - fs::symlink_metadata(path).map_err(|_| err("finalized file is unavailable"))?; - if !link_metadata.file_type().is_file() { - return Err(err("finalized input is not a regular non-symlink file")); - } - let file = File::open(path).map_err(|_| err("finalized file cannot be opened"))?; - let mut reader = BufReader::new(file); - let mut hasher = Sha256::new(); - let mut size = 0u64; - let mut buf = [0u8; 65536]; - loop { - let n = reader - .read(&mut buf) - .map_err(|_| err("finalized file read failed"))?; - if n == 0 { - break; - } - size = size - .checked_add(n as u64) - .ok_or_else(|| err("file size overflow"))?; - hasher.update(&buf[..n]); - } - if size == 0 { - return Err(err("finalized files must be non-empty")); - } - let digest = hasher.finalize(); - Ok((size, digest.iter().map(|b| format!("{b:02x}")).collect())) -} - /// Explicit finite build strategy. Planning never executes either strategy. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] @@ -987,6 +951,84 @@ support="required" fs::remove_dir_all(dir).unwrap(); } #[test] + fn manifest_builder_refuses_artifacts_that_are_not_regular_non_empty_files() { + // The manifest path routes through the crate's single file-digest + // authority, so it inherits its fail-closed policy: a non-regular, + // symlinked, empty, or missing artifact is refused rather than + // recorded. The authority's post-read re-check — which refuses a path + // that changes while it is read — cannot be staged deterministically + // on the supported platforms, so it is asserted directly in + // `digest.rs` instead of being raced here. + let contract = DistributionContract::parse_toml_str(include_str!( + "../../eggpack-contract/tests/fixtures/simple-direct.toml" + )) + .unwrap(); + let dir = test_temp_dir("core-digest-policy"); + let names = [ + "eggsact-1.2.6-x86_64-unknown-linux-gnu", + "eggsact-1.2.6-x86_64-unknown-linux-gnu.sha256", + ]; + let mut files = BTreeMap::new(); + for name in names { + let path = dir.join(name); + fs::write(&path, b"abc").unwrap(); + files.insert(name.to_string(), path); + } + let input = FinalizedReleaseInput { + product_id: "eggsact".into(), + release_id: "1.2.6".into(), + source_revision: "a".repeat(40), + targets: vec![FinalizedTargetInput { + target: "linux-x64".into(), + release_files: files, + archive_members: BTreeMap::new(), + }], + evidence_references: vec![], + }; + assert!(build_manifest(&contract, &input).is_ok()); + fs::write(dir.join(names[0]), b"").unwrap(); + assert!(build_manifest(&contract, &input).is_err()); + fs::remove_file(dir.join(names[0])).unwrap(); + assert!(build_manifest(&contract, &input).is_err()); + fs::remove_dir_all(dir).unwrap(); + } + #[cfg(unix)] + #[test] + fn manifest_builder_refuses_a_symlinked_artifact() { + let contract = DistributionContract::parse_toml_str(include_str!( + "../../eggpack-contract/tests/fixtures/simple-direct.toml" + )) + .unwrap(); + let dir = test_temp_dir("core-digest-symlink"); + let names = [ + "eggsact-1.2.6-x86_64-unknown-linux-gnu", + "eggsact-1.2.6-x86_64-unknown-linux-gnu.sha256", + ]; + let mut files = BTreeMap::new(); + for name in names { + let path = dir.join(name); + fs::write(&path, b"abc").unwrap(); + files.insert(name.to_string(), path); + } + let input = FinalizedReleaseInput { + product_id: "eggsact".into(), + release_id: "1.2.6".into(), + source_revision: "a".repeat(40), + targets: vec![FinalizedTargetInput { + target: "linux-x64".into(), + release_files: files, + archive_members: BTreeMap::new(), + }], + evidence_references: vec![], + }; + let artifact = dir.join(names[0]); + let real = dir.join("real-artifact"); + fs::rename(&artifact, &real).unwrap(); + std::os::unix::fs::symlink(&real, &artifact).unwrap(); + assert!(build_manifest(&contract, &input).is_err()); + fs::remove_dir_all(dir).unwrap(); + } + #[test] fn bundle_and_archive_inputs_preserve_contract_relationships() { for (fixture, release, product, target) in [ ( diff --git a/crates/eggpack-core/src/qualification.rs b/crates/eggpack-core/src/qualification.rs index 35e3dbd..d49c94d 100644 --- a/crates/eggpack-core/src/qualification.rs +++ b/crates/eggpack-core/src/qualification.rs @@ -5,12 +5,11 @@ use crate::{ run_qemu_process, run_qualification_process, CandidateArtifact, CommandSpec, ProcessEvidence, }, - BuildAttempt, BuildBindingsV1, BuildCancellation, HostArch, HostOs, HostRequirement, - LogicalOutputSelector, PlannedTarget, Qualification, ReleasePlan, SupportTier, + file_digest, BuildAttempt, BuildBindingsV1, BuildCancellation, DigestError, HostArch, HostOs, + HostRequirement, LogicalOutputSelector, PlannedTarget, Qualification, ReleasePlan, SupportTier, }; use eggpack_contract::DistributionContract; use serde::{Deserialize, Serialize}; -use sha2::{Digest, Sha256}; use std::{ collections::BTreeMap, fs::{self, File}, @@ -1133,23 +1132,13 @@ fn inspect_candidate( if format_arch != (expected_format, expected_arch) { return Err(QualificationFailure::StructuralMismatch); } - let mut file = - File::open(&canonical).map_err(|_| QualificationFailure::InvalidRuntimeEnvironment)?; - let mut hasher = Sha256::new(); - let mut size = 0u64; - let mut buffer = [0u8; 65536]; - loop { - let read = file - .read(&mut buffer) - .map_err(|_| QualificationFailure::InvalidRuntimeEnvironment)?; - if read == 0 { - break; - } - size = size - .checked_add(read as u64) - .ok_or(QualificationFailure::InvalidRuntimeEnvironment)?; - hasher.update(&buffer[..read]); - } + // The candidate bytes are digested by the crate's single file-digest + // authority, so qualification evidence and the release manifest describe + // the same bytes under the same rules. + let (size, sha256) = file_digest(&canonical).map_err(|error| match error { + DigestError::ChangedDuringRead => QualificationFailure::CandidateChanged, + _ => QualificationFailure::InvalidRuntimeEnvironment, + })?; let after = fs::symlink_metadata(&candidate.path) .map_err(|_| QualificationFailure::CandidateChanged)?; if size != metadata.len() @@ -1165,11 +1154,7 @@ fn inspect_candidate( package: candidate.package.clone(), binary: candidate.binary.clone(), size, - sha256: hasher - .finalize() - .iter() - .map(|byte| format!("{byte:02x}")) - .collect(), + sha256, format: expected_format, architecture: expected_arch, }) From 414f99822cc1123d86864091363dd9dd9481cdb7 Mon Sep 17 00:00:00 2001 From: doc Date: Fri, 23 Oct 2026 14:48:14 +0000 Subject: [PATCH 04/46] plans: accept ADR-0006 and close Build/Qualification M007 Accept ADR-0006 (Option A): the all-zeros SHA-256 sentinel is refused by every producer path, `ReleaseManifest` stays at `schema_version: 1`, and the published `eggpack-manifest` crate takes a `0.1.1` patch release carrying the tightened rule. This authorizes CI M003l's digest-acceptance work package. Close Build/Qualification M007 on implementation `e3c6192`. `eggpack-core` now has one canonical bounded file-digest authority (`crates/eggpack-core/src/digest.rs`) with typed refusals. Core's two planned duplicates were retired, and a third in-crate SHA-256 stream in `qualification.rs` that the plan's inventory had missed was routed through the same helper. The hashed bytes, the in-tree golden digests, and `ReleaseManifest` v1 are unchanged. Also: registry, ADR index, and the build/qualification roadmap reconciled to the new state. M008 is now ready; M003k is closed by the merge at `a0fec98`; CI M003l is unblocked and in progress. --- ...-release-evidence-digest-acceptance-set.md | 25 ++-- plans/adrs/README.md | 9 +- .../closure/build-qualification/007-status.md | 138 ++++++++++++++++++ plans/registry.md | 27 ++-- .../subsystems/build-qualification-roadmap.md | 6 +- 5 files changed, 171 insertions(+), 34 deletions(-) create mode 100644 plans/closure/build-qualification/007-status.md diff --git a/plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md b/plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md index a074288..d007a01 100644 --- a/plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md +++ b/plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md @@ -1,8 +1,8 @@ # ADR-0006: Release Evidence Digest Acceptance Set -Status: **proposed** +Status: **accepted** (Option A) -Date: 2026-10-23 +Date: 2026-10-23 (accepted 2026-10-23) Decision owners: project maintainers @@ -26,16 +26,17 @@ Affected subsystem roadmaps: ## 1. Status note -This record is **proposed**, not accepted. It exists because a post-implementation -review found that Eggpack carries **three different SHA-256 acceptance rules** for -the same concept, and because the choice between them is a public compatibility -decision rather than an internal refactor. +This record is **accepted** (Option A), decided by the project maintainers on +2026-10-23. It exists because a post-implementation review found that Eggpack +carries **three different SHA-256 acceptance rules** for the same concept, and +because the choice between them is a public compatibility decision rather than +an internal refactor. Accepting this ADR authorizes `plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md` -to implement the selected rule set. Until it is accepted, M003l's digest-validator -work package is **blocked**, and every other milestone in this review chain stays -independently implementable. +to implement the selected rule set. The digest-validator work package in M003l +is therefore **unblocked**. Every other milestone in this review chain stays +independently implementable and is unaffected by this decision. ## 2. Context @@ -157,9 +158,13 @@ version-1 documents in the field continue to parse under a tightened rule. ## 5. Decision -**Recommended: Option A — reject the all-zeros digest everywhere, keeping +**Accepted: Option A — reject the all-zeros digest everywhere, keeping `ReleaseManifest` at `schema_version: 1`.** +Option B is rejected: it would leave two behaviours for one rule, which is the +class of duplication this review chain exists to remove. Option C is rejected. +Option D is rejected as disproportionate. + Concretely, on acceptance: 1. One shared SHA-256 hex validator is defined in `eggpack-manifest`, which owns diff --git a/plans/adrs/README.md b/plans/adrs/README.md index 663443a..aa47a7d 100644 --- a/plans/adrs/README.md +++ b/plans/adrs/README.md @@ -37,11 +37,7 @@ Use an ADR when a decision establishes ownership, a public compatibility contrac ## Proposed records -- ADR-0006 — release evidence digest acceptance set. Decides whether the - all-zeros SHA-256 sentinel is refused by every producer path and whether the - published `ReleaseManifest` acceptance set narrows, which is a compatibility - change to the published `eggpack-manifest` crate. Gates the - digest-acceptance work package of CI M003l only. +_None. ADR-0006 was the last proposed record and was accepted on 2026-10-23._ ## Accepted records @@ -49,4 +45,5 @@ Use an ADR when a decision establishes ownership, a public compatibility contrac - ADR-0002 — contract/plan/manifest separation; - ADR-0003 — checked-in generated CI and explicit publication gate; - ADR-0004 — first-party native Cargo/cargo-zigbuild adapter boundary; -- ADR-0005 — native qualification is independent of build strategy when the qualification host matches the target OS/architecture. +- ADR-0005 — native qualification is independent of build strategy when the qualification host matches the target OS/architecture; +- ADR-0006 — release evidence digest acceptance set (accepted 2026-10-23, Option A): the all-zeros SHA-256 sentinel is refused by every producer path, `ReleaseManifest` stays at `schema_version: 1`, and the published `eggpack-manifest` crate takes a `0.1.1` patch release carrying the tightened rule. Authorized the digest-acceptance work package of CI M003l. diff --git a/plans/closure/build-qualification/007-status.md b/plans/closure/build-qualification/007-status.md new file mode 100644 index 0000000..26beaa3 --- /dev/null +++ b/plans/closure/build-qualification/007-status.md @@ -0,0 +1,138 @@ +# Build and Qualification Milestone 007 Closure — Evidence Digest Unification Corrective + +Status: closed + +Source plan: `plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md` + +Roadmap: `plans/subsystems/build-qualification-roadmap.md` + +Related decision: `plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md` (**accepted**, Option A). M007 implements no acceptance set and changes no ADR decision; it delivers the canonical file-digest *implementation* that ADR-0006 §5.1 item 5 names as a prerequisite for CI M003l. + +Reviewed baseline: `a0fec98` (`origin/main` — the merge of `eggstack/eggpack#1`, CI M003k, and `eggstack/eggpack#2`). + +Implementation SHA: `e3c6192b3b0e405a0cfe46e5025f31a185881f7e` — `fix(core): unify producer file-digest authority`. + +## Executive finding + +M007 is closed. `eggpack-core` now has exactly **one** file-digest authority: `file_digest` in the new `crates/eggpack-core/src/digest.rs`, carrying the stricter of the two divergent semantics it replaces. The three in-crate implementations that existed before this milestone are gone, and the two out-of-crate implementations in `eggpack-ci` and `eggpack-github` are now unblocked from being converged onto it by CI M003l. + +Nothing was weakened to achieve this. The hashed bytes are unchanged — same hash function, same encoding, same lowercase hex — and the in-tree golden digests are byte-identical. What changed is *which* helper is used and *what it refuses*: a path that changes length, type, or symlink status while it is being read is now refused on the manifest-building path as well as on the finalization path, where previously only the finalization path checked. That is the intended correction, and it fails closed. + +## Production implementation evidence + +| Location | Change | +|---|---| +| `crates/eggpack-core/src/digest.rs` (new) | `pub fn file_digest(path: &Path) -> Result<(u64, String), DigestError>` (`:102`) — the single producer-side file-digest authority. Pre-open `symlink_metadata`; refuses anything that is not a regular non-symlink file; refuses an empty file **before** the read; streams through a fixed 64 KiB buffer (`hash_stream` `:117`); accumulates size with `checked_add` (`add_size` `:139`); re-checks `symlink_metadata` after the read (`post_read_check` `:144`, `post_read_stable` `:153`) and refuses a path that became a symlink, stopped being a regular file, or changed length. Carries the TOCTOU rationale that the retired `crates/eggpack-core/src/lib.rs:292-296` comment carried. | +| `crates/eggpack-core/src/digest.rs` (new) | `pub enum DigestError` (`:31`) with the typed refusal reasons `Unavailable`, `NotRegularFile`, `Empty`, `OpenFailed`, `ReadFailed`, `SizeOverflow`, `ChangedDuringRead`. Replaces the previous opaque `String` error, so no diagnostic became vaguer than it was. | +| `crates/eggpack-core/src/lib.rs` | `fn digest_file` **retired**. The two `build_manifest` call sites (`:209`, `:256`) now call `file_digest` with subject `"finalized file"`. | +| `crates/eggpack-core/src/finalization.rs` | `fn digest_regular` **retired**. Four call sites routed through `digest_candidate_bytes` (`:316`) and `digest_finalized_bytes` (`:321`). | +| `crates/eggpack-core/src/qualification.rs` | The inline SHA-256 streaming loop inside `inspect_candidate` is replaced by `file_digest` (`:1138-1141`). `DigestError::ChangedDuringRead` maps to `QualificationFailure::CandidateChanged`; every other variant maps to `QualificationFailure::InvalidRuntimeEnvironment`, so all original failure classifications are preserved. | +| `crates/eggpack-core/src/lib.rs` | `pub mod digest;` and the crate-root re-exports of `file_digest` and `DigestError`, so `eggpack-ci` and `eggpack-github` can consume the same authority. | + +Retained, deliberately unchanged: the hash function, the digest encoding, the lowercase hex representation, the finalization order, archive assembly, sidecar content, the `ReleaseManifest v1` field set and `schema_version`, and the published `eggpack-manifest` crate. + +Documentation: `crates/eggpack-core/README.md`, `architecture/core-finalization.md` (a new "File-digest authority" section states the TOCTOU rule **once**, replacing the two separate descriptions), and `architecture/core.md` (file map and a single pointer to that rule). All `file:line` citations in the two architecture documents were re-based **by symbol name** and read back to confirm the cited line holds what the sentence claims. + +## Plan inventory correction — a third in-crate implementation + +The plan's §2 evidence inventory named **two** in-crate file-digest implementations. It was incomplete: `crates/eggpack-core/src/qualification.rs` (`inspect_candidate`) held a **third** SHA-256 streaming loop, which the plan's §5 requirement "every core call site routes to the canonical helper" and its §12 acceptance criterion "exactly one file-digest implementation" both require to be routed. + +It was routed through `file_digest` in this milestone. The change is behaviour-preserving: the same bytes are hashed, the same `canonical` path is inspected, and every original failure classification is retained. Had it been left in place, "exactly one implementation" and "every core call site" would both have been false at closure. + +This is recorded here rather than silently absorbed, because a plan's evidence inventory being short by one implementation is a planning defect worth knowing about: any future change in this area should inventory the whole workspace, not only the two call sites a defect report happened to name. + +## Requirement-to-evidence matrix + +| Plan requirement | Evidence and result | +|---|---| +| §5.1 one canonical helper carrying the stricter semantics | `crates/eggpack-core/src/digest.rs`; `file_digest` performs the pre-open metadata check, the pre-read empty refusal, the bounded streaming read, the `checked_add` accumulation, and the post-read re-check. | +| §5.1 helper is `pub`, returns a typed error | `pub fn file_digest`, `pub enum DigestError`, re-exported at the crate root. | +| §5.2 both duplicates retired, every core call site routed | `grep` for `digest_file` and `digest_regular` returns **zero** occurrences in `eggpack-core`; the only file-digest streaming loop left in the crate is `digest.rs:118`. | +| §5.3 refusal reasons distinguished | The seven `DigestError` variants map one-to-one onto the refusals the two retired helpers performed. | +| §5.4 TOCTOU rationale documented | Carried into the new module's doc comment on `file_digest`. | +| §3 invariant: identical bytes ⇒ identical digest and size | `regular_file_digest_is_the_lowercase_hex_sha256_of_its_bytes` and `identical_bytes_digest_identically_and_different_bytes_differ`; the in-tree golden digests are unchanged and `manifest_records_agree_with_the_finalized_bytes_for_every_artifact` passes on both the pre- and post-change tree. | +| §3 invariant: a symlink is never followed | `symlink_is_refused`, `finalization_refuses_a_symlinked_candidate`, `manifest_builder_refuses_a_symlinked_artifact`. | +| §3 invariant: an empty file is refused before it is read | `empty_file_is_refused_before_it_is_read`. | +| §3 invariant: size overflow is an error, never a wrap | `add_size` uses `checked_add` and returns `DigestError::SizeOverflow`. | +| §3 invariant: streaming through a fixed buffer, never the whole artifact | `hash_stream` reads through a fixed 64 KiB buffer. | +| §8 invariant: no schema change, published crate untouched | `ReleaseManifest v1` fields, `schema_version`, and `crates/eggpack-manifest/**` are untouched by this commit. | +| §8 invariant: no new dependency | `sha2` was already an `eggpack-core` dependency; `Cargo.toml` is unchanged. | +| §4 out of scope: no acceptance set | No SHA-256 hex acceptance rule was added, changed, or removed. ADR-0006 is untouched by this commit. | +| §4 out of scope: `eggpack-ci` and `eggpack-github` digest implementations | Both are untouched by this commit; CI M003l converges them onto `file_digest`. | + +## Verification executed + +All verification below ran against implementation SHA `e3c6192`, scoped to the actual change as the maintainer directed for this stage: + +```text +cargo fmt --all -- --check passed +cargo check -p eggpack-core --all-targets --all-features --locked passed +cargo clippy -p eggpack-core --all-targets --all-features --locked -- -D warnings passed +cargo test -p eggpack-core --all-targets --all-features --locked passed (61 passed, 0 failed, 6 ignored; 57/6 before M007) +cargo check --workspace --all-targets --all-features --locked passed +git diff --check passed +``` + +The workspace-wide `cargo check` was run specifically to prove that retiring the two private helpers broke no other crate; `eggpack-ci` and `eggpack-github` each carry their own digest implementation and do not call core's. + +The four new tests are `regular_file_digest_is_the_lowercase_hex_sha256_of_its_bytes`, `identical_bytes_digest_identically_and_different_bytes_differ`, `empty_file_is_refused_before_it_is_read`, `symlink_is_refused`, and `post_read_symlink_change_is_refused` (`crates/eggpack-core/src/digest.rs`), plus `finalization_refuses_a_symlinked_candidate` (`crates/eggpack-core/src/finalization.rs`) and `manifest_builder_refuses_a_symlinked_artifact` / `manifest_records_agree_with_the_finalized_bytes_for_every_artifact` (`crates/eggpack-core/src/lib.rs`). + +**Pre-change discrimination was verified empirically.** The pre-change tree was extracted to a scratch directory and the new tests were run against it: `finalization_refuses_a_symlinked_candidate` fails against the pre-change tree and passes after the change; `manifest_records_agree_with_the_finalized_bytes_for_every_artifact` passes on **both** trees, which is what proves the digests and sizes are unchanged. + +## Deviations and observable behaviour changes + +1. **The post-read race cannot be staged deterministically.** The plan's §6 WP1 explicitly permits asserting the *presence* of the re-check by unit-testing the post-read comparison directly rather than by racing a thread. `post_read_check` is therefore unit-tested against real files for a length change, a type change, and a symlink change. The tests prove the **comparison refuses**; they do not prove that `file_digest` still *calls* that comparison. This limitation is stated in the test comments, as the plan requires. +2. **Diagnostics were split where the old code merged them.** The retired `digest_regular` used a single message for symlink, non-regular file, and empty file. The new helper distinguishes them ("candidate file is not a regular non-symlink file", "… must be non-empty"), which is the plan's §5.3 requirement that no diagnostic become vaguer. +3. **Two finalization sites changed their subject noun.** The finalized-copy and sidecar digests now report "finalized file …" rather than "candidate file …", because they are no longer digesting a candidate. No message text was otherwise changed. +4. **Behavioural narrowing (intended).** `build_manifest` now refuses a file that changes during the read. Previously only the finalization path refused such a file. The plan's §8 records this as the intended correction. + +## Compatibility and no-regression evidence + +- **No schema version bump.** `ReleaseManifest v1`, `PackConfig v1`, `CIPlan v1`, and `QualificationEvidence` are all unchanged; no serialized field was added, removed, or renamed anywhere. +- **No golden changed.** The in-tree golden digests are byte-identical; `manifest_records_agree_with_the_finalized_bytes_for_every_artifact` passes on both the pre- and post-change tree. +- **No public API break beyond two private removals.** `digest_file` and `digest_regular` were both private `fn`s. `eggpack-core` is not published. +- **No historical closure rewritten.** `plans/closure/build-qualification/001`–`006-status.md` and every other historical closure record are untouched. +- **Pre-existing tests stay green**, including the finalization suite with its golden digests and the qualification suite. + +## Security and reliability review + +- The change removes a **TOCTOU window**, not a check. The manifest-building path previously digested a file without re-checking that the file it read was still the file it opened; it now applies the same post-read re-check the finalization path already applied. The window was exploitable by a process that replaced a finalized artifact between the metadata read and the read itself. +- Nothing is weakened: a symlink is still never followed, an empty file is still refused, and a path that changes during the read is refused rather than digested. +- No signature, provenance, or authenticity claim is introduced. SHA-256 and size remain **integrity facts only**, consistent with the workspace's standing rule that integrity ≠ authenticity. +- No network, credential, privilege, publication, or archive surface is touched. The helper performs no writes and holds no locks, so concurrent callers are independent; each observes a self-consistent `(size, digest)` pair or an error. +- No error message embeds artifact content, so no diagnostic can leak bytes. + +## Failure and recovery review + +- A refused digest is a hard failure of the enclosing operation. It is never downgraded to a warning, never retried against the same path, and never recorded as an empty digest. No partial or placeholder digest is emitted; there is no sentinel success value. +- Restarting a failed finalization re-runs the digest from the beginning; there is no resumable state to corrupt. +- Rollback is a revert of this single commit. The previously laxer `build_manifest` behaviour returns, with no consumer impact, because no producer emits a file that changes during its own read. +- There is no contention or restart hazard: the milestone adds no new external service, cache, or shared state. + +## Findings + +| Severity | Finding | Disposition | +|---|---|---| +| Resolved in this milestone (medium, plan accuracy) | The plan's §2 inventory named two in-crate file-digest implementations; `crates/eggpack-core/src/qualification.rs` (`inspect_candidate`) held a third SHA-256 streaming loop. | Routed through the canonical helper in this milestone, because the plan's own §5 and §12 require "every core call site" and "exactly one implementation" to hold. The plan's inventory was short by one implementation; recorded here so the record is not silently inaccurate. | +| Low (test coverage) | The post-read re-check cannot be proven to be *invoked* by a deterministic test on this platform. | Tested at the comparison level, as the plan's §6 WP1 explicitly permits, with the limitation stated in the test comments. A hostile-reader simulation is not implemented and is not claimed. | +| Operational boundary | Verification ran on Linux x86-64 only. The macOS and Windows lanes are covered by hosted CI only. | Accepted; the same boundary every prior milestone recorded. | +| None | No unresolved medium-or-higher defect in the corrected producer contract. | M007 acceptance criteria satisfied. | + +## Roadmap disposition and dependency transitions + +| Milestone | Status after M007 | Reason | +|---|---|---| +| Build/Qualification M007 | closed | This record; implementation `e3c6192`. | +| Build/Qualification M008 | unblocked | Its only blocker was M007's canonical digest authority. | +| CI/Release M003l | unblocked on its remaining blocker | ADR-0006 is accepted (Option A), and M003l's digest work package now has the canonical helper to consume. Its other gate — the M003k merge — is satisfied by `a0fec98`. | + +## Downstream-unblock answer + +Closing M007 unblocks **Build/Qualification M008** and removes one of **CI/Release M003l**'s three gates. It unblocks no other milestone. + +## Eggstack references + +- Closed source plan: `plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md` +- Related accepted decision: `plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md` +- Successor: `plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md` +- Consumer of the delivered API: `plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md` diff --git a/plans/registry.md b/plans/registry.md index aa3abd1..832eca3 100644 --- a/plans/registry.md +++ b/plans/registry.md @@ -94,9 +94,9 @@ Distribution predecessor evidence: | Contract and conformance | **complete** | `plans/subsystems/contract-conformance-roadmap.md` | M001-M003 closed | M003 closed on `43fa2d7`; closure `plans/closure/contract-conformance/003-status.md`: additive local `eggpack contract expand` scalar projection over existing schema-v1 semantics, 18 new tests including a process-boundary stdout contract, parity proven against eggsact `d4e6e5c` and stegoeggo `v0.5.0` for every target/alias/field. Roadmap §11 completion definition fully met; no contract milestone remains registered | | External backend evaluation | closed | `plans/subsystems/external-backend-evaluation-roadmap.md` | M001 closed (C) | no production backend adopted; new evidence/plan required to reopen | | Release manifest | active | `plans/subsystems/release-manifest-roadmap.md` | M002/M003 closed; M003a closed | M003a closed as a docs-only post-publication downstream-closure reconciliation after Eggup M004 closed (`eggstack/eggup@ea1f1c5e29302e5feca4599db9342d3a5ac93915`; formal Eggup status cleanup `eggstack/eggup@3b82d5397e728649a666690868a1e2d0fe42460d`); closure `plans/closure/release-manifest/003a-status.md`; M003 remains closed and no runtime/package requalification was performed or implied | -| Build and qualification | active | `plans/subsystems/build-qualification-roadmap.md` | M001-M006 closed; M007 and M009 ready; M008 blocked on M007 | M006 closed on `398cd43` + run 36484758546 under accepted ADR-0005 Option A. The 2026-10-23 post-implementation review registered M007 (evidence digest unification), M008 (compatibility floor verification), and M009 (local producer operator commands) | +| Build and qualification | active | `plans/subsystems/build-qualification-roadmap.md` | M001-M007 closed; M008 and M009 ready | M007 closed on `e3c6192`: one canonical bounded file-digest authority in `eggpack-core` (`crates/eggpack-core/src/digest.rs`), retiring core's three divergent digest implementations, including a third in-crate SHA-256 stream in `qualification.rs` that the plan's inventory had missed. M006 closed on `398cd43` + run 36484758546 under accepted ADR-0005 Option A. The 2026-10-23 post-implementation review registered M007 (evidence digest unification, closed), M008 (compatibility floor verification), and M009 (local producer operator commands) | | Bootstrap installers | active; corrective closed | `plans/subsystems/bootstrap-installers-roadmap.md` | M002b closed; prior milestones closed | M002b implementation `88ddf2e`, hosted run `37806244313`; POSIX runtime remains on Unix and Windows PowerShell archive runtime passed. M003 completion definition remains satisfied | -| CI/release orchestration | active; M003j closed, M003k in progress | `plans/subsystems/ci-release-orchestration-roadmap.md` | M003k pre-checkout tag resolution + stage environment | Local gates pass; hosted matrix, producer PR review, and downstream pin/qualification remain. The 2026-10-23 post-implementation review registered M003l (producer rule authority convergence), M003m (bounded process execution convergence), and M003n (producer implementation consolidation), chained behind M003k | +| CI/release orchestration | active; M003j closed, M003k closed, M003l in progress | `plans/subsystems/ci-release-orchestration-roadmap.md` | M003l producer rule authority convergence | M003k merged to `main` at `a0fec98` (PR `eggstack/eggpack#1` plus `eggstack/eggpack#2`); its merge gate is discharged. M003l is unblocked by that merge, by Build/Qualification M007 (`e3c6192`), and by accepted ADR-0006 (Option A). The 2026-10-23 post-implementation review registered M003l, M003m (bounded process execution convergence), and M003n (producer implementation consolidation), chained behind M003l | | Eggup interoperability | active | `plans/subsystems/eggup-interoperability-roadmap.md` | Eggpack M001a + Eggup adapter M001/M001a + Eggup M003 real-consumer adoption + Eggup M004 registry promotion all closed | The whole producer/consumer package seam is closed end to end; Release Manifest M003a closed the remaining Eggpack-side planning drift, and no Eggpack work remains on this seam; Eggwork Operations M003 remains producer-only | | Ecosystem adoption | active | `plans/subsystems/ecosystem-adoption-roadmap.md` | M001/M002/M003a/M003b closed | Closure `plans/closure/ecosystem-adoption/003b-status.md`. Paired plans: Eggpack `plans/implementation/ecosystem-adoption/003b-eggsearch-seven-target-eggpack-producer-cutover.md` (`325d44e`); Eggsearch `plans/implementation/eggpack-release-adoption/001-seven-target-eggpack-producer-cutover.md` (`377f9e8`, registry `6767062`). Implementation landed at `eggstack/eggsearch@eabbf80`; hosted run `37531104901` staged eggsearch `v0.4.2` as draft `405157598` with the exact 19-asset inventory, glibc 2.17 re-proven on all three GNU targets, ARMv7 required consumer validator green, Windows ARM64 required and green, and zero OIDC permission in generated jobs. Provenance attested the staged bytes in run `37561960304`; the draft was published 2026-10-07, closing the named condition | | Planning hygiene | active | `plans/subsystems/planning-hygiene-roadmap.md` | M001/M002 closed; M003 ready | M002 closed at `plans/closure/planning-hygiene/002-status.md`: docs/evidence-only post-M003a handoff reconciliation with an empty production/package/workflow diff; stale/duplicated control-surface text removed and the handoff bound to exact paired-plan paths. M003 ready: docs/evidence-only post-implementation-review baseline reconciliation (architecture citation re-base by symbol name, `AGENTS.md` handoff rewrite, full CLI command reference, review-chain registration) | @@ -107,7 +107,7 @@ Distribution predecessor evidence: Planning Hygiene M002, Ecosystem M003b, Bootstrap M002b, CI M003i, and CI M003j are closed. **Dependency-ready CI M003k:** `plans/implementation/ci-release-orchestration/003k-precheckout-tag-resolution-and-stage-environment.md`. It resolves the downstream wg-basic R001 pre-checkout and stage-environment gates while preserving M003j's safe dispatch handling. -The post-implementation review of 2026-10-23 registered three further dependency-ready milestones. None contends with CI M003k, because each is confined to a crate CI M003k does not touch: **Build/Qualification M007** (evidence digest unification, `crates/eggpack-core/**` only), **Build/Qualification M009** (local producer operator commands, `crates/eggpack-cli/**` only), and **Planning Hygiene M003** (docs/evidence-only). The review chain continues behind them: Build/Qualification M008, then CI M003l, CI M003m, and CI M003n. **ADR-0006 is proposed, not accepted**; it gates the digest-acceptance work package of CI M003l only. +The post-implementation review of 2026-10-23 registered a corrective chain. **Build/Qualification M007 is closed** (`e3c6192`): `eggpack-core` now has one canonical bounded file-digest authority, and the SHA-256 hex acceptance set is decided by **accepted ADR-0006 (Option A)** — the all-zeros sentinel is refused everywhere, `ReleaseManifest` stays at `schema_version: 1`, and the published `eggpack-manifest` crate takes a `0.1.1` patch release carrying the tightened rule. With the M003k merge (`a0fec98`) and M007 in place, **CI M003l is unblocked and in progress**. Still ahead: **Build/Qualification M008** (now ready) and **Build/Qualification M009** (ready), then CI M003m and CI M003n behind M003l, with **Planning Hygiene M003** (docs-only) independent of the chain. The table below is the **milestone-to-closure index plus active ready work**, not an implication that every historical row is executable. @@ -116,8 +116,8 @@ The table below is the **milestone-to-closure index plus active ready work**, no | Bootstrap installers | M002b Windows POSIX archive-test portability | **closed** | `plans/implementation/bootstrap-installers/002b-windows-posix-archive-test-portability-corrective.md` | Closure `plans/closure/bootstrap-installers/002b-status.md`; implementation `88ddf2e`; hosted run `37806244313` all lanes green | | CI orchestration | M003i exact tag versus manifest release ID policy | **closed** | `plans/implementation/ci-release-orchestration/003i-explicit-tag-and-manifest-release-identity-corrective.md` | Closure `plans/closure/ci-release-orchestration/003i-status.md`; implementation `3ddac9d84fc2e10b8451d38672f66b02e06724df`; hosted run `37813044035` all four lanes green. wg-basic M003 may resume with this pin | | CI orchestration | M003j dispatch-tag Bash interpolation corrective | closed | `plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md` | Closure `plans/closure/ci-release-orchestration/003j-status.md`; implementation `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce`; hosted run `37987890305` all four lanes green | -| CI orchestration | M003k pre-checkout tag resolution and stage approval gate | **in progress** | `plans/implementation/ci-release-orchestration/003k-precheckout-tag-resolution-and-stage-environment.md` | PR `eggstack/eggpack#1` at `23d9f0347d89fd6ecd916692c145152e39de687f`; local gate and hosted run `38027143275` passed; independent review/merge and downstream qualification pending | -| CI orchestration | M003l producer rule authority convergence corrective | **blocked** | `plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md` | Blocked on CI M003k merge, Build/Qualification M007, and ADR-0006 acceptance. Removes the duplicate host-match, floor-applicability, exact-tag, SHA-256 acceptance, and file-digest rules; the two exact-tag rule sets are disjoint in both directions and their union becomes canonical | +| CI orchestration | M003k pre-checkout tag resolution and stage approval gate | closed | `plans/implementation/ci-release-orchestration/003k-precheckout-tag-resolution-and-stage-environment.md` | PR `eggstack/eggpack#1` merged to `main` at `1103a1a` (followed by `eggstack/eggpack#2` at `a0fec98`); implementation `fb81aa1`; local gate and hosted run `38027143275` passed | +| CI orchestration | M003l producer rule authority convergence corrective | **in progress** | `plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md` | Unblocked: CI M003k merged (`a0fec98`), Build/Qualification M007 closed (`e3c6192`), ADR-0006 accepted (Option A). Removes the duplicate host-match, floor-applicability, exact-tag, SHA-256 acceptance, and file-digest rules; the two exact-tag rule sets are disjoint in both directions and their union becomes canonical | | Planning hygiene | M001 current evidence baseline + blocker reconciliation | closed | `plans/implementation/planning-hygiene/001-current-evidence-baseline-and-blocker-reconciliation.md` | Closure `plans/closure/planning-hygiene/001-status.md`; discharged CI M003b (eggsact `685fa373` + run `36886042696`) and closed Ecosystem M002 on stegoeggo `v0.5.0` (run `37181914252`); docs-only, zero production/package/workflow delta | | Planning hygiene | M002 post-M003a cross-repository handoff reconciliation | closed | `plans/implementation/planning-hygiene/002-post-m003a-cross-repository-handoff-reconciliation.md` | Closure `plans/closure/planning-hygiene/002-status.md`; docs/evidence-only; stale M003/M003a/M003b control-surface text reconciled against exact paired-plan paths; empty production/package/workflow diff | | Planning hygiene | M003 post-implementation-review baseline reconciliation | **ready** | `plans/implementation/planning-hygiene/003-post-implementation-review-baseline-reconciliation.md` | Docs/evidence-only. Re-bases the `architecture/` citation set and line counts by symbol name against a measured baseline, closes the `ci-consumer-seam.md` and residual `cli.md` drift, rewrites the `AGENTS.md` current handoff, completes the CLI command reference, and registers the review chain. Zero production diff required | @@ -135,8 +135,8 @@ The table below is the **milestone-to-closure index plus active ready work**, no | Build and qualification | M004 finalization/aggregation | closed | `plans/implementation/build-qualification/004-finalization-and-local-aggregation.md` | Closure `plans/closure/build-qualification/004-status.md`; hosted run 36098072913 | | Build and qualification | M005 deterministic cross-tool provisioning | closed | `plans/implementation/build-qualification/005-deterministic-cross-tool-provisioning.md` | Closure `plans/closure/build-qualification/005-status.md`; implementation `7a206ba`; hosted run 36256831000 green; exact Zig 0.14.1 / cargo-zigbuild 0.23.3 provisioning, verified Zig path binding, private cargo-zigbuild cache | | Build and qualification | M006 native qualification for cross-tool builds | closed | `plans/implementation/build-qualification/006-native-qualification-for-cross-tool-builds.md` | Closure `plans/closure/build-qualification/006-status.md`; implementation `398cd43`; hosted run 36484758546 green; host-matched native qualification is now independent of the builder, with split-host qualification and eggsact-shaped five-target render evidence | -| Build and qualification | M007 evidence digest unification corrective | **ready** | `plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md` | Confined to `crates/eggpack-core/**`. Replaces core's two divergent file-digest helpers with one canonical helper carrying the stricter TOCTOU, empty-file, and overflow-checked semantics; delivers the helper CI M003l consumes | -| Build and qualification | M008 compatibility floor verification corrective | **blocked** | `plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md` | Blocked on Build/Qualification M007. A declared glibc floor is currently accepted and silently dropped under `NativeCargo`; M008 adds an explicit floor verification status and independent bounded ELF `GLIBC_x.y` inspection. `ReleaseManifest` v1 unchanged | +| Build and qualification | M007 evidence digest unification corrective | **closed** | `plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md` | Closure `plans/closure/build-qualification/007-status.md`; implementation `e3c6192`. One canonical bounded file-digest authority in `crates/eggpack-core/src/digest.rs` with typed refusals; core's two planned duplicates and a third in-crate SHA-256 stream in `qualification.rs` retired; the hashed bytes, the golden digests, and `ReleaseManifest v1` are unchanged | +| Build and qualification | M008 compatibility floor verification corrective | **ready** | `plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md` | Unblocked by Build/Qualification M007 (`e3c6192`). A declared glibc floor is currently accepted and silently dropped under `NativeCargo`; M008 adds an explicit floor verification status and independent bounded ELF `GLIBC_x.y` inspection. `ReleaseManifest` v1 unchanged | | Build and qualification | M009 local producer operator commands | **ready** | `plans/implementation/build-qualification/009-local-producer-operator-commands.md` | Confined to `crates/eggpack-cli/**`. Restores six of the nine operator commands named by `plans/000-long-term-specification.md` §5.4 (`check`, `plan`, `package`, `qualify`, `collect`, `manifest`); the `ci _*` runner family stays byte-for-byte unchanged | | Bootstrap installers | M001 generator/direct fixtures | closed | `plans/implementation/bootstrap-installers/001-direct-installer-generator.md` | Closure `plans/closure/bootstrap-installers/001-status.md` | | CI orchestration | M001 CIPlan/GitHub renderer | closed | `plans/implementation/ci-release-orchestration/001-ci-plan-and-github-renderer.md` | Closure `plans/closure/ci-release-orchestration/001-status.md`; hosted run 36040032768 passes all lanes | @@ -166,9 +166,6 @@ were removed rather than left to mislead. | Subsystem | Milestone | State | Blocker | |---|---|---|---| -| Architecture decision | ADR-0006 release evidence digest acceptance set | proposed | `plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md`. Awaiting maintainer acceptance. Decides whether the all-zeros SHA-256 sentinel is refused everywhere, and whether the published `ReleaseManifest` acceptance set narrows — a compatibility change to the published `eggpack-manifest` crate. Gates the digest-acceptance work package of CI M003l only; every other milestone in the review chain is independently implementable | -| Build and qualification | M008 compatibility floor verification corrective | blocked | Build/Qualification M007. A declared glibc floor is accepted and silently dropped under `NativeCargo`, and no artifact records that it went unverified; ADR-0005 §9 requires this verification to be planned independently | -| CI orchestration | M003l producer rule authority convergence corrective | blocked | CI M003k merge (PR `eggstack/eggpack#1`, touches `crates/eggpack-ci/src/lib.rs`), Build/Qualification M007, and ADR-0006 acceptance. The two exact-tag rule sets are disjoint in both directions: neither is a superset of the other, so the union becomes canonical | | CI orchestration | M003m bounded process execution convergence corrective | blocked | CI M003l. The CI consumer-validator runner kills only the direct child and joins its reader threads without a bound, so a descendant holding an inherited pipe can wedge a CI job past its timeout | | CI orchestration | M003n producer implementation consolidation corrective | blocked | CI M003m. One drift comparison replaces three byte-identical copies; one staging-payload builder replaces two copies that are 85.5% identical; `render_release_github_inner` is 845 lines; the CI crate's source file is 11,044 lines | | Ecosystem adoption | M004 Gregg sibling bundle | blocked | Remains after Eggsearch target-diversity evidence; prior adoption evidence + Gregg bundle/service review | @@ -285,17 +282,17 @@ Post-implementation review chain [2026-10-23] (independent of the closed history above; it corrects rules and structure that the closed milestones introduced, and rewrites no closure record): -ADR-0006 [PROPOSED: digest acceptance set] +ADR-0006 [ACCEPTED 2026-10-23, Option A: digest acceptance set] | - +--> CI M003l producer rule authority convergence [BLOCKED: M003k merge + M007 + ADR-0006] + +--> CI M003l producer rule authority convergence [IN PROGRESS] | +--> CI M003m bounded process execution convergence [BLOCKED: M003l] | +--> CI M003n producer implementation consolidation [BLOCKED: M003m] -Build/Qualification M007 evidence digest unification [READY: core only] +Build/Qualification M007 evidence digest unification [CLOSED: e3c6192] | - +--> Build/Qualification M008 compatibility floor verification [BLOCKED: M007] + +--> Build/Qualification M008 compatibility floor verification [READY: core only] | +--> CI M003l (also depends on M007) @@ -340,7 +337,7 @@ Eggsearch **M003b passed implementation and is conditionally closed.** M003a set Longer-horizon lines stay as recorded: Ecosystem M004-M007 behind completed Eggsearch adoption, Phase 12 provenance behind a dedicated trust ADR, Phase 13 package adapters behind broader native adoption, Phase 14 stabilization premature. Eggsact's Git-to-registry migration remains separately owned downstream. -**The 2026-10-23 post-implementation review registered a corrective chain.** It found that the workspace carries several rules and structures in more than one place, and that the two copies do not always agree: four file-digest implementations with different TOCTOU behaviour, three SHA-256 acceptance rules where the crate that stages bytes accepts a digest the CI crate refuses, two exact-tag rule sets that are disjoint in both directions, a CI process runner that kills only the direct child and joins its reader threads without a bound, and a drift comparison and a staging-payload builder that each exist in duplicate. It also found a declared-but-unenforced compatibility floor, and a CLI that exposes two of the nine operator commands the canonical specification names. The chain is registered above; it corrects closed milestones' behaviour without rewriting any closure record. Three milestones are dependency-ready now and none contends with CI M003k: Build/Qualification M007, Build/Qualification M009, and Planning Hygiene M003. The rest follow behind M007, M003k, and ADR-0006. +**The 2026-10-23 post-implementation review registered a corrective chain.** It found that the workspace carries several rules and structures in more than one place, and that the two copies do not always agree: four file-digest implementations with different TOCTOU behaviour, three SHA-256 acceptance rules where the crate that stages bytes accepts a digest the CI crate refuses, two exact-tag rule sets that are disjoint in both directions, a CI process runner that kills only the direct child and joins its reader threads without a bound, and a drift comparison and a staging-payload builder that each exist in duplicate. It also found a declared-but-unenforced compatibility floor, and a CLI that exposes two of the nine operator commands the canonical specification names. The chain is registered above; it corrects closed milestones' behaviour without rewriting any closure record. **Build/Qualification M007 is closed** (`e3c6192`) and **ADR-0006 is accepted (Option A)**, so the all-zeros SHA-256 sentinel is refused everywhere and `ReleaseManifest` stays at `schema_version: 1`. **CI M003l is in progress**; Build/Qualification M008 and M009 and Planning Hygiene M003 are ready and independent of it, and CI M003m and M003n follow behind M003l. ## Downstream unblock disposition diff --git a/plans/subsystems/build-qualification-roadmap.md b/plans/subsystems/build-qualification-roadmap.md index 4c07643..89476f7 100644 --- a/plans/subsystems/build-qualification-roadmap.md +++ b/plans/subsystems/build-qualification-roadmap.md @@ -176,7 +176,7 @@ Eggpack can construct and qualify real direct/bundle/archive native releases loc M001 PackConfig and ReleasePlan is closed. Release Manifest M001/M001a and Contract M001/M002 are closed. Backend-evaluation evidence is closed with disposition C, which does not authorize a backend. M005 closed the provisioning prerequisite; M006 then closed the producer-policy gap that first-consumer review exposed, so `Qualification::Native` is now admissible for a `CargoZigbuild` candidate on a matching host. The build/qualification milestone chain through M006 is closed. Ecosystem M001 is unblocked and must re-review the current eggsact baseline and re-pin `eggpack_tool.revision` at the M006 implementation before it implements. -The 2026-10-23 post-implementation review registered three further milestones against this subsystem. **M007** unifies core's two divergent file-digest helpers into one canonical helper, because the weaker copy is the one that produces the aggregated manifest evidence. **M008** plans the independent verification that a produced binary honours a declared glibc/macOS floor, which ADR-0005 §9 requires and which remains unplanned and unclaimed by M006; it adds an explicit floor verification status to the plan and the qualification evidence, because a floor declared under `NativeCargo` is currently accepted and then silently dropped, and nothing downstream records that it went unverified. **M009** restores six of the nine operator commands named by `plans/000-long-term-specification.md` §5.4, so a producer can construct, qualify, finalize, and aggregate a release on a workstation rather than only through a hosted workflow run. M007 and M009 are dependency-ready; M008 follows M007. +The 2026-10-23 post-implementation review registered three further milestones against this subsystem. **M007** unifies core's divergent file-digest helpers into one canonical helper, because the weaker copy is the one that produces the aggregated manifest evidence; it closed on `e3c6192`. **M008** plans the independent verification that a produced binary honours a declared glibc/macOS floor, which ADR-0005 §9 requires and which remains unplanned and unclaimed by M006; it adds an explicit floor verification status to the plan and the qualification evidence, because a floor declared under `NativeCargo` is currently accepted and then silently dropped, and nothing downstream records that it went unverified. It is now ready, unblocked by M007. **M009** restores six of the nine operator commands named by `plans/000-long-term-specification.md` §5.4, so a producer can construct, qualify, finalize, and aggregate a release on a workstation rather than only through a hosted workflow run. | Milestone | Status | Implementation plan | Closure record | Blockers / sequencing | |---|---|---|---|---| @@ -187,6 +187,6 @@ The 2026-10-23 post-implementation review registered three further milestones ag | M004 finalization/aggregation | closed | `plans/implementation/build-qualification/004-finalization-and-local-aggregation.md` | `plans/closure/build-qualification/004-status.md` | Local and hosted verification passed | | M005 deterministic cross-tool provisioning | closed | `plans/implementation/build-qualification/005-deterministic-cross-tool-provisioning.md` | `plans/closure/build-qualification/005-status.md`; implementation `7a206ba`; hosted run 36256831000 green | exact Zig 0.14.1/cargo-zigbuild 0.23.3 provisioning, explicit verified-Zig binding/private cache | | M006 native qualification for cross-tool builds | closed | `plans/implementation/build-qualification/006-native-qualification-for-cross-tool-builds.md` | `plans/closure/build-qualification/006-status.md`; implementation `398cd43`; hosted run 36484758546 green | ADR-0005 Option A implemented; host-matched native qualification is independent of builder, including split-host qualification; Ecosystem M001 unblocked | -| M007 evidence digest unification corrective | ready | `plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md` | — | Confined to `crates/eggpack-core/**`. One canonical file-digest helper replaces core's two divergent copies; delivers the helper CI M003l consumes. No acceptance-set change | -| M008 compatibility floor verification corrective | blocked | `plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md` | — | Blocked on M007. Plans the independent floor verification ADR-0005 §9 requires; adds a floor verification status to the plan and qualification evidence. `ReleaseManifest` v1 unchanged | +| M007 evidence digest unification corrective | closed | `plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md` | `plans/closure/build-qualification/007-status.md`; implementation `e3c6192` | One canonical bounded file-digest authority in `crates/eggpack-core/src/digest.rs` with typed refusals; core's two planned duplicates and a third in-crate SHA-256 stream in `qualification.rs` retired. Hashed bytes, golden digests, and `ReleaseManifest` v1 unchanged. No acceptance-set change | +| M008 compatibility floor verification corrective | ready | `plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md` | — | Unblocked by M007 (`e3c6192`). Plans the independent floor verification ADR-0005 §9 requires; adds a floor verification status to the plan and qualification evidence. `ReleaseManifest` v1 unchanged | | M009 local producer operator commands | ready | `plans/implementation/build-qualification/009-local-producer-operator-commands.md` | — | Confined to `crates/eggpack-cli/**`. Restores six of the nine operator commands named by `plans/000-long-term-specification.md` §5.4; the `ci _*` runner family stays byte-for-byte unchanged | From 9cf0bf8d99230dd9cb7984b718b22a4e26e23c69 Mon Sep 17 00:00:00 2001 From: doc Date: Fri, 23 Oct 2026 15:17:18 +0000 Subject: [PATCH 05/46] fix(ci): converge producer rule authority onto core and manifest Each producer rule now has exactly one owner and one implementation. - eggpack-manifest owns the SHA-256 hex acceptance set (validate_sha256_hex): exactly 64 lowercase hex characters, and the all-zeros placeholder is refused (ADR-0006, Option A). The crate moves to 0.1.1; the ReleaseManifest v1 shape, field set, and schema_version are unchanged. - eggpack-core exposes host_matches_target, validate_policy, validate_floor_applicability, and validate_exact_tag_safety, and re-exports the manifest digest rule. - eggpack-ci applies those rules instead of carrying copies: the CI-side host/target predicate, floor, strategy, toolchain, and native-host derivations are gone; the exact-tag check, the SHA-256 checks, and candidate hashing delegate. Candidate hashing now returns a typed DigestError instead of a (0, "") sentinel. - eggpack-github delegates its tag, digest, and SHA-256 checks. The exact-tag safety rule is the union of the two former concern sets, so it refuses more, never accepts more. The core git-resolution path therefore now refuses tags containing #, @, ', ", `, or $, and also the git-ref-path shapes it already refused. No in-tree tag, workflow input, fixture, or checked-in configuration uses such a tag. Diagnostic wording is preserved at every call site; the only new message text is the all-zeros digest refusal and the newly refused tag shape. Co-Authored-By: Claude Opus 4.8 (1M context) --- Cargo.lock | 2 +- architecture/ci.md | 13 + architecture/core.md | 17 +- architecture/github.md | 13 + architecture/validation-model.md | 54 ++- crates/eggpack-ci/README.md | 10 + crates/eggpack-ci/src/lib.rs | 609 ++++++++++++++++++++++------- crates/eggpack-core/src/builder.rs | 26 +- crates/eggpack-core/src/lib.rs | 181 ++++++++- crates/eggpack-github/README.md | 4 + crates/eggpack-github/src/lib.rs | 163 +++++--- crates/eggpack-manifest/Cargo.toml | 5 +- crates/eggpack-manifest/README.md | 7 + crates/eggpack-manifest/src/lib.rs | 153 ++++++-- 14 files changed, 1014 insertions(+), 243 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index b8c7002..177c8f5 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -251,7 +251,7 @@ dependencies = [ [[package]] name = "eggpack-manifest" -version = "0.1.0" +version = "0.1.1" dependencies = [ "serde", "serde_json", diff --git a/architecture/ci.md b/architecture/ci.md index 86e29a5..b33f82f 100644 --- a/architecture/ci.md +++ b/architecture/ci.md @@ -166,6 +166,19 @@ versioned processes, and it will fail at CI runtime rather than at compile time. restating them. `BuildOutput` (`:94`) is the one place where Cargo-level detail enters, and it is explicit: package and binary are named, never inferred. +- **No producer rule of its own.** The host/target match, the compatibility + floor, the exact-tag safety rule, the SHA-256 hex acceptance set, and the + file digest each have one owner outside this crate. `CIPlan::validate` + (`:282`) calls `eggpack_core::validate_policy` and + `eggpack_core::validate_floor_applicability` instead of re-deriving the + toolchain, floor, or native-qualification host rules; + `validate_sha256_hex` (`:589`) delegates to the manifest rule through core's + re-export; the exact-tag check calls + `eggpack_core::validate_exact_tag_safety`; and candidate hashing calls + `eggpack_core::file_digest`, whose refusal is a typed error rather than a + zero-size placeholder. Each call site keeps its own diagnostic wording, so + the messages this crate emits are unchanged. The full rule map is in + [validation-model.md](validation-model.md). - **No authenticity claim.** Digests and sizes are integrity facts. - **No release selection, update, or rollback.** Those belong to the product repository and to Eggup respectively. diff --git a/architecture/core.md b/architecture/core.md index 06bc154..675acc5 100644 --- a/architecture/core.md +++ b/architecture/core.md @@ -97,8 +97,8 @@ the reason the stages cannot be collapsed: never a skip. This is the rule that unblocked cross-tool builds. The two stages enforce it differently and both must hold: the planning stage rejects an inadmissible combination up front as a fail-closed `CoreError` - (`src/lib.rs:157-160`), and the qualification stage records the observed - `HostMismatch` at run time (`src/qualification.rs:216`). The planning gate + (`src/lib.rs:260-267`), and the qualification stage records the observed + `HostMismatch` at run time (`src/qualification.rs:215`). The planning gate runs only inside `PackConfig::resolve`, not on plain parsing. - **Fail-closed everywhere.** A missing input, an unknown field, an out-of-bounds count, or an unmatched identity is an error. There is no tolerant or @@ -111,6 +111,19 @@ the reason the stages cannot be collapsed: warning and never a placeholder record. The refusal rules — symlinks, empty and non-regular files, and files that change while they are read — are stated once in [core-finalization.md](core-finalization.md). +- **One producer rule authority.** `core` owns the producer's policy rules and + exposes them so that other crates apply them rather than restate them: + `host_matches_target` (`src/lib.rs:90`) for the host/target match, + `validate_policy` (`src/lib.rs:206`) for the whole policy gate, + `validate_floor_applicability` (`src/lib.rs:186`) for the compatibility + floor, and `validate_exact_tag_safety` (`src/lib.rs:313`) for the exact-tag + safety rule. The SHA-256 hex acceptance rule belongs to `eggpack-manifest` + and is re-exported here (`src/lib.rs:18`). Each rule has exactly one + implementation in the workspace; the full map is in + [validation-model.md](validation-model.md). The exact-tag **safety** rule + and the exact-tag **format** rule (`vX.Y.Z`) are separate concerns with + separate diagnostics: safety is about characters and path shape, format is + about the canonical stable version. ## Boundaries diff --git a/architecture/github.md b/architecture/github.md index 4ad952d..dabe232 100644 --- a/architecture/github.md +++ b/architecture/github.md @@ -405,6 +405,19 @@ semantics, only calling `eggpack_bootstrap::render_posix_with_policy` / workflows; and it does not touch registries, Issues, or PRs. The draft is left for a human to publish. +It also owns no producer rule of its own. The SHA-256 hex acceptance set +belongs to `eggpack-manifest` (`validate_sha256_hex`, +`crates/eggpack-manifest/src/lib.rs:98`); `validate_sha256` +(`crates/eggpack-github/src/lib.rs:571`) applies it and keeps this crate's +wording. The file digest belongs to `eggpack-core` (`file_digest`, +`crates/eggpack-core/src/digest.rs:102`); `digest_file` +(`crates/eggpack-github/src/lib.rs:604`) applies it and maps each refusal to +this crate's staging diagnostic. The exact-tag safety rule belongs to +`eggpack-core` (`validate_exact_tag_safety`, +`crates/eggpack-core/src/lib.rs:313`); `validate_tag` +(`crates/eggpack-github/src/lib.rs:494`) applies it. The full rule map is in +[validation-model.md](validation-model.md). + ## Dependencies / dependents Dependencies (`crates/eggpack-github/Cargo.toml:14-26`): `eggpack-contract` diff --git a/architecture/validation-model.md b/architecture/validation-model.md index e7125ba..7e6ed50 100644 --- a/architecture/validation-model.md +++ b/architecture/validation-model.md @@ -356,14 +356,14 @@ Four findings, all verified above, none of them a claim about intent. only partially populated. Rejection is still fail-closed — the effect is diagnostic quality, not acceptance. 4. **Host matching is string-prefix matching, not parsed-triple matching.** - `host_matches_target` (`crates/eggpack-core/src/lib.rs:84-96`) tests + `host_matches_target` (`crates/eggpack-core/src/lib.rs:90-103`) tests `triple.starts_with("x86_64-")` for architecture and then `triple.contains("-linux-")`, `ends_with("-apple-darwin")`, or `contains("-windows-")` for OS. `contains` is a substring test, not a - component test, and the triple is never parsed into components. The - independent copy in `eggpack-ci` (`crates/eggpack-ci/src/lib.rs:393-405`) has - the same property. The nearby floor checks at - `crates/eggpack-core/src/lib.rs:143` and `:146` use the same substring/prefix + component test, and the triple is never parsed into components. There is no + independent copy any more: `eggpack-ci` calls this function. The nearby floor + checks in `floor_applies_to_triple` + (`crates/eggpack-core/src/lib.rs:142-160`) use the same substring/prefix idiom, so floor applicability inherits the same weakness. One further observation, offered as a bound rather than a defect: the @@ -376,6 +376,50 @@ cap their own target count at 256. The contract is producer-authored rather than remotely supplied, so this is a consistency gap in the bounds table rather than an untrusted-input exposure. +## Where each producer rule lives + +Each producer rule has exactly one owner. The owner defines it; every other +crate applies it. There is no second implementation of any of these rules +anywhere in the workspace, and the convergence that produced that state is +recorded in `plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md`. + +| Rule | Owner | Callable as | +|---|---|---| +| Host/target match | `eggpack-core` | `host_matches_target` (`crates/eggpack-core/src/lib.rs:90`) | +| Compatibility-floor applicability | `eggpack-core` | `validate_floor_applicability` (`crates/eggpack-core/src/lib.rs:186`) | +| Exact-tag **safety** | `eggpack-core` | `validate_exact_tag_safety` (`crates/eggpack-core/src/lib.rs:313`) | +| SHA-256 hex acceptance | `eggpack-manifest` | `validate_sha256_hex` (`crates/eggpack-manifest/src/lib.rs:98`) | +| File digest | `eggpack-core` | `file_digest` (`crates/eggpack-core/src/digest.rs:102`) | + +The consumers, and nothing else: + +- **`eggpack-ci`** applies the core rules. `CIPlan::validate` + (`crates/eggpack-ci/src/lib.rs:282`) calls `validate_policy` and + `validate_floor_applicability`; `validate_sha256_hex` + (`crates/eggpack-ci/src/lib.rs:589`) delegates to the manifest rule through + core's re-export (`crates/eggpack-core/src/lib.rs:18`); and the exact-tag + check calls `validate_exact_tag_safety`. Each call site keeps its own + diagnostic wording. +- **`eggpack-github`** applies the manifest and core rules. `validate_sha256` + (`crates/eggpack-github/src/lib.rs:571`) delegates to the manifest rule, + `digest_file` (`crates/eggpack-github/src/lib.rs:604`) delegates to + `file_digest`, and `validate_tag` + (`crates/eggpack-github/src/lib.rs:494`) delegates to + `validate_exact_tag_safety`. +- **`eggpack-core`** owns the rules, and applies them to itself: the git + resolution path uses `validate_exact_tag_safety` + (`crates/eggpack-core/src/builder.rs:430`), and the build-command derivation + uses `validate_floor_applicability` + (`crates/eggpack-core/src/builder.rs:370`). + +Two boundaries matter when reading the table. First, exact-tag **safety** and +exact-tag **format** are different rules: safety is the character-and-shape +rule above; format is the separate canonical-`vX.Y.Z` check with its own +diagnostic. Second, SHA-256 acceptance is an **integrity** fact about bytes — +the accepted set is 64 lowercase hexadecimal characters, minus the all-zeros +placeholder, which no real byte sequence hashes to (ADR-0006). Acceptance says +nothing about authenticity, provenance, or publisher identity. + ## Related deep dives - [overview.md](overview.md) — module map and producer pipeline; start here. diff --git a/crates/eggpack-ci/README.md b/crates/eggpack-ci/README.md index bd4b776..211ed5a 100644 --- a/crates/eggpack-ci/README.md +++ b/crates/eggpack-ci/README.md @@ -67,6 +67,16 @@ the stage job (`--installer-presentation` plus `--source-root` from staging inputs; absent for M003c-compatible staging). Graphs without validators or wrappers render byte-identical to M003c. +This crate owns no producer rule of its own. The host/target match, the +compatibility floor, the exact-tag safety rule, and the file digest belong to +`eggpack-core`; the SHA-256 hex acceptance set belongs to `eggpack-manifest`. +`CIPlan::validate` applies the core policy validation, the exact-tag check +applies the core safety rule, candidate hashing applies the core file digest +(a refusal is a typed error, not a zero-size placeholder), and +`validate_sha256_hex` applies the manifest rule through core's re-export. Each +call site keeps its own diagnostic wording, so this crate's messages and the +rendered workflow bytes are unchanged. + Runner labels and action commit pins are policy inputs rather than CIPlan data. Cross-build runners must declare preinstalled cargo-zigbuild and Zig; generated build jobs check the configured cargo-zigbuild version and never install tools. diff --git a/crates/eggpack-ci/src/lib.rs b/crates/eggpack-ci/src/lib.rs index de6f6a4..6603a34 100644 --- a/crates/eggpack-ci/src/lib.rs +++ b/crates/eggpack-ci/src/lib.rs @@ -5,10 +5,10 @@ use eggpack_contract::DistributionContract; use eggpack_core::{ cargo_command, ArchiveEncoding, BuildAttempt, BuildBindingsV1, BuildStrategy, - CompatibilityFloor, FinalizationRequest, FinalizationTargetInput, HostArch, HostOs, - HostRequirement, LogicalOutputSelector, PackConfig, PlannedAssetForm, PlannedTarget, - Qualification, QualificationBindingsV1, QualificationEvidence, QualificationStatus, - ReleasePlan, SupportTier, TargetPolicy, + FinalizationRequest, FinalizationTargetInput, HostArch, HostOs, HostRequirement, + LogicalOutputSelector, PackConfig, PlannedAssetForm, PlannedTarget, Qualification, + QualificationBindingsV1, QualificationEvidence, QualificationStatus, ReleasePlan, SupportTier, + TargetPolicy, }; use serde::{Deserialize, Serialize}; use sha2::{Digest, Sha256}; @@ -296,46 +296,19 @@ impl CIPlan { for job in &self.targets { let target = &job.planned; let policy = &target.policy; - let cargo_zigbuild_valid = policy - .toolchain - .cargo_zigbuild - .as_deref() - .is_some_and(safe_tool_version); - let zig_valid = policy - .toolchain - .zig - .as_deref() - .is_some_and(safe_tool_version); - let toolchain_valid = safe_tool_version(&policy.toolchain.rust) - && ((policy.strategy == BuildStrategy::CargoZigbuild - && cargo_zigbuild_valid - && zig_valid) - || (policy.strategy == BuildStrategy::NativeCargo - && policy.toolchain.cargo_zigbuild.is_none() - && policy.toolchain.zig.is_none())); - let floor_valid = match policy.floor { - CompatibilityFloor::None => true, - CompatibilityFloor::Glibc { .. } => target.target.contains("-linux-gnu"), - CompatibilityFloor::Macos { .. } => target.target.ends_with("-apple-darwin"), - }; - let native_qualification_valid = if policy.qualification == Qualification::Native { - host_matches_target( - policy.qualification_host.unwrap_or(HostRequirement { - os: policy.host_os, - arch: policy.host_arch, - }), + // The producer owns the policy rules. This crate projects the + // pipeline; it does not restate the toolchain, floor, or + // native-qualification host rules, so it applies them instead. + let policy_valid = eggpack_core::validate_policy(policy, &target.target).is_ok() + && eggpack_core::validate_floor_applicability( + &policy.floor, + policy.strategy, &target.target, ) - } else { - true - }; + .is_ok(); if !safe_target(&target.target) || target.policy.target != target.target - || !toolchain_valid - || !floor_valid - || !native_qualification_valid - || (policy.strategy == BuildStrategy::CargoZigbuild - && matches!(policy.floor, CompatibilityFloor::Macos { .. })) + || !policy_valid || prior.is_some_and(|p| p >= target.target.as_str()) || job.job_id != target_job_id(&target.target) || !job_ids.insert(job.job_id.as_str()) @@ -420,19 +393,6 @@ fn safe_tool_version(value: &str) -> bool { .bytes() .all(|b| b.is_ascii_alphanumeric() || b".+-_".contains(&b)) } -fn host_matches_target(host: HostRequirement, target: &str) -> bool { - let arch_matches = match host.arch { - HostArch::X86_64 => target.starts_with("x86_64-"), - HostArch::Aarch64 => target.starts_with("aarch64-"), - HostArch::Armv7 => target.starts_with("armv7-"), - }; - let os_matches = match host.os { - HostOs::Linux => target.contains("-linux-"), - HostOs::Macos => target.ends_with("-apple-darwin"), - HostOs::Windows => target.contains("-windows-"), - }; - arch_matches && os_matches -} fn selector_matches_form(selector: &LogicalOutputSelector, form: PlannedAssetForm) -> bool { match (selector, form) { (LogicalOutputSelector::Direct, PlannedAssetForm::Direct) @@ -545,14 +505,8 @@ impl ZigOfficialArchiveV1 { /// Validate both digests are exact 64-character lowercase hex SHA-256. pub fn validate(&self) -> Result<(), CiError> { for digest in [&self.linux_x86_64_sha256, &self.linux_aarch64_sha256] { - if digest.len() != 64 - || !digest - .bytes() - .all(|b| b.is_ascii_hexdigit() && !b.is_ascii_uppercase()) - || digest == &"0".repeat(64) - { - return Err(fail("invalid Zig official archive SHA-256")); - } + validate_sha256_hex(digest) + .map_err(|_| fail("invalid Zig official archive SHA-256"))?; } Ok(()) } @@ -629,16 +583,11 @@ pub fn zig_expected_digest( } /// Validate one hex SHA-256 digest string without trusting remote content. +/// +/// The acceptance set is owned by `eggpack-manifest` (ADR-0006) and re-exported +/// by `eggpack-core`; this crate applies it rather than restating it. pub fn validate_sha256_hex(digest: &str) -> Result<(), CiError> { - if digest.len() != 64 - || !digest - .bytes() - .all(|b| b.is_ascii_hexdigit() && !b.is_ascii_uppercase()) - || digest == "0".repeat(64) - { - return Err(fail("invalid SHA-256 digest")); - } - Ok(()) + eggpack_core::validate_sha256_hex(digest).map_err(|_| fail("invalid SHA-256 digest")) } /// Pure archive top-level layout check for an official Zig archive listing. @@ -4390,13 +4339,8 @@ impl ConsumerValidationEvidenceV1 { // that was never observed. match (&self.candidate_sha256, self.candidate_size) { (Some(digest), size) if size > 0 => { - if digest.len() != 64 - || !digest - .bytes() - .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)) - { - return Err(fail("consumer evidence digest must be lowercase hex")); - } + validate_sha256_hex(digest) + .map_err(|_| fail("consumer evidence digest must be lowercase hex"))?; } (Some(_), _) => { return Err(fail( @@ -4558,14 +4502,8 @@ pub fn run_consumer_validator( "consumer validation working directory is not a real directory", )); } - if request.expected_sha256.len() != 64 - || !request - .expected_sha256 - .bytes() - .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)) - { - return Err(fail("expected candidate digest must be lowercase hex")); - } + validate_sha256_hex(request.expected_sha256) + .map_err(|_| fail("expected candidate digest must be lowercase hex"))?; if !safe_metadata(request.release_id, 256) || !safe_metadata(request.source_revision, 256) || !safe_target(request.target) @@ -4590,12 +4528,19 @@ pub fn run_consumer_validator( // evidence records an absent candidate rather than a synthetic one: a // never-read candidate must not be published as a digest, because this // document is a claim about final bytes. - let (observed_size, observed_sha) = hash_candidate_file(request.candidate_path); - let candidate_ok = is_regular_nonempty_file(request.candidate_path) - && observed_size == request.expected_size - && observed_sha == request.expected_sha256; - let evidence_size = observed_size; - let evidence_sha = (observed_sha.len() == 64).then_some(observed_sha); + let observed = hash_candidate_file(request.candidate_path); + let candidate_ok = match &observed { + Ok((size, sha)) => { + is_regular_nonempty_file(request.candidate_path) + && *size == request.expected_size + && *sha == request.expected_sha256 + } + Err(_) => false, + }; + let (evidence_size, evidence_sha) = match &observed { + Ok((size, sha)) => (*size, Some(sha.clone())), + Err(_) => (0, None), + }; if !candidate_ok { return consumer_evidence_shell( request, @@ -4686,38 +4631,13 @@ fn ensure_candidate_executable(path: &Path) -> bool { } } -fn hash_candidate_file(path: &Path) -> (u64, String) { - let meta = match std::fs::symlink_metadata(path) { - Ok(meta) => meta, - Err(_) => return (0, String::new()), - }; - if meta.file_type().is_symlink() || !meta.is_file() || meta.len() == 0 { - return (0, String::new()); - } - let mut file = match std::fs::File::open(path) { - Ok(file) => file, - Err(_) => return (0, String::new()), - }; - use std::io::Read; - let mut hasher = Sha256::new(); - let mut chunk = [0u8; 65536]; - let mut size = 0u64; - loop { - match file.read(&mut chunk) { - Ok(0) => break, - Ok(count) => { - size += count as u64; - hasher.update(&chunk[..count]); - } - Err(_) => return (0, String::new()), - } - } - let digest: String = hasher - .finalize() - .iter() - .map(|byte| format!("{byte:02x}")) - .collect(); - (size, digest) +/// Digest one candidate file for the consumer-evidence identity. +/// +/// The canonical producer file-digest helper owns this. There is no sentinel +/// success value, no empty digest, and no zero-size placeholder: a refusal is +/// a typed error and the caller records an absent candidate. +fn hash_candidate_file(path: &Path) -> Result<(u64, String), eggpack_core::DigestError> { + eggpack_core::file_digest(path) } fn validator_command( @@ -4964,19 +4884,23 @@ impl ReleaseWorkflowShapeV1 { } fn validate_exact_tag(tag: &str) -> Result<(), CiError> { - if tag.is_empty() || tag.len() > 128 { - return Err(fail("exact tag out of bounds")); - } - if tag.chars().any(char::is_control) { - return Err(fail("exact tag contains control characters")); - } - if tag.contains(['?', '#', '@', ' ', '\\', '\'', '"', '`', '$']) { - return Err(fail("exact tag contains query/injection characters")); - } - if tag.contains("..") || tag.starts_with('/') || tag.ends_with('/') { - return Err(fail("exact tag has unsafe path shape")); - } - Ok(()) + // The canonical exact-tag safety rule is owned by `eggpack-core`; this + // crate keeps its own diagnostic wording for each refusal class. + eggpack_core::validate_exact_tag_safety(tag).map_err(|error| { + fail(match error { + eggpack_core::ExactTagSafetyError::OutOfBounds => "exact tag out of bounds", + eggpack_core::ExactTagSafetyError::ControlCharacters => { + "exact tag contains control characters" + } + eggpack_core::ExactTagSafetyError::QueryOrInjectionCharacters => { + "exact tag contains query/injection characters" + } + eggpack_core::ExactTagSafetyError::UnsafePathShape => "exact tag has unsafe path shape", + eggpack_core::ExactTagSafetyError::UnsafeGitRefPath => { + "exact tag has unsafe git ref path shape" + } + }) + }) } fn validate_source_revision(revision: &str) -> Result<(), CiError> { @@ -9886,7 +9810,7 @@ mod tests { arch: planned.policy.host_arch, }); assert_eq!(qual.host, expected); - assert!(host_matches_target(qual.host, &qual.target)); + assert!(eggpack_core::host_matches_target(qual.host, &qual.target)); } let yaml = render_reusable_release_github(&contract, &shape, &policy).unwrap(); assert_eq!( @@ -11079,4 +11003,415 @@ support="required" &render_github(&graph, &policy()).unwrap(), ); } + + // ----------------------------------------------------------------------- + // M003l — producer rule authority convergence. + // + // The canonical rules now live in one place. The expected-outcome tables + // below are the pre-convergence rules of the crates that used to own + // them, kept here only so the canonical rule can be shown to agree with + // them case by case. The assertions themselves are written against the + // canonical rule alone. + // ----------------------------------------------------------------------- + + /// The pre-convergence CI-side host/target predicate. + fn pre_convergence_ci_host_matches_target(host: HostRequirement, target: &str) -> bool { + let arch_matches = match host.arch { + HostArch::X86_64 => target.starts_with("x86_64-"), + HostArch::Aarch64 => target.starts_with("aarch64-"), + HostArch::Armv7 => target.starts_with("armv7-"), + }; + let os_matches = match host.os { + HostOs::Linux => target.contains("-linux-"), + HostOs::Macos => target.ends_with("-apple-darwin"), + HostOs::Windows => target.contains("-windows-"), + }; + arch_matches && os_matches + } + + #[test] + fn m003l_core_host_target_rule_reproduces_every_pre_convergence_ci_outcome() { + let hosts = [ + HostRequirement { + os: HostOs::Linux, + arch: HostArch::X86_64, + }, + HostRequirement { + os: HostOs::Linux, + arch: HostArch::Aarch64, + }, + HostRequirement { + os: HostOs::Linux, + arch: HostArch::Armv7, + }, + HostRequirement { + os: HostOs::Macos, + arch: HostArch::X86_64, + }, + HostRequirement { + os: HostOs::Macos, + arch: HostArch::Aarch64, + }, + HostRequirement { + os: HostOs::Macos, + arch: HostArch::Armv7, + }, + HostRequirement { + os: HostOs::Windows, + arch: HostArch::X86_64, + }, + HostRequirement { + os: HostOs::Windows, + arch: HostArch::Aarch64, + }, + HostRequirement { + os: HostOs::Windows, + arch: HostArch::Armv7, + }, + ]; + const TRIPLES: &[&str] = &[ + "x86_64-unknown-linux-gnu", + "aarch64-unknown-linux-gnu", + "armv7-unknown-linux-gnueabihf", + "x86_64-unknown-linux-musl", + "aarch64-unknown-linux-musl", + "x86_64-apple-darwin", + "aarch64-apple-darwin", + "x86_64-pc-windows-msvc", + "aarch64-pc-windows-msvc", + "armv7-pc-windows-msvc", + "x86_64-unknown-freebsd", + "aarch64-unknown-none", + ]; + for triple in TRIPLES { + for host in hosts { + assert_eq!( + eggpack_core::host_matches_target(host, triple), + pre_convergence_ci_host_matches_target(host, triple), + "core host/target rule diverged for {host:?} on {triple}" + ); + } + } + // Pinned outcomes, so the table above cannot silently agree with a + // wrong rule. + assert!(eggpack_core::host_matches_target( + hosts[0], + "x86_64-unknown-linux-gnu" + )); + assert!(!eggpack_core::host_matches_target( + hosts[0], + "aarch64-unknown-linux-gnu" + )); + assert!(eggpack_core::host_matches_target( + hosts[3], + "x86_64-apple-darwin" + )); + assert!(!eggpack_core::host_matches_target( + hosts[3], + "x86_64-unknown-linux-gnu" + )); + assert!(eggpack_core::host_matches_target( + hosts[6], + "x86_64-pc-windows-msvc" + )); + assert!(!eggpack_core::host_matches_target( + hosts[6], + "x86_64-unknown-freebsd" + )); + } + + #[test] + fn m003l_floor_applicability_is_refused_in_every_pre_convergence_case() { + // A glibc floor on a target that is not GNU/Linux. + assert_eq!( + eggpack_core::validate_floor_applicability( + &CompatibilityFloor::Glibc { + major: 2, + minor: 17 + }, + BuildStrategy::NativeCargo, + "aarch64-apple-darwin", + ), + Err(eggpack_core::FloorApplicabilityError::NotGlibcTarget) + ); + // A macOS floor on a target that is not Darwin. + assert_eq!( + eggpack_core::validate_floor_applicability( + &CompatibilityFloor::Macos { + major: 13, + minor: 0 + }, + BuildStrategy::NativeCargo, + "x86_64-unknown-linux-gnu", + ), + Err(eggpack_core::FloorApplicabilityError::NotMacosTarget) + ); + // A macOS floor under cargo-zigbuild. + assert_eq!( + eggpack_core::validate_floor_applicability( + &CompatibilityFloor::Macos { + major: 13, + minor: 0 + }, + BuildStrategy::CargoZigbuild, + "x86_64-apple-darwin", + ), + Err(eggpack_core::FloorApplicabilityError::MacosFloorUnderZigbuild) + ); + // The shapes that were accepted stay accepted. + assert!(eggpack_core::validate_floor_applicability( + &CompatibilityFloor::Glibc { + major: 2, + minor: 17 + }, + BuildStrategy::NativeCargo, + "x86_64-unknown-linux-gnu", + ) + .is_ok()); + assert!(eggpack_core::validate_floor_applicability( + &CompatibilityFloor::Macos { + major: 13, + minor: 0 + }, + BuildStrategy::NativeCargo, + "x86_64-apple-darwin", + ) + .is_ok()); + assert!(eggpack_core::validate_floor_applicability( + &CompatibilityFloor::None, + BuildStrategy::CargoZigbuild, + "x86_64-unknown-linux-gnu", + ) + .is_ok()); + + // The projected pipeline still refuses the same three cases. + let (contract, shape, policy) = m006_shape_and_policy(); + let mut glibc_outside = shape.clone(); + let darwin = glibc_outside + .targets + .iter_mut() + .find(|p| p.target == "aarch64-apple-darwin") + .unwrap(); + darwin.floor = CompatibilityFloor::Glibc { + major: 2, + minor: 17, + }; + assert!(render_reusable_release_github(&contract, &glibc_outside, &policy).is_err()); + + let mut macos_outside = shape.clone(); + let linux = macos_outside + .targets + .iter_mut() + .find(|p| p.target == "aarch64-unknown-linux-gnu") + .unwrap(); + linux.floor = CompatibilityFloor::Macos { + major: 13, + minor: 0, + }; + assert!(render_reusable_release_github(&contract, &macos_outside, &policy).is_err()); + + let mut macos_under_zigbuild = shape.clone(); + let darwin = macos_under_zigbuild + .targets + .iter_mut() + .find(|p| p.target == "aarch64-apple-darwin") + .unwrap(); + darwin.strategy = BuildStrategy::CargoZigbuild; + darwin.toolchain = ToolchainRequirement { + rust: "1.89.0".into(), + cargo_zigbuild: Some(M005_CARGO_ZIGBUILD_VERSION.into()), + zig: Some(M005_ZIG_VERSION.into()), + }; + darwin.floor = CompatibilityFloor::Macos { + major: 13, + minor: 0, + }; + assert!(render_reusable_release_github(&contract, &macos_under_zigbuild, &policy).is_err()); + } + + /// The pre-convergence core-side exact-tag safety rule. + fn pre_convergence_core_tag_is_safe(tag: &str) -> bool { + !(tag.is_empty() + || tag.len() > 128 + || tag.chars().any(char::is_control) + || tag.starts_with('/') + || tag.ends_with('/') + || tag.ends_with('.') + || tag.contains("..") + || tag.contains("@{") + || tag.contains(['?', '\\', '^', ':', '*', '[', '~', ' ']) + || tag.split('/').any(|component| { + component.is_empty() || component.starts_with('.') || component.ends_with(".lock") + })) + } + + /// The pre-convergence CI-side exact-tag safety rule. + fn pre_convergence_ci_tag_is_safe(tag: &str) -> bool { + !(tag.is_empty() + || tag.len() > 128 + || tag.chars().any(char::is_control) + || tag.contains(['?', '#', '@', ' ', '\\', '\'', '"', '`', '$']) + || tag.contains("..") + || tag.starts_with('/') + || tag.ends_with('/')) + } + + #[test] + fn m003l_canonical_tag_safety_is_the_union_of_both_pre_convergence_rules() { + const TAGS: &[&str] = &[ + "", + "v1.2.3", + "release/v1.2.3", + "v1.2.3-rc.1", + "v1.2.3+build.1", + "v1.2.3#", + "v1.2.3@", + "v1.2.3'", + "v1.2.3\"", + "v1.2.3`", + "v1.2.3$", + "v1.2.3?", + "v1.2.3 ", + "v1.2.3\\", + "v1.2.3^", + "v1.2.3:", + "v1.2.3*", + "v1.2.3[", + "v1.2.3~", + "v1.2.3.", + "v1..2.3", + "v1.2.3@{", + "/v1.2.3", + "v1.2.3/", + "release//v1.2.3", + "release/.hidden/v1.2.3", + "release/v1.2.3.lock", + "v1.2.3\n", + "v1.2.3\t", + ]; + for tag in TAGS { + let canonical = eggpack_core::validate_exact_tag_safety(tag).is_ok(); + let core = pre_convergence_core_tag_is_safe(tag); + let ci = pre_convergence_ci_tag_is_safe(tag); + // The canonical rule is the union of the two concern sets, so a + // tag is accepted exactly when both former rules accepted it. + assert_eq!( + canonical, + core && ci, + "canonical tag safety diverged for {tag:?}" + ); + // The canonical accepted set is a subset of the union of the two + // former accepted sets: it accepts nothing either rule refused. + assert!( + !canonical || core || ci, + "canonical tag safety widened for {tag:?}" + ); + } + // Every character class that either former rule refused is refused by + // the canonical rule. + for character in [ + '?', '#', '@', ' ', '\\', '\'', '"', '`', '$', '^', ':', '*', '[', '~', + ] { + let tag = format!("v1.2.3{character}"); + assert!( + !pre_convergence_core_tag_is_safe(&tag) || !pre_convergence_ci_tag_is_safe(&tag), + "expected a pre-convergence refusal for {tag:?}" + ); + assert!( + eggpack_core::validate_exact_tag_safety(&tag).is_err(), + "canonical tag safety accepted {tag:?}" + ); + } + // A canonical version tag and a multi-segment tag stay accepted. + assert!(eggpack_core::validate_exact_tag_safety("v1.2.3").is_ok()); + assert!(eggpack_core::validate_exact_tag_safety("release/v1.2.3").is_ok()); + } + + #[test] + fn m003l_candidate_digest_refusals_are_typed_and_never_an_empty_digest() { + let root = eggpack_core_test_temp("m003l-digest"); + let missing = root.join("missing.bin"); + let empty = root.join("empty.bin"); + std::fs::write(&empty, b"").unwrap(); + let payload = root.join("payload.bin"); + std::fs::write(&payload, b"payload").unwrap(); + + // A missing file. + assert!(hash_candidate_file(&missing).is_err()); + + // An empty file. + assert!(hash_candidate_file(&empty).is_err()); + + // A symlink. + #[cfg(unix)] + { + let link = root.join("link.bin"); + std::os::unix::fs::symlink(&payload, &link).unwrap(); + assert!(hash_candidate_file(&link).is_err()); + } + + // An unreadable file. A privileged process may still read it; the + // digest is then well-formed rather than empty. + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + let unreadable = root.join("unreadable.bin"); + std::fs::write(&unreadable, b"payload").unwrap(); + std::fs::set_permissions(&unreadable, std::fs::Permissions::from_mode(0o000)).unwrap(); + match hash_candidate_file(&unreadable) { + Err(_) => {} + Ok((size, digest)) => { + assert_eq!(size, 7); + assert_eq!(digest.len(), 64); + } + } + } + + // No refusal path yields an empty digest string. + for path in [&missing, &empty, &payload] { + if let Ok((_, digest)) = hash_candidate_file(path) { + assert!(!digest.is_empty(), "empty digest for {path:?}"); + } + } + + // A readable regular file still digests to a 64-character hex digest. + let (size, digest) = hash_candidate_file(&payload).unwrap(); + assert_eq!(size, 7); + assert_eq!(digest.len(), 64); + assert!(digest + .bytes() + .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))); + + std::fs::remove_dir_all(&root).ok(); + } + + #[test] + fn m003l_sha256_acceptance_set_is_identical_at_every_call_site() { + const DIGESTS: &[&str] = &[ + "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90", + "0000000000000000000000000000000000000000000000000000000000000000", + "A1B2C3D4E5F60718293A4B5C6D7E8F90A1B2C3D4E5F60718293A4B5C6D7E8F90", + "g1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90", + "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9", + "a1b2c3d4", + "", + ]; + for digest in DIGESTS { + let canonical = eggpack_manifest::validate_sha256_hex(digest).is_ok(); + assert_eq!( + eggpack_core::validate_sha256_hex(digest).is_ok(), + canonical, + "core re-export diverged for {digest:?}" + ); + assert_eq!( + validate_sha256_hex(digest).is_ok(), + canonical, + "CI call site diverged for {digest:?}" + ); + } + // The all-zeros placeholder is refused at every call site. + assert!(!validate_sha256_hex(&"0".repeat(64)).is_ok()); + assert!(!eggpack_manifest::validate_sha256_hex(&"0".repeat(64)).is_ok()); + assert!(!eggpack_core::validate_sha256_hex(&"0".repeat(64)).is_ok()); + } } diff --git a/crates/eggpack-core/src/builder.rs b/crates/eggpack-core/src/builder.rs index fd13d54..59a50d8 100644 --- a/crates/eggpack-core/src/builder.rs +++ b/crates/eggpack-core/src/builder.rs @@ -360,7 +360,15 @@ pub fn cargo_command( format!("{}.{major}.{minor}", target.target) } CompatibilityFloor::Macos { .. } => { - return Err(build_err("macOS floor cannot use cargo-zigbuild")); + // The canonical floor rule owns this refusal: a macOS floor + // cannot be satisfied by a cargo-zigbuild build. + crate::validate_floor_applicability( + &target.policy.floor, + target.policy.strategy, + &target.target, + ) + .map_err(|_| build_err("macOS floor cannot use cargo-zigbuild"))?; + target.target.clone() } CompatibilityFloor::None => target.target.clone(), }; @@ -424,19 +432,9 @@ pub fn run_git_tag_bounded( expected: &str, cwd: Option<&Path>, ) -> Result { - if tag.is_empty() - || tag.len() > 128 - || tag.chars().any(char::is_control) - || tag.starts_with('/') - || tag.ends_with('/') - || tag.ends_with('.') - || tag.contains("..") - || tag.contains("@{") - || tag.contains(['?', '\\', '^', ':', '*', '[', '~', ' ']) - || tag.split('/').any(|component| { - component.is_empty() || component.starts_with('.') || component.ends_with(".lock") - }) - { + // The canonical exact-tag safety rule owns this refusal: it carries the + // union of the git-ref-path concerns and the shell-metacharacter concerns. + if crate::validate_exact_tag_safety(tag).is_err() { return Err(build_err("invalid exact git tag")); } run_git_resolve_bounded( diff --git a/crates/eggpack-core/src/lib.rs b/crates/eggpack-core/src/lib.rs index 02e9b91..1fcb5d7 100644 --- a/crates/eggpack-core/src/lib.rs +++ b/crates/eggpack-core/src/lib.rs @@ -15,6 +15,7 @@ use eggpack_contract::{ expected_release_files, validate_release_inventory, DistributionContract, ExpandedAssets, ExtrasPolicy, ReleaseInventory, }; +pub use eggpack_manifest::{validate_sha256_hex, Sha256Error}; use eggpack_manifest::{ ArchiveMemberRecord, ArtifactForm, ArtifactRecord, BundleRecord, ByteEvidence, ReleaseManifest, TargetRecord, @@ -78,7 +79,15 @@ impl std::error::Error for CoreError {} fn err(s: impl Into) -> CoreError { CoreError(s.into()) } -fn host_matches_target(host: HostRequirement, triple: &str) -> bool { +/// Whether a host requirement matches a canonical target triple. +/// +/// This is the **single** producer-side host/target match rule. Architecture +/// is a triple prefix (`x86_64-`, `aarch64-`, `armv7-`) and the operating +/// system is a triple predicate (`-linux-`, `-apple-darwin`, `-windows-`). +/// +/// `Qualification::Native` is host-matched against this predicate, and +/// `eggpack-ci` calls it instead of carrying an independent copy. +pub fn host_matches_target(host: HostRequirement, triple: &str) -> bool { let arch = match host.arch { HostArch::X86_64 => triple.starts_with("x86_64-"), HostArch::Aarch64 => triple.starts_with("aarch64-"), @@ -112,7 +121,89 @@ fn valid_tool_version(value: &str) -> bool { .all(|part| !part.is_empty() && part.bytes().all(|b| b.is_ascii_digit())) } -fn validate_policy(policy: &TargetPolicy, triple: &str) -> Result<(), CoreError> { +/// Why a declared compatibility floor does not apply to a target. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum FloorApplicabilityError { + /// A glibc floor was declared for a target that is not GNU/Linux. + NotGlibcTarget, + /// A macOS floor was declared for a target that is not macOS. + NotMacosTarget, + /// A macOS floor was declared for a cargo-zigbuild build. + MacosFloorUnderZigbuild, +} + +/// The compatibility-floor half of the floor rule that concerns the target +/// triple alone. +/// +/// A glibc floor applies only to a `-linux-gnu` triple and a macOS floor only +/// to an `-apple-darwin` triple. The strategy half of the same rule lives in +/// [`floor_applies_to_strategy`]; the two are composed by the canonical +/// [`validate_floor_applicability`]. +fn floor_applies_to_triple( + floor: &CompatibilityFloor, + triple: &str, +) -> Result<(), FloorApplicabilityError> { + match floor { + CompatibilityFloor::None => Ok(()), + CompatibilityFloor::Glibc { .. } if !triple.contains("-linux-gnu") => { + Err(FloorApplicabilityError::NotGlibcTarget) + } + CompatibilityFloor::Macos { .. } if !triple.ends_with("-apple-darwin") => { + Err(FloorApplicabilityError::NotMacosTarget) + } + _ => Ok(()), + } +} + +/// The compatibility-floor half of the floor rule that concerns the build +/// strategy alone. +/// +/// A macOS floor cannot be satisfied by a cargo-zigbuild build: the cross +/// tool does not produce a macOS deployment target, so the declared floor +/// could never be proven. +fn floor_applies_to_strategy( + floor: &CompatibilityFloor, + strategy: BuildStrategy, +) -> Result<(), FloorApplicabilityError> { + match (floor, strategy) { + (CompatibilityFloor::Macos { .. }, BuildStrategy::CargoZigbuild) => { + Err(FloorApplicabilityError::MacosFloorUnderZigbuild) + } + _ => Ok(()), + } +} + +/// Whether the declared compatibility floor applies to a target triple and a +/// build strategy. +/// +/// This is the **single** producer-side floor-applicability rule. It composes +/// the two halves of the rule: a glibc floor requires a `-linux-gnu` triple +/// and a macOS floor requires an `-apple-darwin` triple, and a macOS floor is +/// incompatible with a cargo-zigbuild build. +/// +/// `eggpack-ci` applies it to a projected plan instead of re-deriving the +/// floor rules. +pub fn validate_floor_applicability( + floor: &CompatibilityFloor, + strategy: BuildStrategy, + triple: &str, +) -> Result<(), FloorApplicabilityError> { + floor_applies_to_triple(floor, triple)?; + floor_applies_to_strategy(floor, strategy) +} + +/// Validate one target policy against its canonical target triple. +/// +/// This is the **single** producer-side policy validation rule. It covers the +/// toolchain requirement shape, the cross-tool presence rule for the selected +/// strategy, the compatibility-floor applicability rule, and the +/// native-qualification host match. +/// +/// `eggpack-ci` applies it to a `CIPlan` instead of re-deriving any of those +/// rules. The macOS-floor-under-cargo-zigbuild refusal is enforced where the +/// build command is derived, so policy resolution keeps its outcome; the +/// canonical floor rule covers it. +pub fn validate_policy(policy: &TargetPolicy, triple: &str) -> Result<(), CoreError> { if policy.toolchain.rust.is_empty() || policy.toolchain.rust.len() > 64 || !policy @@ -151,14 +242,18 @@ fn validate_policy(policy: &TargetPolicy, triple: &str) -> Result<(), CoreError> } } } - match policy.floor { - CompatibilityFloor::Glibc { .. } if !triple.contains("-linux-gnu") => { - return Err(err("glibc floor applies only to GNU/Linux targets")) - } - CompatibilityFloor::Macos { .. } if !triple.ends_with("-apple-darwin") => { - return Err(err("macOS floor applies only to macOS targets")) - } - _ => {} + if let Err(error) = floor_applies_to_triple(&policy.floor, triple) { + return Err(match error { + FloorApplicabilityError::NotGlibcTarget => { + err("glibc floor applies only to GNU/Linux targets") + } + FloorApplicabilityError::NotMacosTarget => { + err("macOS floor applies only to macOS targets") + } + FloorApplicabilityError::MacosFloorUnderZigbuild => { + err("macOS floor cannot use cargo-zigbuild") + } + }); } if policy.qualification == Qualification::Native { let host = policy.qualification_host.unwrap_or(HostRequirement { @@ -174,6 +269,72 @@ fn validate_policy(policy: &TargetPolicy, triple: &str) -> Result<(), CoreError> Ok(()) } +/// Why an exact release tag was refused for safety reasons. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum ExactTagSafetyError { + /// The tag is empty or longer than the documented bound. + OutOfBounds, + /// The tag contains a control character. + ControlCharacters, + /// The tag contains a character that is special to a query or a shell. + QueryOrInjectionCharacters, + /// The tag has an unsafe path shape. + UnsafePathShape, + /// The tag has a shape that is unsafe as a git ref path. + UnsafeGitRefPath, +} + +/// The longest exact release tag that is considered at all. +const MAX_EXACT_TAG_BYTES: usize = 128; + +/// Whether an exact release tag is safe to handle. +/// +/// This is the **single** exact-tag safety rule in the workspace. It carries +/// the union of the two concern sets that previously existed as separate +/// partial rules: +/// +/// - the git-ref-path concerns — a tag used as +/// `refs/tags/^{commit}` must not contain `..`, must not begin or end +/// with `/`, must not end with `.`, must not contain `@{`, must not contain +/// `^`, `:`, `*`, `[` or `~`, and must not carry an empty, `.`-leading, or +/// `.lock`-ending path component; +/// - the shell-metacharacter concerns — a tag arriving from a workflow +/// dispatch input must not contain `?`, `#`, `@`, a space, `\`, `'`, `"`, +/// `` ` `` or `$`. +/// +/// A tag is accepted only if it satisfies every concern, so the accepted set +/// is the intersection of the two former accepted sets: this rule can only +/// refuse more, never accept more. +/// +/// This validator is **safety only**. The canonical *format* check — a +/// `vX.Y.Z` stable version — is a separate, named concern with its own +/// diagnostic, and a tag that is safe but not canonical is refused by the +/// format check. +pub fn validate_exact_tag_safety(tag: &str) -> Result<(), ExactTagSafetyError> { + if tag.is_empty() || tag.len() > MAX_EXACT_TAG_BYTES { + return Err(ExactTagSafetyError::OutOfBounds); + } + if tag.chars().any(char::is_control) { + return Err(ExactTagSafetyError::ControlCharacters); + } + if tag.contains(['?', '#', '@', ' ', '\\', '\'', '"', '`', '$']) { + return Err(ExactTagSafetyError::QueryOrInjectionCharacters); + } + if tag.contains("..") || tag.starts_with('/') || tag.ends_with('/') { + return Err(ExactTagSafetyError::UnsafePathShape); + } + if tag.ends_with('.') + || tag.contains("@{") + || tag.contains(['^', ':', '*', '[', '~']) + || tag.split('/').any(|component| { + component.is_empty() || component.starts_with('.') || component.ends_with(".lock") + }) + { + return Err(ExactTagSafetyError::UnsafeGitRefPath); + } + Ok(()) +} + /// Build and hash a complete schema-v1 manifest from explicitly supplied files. pub fn build_manifest( contract: &DistributionContract, diff --git a/crates/eggpack-github/README.md b/crates/eggpack-github/README.md index 249586d..6fd3d3f 100644 --- a/crates/eggpack-github/README.md +++ b/crates/eggpack-github/README.md @@ -16,6 +16,10 @@ GitHub draft release staging adapter and local staging payload materializer (CI - Production asset files are opened once, length- and SHA-256-verified in bounded 64 KiB chunks, then uploaded from that same handle as a known-length one-shot stream. No full-file upload buffer is materialized. - Asset reconciliation reads every page under the policy bound (default 16, maximum 32); a full final allowed page fails closed because completeness is unknown. - Upload templates are parsed and checked against the exact HTTPS `uploads.github.com` origin and current release path. Asset names are encoded as URL query pairs and round-trip unchanged. +- This crate owns no producer rule of its own. The SHA-256 hex acceptance set + belongs to `eggpack-manifest` (ADR-0006), the file digest and the exact-tag + safety rule belong to `eggpack-core`; this crate applies them and keeps its + own diagnostic wording. Local payload (`prepare_staging_payload`) revalidates the finalized root against the contract and manifest, rejects missing/extra/tampered files, writes a standalone `release-manifest.json` that decodes back to the exact M004 manifest, generates deterministic `install.sh`/`install.ps1` with exact-tag origins (`https://github.com///releases/download/`), and emits a deterministic `StagingPayloadV1`. M004 root semantics are unchanged. diff --git a/crates/eggpack-github/src/lib.rs b/crates/eggpack-github/src/lib.rs index f3f5dab..c9becdd 100644 --- a/crates/eggpack-github/src/lib.rs +++ b/crates/eggpack-github/src/lib.rs @@ -492,19 +492,23 @@ fn validate_repo(value: &str) -> Result<(), GithubError> { } fn validate_tag(value: &str) -> Result<(), GithubError> { - if value.is_empty() || value.len() > 128 { - return Err(fail("tag out of bounds")); - } - if value.chars().any(char::is_control) { - return Err(fail("tag contains control characters")); - } - if value.contains(['?', '#', '@', ' ', '\\', '\'', '"', '`', '$']) { - return Err(fail("tag contains query/injection characters")); - } - if value.contains("..") || value.starts_with('/') || value.ends_with('/') { - return Err(fail("tag has unsafe path shape")); - } - Ok(()) + // The canonical exact-tag safety rule is owned by `eggpack-core`; this + // crate keeps its own diagnostic wording for each refusal class. + eggpack_core::validate_exact_tag_safety(value).map_err(|error| { + fail(match error { + eggpack_core::ExactTagSafetyError::OutOfBounds => "tag out of bounds", + eggpack_core::ExactTagSafetyError::ControlCharacters => { + "tag contains control characters" + } + eggpack_core::ExactTagSafetyError::QueryOrInjectionCharacters => { + "tag contains query/injection characters" + } + eggpack_core::ExactTagSafetyError::UnsafePathShape => "tag has unsafe path shape", + eggpack_core::ExactTagSafetyError::UnsafeGitRefPath => { + "tag has unsafe git ref path shape" + } + }) + }) } fn validate_title(value: &str) -> Result<(), GithubError> { @@ -565,14 +569,14 @@ fn validate_relative_path(value: &str) -> Result<(), GithubError> { } fn validate_sha256(value: &str) -> Result<(), GithubError> { - if value.len() != 64 - || !value - .bytes() - .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)) - { - return Err(fail("sha256 must be 64 lowercase hex characters")); - } - Ok(()) + // The SHA-256 hex acceptance set is owned by `eggpack-manifest` + // (ADR-0006); this crate applies it rather than restating it. + eggpack_manifest::validate_sha256_hex(value).map_err(|error| { + fail(match error { + eggpack_manifest::Sha256Error::AllZeros => "sha256 must not be the all-zeros digest", + _ => "sha256 must be 64 lowercase hex characters", + }) + }) } /// Read a credential from the environment without logging it. @@ -587,44 +591,33 @@ pub fn read_token(env_name: &str) -> Result { Ok(value) } -/// Digest one staging file with a fixed-size buffer. +/// Digest one staging file with the canonical producer file-digest helper. /// /// The bytes are never held in memory: a finalized release bundle can be far /// larger than the process should grow to accommodate, and the rest of this /// crate already streams — `streamed_upload_body` and `verify_file` both read /// in `UPLOAD_CHUNK_BYTES` chunks. Peak memory here is therefore independent /// of artifact size. +/// +/// The digest rule itself is owned by `eggpack-core`; this wrapper only keeps +/// the crate's own staging diagnostic wording. fn digest_file(path: &Path) -> Result<(u64, String), GithubError> { - let metadata = - std::fs::symlink_metadata(path).map_err(|_| fail("staging file is unavailable"))?; - if metadata.file_type().is_symlink() || !metadata.is_file() || metadata.len() == 0 { - return Err(fail("staging file must be a non-empty regular file")); - } - use sha2::Digest; - use std::io::Read as _; - let mut file = std::fs::File::open(path).map_err(|_| fail("staging file cannot be read"))?; - let mut hasher = sha2::Sha256::new(); - let mut buffer = vec![0u8; UPLOAD_CHUNK_BYTES]; - let mut size: u64 = 0; - loop { - let count = file - .read(&mut buffer) - .map_err(|_| fail("staging file cannot be read"))?; - if count == 0 { - break; + eggpack_core::file_digest(path).map_err(|error| fail(staging_digest_message(error))) +} + +/// Map a canonical file-digest refusal to this crate's staging diagnostic. +fn staging_digest_message(error: eggpack_core::DigestError) -> &'static str { + match error { + eggpack_core::DigestError::Unavailable => "staging file is unavailable", + eggpack_core::DigestError::NotRegularFile | eggpack_core::DigestError::Empty => { + "staging file must be a non-empty regular file" } - hasher.update(&buffer[..count]); - size = size - .checked_add(count as u64) - .ok_or_else(|| fail("staging file size exceeds the platform bound"))?; - } - let after = - std::fs::symlink_metadata(path).map_err(|_| fail("staging file changed during read"))?; - if after.file_type().is_symlink() || !after.is_file() || after.len() != size { - return Err(fail("staging file changed during read")); + eggpack_core::DigestError::OpenFailed | eggpack_core::DigestError::ReadFailed => { + "staging file cannot be read" + } + eggpack_core::DigestError::SizeOverflow => "staging file size exceeds the platform bound", + eggpack_core::DigestError::ChangedDuringRead => "staging file changed during read", } - let digest = hasher.finalize(); - Ok((size, digest.iter().map(|b| format!("{b:02x}")).collect())) } fn reject_symlink_dir(path: &Path, label: &str) -> Result<(), GithubError> { @@ -3266,3 +3259,73 @@ impl GithubApi for FixtureGithub { #[cfg(test)] mod tests; + +/// M003l: the SHA-256 acceptance set is the canonical one, applied here +/// rather than restated. +#[cfg(test)] +mod m003l_rule_convergence_tests { + use super::*; + + #[test] + fn sha256_acceptance_set_is_the_canonical_one() { + const DIGESTS: &[&str] = &[ + "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90", + "0000000000000000000000000000000000000000000000000000000000000000", + "A1B2C3D4E5F60718293A4B5C6D7E8F90A1B2C3D4E5F60718293A4B5C6D7E8F90", + "g1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90", + "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9", + "a1b2c3d4", + "", + ]; + for digest in DIGESTS { + assert_eq!( + validate_sha256(digest).is_ok(), + eggpack_manifest::validate_sha256_hex(digest).is_ok(), + "GitHub call site diverged for {digest:?}" + ); + } + // The all-zeros placeholder is refused. + assert!(validate_sha256(&"0".repeat(64)).is_err()); + // A canonical digest is accepted. + assert!(validate_sha256( + "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" + ) + .is_ok()); + } + + #[test] + fn exact_tag_safety_is_the_canonical_one() { + // Every character class the pre-convergence rule refused is still + // refused, and the canonical rule adds the git-ref-path concerns. + for tag in [ + "", + "v1.2.3#", + "v1.2.3@", + "v1.2.3'", + "v1.2.3\"", + "v1.2.3`", + "v1.2.3$", + "v1.2.3?", + "v1.2.3 ", + "v1.2.3\\", + "v1.2.3^", + "v1.2.3:", + "v1.2.3*", + "v1.2.3[", + "v1.2.3~", + "v1.2.3.", + "v1..2.3", + "/v1.2.3", + "v1.2.3/", + "release/v1.2.3.lock", + ] { + assert!( + validate_tag(tag).is_err(), + "GitHub accepted an unsafe tag {tag:?}" + ); + } + // A canonical version tag and a multi-segment tag stay accepted. + assert!(validate_tag("v1.2.3").is_ok()); + assert!(validate_tag("release/v1.2.3").is_ok()); + } +} diff --git a/crates/eggpack-manifest/Cargo.toml b/crates/eggpack-manifest/Cargo.toml index a888bd9..a439a03 100644 --- a/crates/eggpack-manifest/Cargo.toml +++ b/crates/eggpack-manifest/Cargo.toml @@ -1,6 +1,9 @@ [package] name = "eggpack-manifest" -version.workspace = true +# ADR-0006 (Option A) narrows the published digest acceptance set, so this +# crate carries its own patch version. The workspace version stays 0.1.0 for +# the other six crates; `^0.1.0` dependents resolve 0.1.1 unchanged. +version = "0.1.1" edition.workspace = true rust-version.workspace = true license.workspace = true diff --git a/crates/eggpack-manifest/README.md b/crates/eggpack-manifest/README.md index 1afaa95..8a29c90 100644 --- a/crates/eggpack-manifest/README.md +++ b/crates/eggpack-manifest/README.md @@ -6,6 +6,13 @@ The crate is a synchronous leaf parser and serializer. It performs no filesystem Serialization sorts target triples, bundle entries, and archive members lexically. This creates stable application JSON, but does not claim signing-grade canonical JSON. Unknown fields and unsupported schema versions fail closed. Input is limited to 1 MiB; collections and strings have explicit bounds. +This crate also owns the SHA-256 hex acceptance rule for the whole workspace: +`validate_sha256_hex` accepts exactly 64 lowercase hexadecimal characters and +refuses the all-zeros placeholder, which no real byte sequence hashes to +(ADR-0006). `eggpack-core`, `eggpack-ci`, and `eggpack-github` apply that rule +rather than restating it. The JSON wire shape, the field set, and +`schema_version: 1` are unchanged by it. + # Consumer integration Consumers can select an exact canonical target with `ReleaseManifest::target` diff --git a/crates/eggpack-manifest/src/lib.rs b/crates/eggpack-manifest/src/lib.rs index f3bd09f..28e944b 100644 --- a/crates/eggpack-manifest/src/lib.rs +++ b/crates/eggpack-manifest/src/lib.rs @@ -46,6 +46,70 @@ impl std::error::Error for ManifestError {} fn invalid(s: impl Into) -> ManifestError { ManifestError::Invalid(s.into()) } + +/// Why a SHA-256 hex digest string was refused. +/// +/// ADR-0006 (Option A) fixes one acceptance set for the whole workspace: +/// exactly 64 lowercase hexadecimal characters, and not the all-zeros +/// placeholder that no real file digest can produce. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Sha256Error { + /// The digest is not exactly 64 characters long. + Length, + /// The digest contains a character that is not lowercase hexadecimal. + NotLowercaseHex, + /// The digest is the all-zeros placeholder, which is never a real digest. + AllZeros, +} + +impl Sha256Error { + /// Bounded, single-line reason phrase for this refusal. + pub fn reason(self) -> &'static str { + match self { + Self::Length => "must be 64 characters", + Self::NotLowercaseHex => "must be lowercase hexadecimal", + Self::AllZeros => "must not be the all-zeros digest", + } + } +} + +impl fmt::Display for Sha256Error { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(self.reason()) + } +} +impl std::error::Error for Sha256Error {} + +/// The all-zeros placeholder digest. No byte sequence hashes to it. +const ALL_ZEROS_SHA256: &str = "0000000000000000000000000000000000000000000000000000000000000000"; + +/// Validate one SHA-256 hex digest against the canonical acceptance set. +/// +/// This is the **single** SHA-256 hex acceptance rule in the workspace. The +/// crate that owns the evidence schema owns the rule, and `eggpack-core`, +/// `eggpack-ci`, and `eggpack-github` all consume it instead of restating it. +/// +/// The accepted set is exactly 64 lowercase hexadecimal characters, minus the +/// all-zeros placeholder, which can only mean "no digest was computed" and +/// which no legitimate producer emits (ADR-0006). +/// +/// A digest is an integrity fact about bytes. Acceptance here says nothing +/// about authenticity, provenance, or publisher identity. +pub fn validate_sha256_hex(digest: &str) -> Result<(), Sha256Error> { + if digest.len() != 64 { + return Err(Sha256Error::Length); + } + if !digest + .bytes() + .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte)) + { + return Err(Sha256Error::NotLowercaseHex); + } + if digest == ALL_ZEROS_SHA256 { + return Err(Sha256Error::AllZeros); + } + Ok(()) +} fn bounded(s: &str, max: usize, label: &str) -> Result<(), ManifestError> { if s.is_empty() || s.len() > max || s.chars().any(char::is_control) { return Err(invalid(format!("invalid {label}"))); @@ -286,16 +350,10 @@ impl ArtifactRecord { if self.size == 0 { return Err(invalid("size must be non-zero")); } - if self.sha256.len() != 64 - || !self - .sha256 - .bytes() - .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)) - { - return Err(invalid( - "sha256 must be 64 lowercase hexadecimal characters", - )); - } + validate_sha256_hex(&self.sha256).map_err(|error| match error { + Sha256Error::AllZeros => invalid("sha256 must not be the all-zeros digest"), + _ => invalid("sha256 must be 64 lowercase hexadecimal characters"), + })?; Ok(()) } } @@ -308,23 +366,19 @@ impl ByteEvidence { if self.size == 0 { return Err(invalid("size must be non-zero")); } - if self.sha256.len() != 64 - || !self - .sha256 - .bytes() - .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)) - { - return Err(invalid( - "sha256 must be 64 lowercase hexadecimal characters", - )); - } + validate_sha256_hex(&self.sha256).map_err(|error| match error { + Sha256Error::AllZeros => invalid("sha256 must not be the all-zeros digest"), + _ => invalid("sha256 must be 64 lowercase hexadecimal characters"), + })?; Ok(()) } } fn decode_sha256(hex: &str) -> Result<[u8; 32], ManifestError> { - if hex.len() != 64 { - return Err(invalid("sha256 must contain 64 lowercase hex characters")); - } + validate_sha256_hex(hex).map_err(|error| match error { + Sha256Error::Length => invalid("sha256 must contain 64 lowercase hex characters"), + Sha256Error::AllZeros => invalid("sha256 must not be the all-zeros digest"), + Sha256Error::NotLowercaseHex => invalid("invalid lowercase sha256"), + })?; let mut out = [0u8; 32]; for (i, pair) in hex.as_bytes().as_chunks::<2>().0.iter().enumerate() { let digit = |b: u8| match b { @@ -1426,4 +1480,57 @@ mod tests { ); } } + + #[test] + fn m003l_sha256_acceptance_set_is_the_canonical_one() { + // The canonical acceptance set: exactly 64 lowercase hexadecimal + // characters, and not the all-zeros placeholder (ADR-0006). + assert!(validate_sha256_hex( + "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" + ) + .is_ok()); + assert_eq!( + validate_sha256_hex(&"0".repeat(64)), + Err(Sha256Error::AllZeros) + ); + assert_eq!( + validate_sha256_hex(&"A".repeat(64)), + Err(Sha256Error::NotLowercaseHex) + ); + assert_eq!( + validate_sha256_hex(&"g".repeat(64)), + Err(Sha256Error::NotLowercaseHex) + ); + assert_eq!( + validate_sha256_hex(&"a".repeat(63)), + Err(Sha256Error::Length) + ); + assert_eq!( + validate_sha256_hex(&"a".repeat(65)), + Err(Sha256Error::Length) + ); + assert_eq!(validate_sha256_hex(""), Err(Sha256Error::Length)); + // The document shape is unchanged, but the acceptance set tightened: + // the all-zeros placeholder is no longer a usable evidence digest. + assert!(ByteEvidence::validate(&ByteEvidence { + size: 1, + sha256: "0".repeat(64), + }) + .is_err()); + assert!(ByteEvidence::validate(&ByteEvidence { + size: 1, + sha256: "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90".to_owned(), + }) + .is_ok()); + // The reason phrases stay single-line and bounded. + for error in [ + Sha256Error::Length, + Sha256Error::NotLowercaseHex, + Sha256Error::AllZeros, + ] { + let reason = error.reason(); + assert!(!reason.is_empty() && !reason.contains('\n')); + assert!(reason.len() <= 64); + } + } } From 41b752fddd9fae8e88753d1b3731602a2da85a5e Mon Sep 17 00:00:00 2001 From: doc Date: Fri, 23 Oct 2026 15:21:22 +0000 Subject: [PATCH 06/46] plans: close CI/Release M003l producer rule authority convergence Close CI/Release M003l on implementation `9cf0bf8`, under accepted ADR-0006 (Option A). The workspace now carries one owner per producer concept: host/target match, compatibility-floor applicability, exact-tag safety, the SHA-256 hex acceptance set, and the file digest. The two exact-tag rule sets were disjoint in both directions, so the canonical validator is their union, and the M003j canonical format check stays a separate function with a separate diagnostic. ADR-0006 Option A is implemented: the all-zeros SHA-256 sentinel is refused by every producer path, `ReleaseManifest` stays at `schema_version: 1`, and the published `eggpack-manifest` crate takes a `0.1.1` patch release carrying the tightened rule. `eggup-eggpack` is named as the affected downstream consumer. Two plan inaccuracies are recorded in the closure rather than absorbed: a fourth SHA-256 acceptance set in `core/qualification.rs` (discharged by Build M008, which owns that file), and the core-side rule copies living in `core/builder.rs` rather than `core/lib.rs` (converged here). CI M003m is unblocked and ready; CI M003n follows behind it. --- .../ci-release-orchestration/003l-status.md | 203 ++++++++++++++++++ plans/registry.md | 18 +- .../ci-release-orchestration-roadmap.md | 8 +- 3 files changed, 216 insertions(+), 13 deletions(-) create mode 100644 plans/closure/ci-release-orchestration/003l-status.md diff --git a/plans/closure/ci-release-orchestration/003l-status.md b/plans/closure/ci-release-orchestration/003l-status.md new file mode 100644 index 0000000..5906afd --- /dev/null +++ b/plans/closure/ci-release-orchestration/003l-status.md @@ -0,0 +1,203 @@ +# CI/Release Milestone 003l Closure — Producer Rule Authority Convergence Corrective + +Status: closed + +Source plan: `plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md` + +Roadmap: `plans/subsystems/ci-release-orchestration-roadmap.md` + +Accepted decision: `plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md` (**accepted**, Option A, 2026-10-23) + +Reviewed baseline: `a0fec98` (`origin/main` — the merge of `eggstack/eggpack#1` (CI M003k) and `eggstack/eggpack#2`). + +Implementation SHA: `9cf0bf8` — `fix(ci): converge producer rule authority onto core and manifest`. + +Predecessor in this chain: Build/Qualification M007 (`e3c6192`), which delivered the canonical file-digest authority this milestone consumes. + +## Executive finding + +M003l is closed. The workspace now carries **one** SHA-256 hex acceptance rule, **one** host/target match rule, **one** floor-applicability rule, **one** exact-tag safety rule, and **one** file-digest authority. Five divergent copies across `eggpack-core`, `eggpack-ci`, and `eggpack-github` were deleted and replaced by delegation to their owners. + +The acceptance set that ADR-0006 decided is now real: the all-zeros sentinel is refused by every producer path, including the published `eggpack-manifest` crate, which carries the rule in a `0.1.1` patch release. `ReleaseManifest v1` did not change — no field, no shape, no `schema_version` — so a consumer that reads real producer output is unaffected. A consumer that *emits or accepts* an all-zeros digest will now fail validation, and `eggup-eggpack` is named as the affected downstream consumer. + +Nothing was weakened. Every rule kept its refusal set, and where a rule moved between crates the diagnostic wording stayed byte-identical so that a consumer grepping a CI log line does not see it change. + +## Production implementation evidence + +### `eggpack-manifest` — the SHA-256 acceptance set (ADR-0006 §5.1 item 1) + +| Location | Change | +|---|---| +| `crates/eggpack-manifest/src/lib.rs` | `pub enum Sha256Error` (`:56`) with `NotLowercaseHex` (`:60`) and `AllZeros` (`:62`); `pub fn validate_sha256_hex(digest: &str) -> Result<(), Sha256Error>` (`:98`) — the single SHA-256 hex acceptance rule: exactly 64 lowercase hex characters, and never the all-zeros digest. | +| `crates/eggpack-manifest/src/lib.rs` | `ArtifactRecord::validate`, `ByteEvidence::validate`, and `decode_sha256` now route through `validate_sha256_hex` instead of restating the rule. | +| `crates/eggpack-manifest/Cargo.toml` | Explicit `version = "0.1.1"`, with a comment recording why the crate carries its own patch version while `[workspace.package] version` stays `0.1.0` for the other six crates. The dependents' `version = "0.1.0"` requirement is unchanged: `^0.1.0` permits `0.1.1`. | +| `Cargo.lock` | Refreshed for the version change. `cargo package -p eggpack-manifest --locked --allow-dirty` verifies `eggpack-manifest v0.1.1` successfully. | + +### `eggpack-core` — the canonical producer rule surface + +| Location | Change | +|---|---| +| `crates/eggpack-core/src/lib.rs` | `pub fn host_matches_target(host: HostRequirement, triple: &str) -> bool` (`:90`) — was private. The single host/target match rule. | +| `crates/eggpack-core/src/lib.rs` | `pub enum FloorApplicabilityError` (`:126`) with `NotGlibcTarget`, `NotMacosTarget`, `MacosFloorUnderZigbuild`; `pub fn validate_floor_applicability(floor, strategy, triple)` (`:186`) — the single floor-applicability rule, composed of a triple half and a strategy half. | +| `crates/eggpack-core/src/lib.rs` | `pub fn validate_policy(policy, triple) -> Result<(), CoreError>` (`:206`) — was private. The single policy validation rule. | +| `crates/eggpack-core/src/lib.rs` | `pub enum ExactTagSafetyError` (`:274`) with `OutOfBounds`, `ControlCharacters`, `QueryOrInjectionCharacters`, `UnsafePathShape`, `UnsafeGitRefPath`; `pub fn validate_exact_tag_safety(tag) -> Result<(), ExactTagSafetyError>` (`:313`) — the single exact-tag **safety** rule, carrying the union of the two former concern sets. | +| `crates/eggpack-core/src/lib.rs` | `pub use eggpack_manifest::{validate_sha256_hex, Sha256Error};` (`:18`). | +| `crates/eggpack-core/src/builder.rs` | `run_git_tag_bounded` now calls `crate::validate_exact_tag_safety(tag)` instead of its own inline condition list. `cargo_command` now calls `crate::validate_floor_applicability(...)` for the macOS-floor-under-zigbuild refusal. **Both were in scope by substance even though they live in `builder.rs` rather than `lib.rs`.** | + +### `eggpack-ci` — five copies deleted + +Deleted: the CI crate's private `host_matches_target`, its floor/strategy validity helpers (`floor_valid`, `toolchain_valid`, `native_qualification_valid`, the CargoZigbuild/macOS check), its independent SHA-256 validator body, its independent exact-tag safety body, and its own file-digest implementation. + +What remains in `eggpack-ci` are **thin delegations that keep the crate's own diagnostic wording**: + +| Location | Change | +|---|---| +| `crates/eggpack-ci/src/lib.rs:589` | `pub fn validate_sha256_hex` now applies `eggpack_core::validate_sha256_hex` and maps the refusal to the CI crate's own `"invalid SHA-256 digest"`. | +| `crates/eggpack-ci/src/lib.rs:4639` | `fn hash_candidate_file` now returns `Result<(u64, String), eggpack_core::DigestError>` and delegates to `eggpack_core::file_digest`. **There is no longer a `(0, String::new())` sentinel success value and no empty digest on any path.** | +| `crates/eggpack-ci/src/lib.rs:4886` | `fn validate_exact_tag` delegates to `eggpack_core::validate_exact_tag_safety` and maps each refusal class to the CI crate's existing message wording. | +| `crates/eggpack-ci/src/lib.rs` | `CIPlan::validate` applies the core policy validation instead of re-deriving the host match and the floor rules. | + +### `eggpack-github` — two copies deleted + +| Location | Change | +|---|---| +| `crates/eggpack-github/src/lib.rs:571` | `fn validate_sha256` delegates to `eggpack_manifest::validate_sha256_hex` and keeps the crate's own wording, adding `"sha256 must not be the all-zeros digest"` for the new refusal class. | +| `crates/eggpack-github/src/lib.rs:604` | `fn digest_file` delegates to `eggpack_core::file_digest` and maps each canonical refusal to the crate's existing staging diagnostics (`staging_digest_message`). | +| `crates/eggpack-github/src/lib.rs` | `validate_tag` delegates to the canonical exact-tag safety rule. | + +## The exact-tag safety rule — the union, proven + +Neither former validator was a superset of the other, so the canonical rule is the **union**, not "the same rule twice": + +- empty; length bound; control characters — from both; +- `?`, space, `\` — from both; +- `..`; leading and trailing `/` — from both; +- `#`, `@`, `'`, `"`, `` ` ``, `$` — from the CI concern set; +- trailing `.`; `@{`; `^`, `:`, `*`, `[`, `~` — from the core concern set; +- path components that are empty, begin with `.`, or end with `.lock` — from the core concern set. + +The canonical validator is **safety only**. The M003j canonical-**format** check (`vX.Y.Z`) remains a separate function with a separate diagnostic; the two were not merged. + +## The one behaviour change a caller can observe + +**The core git-resolution path now refuses tags containing `#`, `@`, `'`, `"`, `` ` ``, or `$` that it previously accepted.** This is fail-closed and correct — those characters are special to git and to shells — but it is a change on a path exercised by live consumer releases. + +Grep evidence that no in-tree tag, workflow input, or consumer configuration is affected: + +- `git tag -l` in this repository lists exactly one tag: `eggpack-manifest-v0.1.0`. +- The in-tree tag literals are `v1.2.3`, `v1.2.4`, `v1.2.5`, `v1.2.6`, `v2.4.0`, `v3.1.0`, the negative test `v1?x`, and the malformed `vX`. +- `release_tag` is a required input with no default, so no workflow supplies an implicit tag. +- No checked-in fixture carries a tag value. + +The other observable changes are narrowings in the same direction: the CI crate's consumer-evidence digest check and expected-digest check now refuse an all-zeros digest; `eggpack-manifest`'s `sha256_bytes` refuses one; and `CIPlan::validate` now enforces core's stricter complete-version rule for the `cargo_zigbuild` and `zig` toolchain versions instead of the CI crate's own looser reading. + +**Not changed:** `eggpack-core`'s `PackConfig::resolve` outcome. The macOS-floor-under-zigbuild refusal stays at build-command derivation, and `validate_policy` continues to apply only the triple half of the floor rule, so a producer that declares a macOS floor under `CargoZigbuild` still resolves and is still refused at the same point with the same message. + +## Diagnostic compatibility + +No message text was removed. Messages that moved between crates kept their wording: + +- `"glibc floor applies only to GNU/Linux targets"`, `"macOS floor applies only to macOS targets"`, and `"macOS floor cannot use cargo-zigbuild"` are unchanged in core. +- `"invalid SHA-256 digest"` in the CI crate and `"sha256 must be 64 lowercase hex characters"` in the GitHub and manifest crates are unchanged. +- The CI crate's exact-tag messages (`"exact tag out of bounds"`, `"exact tag contains control characters"`, `"exact tag contains query/injection characters"`, `"exact tag has unsafe path shape"`, `"exact tag has unsafe git ref path shape"`) are unchanged. +- The GitHub crate's staging digest messages (`"staging file is unavailable"`, `"staging file must be a non-empty regular file"`, `"staging file cannot be read"`, `"staging file size exceeds the platform bound"`, `"staging file changed during read"`) are unchanged. + +New message classes: `"sha256 must not be the all-zeros digest"` in the manifest and GitHub crates, and the GitHub crate's mapping of the two canonical tag refusal classes onto its own wording. + +## Verification executed + +All verification below ran against implementation SHA `9cf0bf8`, scoped to the actual change as the maintainer directed for this stage: + +```text +cargo fmt --all -- --check passed +cargo check --workspace --all-targets --all-features --locked passed +cargo clippy --workspace --all-targets --all-features --locked -- -D warnings passed +cargo test -p eggpack-manifest --all-targets --all-features --locked passed (28 passed, 0 failed) +cargo test -p eggpack-ci --all-targets --all-features --locked passed (67 passed, 0 failed, 3 ignored) +cargo test -p eggpack-github --all-targets --all-features --locked passed (39 passed, 0 failed) +cargo test -p eggpack-core --all-targets --all-features --locked passed (61 passed, 0 failed, 6 ignored) +cargo package -p eggpack-manifest --locked --allow-dirty passed (eggpack-manifest v0.1.1, 6 files) +``` + +The `eggpack-core` test run was added because this milestone edited core; the other three crates are the ones the milestone changed. + +**The workspace-wide `cargo check` and `cargo clippy -D warnings` are the proof that no second implementation of any of the five rules survived.** The greps behind that claim: + +- `digest_file` / `hash_candidate_file`: the CI and GitHub survivors are now one-line delegations to `eggpack_core::file_digest`, with the sentinel `(0, String::new())` return gone. +- `validate_sha256` / `validate_sha256_hex`: the CI and GitHub survivors are delegations to `eggpack_manifest::validate_sha256_hex`. +- `host_matches_target`: one definition, in `eggpack-core`. +- `validate_exact_tag` / `validate_exact_tag_safety`: one rule, in `eggpack-core`; the CI survivor maps refusal classes onto its own wording. +- `validate_policy` / `validate_floor_applicability`: one rule, in `eggpack-core`. + +## Requirement-to-evidence matrix + +| Plan requirement | Evidence and result | +|---|---| +| §5.1 item 1 — host/target match callable from `eggpack-ci` | `eggpack_core::host_matches_target`; `CIPlan::validate` calls it. The CI copy is deleted. | +| §5.1 item 2 — policy validation callable from `eggpack-ci` | `eggpack_core::validate_policy` and `eggpack_core::validate_floor_applicability`; the CI floor and strategy helpers are deleted. | +| §5.1 item 3 — the canonical exact-tag safety validator | `eggpack_core::validate_exact_tag_safety`, carrying the union of both concern sets. | +| §5.1 item 4 — the canonical SHA-256 hex validator, per ADR-0006 | `eggpack_manifest::validate_sha256_hex`, re-exported by core and applied by core, CI, and GitHub. | +| §5.1 item 5 — the canonical file-digest helper, from M007 | `eggpack_core::file_digest`, consumed by the CI and GitHub crates. | +| §5.2 — every deletion verified by grep | The greps above; no second implementation of any of the five rules survives in the workspace. | +| §5.3 — the union, and the M003j format check kept separate | The concern-set table above; the format check remains a separate function with a separate diagnostic. | +| §5.4 — diagnostic compatibility | The "Diagnostic compatibility" section above; no message text removed, moved messages byte-identical. | +| §3 invariant: no second implementation of any producer rule | Confirmed by grep and by the clean workspace `clippy -D warnings`. | +| §3 invariant: `ReleaseManifest v1` unchanged | No field, no shape, no `schema_version` change anywhere in this milestone. | +| §3 invariant: integrity ≠ authenticity | No signature, provenance, or publisher-identity claim is introduced. The rule is about digest *format*, not about who produced the bytes. | +| §8 — the published crate's acceptance set narrows, and the narrowing is recorded | `eggpack-manifest` `0.1.1`; the compatibility event is this record and `architecture/manifest.md`'s subject area, and `eggup-eggpack` is named above. | + +## Compatibility and no-regression evidence + +- **No schema version bump.** `ReleaseManifest v1`, `PackConfig v1`, `CIPlan v1`, and `QualificationEvidence` are unchanged in shape. +- **No generated workflow byte changed.** The `ci _*` runner arguments, exit discipline, and diagnostics are unchanged, so `eggpack ci check` drift status is unchanged for every existing consumer. +- **No dependency added** in any crate. +- **No historical closure rewritten.** `plans/closure/ci-release-orchestration/001`–`003j-status.md` and every other historical closure record are untouched. +- **Pre-existing tests stay green** across all four affected crates. +- **`eggpack-core` is not published**, so its new public API surface carries no external compatibility cost. + +## Security and reliability review + +- The all-zeros digest is a natural "digest not computed" sentinel. Refusing it everywhere means a producer cannot record a placeholder as if it were evidence. The published crate is the boundary that matters most, because its documents are consumed by other software. +- The exact-tag union **narrows** what the core git path accepts. Git itself treats `#`, `@{`, `^`, `:`, `*`, `[`, and `~` as special in ref names, and shells treat `#`, `'`, `"`, `` ` ``, and `$` as metacharacters. Refusing them at the producer's own boundary is fail-closed. +- The CI candidate-hashing path no longer has a `(0, String::new())` sentinel: a missing, symlinked, empty, or unreadable candidate now produces a **typed error** and an absent candidate record, never an empty digest that could be mistaken for a computed one. +- No signature, provenance, or authenticity claim is introduced. SHA-256 and size remain **integrity facts only**. +- No new network, credential, privilege, archive, or publication surface is touched. + +## Failure and recovery review + +- A rule that moved between crates fails **closed** in its new home: a refusal that was previously possible in one crate is still possible, now via the canonical rule. +- The narrowed tag acceptance set fails closed: an unsafe tag is refused earlier, not later. +- The narrowed SHA-256 acceptance set fails closed: a placeholder digest is refused rather than recorded. +- Rollback is a revert of this single commit. The previously permissive acceptance set returns, with no consumer impact beyond re-admitting the all-zeros sentinel. +- There is no contention or restart hazard: the milestone adds no new external service, cache, or shared state. + +## Findings + +| Severity | Finding | Disposition | +|---|---|---| +| Resolved in this milestone (medium, plan accuracy) | The plan's §2 inventory named **three** SHA-256 acceptance rules. There was a **fourth**: `crates/eggpack-core/src/qualification.rs` validated a candidate's recorded digest inline with a 64-character lowercase-hex check and accepted the all-zeros digest. ADR-0006 §5.1 requires `eggpack-core` to consume the canonical validator, so the inline check is a restatement of the rule. | Routed through `eggpack_core::validate_sha256_hex` in **Build/Qualification M008**, which owns `qualification.rs`. M003l did not own that file, so the correction is recorded here and discharged by the successor milestone rather than silently left. | +| Resolved in this milestone (medium, plan scope accuracy) | The plan's §4 scope named `crates/eggpack-core/**` visibility changes, but the two core-side rule *copies* — the exact-tag condition list in `run_git_tag_bounded` and the macOS-floor refusal in `cargo_command` — live in `crates/eggpack-core/src/builder.rs`. Leaving them would have left two live implementations of two of the five rules, failing the plan's own §12 requirement. | Both are routed to the canonical rules in this milestone. The plan's scope description was short by one file; recorded here so the record is not silently inaccurate. | +| Low (residual) | `eggpack-github`'s `verify_file` hashes a generic `ReadSeek` rather than a path, so the path-based `file_digest` cannot serve it. It is a different operation (streaming a caller-supplied reader), not a duplicate of the file-digest rule. | Left as-is and recorded. It is not a second *file-digest* implementation: it takes no path and makes no path-metadata decision. | +| Operational boundary | Verification ran on Linux x86-64 only. The macOS and Windows lanes are covered by hosted CI only. | Accepted; the same boundary every prior milestone recorded. No hosted run was claimed because nothing was pushed. | +| None | No unresolved medium-or-higher defect in the corrected producer contract. | M003l acceptance criteria satisfied. | + +## Roadmap disposition and dependency transitions + +| Milestone | Status after M003l | Reason | +|---|---|---| +| CI/Release M003l | closed | This record; implementation `9cf0bf8`. | +| CI/Release M003m | unblocked | Its only blocker was M003l. | +| CI/Release M003n | still blocked | It follows M003m. | +| Build/Qualification M008 | in progress | It consumes this milestone's canonical rule surface and discharges the residual `qualification.rs` SHA-256 acceptance set recorded above. | + +## Downstream-unblock answer + +Closing M003l unblocks **CI/Release M003m** and nothing else. Because M003m has not itself closed, CI M003n and every later milestone in the chain remain blocked behind it. + +## Eggstack references + +- Accepted decision: `plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md` +- Closed source plan: `plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md` +- Predecessor that delivered the digest authority: `plans/closure/build-qualification/007-status.md` (`e3c6192`) +- Successor: `plans/implementation/ci-release-orchestration/003m-bounded-process-execution-convergence-corrective.md` +- Downstream consumer to be notified: `eggup-eggpack` (the only known consumer of `eggpack-manifest 0.1.0`), which must be given the `0.1.1` patch release and the narrowed acceptance set. diff --git a/plans/registry.md b/plans/registry.md index 832eca3..97dad0c 100644 --- a/plans/registry.md +++ b/plans/registry.md @@ -96,7 +96,7 @@ Distribution predecessor evidence: | Release manifest | active | `plans/subsystems/release-manifest-roadmap.md` | M002/M003 closed; M003a closed | M003a closed as a docs-only post-publication downstream-closure reconciliation after Eggup M004 closed (`eggstack/eggup@ea1f1c5e29302e5feca4599db9342d3a5ac93915`; formal Eggup status cleanup `eggstack/eggup@3b82d5397e728649a666690868a1e2d0fe42460d`); closure `plans/closure/release-manifest/003a-status.md`; M003 remains closed and no runtime/package requalification was performed or implied | | Build and qualification | active | `plans/subsystems/build-qualification-roadmap.md` | M001-M007 closed; M008 and M009 ready | M007 closed on `e3c6192`: one canonical bounded file-digest authority in `eggpack-core` (`crates/eggpack-core/src/digest.rs`), retiring core's three divergent digest implementations, including a third in-crate SHA-256 stream in `qualification.rs` that the plan's inventory had missed. M006 closed on `398cd43` + run 36484758546 under accepted ADR-0005 Option A. The 2026-10-23 post-implementation review registered M007 (evidence digest unification, closed), M008 (compatibility floor verification), and M009 (local producer operator commands) | | Bootstrap installers | active; corrective closed | `plans/subsystems/bootstrap-installers-roadmap.md` | M002b closed; prior milestones closed | M002b implementation `88ddf2e`, hosted run `37806244313`; POSIX runtime remains on Unix and Windows PowerShell archive runtime passed. M003 completion definition remains satisfied | -| CI/release orchestration | active; M003j closed, M003k closed, M003l in progress | `plans/subsystems/ci-release-orchestration-roadmap.md` | M003l producer rule authority convergence | M003k merged to `main` at `a0fec98` (PR `eggstack/eggpack#1` plus `eggstack/eggpack#2`); its merge gate is discharged. M003l is unblocked by that merge, by Build/Qualification M007 (`e3c6192`), and by accepted ADR-0006 (Option A). The 2026-10-23 post-implementation review registered M003l, M003m (bounded process execution convergence), and M003n (producer implementation consolidation), chained behind M003l | +| CI/release orchestration | active; M003j closed, M003k closed, M003l closed, M003m ready | `plans/subsystems/ci-release-orchestration-roadmap.md` | M003m bounded process execution convergence | M003k merged to `main` at `a0fec98`; M003l closed on `9cf0bf8` under accepted ADR-0006 (Option A): one SHA-256 hex acceptance rule (the all-zeros sentinel is refused everywhere), one host/target match rule, one floor-applicability rule, one exact-tag safety rule (the union of two disjoint concern sets), and one file-digest authority. `eggpack-manifest` takes `0.1.1`; `ReleaseManifest` v1 unchanged. M003m is unblocked | | Eggup interoperability | active | `plans/subsystems/eggup-interoperability-roadmap.md` | Eggpack M001a + Eggup adapter M001/M001a + Eggup M003 real-consumer adoption + Eggup M004 registry promotion all closed | The whole producer/consumer package seam is closed end to end; Release Manifest M003a closed the remaining Eggpack-side planning drift, and no Eggpack work remains on this seam; Eggwork Operations M003 remains producer-only | | Ecosystem adoption | active | `plans/subsystems/ecosystem-adoption-roadmap.md` | M001/M002/M003a/M003b closed | Closure `plans/closure/ecosystem-adoption/003b-status.md`. Paired plans: Eggpack `plans/implementation/ecosystem-adoption/003b-eggsearch-seven-target-eggpack-producer-cutover.md` (`325d44e`); Eggsearch `plans/implementation/eggpack-release-adoption/001-seven-target-eggpack-producer-cutover.md` (`377f9e8`, registry `6767062`). Implementation landed at `eggstack/eggsearch@eabbf80`; hosted run `37531104901` staged eggsearch `v0.4.2` as draft `405157598` with the exact 19-asset inventory, glibc 2.17 re-proven on all three GNU targets, ARMv7 required consumer validator green, Windows ARM64 required and green, and zero OIDC permission in generated jobs. Provenance attested the staged bytes in run `37561960304`; the draft was published 2026-10-07, closing the named condition | | Planning hygiene | active | `plans/subsystems/planning-hygiene-roadmap.md` | M001/M002 closed; M003 ready | M002 closed at `plans/closure/planning-hygiene/002-status.md`: docs/evidence-only post-M003a handoff reconciliation with an empty production/package/workflow diff; stale/duplicated control-surface text removed and the handoff bound to exact paired-plan paths. M003 ready: docs/evidence-only post-implementation-review baseline reconciliation (architecture citation re-base by symbol name, `AGENTS.md` handoff rewrite, full CLI command reference, review-chain registration) | @@ -107,7 +107,7 @@ Distribution predecessor evidence: Planning Hygiene M002, Ecosystem M003b, Bootstrap M002b, CI M003i, and CI M003j are closed. **Dependency-ready CI M003k:** `plans/implementation/ci-release-orchestration/003k-precheckout-tag-resolution-and-stage-environment.md`. It resolves the downstream wg-basic R001 pre-checkout and stage-environment gates while preserving M003j's safe dispatch handling. -The post-implementation review of 2026-10-23 registered a corrective chain. **Build/Qualification M007 is closed** (`e3c6192`): `eggpack-core` now has one canonical bounded file-digest authority, and the SHA-256 hex acceptance set is decided by **accepted ADR-0006 (Option A)** — the all-zeros sentinel is refused everywhere, `ReleaseManifest` stays at `schema_version: 1`, and the published `eggpack-manifest` crate takes a `0.1.1` patch release carrying the tightened rule. With the M003k merge (`a0fec98`) and M007 in place, **CI M003l is unblocked and in progress**. Still ahead: **Build/Qualification M008** (now ready) and **Build/Qualification M009** (ready), then CI M003m and CI M003n behind M003l, with **Planning Hygiene M003** (docs-only) independent of the chain. +The post-implementation review of 2026-10-23 registered a corrective chain. **Build/Qualification M007 is closed** (`e3c6192`): `eggpack-core` now has one canonical bounded file-digest authority. **ADR-0006 is accepted (Option A)**: the all-zeros SHA-256 sentinel is refused everywhere, `ReleaseManifest` stays at `schema_version: 1`, and the published `eggpack-manifest` crate takes a `0.1.1` patch release carrying the tightened rule. **CI M003l is closed** (`9cf0bf8`): the duplicate host-match, floor-applicability, exact-tag, SHA-256 acceptance, and file-digest rules are gone, and the two exact-tag rule sets — disjoint in both directions — are replaced by their union. **Build/Qualification M008 is in progress** and **CI M003m is ready**; **Build/Qualification M009** (ready) and **Planning Hygiene M003** (docs-only) are independent of both, and CI M003n follows behind M003m. The table below is the **milestone-to-closure index plus active ready work**, not an implication that every historical row is executable. @@ -117,7 +117,7 @@ The table below is the **milestone-to-closure index plus active ready work**, no | CI orchestration | M003i exact tag versus manifest release ID policy | **closed** | `plans/implementation/ci-release-orchestration/003i-explicit-tag-and-manifest-release-identity-corrective.md` | Closure `plans/closure/ci-release-orchestration/003i-status.md`; implementation `3ddac9d84fc2e10b8451d38672f66b02e06724df`; hosted run `37813044035` all four lanes green. wg-basic M003 may resume with this pin | | CI orchestration | M003j dispatch-tag Bash interpolation corrective | closed | `plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md` | Closure `plans/closure/ci-release-orchestration/003j-status.md`; implementation `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce`; hosted run `37987890305` all four lanes green | | CI orchestration | M003k pre-checkout tag resolution and stage approval gate | closed | `plans/implementation/ci-release-orchestration/003k-precheckout-tag-resolution-and-stage-environment.md` | PR `eggstack/eggpack#1` merged to `main` at `1103a1a` (followed by `eggstack/eggpack#2` at `a0fec98`); implementation `fb81aa1`; local gate and hosted run `38027143275` passed | -| CI orchestration | M003l producer rule authority convergence corrective | **in progress** | `plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md` | Unblocked: CI M003k merged (`a0fec98`), Build/Qualification M007 closed (`e3c6192`), ADR-0006 accepted (Option A). Removes the duplicate host-match, floor-applicability, exact-tag, SHA-256 acceptance, and file-digest rules; the two exact-tag rule sets are disjoint in both directions and their union becomes canonical | +| CI orchestration | M003l producer rule authority convergence corrective | **closed** | `plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md` | Closure `plans/closure/ci-release-orchestration/003l-status.md`; implementation `9cf0bf8`; accepted ADR-0006 Option A implemented. The duplicate host-match, floor-applicability, exact-tag, SHA-256 acceptance, and file-digest rules are gone; the two exact-tag rule sets were disjoint in both directions and their union is canonical | | Planning hygiene | M001 current evidence baseline + blocker reconciliation | closed | `plans/implementation/planning-hygiene/001-current-evidence-baseline-and-blocker-reconciliation.md` | Closure `plans/closure/planning-hygiene/001-status.md`; discharged CI M003b (eggsact `685fa373` + run `36886042696`) and closed Ecosystem M002 on stegoeggo `v0.5.0` (run `37181914252`); docs-only, zero production/package/workflow delta | | Planning hygiene | M002 post-M003a cross-repository handoff reconciliation | closed | `plans/implementation/planning-hygiene/002-post-m003a-cross-repository-handoff-reconciliation.md` | Closure `plans/closure/planning-hygiene/002-status.md`; docs/evidence-only; stale M003/M003a/M003b control-surface text reconciled against exact paired-plan paths; empty production/package/workflow diff | | Planning hygiene | M003 post-implementation-review baseline reconciliation | **ready** | `plans/implementation/planning-hygiene/003-post-implementation-review-baseline-reconciliation.md` | Docs/evidence-only. Re-bases the `architecture/` citation set and line counts by symbol name against a measured baseline, closes the `ci-consumer-seam.md` and residual `cli.md` drift, rewrites the `AGENTS.md` current handoff, completes the CLI command reference, and registers the review chain. Zero production diff required | @@ -154,7 +154,7 @@ The table below is the **milestone-to-closure index plus active ready work**, no | Bootstrap installers | M002a PowerShell archive runtime evidence | closed | `plans/implementation/bootstrap-installers/002a-powershell-archive-runtime-evidence-corrective.md` | Closure `plans/closure/bootstrap-installers/002a-status.md`; implementation `4d2270a`; hosted run 36154905956 (attempt 1, all lanes green) | | Eggup interoperability | M001 Eggpack interface/fixtures | closed (historical) | `plans/implementation/eggup-interoperability/001-manifest-consumer-contract-and-fixtures.md` | Closure `plans/closure/eggup-interoperability/001-status.md`; post-closure projection defect tracked by M001a | | Eggup interoperability | M001a projection fixture consistency corrective | closed | `plans/implementation/eggup-interoperability/001a-projection-fixture-consistency-corrective.md` | Closure `plans/closure/eggup-interoperability/001a-status.md`; corrected pairwise fixture baseline | -| CI orchestration | M003m bounded process execution convergence corrective | **blocked** | `plans/implementation/ci-release-orchestration/003m-bounded-process-execution-convergence-corrective.md` | Blocked on CI M003l. The CI consumer-validator runner kills only the direct child and joins its reader threads without a bound, so a descendant holding a pipe can wedge a CI job past its timeout; converges on core's process-group runner and carries CI's prompt output-limit detection into it | +| CI orchestration | M003m bounded process execution convergence corrective | **ready** | `plans/implementation/ci-release-orchestration/003m-bounded-process-execution-convergence-corrective.md` | Unblocked by CI M003l (`9cf0bf8`). The CI consumer-validator runner kills only the direct child and joins its reader threads without a bound, so a descendant holding a pipe can wedge a CI job past its timeout; converges on core's process-group runner and carries CI's prompt output-limit detection into it | | CI orchestration | M003n producer implementation consolidation corrective | **blocked** | `plans/implementation/ci-release-orchestration/003n-producer-implementation-consolidation-corrective.md` | Blocked on CI M003m. One drift comparison replaces three byte-identical copies; one staging-payload builder replaces two copies that are 85.5% identical (301 of 352 lines); `render_release_github_inner` (845 lines) is decomposed; the CI crate's 11,044-line source file becomes a module tree. Byte-identical outputs required | ## Planned / blocked work @@ -284,17 +284,17 @@ introduced, and rewrites no closure record): ADR-0006 [ACCEPTED 2026-10-23, Option A: digest acceptance set] | - +--> CI M003l producer rule authority convergence [IN PROGRESS] + +--> CI M003l producer rule authority convergence [CLOSED: 9cf0bf8] | - +--> CI M003m bounded process execution convergence [BLOCKED: M003l] + +--> CI M003m bounded process execution convergence [READY] | +--> CI M003n producer implementation consolidation [BLOCKED: M003m] Build/Qualification M007 evidence digest unification [CLOSED: e3c6192] | - +--> Build/Qualification M008 compatibility floor verification [READY: core only] + +--> Build/Qualification M008 compatibility floor verification [IN PROGRESS: core only] | - +--> CI M003l (also depends on M007) + +--> CI M003l (also depends on M007) [CLOSED: 9cf0bf8] Build/Qualification M009 local producer operator commands [READY: cli only] @@ -337,7 +337,7 @@ Eggsearch **M003b passed implementation and is conditionally closed.** M003a set Longer-horizon lines stay as recorded: Ecosystem M004-M007 behind completed Eggsearch adoption, Phase 12 provenance behind a dedicated trust ADR, Phase 13 package adapters behind broader native adoption, Phase 14 stabilization premature. Eggsact's Git-to-registry migration remains separately owned downstream. -**The 2026-10-23 post-implementation review registered a corrective chain.** It found that the workspace carries several rules and structures in more than one place, and that the two copies do not always agree: four file-digest implementations with different TOCTOU behaviour, three SHA-256 acceptance rules where the crate that stages bytes accepts a digest the CI crate refuses, two exact-tag rule sets that are disjoint in both directions, a CI process runner that kills only the direct child and joins its reader threads without a bound, and a drift comparison and a staging-payload builder that each exist in duplicate. It also found a declared-but-unenforced compatibility floor, and a CLI that exposes two of the nine operator commands the canonical specification names. The chain is registered above; it corrects closed milestones' behaviour without rewriting any closure record. **Build/Qualification M007 is closed** (`e3c6192`) and **ADR-0006 is accepted (Option A)**, so the all-zeros SHA-256 sentinel is refused everywhere and `ReleaseManifest` stays at `schema_version: 1`. **CI M003l is in progress**; Build/Qualification M008 and M009 and Planning Hygiene M003 are ready and independent of it, and CI M003m and M003n follow behind M003l. +**The 2026-10-23 post-implementation review registered a corrective chain.** It found that the workspace carries several rules and structures in more than one place, and that the two copies do not always agree: four file-digest implementations with different TOCTOU behaviour, three SHA-256 acceptance rules where the crate that stages bytes accepts a digest the CI crate refuses, two exact-tag rule sets that are disjoint in both directions, a CI process runner that kills only the direct child and joins its reader threads without a bound, and a drift comparison and a staging-payload builder that each exist in duplicate. It also found a declared-but-unenforced compatibility floor, and a CLI that exposes two of the nine operator commands the canonical specification names. The chain is registered above; it corrects closed milestones' behaviour without rewriting any closure record. **Build/Qualification M007 is closed** (`e3c6192`), **ADR-0006 is accepted (Option A)**, and **CI M003l is closed** (`9cf0bf8`), so the all-zeros SHA-256 sentinel is refused everywhere, `ReleaseManifest` stays at `schema_version: 1`, and the workspace carries one rule per producer concept. **Build/Qualification M008 is in progress** and **CI M003m is ready**; **Build/Qualification M009** and **Planning Hygiene M003** are ready and independent of both, and CI M003n follows behind M003m. ## Downstream unblock disposition diff --git a/plans/subsystems/ci-release-orchestration-roadmap.md b/plans/subsystems/ci-release-orchestration-roadmap.md index bc7308b..2282d8d 100644 --- a/plans/subsystems/ci-release-orchestration-roadmap.md +++ b/plans/subsystems/ci-release-orchestration-roadmap.md @@ -104,7 +104,7 @@ M003j dispatch-tag shell-injection corrective: `plans/implementation/ci-release- M003k pre-checkout tag resolution and stage-environment support: `plans/implementation/ci-release-orchestration/003k-precheckout-tag-resolution-and-stage-environment.md` (**in progress**; PR `eggstack/eggpack#1`, producer head `23d9f0347d89fd6ecd916692c145152e39de687f`, local gate and hosted run `38027143275` passed; independent review/merge and downstream qualification remain). -The 2026-10-23 post-implementation review registered three further corrective milestones against this subsystem, chained behind M003k because each modifies `crates/eggpack-ci/src/lib.rs`. **M003l** converges the producer rules the CI crate re-derives — host/target matching, compatibility-floor applicability, exact-tag safety, the SHA-256 hex acceptance set, and the file digest — onto single owners in `eggpack-core`; the two exact-tag rule sets are disjoint in both directions, so neither is currently a superset of the other and their union becomes canonical. **M003m** converges the CI consumer-validator execution onto the workspace's single bounded process runner, which kills the whole process group and bounds its reader-thread joins; today the CI runner kills only the direct child and can therefore block indefinitely when a descendant holds an inherited pipe, defeating the timeout, cancellation, and output bounds the same function implements. **M003n** removes the duplicated drift comparison and staging-payload builder, decomposes the 845-line `render_release_github_inner`, and turns the 11,044-line CI source file into a module tree, with byte-identical outputs required throughout. ADR-0006 is proposed and gates M003l's digest-acceptance work package only. +The 2026-10-23 post-implementation review registered three further corrective milestones against this subsystem, chained behind M003k because each modifies `crates/eggpack-ci/src/lib.rs`. **M003l** converged the producer rules the CI crate re-derives — host/target matching, compatibility-floor applicability, exact-tag safety, the SHA-256 hex acceptance set, and the file digest — onto single owners in `eggpack-core` and `eggpack-manifest`; it closed on `9cf0bf8` under accepted ADR-0006 (Option A), and the two exact-tag rule sets that were disjoint in both directions are now replaced by their union. **M003m** converges the CI consumer-validator execution onto the workspace's single bounded process runner, which kills the whole process group and bounds its reader-thread joins; today the CI runner kills only the direct child and can therefore block indefinitely when a descendant holds an inherited pipe, defeating the timeout, cancellation, and output bounds the same function implements. It is ready, unblocked by M003l. **M003n** removes the duplicated drift comparison and staging-payload builder, decomposes the 845-line `render_release_github_inner`, and turns the CI source file into a module tree, with byte-identical outputs required throughout. ## 8. Cross-cutting requirements @@ -148,9 +148,9 @@ Build/Qualification M001-M006 and CI M001/M002/M002a/M003c-M003g are closed on t | M003i explicit tag and manifest release identity corrective | closed | `plans/implementation/ci-release-orchestration/003i-explicit-tag-and-manifest-release-identity-corrective.md` | `plans/closure/ci-release-orchestration/003i-status.md`; implementation `3ddac9d84fc2e10b8451d38672f66b02e06724df`; hosted run `37813044035` passed all four lanes | Finite checked-in opt-in stable-tag mapping with explicitly versioned runtime envelope; legacy exact-tag workflow bytes and ReleaseManifest v1 remain unchanged; wg-basic M003 may resume against the immutable producer SHA | | M003j dispatch tag shell-injection corrective | closed | `plans/implementation/ci-release-orchestration/003j-dispatch-tag-shell-injection-corrective.md` | `plans/closure/ci-release-orchestration/003j-status.md`; implementation `559d940af0fe6a2951eb17de1fcbecbf9e0bb6ce`; hosted run `37987890305` all four lanes green | Injection is fixed; pre-checkout ordering and stage environment remain M003k requirements | | M003k pre-checkout tag resolution + stage approval gate | in progress | `plans/implementation/ci-release-orchestration/003k-precheckout-tag-resolution-and-stage-environment.md` | PR `eggstack/eggpack#1` at `23d9f0347d89fd6ecd916692c145152e39de687f`; run `38027143275` all four lanes green; independent review/merge and downstream `dbowm91/wg-basic` qualification pending | -| M003l producer rule authority convergence corrective | blocked | `plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md` | — | Blocked on M003k merge, Build/Qualification M007, and ADR-0006 acceptance. One owner each for host/target match, floor applicability, exact-tag safety, SHA-256 acceptance, and the file digest; the two exact-tag rule sets are disjoint in both directions, so their union becomes canonical | -| M003m bounded process execution convergence corrective | blocked | `plans/implementation/ci-release-orchestration/003m-bounded-process-execution-convergence-corrective.md` | — | Blocked on M003l. The CI consumer-validator runner kills only the direct child and joins its reader threads without a bound; converges on core's process-group runner and carries CI's prompt output-limit detection into it | -| M003n producer implementation consolidation corrective | blocked | `plans/implementation/ci-release-orchestration/003n-producer-implementation-consolidation-corrective.md` | — | Blocked on M003m. One drift comparison replaces three byte-identical copies; one staging-payload builder replaces two copies that are 85.5% identical; `render_release_github_inner` (845 lines) is decomposed; the 11,044-line CI source file becomes a module tree. Byte-identical outputs required | +| M003l producer rule authority convergence corrective | closed | `plans/implementation/ci-release-orchestration/003l-producer-rule-authority-convergence-corrective.md` | `plans/closure/ci-release-orchestration/003l-status.md`; implementation `9cf0bf8` | Accepted ADR-0006 Option A implemented. One owner each for host/target match, floor applicability, exact-tag safety, SHA-256 acceptance, and the file digest; the two exact-tag rule sets were disjoint in both directions and their union is canonical. `eggpack-manifest` `0.1.1`; `ReleaseManifest` v1 unchanged | +| M003m bounded process execution convergence corrective | ready | `plans/implementation/ci-release-orchestration/003m-bounded-process-execution-convergence-corrective.md` | — | Unblocked by M003l (`9cf0bf8`). The CI consumer-validator runner kills only the direct child and joins its reader threads without a bound; converges on core's process-group runner and carries CI's prompt output-limit detection into it | +| M003n producer implementation consolidation corrective | blocked | `plans/implementation/ci-release-orchestration/003n-producer-implementation-consolidation-corrective.md` | — | Blocked on M003m. One drift comparison replaces three byte-identical copies; one staging-payload builder replaces two copies that are 85.5% identical; `render_release_github_inner` (845 lines) is decomposed; the CI crate's 11,044-line source file becomes a module tree. Byte-identical outputs required | ## 13. 2026-10-08 corrective addendum — M003i From 7e7cb6a1f116a0e6e222d213438d2cf38e4a3ed4 Mon Sep 17 00:00:00 2001 From: doc Date: Fri, 23 Oct 2026 15:46:24 +0000 Subject: [PATCH 07/46] feat(core): record compatibility floor verification status Add the single producer-side compatibility-floor verification status model and compute it from the produced bytes. - `FloorVerificationStatus` (closed, finite enum) with the reasons `PendingInspection`, `UnreadableCandidate`, `MalformedCandidate`, `NoVersionRequirement`, `UnrecognizedVersionRequirement`, and `FloorKindNotVerifiable`. - `PlannedTarget::floor_status` records the status a declared floor implies at plan time; `ReleasePlan::validate` refuses a plan whose stated status disagrees with its declared floor. - `QualificationEvidence::floor` records the status of the inspected bytes. A floor contradicted by the bytes fails the qualification for that target (`FloorNotSatisfied`) and is never reported as merely unverified; a floor that is merely unverifiable is a recorded status, not a failed release. - Bounded ELF reader: program headers, dynamic table, and `GLIBC_x.y` version requirements, with fixed bounds on every table and offset. The comparison direction is `required <= declared`. - Route the candidate digest acceptance check through the canonical `validate_sha256_hex`, so the all-zeros digest is refused like everywhere else in the producer. The cargo-zigbuild triple rewrite and the macOS-under-zigbuild refusal are byte-unchanged, and the refusal still fires at build-command time. --- architecture/core-build.md | 257 ++--- architecture/core-planning.md | 220 ++-- architecture/core-qualification.md | 352 +++--- crates/eggpack-ci/src/lib.rs | 2 + crates/eggpack-core/README.md | 4 +- crates/eggpack-core/src/builder.rs | 69 ++ crates/eggpack-core/src/finalization.rs | 1 + crates/eggpack-core/src/floor.rs | 1260 ++++++++++++++++++++++ crates/eggpack-core/src/lib.rs | 99 +- crates/eggpack-core/src/qualification.rs | 438 +++++++- 10 files changed, 2308 insertions(+), 394 deletions(-) create mode 100644 crates/eggpack-core/src/floor.rs diff --git a/architecture/core-build.md b/architecture/core-build.md index 5965f90..8a9549e 100644 --- a/architecture/core-build.md +++ b/architecture/core-build.md @@ -4,22 +4,22 @@ Explicit Cargo build bindings, the two first-party Cargo command adapters, bound cancellable process execution, private per-invocation target storage, and candidate byte discovery. One of four `eggpack-core` stage deep dives (planning, build, qualification, finalization); the stage between `ReleasePlan` (intent) and `QualificationEvidence` -(proof). Single file `crates/eggpack-core/src/builder.rs` (1301 lines, +(proof). Single file `crates/eggpack-core/src/builder.rs` (1734 lines, `#![forbid(unsafe_code)]` inherited from the workspace), re-exported wholesale at crate -root (`crates/eggpack-core/src/lib.rs:8`). +root (`crates/eggpack-core/src/lib.rs:10`). ## Inputs and outputs - in: `&ReleasePlan`, `&PlannedTarget` — from `PackConfig::resolve` - (`crates/eggpack-core/src/lib.rs:456`, `:468`). + (`crates/eggpack-core/src/lib.rs:709`, `:618`). - in: `&[BuildBinding]` — the caller's per-target slice, **not** coverage-validated here. -- in: `&DistributionContract` — only via `BuildBindingsV1::validate_for` (`:261`). +- in: `&DistributionContract` — only via `BuildBindingsV1::validate_for` (`:284`). - in: `repository_root`, `work_root`, `invocation`, `&BuildCancellation`. -- out: `BuildAttempt` (`:202`) — identity, bounded `ProcessEvidence`, `Vec`. -- out: `ProcessEvidence` (`:174`) — outcome plus retained byte **counts** only. +- out: `BuildAttempt` (`:227`) — identity, bounded `ProcessEvidence`, `Vec`. +- out: `ProcessEvidence` (`:199`) — outcome plus retained byte **counts** only. -`BuildAttempt` is identity-bound to `release_id` + `source_revision` (`:204`, `:206`) and to -the one `target` / `strategy` it ran (`:208`, `:210`). It records what was attempted, not +`BuildAttempt` is identity-bound to `release_id` + `source_revision` (`:229`, `:231`) and to +the one `target` / `strategy` it ran (`:233`, `:235`). It records what was attempted, not what was proved: this module never inspects a candidate's format, architecture, or runtime behaviour, so `Success` means a command exited zero — never that the candidate qualifies. @@ -28,170 +28,170 @@ behaviour, so `Success` means a command exited zero — never that the candidate A contract output slot is not a filesystem path, so each slot is bound by hand to a Cargo package and binary target. -- `LogicalOutputSelector` (`:49`), tagged and `deny_unknown_fields` (`:48`): `Direct` - (`:51`); `BundleEntry{index}` indexed by **contract order** (`:53-56`); - `ArchiveMember{source}` keyed by the **exact contract source string** (`:58-61`). -- `BuildBinding{selector, package, binary}` (`:67-74`) pairs a slot with one Cargo +- `LogicalOutputSelector` (`:68`), tagged and `deny_unknown_fields` (`:67`): `Direct` + (`:70`); `BundleEntry{index}` indexed by **contract order** (`:71-75`); + `ArchiveMember{source}` keyed by the **exact contract source string** (`:76-80`). +- `BuildBinding{selector, package, binary}` (`:86-93`) pairs a slot with one Cargo `--package` / `--bin` pair. - `BuildBindingsV1{schema_version, targets: BTreeMap>}` - (`:79-84`), strict version 1. `from_toml` (`:221`) parses via `toml::from_str` then runs - `validate_shape` (`:227`). + (`:98-103`), strict version 1. `from_toml` (`:246-251`) parses via `toml::from_str` then runs + `validate_shape` (`:252-282`). -`validate_shape` (`:227-257`) is the fail-closed bound layer: `schema_version == 1` and -1..=256 targets (`:228`); per target a non-empty key and 1..=256 bindings (`:232`); unique -selectors plus `valid_identifier` package/binary (`:237-242`), where -`valid_identifier` (`:301-306`) allows only `[A-Za-z0-9_.-]`, ≤128 bytes. +`validate_shape` (`:252-282`) is the fail-closed bound layer: `schema_version == 1` and +1..=256 targets (`:253-255`); per target a non-empty key and 1..=256 bindings (`:256-259`); unique +selectors plus `valid_identifier` package/binary (`:260-267`), where +`valid_identifier` (`:326-331`) allows only `[A-Za-z0-9_.-]`, ≤128 bytes. `ArchiveMember.source` must be a non-empty ≤255-byte relative path with no leading `/` -and no empty/`.`/`..` component (`:243-253`). +and no empty/`.`/`..` component (`:268-278`). -**Exact plan coverage** is `validate_for` (`:259-299`). For every `plan.targets` entry it -looks up `self.targets[&target.target]` (`:266-269`, else `missing target bindings`), -expands the contract (`:270-272`), and derives the expected slot set from the expanded +**Exact plan coverage** is `validate_for` (`:284-324`). For every `plan.targets` entry it +looks up `self.targets[&target.target]` (`:291-294`, else `missing target bindings`), +expands the contract (`:295-297`), and derives the expected slot set from the expanded `ExpandedAssets` variant — `Direct` ⇒ `{Direct}`; `Bundle` ⇒ `BundleEntry{0..entries.len()}`; -`Archive` ⇒ `ArchiveMember{source}` per member (`:273-283`). The binding selectors must -then be **equal as sets** (`:284-289`): equality in both directions means neither a +`Archive` ⇒ `ArchiveMember{source}` per member (`:298-308`). The binding selectors must +then be **equal as sets** (`:309-310`): equality in both directions means neither a missing nor an extra slot is accepted, reported as the single `bindings do not exactly -cover contract Cargo slots` (`:286-288`). Any binding target key absent from the plan is -rejected as `bindings include target outside ReleasePlan` (`:291-297`). Contract expansion +cover contract Cargo slots` (`:311-314`). Any binding target key absent from the plan is +rejected as `bindings include target outside ReleasePlan` (`:316-322`). Contract expansion is the authority: a `BuildBinding` cannot redefine layout, only map an already-contractual slot onto a Cargo target. ## Command construction by build strategy -`cargo_command` (`:309-366`) is the only builder and is total over the two -`BuildStrategy` variants. It re-validates both identifiers (`:316-318`), so it is safe to +`cargo_command` (`:334-401`) is the only builder and is total over the two +`BuildStrategy` variants. It re-validates both identifiers (`:341-343`), so it is safe to call with a hand-built binding. -| Aspect | `NativeCargo` (`:321-328`) | `CargoZigbuild` (`:329-336`) | +| Aspect | `NativeCargo` (`:351`) | `CargoZigbuild` (`:352`) | | --- | --- | --- | | subcommand | `build` | `zigbuild` | | shared args | `+`, `--release`, `--locked`, `--target ` | identical | -| glibc floor | not encoded | `args[5]` rewritten to `..` (`:338-340`) | -| macOS floor | n/a | rejected: `macOS floor cannot use cargo-zigbuild` (`:341-343`) | - -Both append exactly `--package --bin ` (`:345-350`). The executable is -always the bare tool name `cargo` (`:357`); executable and argv are separate OS arguments, so -no shell is involved (`:106`). One environment variable is injected, `CARGO_TARGET_DIR` = -the private target directory (`:351-355`); `cwd` is the caller's (`:359`), both stream limits -are `MAX_OUTPUT` (256 KiB, `:18`, `:362-363`), and `expected_stdout` is `None` (`:364`). -`execute_target_cancellable` supplies a fixed 1800 s build timeout (`:736`). - -`preflight` (`:584-674`) runs before any build: `rustc + --version` (`:589`) and -`cargo + --version` (`:608`), each 10 s / 1024 bytes, failing closed on any -non-`Success` outcome (`:605-607`, `:624-626`). Under `CargoZigbuild` it also requires both -cross-tool versions to be declared (`:628-639`) and requires each declared pin to be a complete +| glibc floor | not encoded | `args[5]` rewritten to `..` (`:358-361`) | +| macOS floor | n/a | rejected: `macOS floor cannot use cargo-zigbuild` (`:362-372`) | + +Both append exactly `--package --bin ` (`:379-384`). The executable is +always the bare tool name `cargo` (`:391`); executable and argv are separate OS arguments, so +no shell is involved (`:126`). One environment variable is injected, `CARGO_TARGET_DIR` = +the private target directory (`:385-389`); `cwd` is the caller's (`:393`), both stream limits +are `MAX_OUTPUT` (256 KiB, `:18-19`, `:396-397`), and `expected_stdout` is `None` (`:398`). +`execute_target_cancellable` supplies a fixed 1800 s build timeout (`:891`). + +`preflight` (`:732-831`) runs before any build: `rustc + --version` (`:739`) and +`cargo + --version` (`:759`), each 10 s / 1024 bytes, failing closed on any +non-`Success` outcome (`:754-756`, `:774-776`). Under `CargoZigbuild` it also requires both +cross-tool versions to be declared (`:777-789`) and requires each declared pin to be a complete `MAJOR.MINOR.PATCH` version. `cargo zigbuild --version` and `zig version` are matched by **trimmed equality** (`expected_stdout_exact`), not by substring, so a pin of `0.23.3` is not satisfied by a reported `0.23.30`; mismatch yields `cargo-zigbuild version mismatch` / `Zig version mismatch`. The expected value is compared internally and never -surfaced (`:124`). +surfaced (`:143-149`). ## Bounded cancellable process execution -All execution funnels through the private `run_bounded_inner` (`:391-563`). Three entry -points select an `ExecutableAllowance` (`:100-104`): +All execution funnels through the private `run_bounded_inner` (`:488-690`). Three entry +points select an `ExecutableAllowance` (`:119-124`): | Entry | Allowance | Executable rule | | --- | --- | --- | -| `run_bounded_cancellable` (`:370`) | `Builder` | `cargo` \| `rustc` \| `zig` (`:397-399`) | -| `run_qualification_process` (`:377`) | `Candidate` | must be an **absolute path** (`:400`) | -| `run_qemu_process` (`:384`) | `Qemu` | `qemu-x86_64` \| `qemu-aarch64` \| `qemu-arm` (`:401-404`) | +| `run_bounded_cancellable` (`:405`) | `Builder` | `cargo` \| `rustc` \| `zig` (`:494-496`) | +| `run_qualification_process` (`:474`) | `Candidate` | must be an **absolute path** (`:497`) | +| `run_qemu_process` (`:481`) | `Qemu` | `qemu-x86_64` \| `qemu-aarch64` \| `qemu-arm` (`:498-501`) | This is the ADR-0004 adapter restriction enforced at the exec boundary: not a command DSL, -and callers cannot widen the set at runtime. `test :947-949` pins it by rewriting the +and callers cannot widen the set at runtime. `test :1111-1113` pins it by rewriting the executable to `sh` and asserting rejection. -**Bound validation** (`:406-415`) rejects the whole call unless the executable is allowed, -`timeout` is non-zero and ≤86 400 s (`:407-408`), and both limits are non-zero and ≤`MAX_OUTPUT` -(`:409-412`). **Process-group control** uses `command_group::CommandGroup` (`:4`): -`group_spawn()` (`:479`) places the child in its own group/job, and `kill()` + `wait()` -(`:502-507`, `:511-516`) terminate the **group**, so build scripts and descendants die with +**Bound validation** (`:504-513`) rejects the whole call unless the executable is allowed, +`timeout` is non-zero and ≤86 400 s (`:505-506`), and both limits are non-zero and ≤`MAX_OUTPUT` +(`:507-510`). **Process-group control** uses `command_group::CommandGroup` (`:4`): +`group_spawn()` (`:591`) places the child in its own group/job, and `kill()` + `wait()` +(`:614-619`, `:623-628`) terminate the **group**, so build scripts and descendants die with the driver; termination failure is an error, not a swallowed outcome. The **poll loop** -(`:499-527`, 20 ms granularity at `:526`) tests cancellation **first** (`:501-509` → -`Cancelled`), then the deadline (`:510-518` → `TimedOut`), then child exit (`:519-525`), so +(`:612-639`, 20 ms granularity at `:638`) tests cancellation **first** (`:613-621` → +`Cancelled`), then the deadline (`:622-630` → `TimedOut`), then child exit (`:631-637`), so cancellation wins over a concurrent timeout. -**Bounded capture**: stdout and stderr are taken from the group child (`:481-490`) and -drained on two threads by `drain` (`:565-581`), which retains at most `limit` bytes and -raises an overflow flag on truncation (`:572-576`). Reader threads are always joined -(`:528-529`), so nothing is lost before the pipes are read. +**Bounded capture**: stdout and stderr are taken from the group child (`:529-530`) and +drained on two threads by `drain` (`:607-610`, `:713-729`), which retains at most `limit` bytes and +raises an overflow flag on truncation (`:719-724`). Reader threads are always joined +(`:651-652`, `:698-712`), so nothing is lost before the pipes are read. -**Contents never returned.** `ProcessEvidence` (`:174-181`) carries only `outcome`, +**Contents never returned.** `ProcessEvidence` (`:199-206`) carries only `outcome`, `stdout_bytes`, `stderr_bytes` — counts, never bytes. The captured buffers are local to -`run_bounded_inner` and dropped at return (`:534-541`, `:559-563`), which is what lets -`expected_stdout` be checked internally (`:542-545`) without becoming a side channel, so a +`run_bounded_inner` and dropped at return (`:657-664`), which is what lets +`expected_stdout` be checked internally (`:665-671`) without becoming a side channel, so a failure is diagnosable only by outcome and counts. -**Outcome classification** (`:546-558`), in precedence order: `TimedOut` → `Cancelled` → +**Outcome classification** (`:672-684`), in precedence order: `TimedOut` → `Cancelled` → `OutputLimitExceeded` → `Failed(-1)` when an `expected_stdout` substring is absent -(`:552-553`) → `Success` → `Failed(status.code().unwrap_or(-1))`. A signal-terminated child +(`:678-679`) → `Success` → `Failed(status.code().unwrap_or(-1))`. A signal-terminated child also lands on `-1`, so a missing substring is indistinguishable from signal death. The timeout/cancel path re-reads status after `wait()` and fails closed if unavailable -(`process cleanup incomplete`, `:530-533`). `BuildCancellation` (`:157`) is a `Clone` handle -over `Arc` whose `cancel()` is `SeqCst` and idempotent (`:164-169`). +(`process cleanup incomplete`, `:653-656`). `BuildCancellation` (`:182`) is a `Clone` handle +over `Arc` whose `cancel()` is `SeqCst` and idempotent (`:183-198`). ## Environment handling and Windows requirements -`env_clear()` (`:429`) is unconditional: the child starts from an empty environment, -re-populated only from a fixed allowlist. `stdin` is `Stdio::null()` (`:430`), so a child +`env_clear()` (`:527`) is unconditional: the child starts from an empty environment, +re-populated only from a fixed allowlist. `stdin` is `Stdio::null()` (`:528`), so a child can never block on input or prompt. The `Candidate` and `Qemu` allowances get `PATH`, -`SystemRoot`, `WINDIR`, `TEMP`, `TMP` (`:434`); `Builder` gets those five plus `HOME`, +`SystemRoot`, `WINDIR`, `TEMP`, `TMP` (`:546`); `Builder` gets those five plus `HOME`, `USERPROFILE`, `CARGO_HOME`, `RUSTUP_HOME`, `LIB`, `LIBPATH`, `INCLUDE`, `VCToolsInstallDir`, `VisualStudioVersion`, `VCINSTALLDIR`, `WindowsSdkDir`, `WindowsSDKVersion`, -`UniversalCRTSdkDir`, and `UCRTVersion` (`:436-456`). Each key is copied only if present in -the parent (`:459-463`); the rustup and MSVC homes are needed because `cargo`/`rustup` -resolve toolchains and the linker through them. `spec.env` is applied last (`:477`), so the +`UniversalCRTSdkDir`, and `UCRTVersion` (`:548-568`). Each key is copied only if present in +the parent (`:571-575`); the rustup and MSVC homes are needed because `cargo`/`rustup` +resolve toolchains and the linker through them. `spec.env` is applied last (`:589`), so the module's own override — in practice only `CARGO_TARGET_DIR` — wins. **Windows Cargo builds require an already-initialized MSVC environment.** This module neither provisions nor validates one; it only preserves one. On `#[cfg(windows)]`, when `VCToolsInstallDir` is set, `$VCToolsInstallDir/bin/Hostx64/x64` is prepended to `PATH` -(`:464-476`) so `link.exe` resolves from the active VCTools instance. If the environment was +(`:576-588`) so `link.exe` resolves from the active VCTools instance. If the environment was never initialized, those keys are simply absent, `cargo` cannot find a linker, and the failure surfaces as a bounded non-`Success` `ProcessEvidence` (`Failed(code)`) or, if the toolchain -itself is unreachable, as `configured Rust toolchain preflight failed` (`:606`) — never as +itself is unreachable, as `configured Rust toolchain preflight failed` (`:754-756`) — never as captured linker diagnostics, since output contents are not returned. The obligation is met outside this crate: CI uses `ilammy/msvc-dev-cmd@v1` and asserts `link.exe` resolves under `VCToolsInstallDir` (`.github/workflows/ci.yml:44-56`). On naming, `discover_candidate` -appends `.exe` when the triple contains the `-windows-` component (`:916-919`). +appends `.exe` when the triple contains the `-windows-` component (`:1015-1019`). The match is anchored on that component rather than a bare `windows` substring, so a hypothetical `x86_64-unknown-notwindowsish` triple does not pick up a Windows suffix; and the suffix is appended to the whole binary name via `set_file_name`, so a dotted name such as `tool.cli` resolves to `tool.cli.exe` as Cargo produces it, not to the truncating `tool.exe` that `set_extension` -would have yielded. `valid_identifier` (`:311-316`) admits `.`, so this case is +would have yielded. `valid_identifier` (`:326-331`) admits `.`, so this case is reachable rather than hypothetical. ## Candidate discovery and private target directories -`private_target_dir` (`:790-831`) establishes per-invocation storage isolation: +`private_target_dir` (`:951-992`) establishes per-invocation storage isolation: `work_root` must be absolute and must pre-exist as a real directory, and a symlink work -root is rejected (`:795-808`). The name is `{safe(invocation)}-{safe(target)}` (`:811`), -where `safe_component` (`:832-842`) maps every character outside `[A-Za-z0-9_-]` to `_`, so +root is rejected (`:956-969`). The name is `{safe(invocation)}-{safe(target)}` (`:972`), +where `safe_component` (`:993-1003`) maps every character outside `[A-Za-z0-9_-]` to `_`, so no caller string can traverse or inject a path; `invocation` is bounded to ≤128 bytes -(`:797`). `create_dir` makes an existing path a hard error, so invocations are private -rather than reused (`:813-818`); the created path is then re-canonicalized and must stay +(`:957-958`). `create_dir` makes an existing path a hard error, so invocations are private +rather than reused (`:974-980`); the created path is then re-canonicalized and must stay under the canonicalized work root, which is defence against a pre-existing symlink inside -the root (`:820-824`). A `.eggpack-owner` marker records `1\n\n\n` -(`:825-829`). +the root (`:981-985`). A `.eggpack-owner` marker records `1\n\n\n` +(`:986-990`). -The function is **not** pure: it mutates the filesystem. It returns `/target` (`:830`), +The function is **not** pure: it mutates the filesystem. It returns `/target` (`:991`), the directory handed to Cargo as `CARGO_TARGET_DIR`; the marker lives in the parent, not in -the returned path, which `execute_target_cancellable` then creates explicitly (`:722-723`) -and passes to `cargo_command` (`:735`). Isolation provided: no ambient or shared Cargo +the returned path, which `execute_target_cancellable` then creates explicitly (`:876-878`) +and passes to `cargo_command` (`:886-892`). Isolation provided: no ambient or shared Cargo target directory is ever written, so builds cannot contaminate one another or the caller's tree. -`discover_candidate` (`:845-884`) resolves exactly one path, -`//release/[.exe]` (`:853-856`) and validates before trusting -it: `binary` must be a valid identifier (`:850-852`); the entry must exist as a **non-empty -regular file, not a symlink** (`symlink_metadata` plus type and length checks, `:857-861`); -the canonicalized file must be contained in the canonicalized target directory (`:862-868`), +`discover_candidate` (`:1006-1047`) resolves exactly one path, +`//release/[.exe]` (`:1014-1019`) and validates before trusting +it: `binary` must be a valid identifier (`:1011-1013`); the entry must exist as a **non-empty +regular file, not a symlink** (`symlink_metadata` plus type and length checks, `:1020-1024`); +the canonicalized file must be contained in the canonicalized target directory (`:1025-1031`), since the symlink check alone would not stop a hardlink or a raced path; and both parents -(`` and `release`) must be real directories, not symlinks (`:869-882`). +(`` and `release`) must be real directories, not symlinks (`:1032-1045`). -It returns `(path, metadata.len())` (`:883`); nothing is read or hashed here, so the `size` on -`CandidateArtifact` (`:197`) is metadata only. A `CandidateArtifact` (`:185-198`) is bytes +It returns `(path, metadata.len())` (`:1046`); nothing is read or hashed here, so the `size` on +`CandidateArtifact` (`:222`) is metadata only. A `CandidateArtifact` (`:210-223`) is bytes plus identity (target, slot, package, binary); the build stage never installs, archives, publishes, or authenticates. @@ -201,26 +201,28 @@ Paths are `crates/eggpack-core/src/builder.rs` unless noted. | Line | Item | Note | | --- | --- | --- | -| `:18` | `MAX_OUTPUT` | `256 * 1024`; ceiling on each captured stream | -| `:24` | `ensure_candidate_executable` | private; unix-only; `mode \|= 0o111` on a non-symlink regular file (mode is not part of recorded size/digest) | -| `:49` `:67` `:79` | `LogicalOutputSelector`, `BuildBinding`, `BuildBindingsV1` | slot / slot+package+bin / strict version-1 document | -| `:88` `:95` | `BuildError`, `build_err` | `Display` + `Error`; fixed internal message only, never process text | -| `:100` `:108` `:129` | `ExecutableAllowance`, `CommandSpec`, `BoundCommand` | `ExecutableAllowance` private; **`BoundCommand` is declared public but never constructed anywhere in the workspace** | -| `:142` `:157` `:174` | `CommandOutcome`, `BuildCancellation`, `ProcessEvidence` | `BuildCancellation` = `Clone` `Arc`, `new` `:160` / `cancel` `:164` / `is_cancelled` `:167` | -| `:185` `:202` | `CandidateArtifact`, `BuildAttempt` | the two public result types | -| `:221` `:227` `:259` `:301` | `from_toml`, `validate_shape`, `validate_for`, `valid_identifier` | first two private; `[A-Za-z0-9_.-]`, ≤128 bytes | -| `:309` `:584` | `cargo_command`, `preflight` | `preflight` private | -| `:370` `:377` `:384` `:391` `:565` | `run_bounded_cancellable`, `run_qualification_process`, `run_qemu_process`, `run_bounded_inner`, `drain` | the middle two are `pub(crate)`; `run_bounded_inner` private and holds all enforcement | -| `:677` `:697` `:790` `:832` `:845` | `execute_target`, `execute_target_cancellable`, `private_target_dir`, `safe_component`, `discover_candidate` | `safe_component` private | - -**Tests (`:886-1301`):** explicit non-shell command and `sh` rejection (`:916-950`); zigbuild -glibc rewrite and macOS-floor rejection (`:952-988`); binding duplicate and unknown-field -rejection (`:990-1003`); exact direct-slot coverage (`:1005-1034`); candidate regularity and -non-emptiness (`:1036-1051`); relative and reused work roots rejected (`:1053-1059`); bounded -output, nonzero exit, and overflow classified `OutputLimitExceeded` (`:1061-1124`); timeout -and cancellation each killing and waiting for a real Cargo build script over three -iterations (`:1126-1244`); a real local Cargo fixture producing a direct candidate -(`:1246-1300`). +| `:18-19` | `MAX_OUTPUT` | `256 * 1024`; ceiling on each captured stream | +| `:43` | `ensure_candidate_executable` | private; unix-only; `mode \|= 0o111` on a non-symlink regular file (mode is not part of recorded size/digest) | +| `:68` `:86` `:98` | `LogicalOutputSelector`, `BuildBinding`, `BuildBindingsV1` | slot / slot+package+bin / strict version-1 document | +| `:107` `:114` | `BuildError`, `build_err` | `Display` + `Error`; fixed internal message only, never process text | +| `:119` `:128` `:154` | `ExecutableAllowance`, `CommandSpec`, `BoundCommand` | `ExecutableAllowance` private; **`BoundCommand` is declared public but never constructed anywhere in the workspace** | +| `:167` `:182` `:199` | `CommandOutcome`, `BuildCancellation`, `ProcessEvidence` | `BuildCancellation` = `Clone` `Arc`, `new` `:185` / `cancel` `:189` / `is_cancelled` `:192` | +| `:210` `:227` | `CandidateArtifact`, `BuildAttempt` | the two public result types | +| `:246` `:252` `:284` `:326` | `from_toml`, `validate_shape`, `validate_for`, `valid_identifier` | first two private; `[A-Za-z0-9_.-]`, ≤128 bytes | +| `:334` `:732` | `cargo_command`, `preflight` | `preflight` private | +| `:405` `:474` `:481` `:488` `:713` | `run_bounded_cancellable`, `run_qualification_process`, `run_qemu_process`, `run_bounded_inner`, `drain` | the middle two are `pub(crate)`; `run_bounded_inner` private and holds all enforcement | +| `:832` `:852` `:951` `:993` `:1006` | `execute_target`, `execute_target_cancellable`, `private_target_dir`, `safe_component`, `discover_candidate` | `safe_component` private | + +**Tests (`:1050-1734`):** explicit non-shell command and `sh` rejection (`:1080-1114`); zigbuild +glibc rewrite and macOS-floor rejection (`:1116-1157`) plus the byte-unchanged regression pin for +the triple rewrite and the macOS-under-zigbuild refusal (`:1159-1223`); binding duplicate and +unknown-field rejection (`:1225-1238`); exact direct-slot coverage (`:1240-1269`); candidate +regularity and non-emptiness (`:1271-1286`); relative and reused work roots rejected +(`:1415-1421`); bounded output, nonzero exit, and overflow classified `OutputLimitExceeded` +(`:1423-1489`); timeout and cancellation each killing and waiting for a real Cargo build +script over three iterations (`:1491-1619`), plus the parked-descendant and parked-reader +cases (`:1621-1676`); a real local Cargo fixture producing a direct candidate +(`:1678-1734`). ## Boundaries / non-goals @@ -228,17 +230,17 @@ iterations (`:1126-1244`); a real local Cargo fixture producing a direct candida not qualification; `qualification.rs` owns that) and **does not finalize** (no contract-named copying, archiving, manifest aggregation, or `release-manifest.json`). - **Does not touch the network directly** — but it also does not forbid the child from - reaching it. `cargo_command` passes `--locked`, not `--offline` (`:322-336`); the in-file - fixture test adds `--offline` explicitly (`:1147`), which production does not. + reaching it. `cargo_command` passes `--locked`, not `--offline` (`:348-356`); the in-file + fixture test adds `--offline` explicitly (`:1512`), which production does not. - **No shell and no generic command DSL.** Executable and argv are separate OS arguments, and the executable set is a closed per-allowance enumeration checked at spawn - (`:396-415`), per ADR-0004. A `CommandSpec` is a description, not an interpreter; there + (`:493-513`), per ADR-0004. A `CommandSpec` is a description, not an interpreter; there is no plugin or scripting seam. -- **No binding-coverage validation inside the build path.** `validate_for` (`:259`) is +- **No binding-coverage validation inside the build path.** `validate_for` (`:284`) is caller-invoked; `execute_target_cancellable` validates only plan membership, - `schema_version == 1`, and non-empty `release_id` / `source_revision` (`:706-714`). An + `schema_version == 1`, and non-empty `release_id` / `source_revision` (`:861-869`). An empty `bindings` slice therefore yields `Ok(BuildAttempt)` whose `process.outcome` is the - `Success` initializer (`:725-729`) with zero candidates. + `Success` initializer (`:880-884`) with zero candidates. - **No output evidence** (failures are not diagnosable from captured text, by design), no cross-tool provisioning (`preflight` requires declared versions to be present; it does not install them), and no archive encoding, extraction, publication, signing, or install. @@ -246,11 +248,12 @@ iterations (`:1126-1244`); a real local Cargo fixture producing a direct candida ## Dependencies / dependents - Own dependencies used here: `command-group 5.0.1` (`Cargo.toml:21`, process groups), `toml - 0.8` (`:20`, `from_toml` at `builder.rs233`), `serde` derive (`:17`), `eggpack-contract` - (`:15`, `DistributionContract` + `ExpandedAssets` at `builder.rs:5`), and `std` - process/thread/IO primitives. `sha2` is a **crate-level** dependency but is not used in - this file (it is used in `lib.rs`, `qualification.rs`, and `finalization.rs`). -- In-crate dependents: `qualification.rs:4-8` imports `run_qualification_process`, + 0.8` (`Cargo.toml:20`, `from_toml` at `builder.rs:246`), `serde` derive (`Cargo.toml:17`), + `eggpack-contract` (`Cargo.toml:15`, `DistributionContract` + `ExpandedAssets` at + `builder.rs:5`), and `std` process/thread/IO primitives. `sha2` is a **crate-level** + dependency but is not used in this file (it is used by the digest authority in + `src/digest.rs`). +- In-crate dependents: `qualification.rs:3-8` imports `run_qualification_process`, `run_qemu_process`, `CommandSpec`, `CandidateArtifact`, `BuildAttempt`, `BuildBindingsV1`, and `BuildCancellation`; `finalization.rs:4` imports `BuildAttempt`, `CandidateArtifact`, and `LogicalOutputSelector`. diff --git a/architecture/core-planning.md b/architecture/core-planning.md index 8df14b1..ccd9447 100644 --- a/architecture/core-planning.md +++ b/architecture/core-planning.md @@ -7,56 +7,63 @@ schema-v1 `ReleaseManifest` from explicitly supplied finalized files. It is one of four `eggpack-core` stage deep dives, alongside `core-build.md`, `core-qualification.md`, and `core-finalization.md`. -Crate root: `crates/eggpack-core/src/lib.rs`, 1056 lines, `#![forbid(unsafe_code)]` +Crate root: `crates/eggpack-core/src/lib.rs`, 1379 lines, `#![forbid(unsafe_code)]` (`:1`), `#![deny(missing_docs)]` (`:2`). The file is the crate root and declares -the three sibling stages, re-exported wholesale at `:5-10` -(`builder`, `finalization`, `qualification`). Lines 1–583 are non-test code; -`:585-1056` are unit tests. +the sibling stages, re-exported wholesale at `:10-14` +(`builder`, `digest`, `finalization`, `floor`, `qualification`). Lines 1–769 are +non-test code; `:771-1379` are unit tests. ## Inputs and outputs | Entry point | Inputs | Output | I/O | | --- | --- | --- | --- | -| `PackConfig::from_toml` (`:502`) | TOML string | `PackConfig` | none | -| `PackConfig::resolve` (`:526`) | `&PackConfig`, `&DistributionContract`, `release_id`, `source_revision`, `&[String]` selected | `ReleasePlan` | none | -| `ReleasePlan::to_json` (`:489`) | `&ReleasePlan` | compact JSON `String` | none | -| `build_manifest` (`:166`) | `&DistributionContract`, `&FinalizedReleaseInput` | `eggpack_manifest::ReleaseManifest` | reads supplied files | - -Planning is pure. The only filesystem access in this file is `digest_file` -(`:276`), called exclusively from `build_manifest`; it opens exactly the paths -the caller named in `FinalizedTargetInput`. `test_temp_dir` (`:31`) is +| `PackConfig::from_toml` (`:678`) | TOML string | `PackConfig` | none | +| `PackConfig::resolve` (`:709`) | `&PackConfig`, `&DistributionContract`, `release_id`, `source_revision`, `&[String]` selected | `ReleasePlan` | none | +| `ReleasePlan::to_json` (`:671`) | `&ReleasePlan` | compact JSON `String` | none | +| `build_manifest` (`:341`) | `&DistributionContract`, `&FinalizedReleaseInput` | `eggpack_manifest::ReleaseManifest` | reads supplied files | + +Planning is pure. The only filesystem access in this file is the crate's single +file-digest authority, `crate::file_digest` (`src/digest.rs:102-114`), called +exclusively from `build_manifest` (`:372-373`, `:419-420`); it opens exactly the +paths the caller named in `FinalizedTargetInput`. `test_temp_dir` (`:31`) is `#[cfg(test)]`-only. ## Policy vocabulary All policy types are `serde(rename_all = "snake_case")`; every input struct -carries `deny_unknown_fields` (`HostRequirement :369`, `ToolchainRequirement -:384`, `TargetPolicy :418`, `PackConfig :447`), and the two input documents are -additionally version-gated. Output-only types (`ReleasePlan :456`, -`PlannedTarget :468`) do not, since they are never parsed from untrusted input. +carries `deny_unknown_fields` (`HostRequirement :518`, `ToolchainRequirement +:533`, `TargetPolicy :567`, `PackConfig :596`), and the two input documents are +additionally version-gated. The two output types carry it as well +(`ReleasePlan :605`, `PlannedTarget :618`): `eggpack-ci` parses a plan back and +compares it with the canonical re-resolution, so an unknown field in a plan +document is refused rather than ignored. | Type | Variants / fields | Load-bearing meaning | | --- | --- | --- | -| `BuildStrategy` (`:308`) | `NativeCargo`, `CargoZigbuild` | Finite, explicit; planning never executes either (`:305`). Mutually exclusive cross-tool presence is enforced at `:126-141`. | -| `HostOs` (`:317`) | `Linux`, `Macos`, `Windows` | Build-host family. | -| `HostArch` (`:328`) | `X86_64`, `Aarch64`, `Armv7` | Build-host family; serialized as `x86_64` (`:328-334`). | -| `Qualification` (`:339`) | `Native`, `DeferredNative`, `Emulated`, `Structural` | Intent only, stored as intent (`:336`). Only `Native` triggers host matching (`:151`). Builder-independent by design: a `CargoZigbuild` candidate is admissible for `Native` (`:342-347`). | -| `SupportTier` (`:359`) | `Required`, `NonGating`, `Experimental` | Gating tier. Carried through planning; **not enforced anywhere in this file** (see Boundaries). | -| `HostRequirement` (`:370`) | `os`, `arch` | Provider-neutral host capability. | -| `ToolchainRequirement` (`:385`) | `rust: String`, `cargo_zigbuild: Option`, `zig: Option` | No version is inferred from the host (`:376`). `zig` is an additive optional field for schema-v1 back-compat (`:377-382`). | -| `CompatibilityFloor` (`:398`) | `None`, `Glibc{major,minor}`, `Macos{major,minor}` | Internally tagged `kind` (`:397`). A build-policy input, not a proof (`:433-439`). | -| `TargetPolicy` (`:419`) | target, strategy, host_os, host_arch, `qualification_host`, toolchain, floor, qualification, support | One target's full producer policy. | -| `PackConfig` (`:448`) | `schema_version: u32`, `targets: Vec` | Strict v1 document. | -| `ReleasePlan` (`:456`) | `schema_version`, `release_id`, `source_revision`, `targets: Vec` | Intent, canonically ordered. Not evidence. | -| `PlannedTarget` (`:468`) | `target`, `policy: TargetPolicy`, `artifact_form: PlannedAssetForm` | Canonical triple + resolved policy + contract-derived form. | -| `PlannedAssetForm` (`:479`) | `Direct`, `Bundle`, `Archive` | Mirrors `eggpack_contract::AssetForm` (`:561-565`) but carries no names — identity is re-derived from the contract at build/manifest time. | -| `CoreError` (`:74`) | newtype over `String` | Opaque by design: paths and file contents are intentionally omitted (`:72`). Every failure funnels through `err()` (`:81`). | +| `BuildStrategy` (`:456`) | `NativeCargo`, `CargoZigbuild` | Finite, explicit; planning never executes either (`:453`). Mutually exclusive cross-tool presence is enforced at `:231-246`. | +| `HostOs` (`:465`) | `Linux`, `Macos`, `Windows` | Build-host family. | +| `HostArch` (`:476`) | `X86_64`, `Aarch64`, `Armv7` | Build-host family; serialized as `x86_64` (`:476-486`). | +| `Qualification` (`:487`) | `Native`, `DeferredNative`, `Emulated`, `Structural` | Intent only, stored as intent (`:488`). Only `Native` triggers host matching (`:260-270`). Builder-independent by design: a `CargoZigbuild` candidate is admissible for `Native` (`:489-496`). | +| `SupportTier` (`:507`) | `Required`, `NonGating`, `Experimental` | Gating tier. Carried through planning; **not enforced anywhere in this file** (see Boundaries). | +| `HostRequirement` (`:518`) | `os`, `arch` | Provider-neutral host capability. | +| `ToolchainRequirement` (`:533`) | `rust: String`, `cargo_zigbuild: Option`, `zig: Option` | No version is inferred from the host (`:524`). `zig` is an additive optional field for schema-v1 back-compat (`:526-530`). | +| `CompatibilityFloor` (`:546`) | `None`, `Glibc{major,minor}`, `Macos{major,minor}` | Internally tagged `kind` (`:545`). A build-policy input, not a proof (`:581-587`). | +| `TargetPolicy` (`:567`) | target, strategy, host_os, host_arch, `qualification_host`, toolchain, floor, qualification, support | One target's full producer policy. | +| `PackConfig` (`:596`) | `schema_version: u32`, `targets: Vec` | Strict v1 document. | +| `ReleasePlan` (`:605`) | `schema_version`, `release_id`, `source_revision`, `targets: Vec` | Intent, canonically ordered. Not evidence. | +| `PlannedTarget` (`:618`) | `target`, `policy: TargetPolicy`, `artifact_form: PlannedAssetForm`, `floor_status: FloorVerificationStatus` | Canonical triple + resolved policy + contract-derived form + the declared floor's plan-time status (`:625-633`). | +| `PlannedAssetForm` (`:638`) | `Direct`, `Bundle`, `Archive` | Mirrors `eggpack_contract::AssetForm` (`:746-750`) but carries no names — identity is re-derived from the contract at build/manifest time. | +| `CoreError` (`:74`) | newtype over `String` | Opaque by design: paths and file contents are intentionally omitted (`:72`). Every failure funnels through `err()` (`:81-83`). | | `FinalizedTargetInput` (`:48`) | `target`, `release_files`, `archive_members` | Explicit per-target filename → local path maps. | | `FinalizedReleaseInput` (`:59`) | `product_id`, `release_id`, `source_revision`, `targets`, `evidence_references` | Caller-supplied release identity and inventory. | `ReleasePlan` is deliberately a lossless projection: `PlannedTarget.policy` -retains the whole `TargetPolicy` (`:472`), so a plan can be re-serialized and -re-resolved without consulting the original config. +retains the whole `TargetPolicy` (`:622`), so a plan can be re-serialized and +re-resolved without consulting the original config. The added +`PlannedTarget.floor_status` (`:625-633`) is the one field that is *derived* +rather than retained: it is a pure function of the retained policy +(`planned_floor_status`, `src/floor.rs:105-132`), so it cannot be chosen by a +caller and cannot disagree with the declaration it summarises. Release identity mapping is owned by `eggpack-ci`, not by `PackConfig` or `ReleasePlan`. The default mode passes the exact tag as `release_id`. A checked-in @@ -68,133 +75,155 @@ change. ## `PackConfig` -> `ReleasePlan` -`from_toml` (`:502-524`) is the **weak** gate: `toml::from_str` under +`from_toml` (`:678-707`) is the **weak** gate: `toml::from_str` under `deny_unknown_fields`, then `schema_version == 1`, non-empty `targets` -(`:504-506`), and a per-target scan rejecting empty targets, duplicate -`target` strings, empty/over-64-byte `rust`, and the -`CargoZigbuild` ⇔ `cargo_zigbuild.is_some()` coupling (`:513-522`). +(`:680-682`), a bounded target count (`:687-689`), and a per-target scan +rejecting empty targets, duplicate `target` strings, empty/over-64-byte `rust`, +and the `CargoZigbuild` ⇔ `cargo_zigbuild.is_some()` coupling (`:697-706`). -`validate_policy` (`:105-163`) is the **strict** gate, and runs only inside -`resolve` (`:541`) — not in `from_toml`. A parsed-but-unresolved config can +`validate_policy` (`:208-272`) is the **strict** gate, and runs only inside +`resolve` (`:724`) — not in `from_toml`. A parsed-but-unresolved config can therefore still carry an invalid policy. The leniency is intentional and commented: the additive `zig` field's presence rules are deferred to resolution, "which fails closed rather than selecting an ambient Zig" -(`:508-512`). +(`:691-696`). -`resolve` (`:526-582`) runs in four ordered steps: +`resolve` (`:709-769`) runs in four ordered steps: -1. **Version gate.** `schema_version != 1` → error (`:533-535`). The +1. **Version gate.** `schema_version != 1` → error (`:717-719`). The *contract's* own schema version is not re-checked here; it is guaranteed by contract parsing. 2. **Policy ingest and validation.** Every declared policy is resolved through - `contract.resolve` (exact-match triple or alias, `:538-540`), validated, - and keyed by **canonical** triple into a `BTreeMap` (`:536, :542`). Two + `contract.resolve` (exact-match triple or alias, `:721-723`), validated, + and keyed by **canonical** triple into a `BTreeMap` (`:719`, `:725`). Two distinct aliases collapsing to one triple is rejected as - "duplicate canonical policy target" (`:542-544`). Note this iterates *all* + "duplicate canonical policy target" (`:725-727`). Note this iterates *all* declared policies, not just selected ones: a bad policy on an unselected target still fails resolution. 3. **Selection and coverage.** Each `selected` entry resolves through the - contract (`:549-551`); duplicates are rejected (`:552-554`), and every + contract (`:732-734`); duplicates are rejected (`:735-737`), and every selected target must have a resolved policy or the call fails with - "selected target has no policy" (`:555-559`). `policy.target` is - **rewritten to the canonical triple** (`:560`), and `artifact_form` is - derived solely from the contract's `AssetForm` (`:561-565`). Empty selection - is an error (`:572-574`). + "selected target has no policy" (`:738-742`). `policy.target` is + **rewritten to the canonical triple** (`:743`), and `artifact_form` is + derived solely from the contract's `AssetForm` (`:744-748`). The floor status + is derived from the resolved policy (`:749`). Empty selection is an error + (`:757-759`). 4. **Canonical sort and assembly.** `targets.sort_by(|a, b| a.target.cmp(&b.target))` - (`:575`) — byte-order `Ord` over canonical triples, which is what makes the + (`:760`) — byte-order `Ord` over canonical triples, which is what makes the plan deterministic regardless of `selected` order or policy declaration order. - The `BTreeMap` at `:536` gives the same ordering guarantee on the policy side. + The `BTreeMap` at `:719` gives the same ordering guarantee on the policy side. -`to_json` (`:489-498`) re-checks `schema_version == 1`, non-empty -`release_id`/`source_revision`, and non-empty `targets` (`:490-496`) before -emitting compact `serde_json`. Those two string bounds are *only* enforced here; -`resolve` itself does not reject empty identity strings (`:576-581`). +`to_json` (`:671-674`) first runs `ReleasePlan::validate` (`:653-669`), which +re-checks `schema_version == 1`, non-empty `release_id`/`source_revision`, and +non-empty `targets` (`:654-660`), and which also requires every target's +`floor_status` to equal the status its policy implies (`:661-667`). Those two +string bounds are *only* enforced here; `resolve` itself does not reject empty +identity strings (`:761-766`). ## `validate_policy` and native qualification host matching -`validate_policy` (`:105-163`) enforces, in order: +`validate_policy` (`:208-272`) enforces, in order: -- **Toolchain bounds** (`:106-125`): `rust` non-empty, ≤64 bytes, alphanumeric +- **Toolchain bounds** (`:209-230`): `rust` non-empty, ≤64 bytes, alphanumeric or `.-+_`; optional `cargo_zigbuild` and `zig` additionally pass - `valid_tool_version` (`:97-103`) — a **complete `MAJOR.MINOR.PATCH`**, with an + `valid_tool_version` (`:112-127`) — a **complete `MAJOR.MINOR.PATCH`**, with an optional SemVer pre-release/build suffix. A partial pin is rejected: `0` and `0.14` would satisfy the preflight comparison against almost any reported version, leaving a declared requirement effectively unset while every check still reported success. Failure message is the single shared "toolchain requirement is empty, overlong, or not a complete version". -- **Strategy/tool coupling** (`:126-141`): `NativeCargo` must declare neither +- **Strategy/tool coupling** (`:231-246`): `NativeCargo` must declare neither cross-tool field; `CargoZigbuild` must declare **both**. Fails closed — there is no ambient-tool fallback. -- **Floor/target coherence** (`:142-150`): `Glibc` requires `-linux-gnu` in the - triple; `Macos` requires the `-apple-darwin` suffix. -- **Native host matching** (`:151-161`). +- **Floor/target coherence** (`:247-259`): `Glibc` requires `-linux-gnu` in the + triple; `Macos` requires the `-apple-darwin` suffix. This is the *triple* half + of the canonical floor rule (`floor_applies_to_triple`, `:144-165`); the + *strategy* half (`floor_applies_to_strategy`, `:166-187`) is enforced later, + at build-command time in `cargo_command`, not here. +- **Native host matching** (`:260-270`). For `Qualification::Native`, the effective host is `policy.qualification_host` if present, else synthesized from `host_os` + -`host_arch` (`:152-155`). `host_matches_target` (`:84-96`) then requires **both** +`host_arch` (`:261-264`). `host_matches_target` (`:92-111`) then requires **both** dimensions to agree, using prefix/substring matching rather than a full triple parse: | Host dimension | Test on the triple | | --- | --- | -| `X86_64` / `Aarch64` / `Armv7` | `starts_with("x86_64-")` / `"aarch64-"` / `"armv7-"` (`:86-88`) | -| `Linux` / `Macos` / `Windows` | `contains("-linux-")` / `ends_with("-apple-darwin")` / `contains("-windows-")` (`:91-93`) | +| `X86_64` / `Aarch64` / `Armv7` | `starts_with("x86_64-")` / `"aarch64-"` / `"armv7-"` (`:93-97`) | +| `Linux` / `Macos` / `Windows` | `contains("-linux-")` / `ends_with("-apple-darwin")` / `contains("-windows-")` (`:98-102`) | -A mismatch returns a `CoreError` (`:157-160`), so a `Native` policy that +A mismatch returns a `CoreError` (`:265-269`), so a `Native` policy that cannot be host-matched can never reach a plan at all — planning fails closed before any build or qualification begins. The `HostMismatch` **record** is not produced here. It is -`QualificationFailure::HostMismatch` (`qualification.rs:216`), emitted as +`QualificationFailure::HostMismatch` (`qualification.rs:210-236`), emitted as `QualificationStatus::Failed(QualificationFailure::HostMismatch)` for native, -deferred-native, and emulated paths (`qualification.rs:694`, `:725`, `:760`). +deferred-native, and emulated paths (`qualification.rs:736-746`, `:768-781`, +`:806-816`). A non-matching host is a failed record — never a pass, never a skip, and never -an executed smoke (asserted at `qualification.rs1845-1870`). See +an executed smoke (asserted at `qualification.rs:2013-2053`). See `core-qualification.md`. **A native run does not prove a declared deployment floor.** `floor` is a build-policy input carried into the cross-tool build command; the doc comment -states the boundary directly (`:433-439`): native evidence proves that the +states the boundary directly (`:581-587`): native evidence proves that the exact candidate executes on the qualifying host, "it is not independent proof that the produced binary honours this declared minimum runtime." `validate_policy` -checks only that the floor is *coherent with the triple* (`:142-150`) — never +checks only that the floor is *coherent with the triple* (`:247-259`) — never that the binary meets it. +**Planning records the floor; it never verifies it.** The plan carries the +declared floor (`TargetPolicy::floor`) and the status that declaration implies +(`PlannedTarget.floor_status`, `:625-633`). `planned_floor_status` +(`src/floor.rs:105-131`) is a pure function of the policy: +`CompatibilityFloor::None` → `NotDeclared`; a glibc floor under +`CargoZigbuild` → `ToolchainBound` (the floor is bound into the toolchain by +the triple rewrite); a glibc floor under `NativeCargo` → +`Unverified(PendingInspection)` (the bytes have not been inspected yet); a +macOS floor → `Unverified(FloorKindNotVerifiable)` (Mach-O deployment-target +verification is a named follow-on). The byte-level verification itself is +never done here — it belongs to qualification, and it is recorded on the +evidence (`core-qualification.md`). + ## `build_manifest` -`build_manifest` (`:166-274`) converts caller-supplied finalized files into an +`build_manifest` (`:341-451`) converts caller-supplied finalized files into an `eggpack_manifest::ReleaseManifest`. It is the only place this file touches the filesystem or hashes bytes. -1. **Identity and bounds** (`:170-175`): `contract.product.id` must equal +1. **Identity and bounds** (`:345-350`): `contract.product.id` must equal `input.product_id`; target count must be 1–256. -2. **Per target** (`:178-261`): expand via `contract.expand(target, release_id)` - (`:179-181`), rejecting duplicate canonical triples (`:182-184`). -3. **Exact inventory** (`:185-191`): derives the expected file set with +2. **Per target** (`:353-438`): expand via `contract.expand(target, release_id)` + (`:354-356`), rejecting duplicate canonical triples (`:357-359`). +3. **Exact inventory** (`:360-366`): derives the expected file set with `expected_release_files`, builds a `ReleaseInventory` from the caller's keys, and requires `validate_release_inventory(&expected, &inventory, ExtrasPolicy::Exact).is_conformant()`. This is **stricter than the contract's default** `AllowExtras` — a missing sidecar and an unexpected extra file are both fatal. -4. **Form-specific records** (`:204-256`): `Direct` and `Bundle` reject any - `archive_members` input (`:206-208`, `:215-217`). `Archive` requires - `archive_members.len() == members.len()` (`:232-234`) and then looks each +4. **Form-specific records** (`:380-433`): `Direct` and `Bundle` reject any + `archive_members` input (`:382-384`, `:391-393`). `Archive` requires + `archive_members.len() == members.len()` (`:408-410`) and then looks each member up by `source`. Note this is a length check plus per-source lookup, **not** `validate_archive_member_inventory`, so a same-length map with wrong keys fails as "required archive member path missing" rather than as a conformance report. -5. **Evidence and self-check** (`:257-273`): assembles `TargetRecord`s in caller +5. **Evidence and self-check** (`:434-450`): assembles `TargetRecord`s in caller order, builds the manifest with `schema_version: 1`, and finishes with - `manifest.validate()` (`:270-272`) so the constructed document must satisfy + `manifest.validate()` (`:447-449`) so the constructed document must satisfy `eggpack-manifest` bounds — `evidence_references` and `source_revision` are bounded there, not here. -`digest_file` (`:276-303`) is the sole byte reader: it resolves the path with -`symlink_metadata` and requires a regular non-symlink file (`:277-280`), streams -through a 64 KiB buffer, accumulates size with `checked_add` (`:293-295`), -rejects zero-length files (`:298-300`), and emits lowercase hex SHA-256 -(`:302`). SHA-256 plus size are **integrity facts only** — no signature or -provenance claim is made or implied. +`crate::file_digest` (`src/digest.rs:102-114`) is the sole byte reader: it +resolves the path with `symlink_metadata` and requires a regular non-symlink +file, rejects an empty file before reading it, streams through a fixed 64 KiB +buffer (`src/digest.rs:20-24`), accumulates size with overflow checking +(`src/digest.rs:138-141`), and re-inspects the path after the read so a path +that changed length or type is refused (`src/digest.rs:143-155`). SHA-256 plus +size are **integrity facts only** — no signature or provenance claim is made or +implied. ## Boundaries / non-goals @@ -202,19 +231,20 @@ provenance claim is made or implied. `ReleaseManifest` is the only final-bytes evidence. `PlannedAssetForm` carries no filenames, so a plan cannot stand in for a manifest. - **Never executes a strategy.** `BuildStrategy` is a value, not a switch - (`:305`). + (`:453`). - **`SupportTier` is inert here.** `resolve` does not require that every `Required` target be selected, and no tier comparison exists in this file. Selection coverage is caller-driven. - **No ambient inference.** Toolchain versions are never read from the host, and no tool lookup, version probe, or fallback happens at planning. -- **No floor verification** beyond triple coherence (see above). +- **No floor verification.** Planning records the declared floor and the status it + implies; the byte-level verification is qualification's job (see above). - **No ordering, publishing, or network.** No semver comparison, no process execution, no HTTP, no archive extraction. Archive/tar handling lives in `finalization`, not here. - **Errors are opaque.** `CoreError` carries a fixed message string; no path, filename, or file content is ever placed in an error (`:72`). -- `digest_file` rejects symlinks and empty files; it does **not** verify that a +- `file_digest` rejects symlinks and empty files; it does **not** verify that a file sits inside a finalized output root — that containment is `finalization`'s invariant. @@ -224,11 +254,11 @@ Own dependencies (`crates/eggpack-core/Cargo.toml:14-23`): | Crate | Used here for | | --- | --- | -| `eggpack-contract` | `DistributionContract::{resolve, expand}`, `AssetForm`, `ExpandedAssets`, `expected_release_files`, `validate_release_inventory`, `ExtrasPolicy`, `ReleaseInventory` (`:12-15`) | -| `eggpack-manifest` | `ReleaseManifest`, `TargetRecord`, `ArtifactForm`, `ArtifactRecord`, `BundleRecord`, `ArchiveMemberRecord`, `ByteEvidence` (`:16-19`) | -| `serde` / `serde_json` | derive + strict `deny_unknown_fields`; compact plan JSON (`:20`, `:497`) | -| `sha2` | `Sha256` streaming digest (`:21`, `:283`) | -| `toml` | `PackConfig::from_toml` (`:503`) | +| `eggpack-contract` | `DistributionContract::{resolve, expand}`, `AssetForm`, `ExpandedAssets`, `expected_release_files`, `validate_release_inventory`, `ExtrasPolicy`, `ReleaseInventory` (`Cargo.toml:15`) | +| `eggpack-manifest` | `ReleaseManifest`, `TargetRecord`, `ArtifactForm`, `ArtifactRecord`, `BundleRecord`, `ArchiveMemberRecord`, `ByteEvidence`, `validate_sha256_hex` (`Cargo.toml:16`) | +| `serde` / `serde_json` | derive + strict `deny_unknown_fields`; compact plan JSON (`Cargo.toml:17-18`, `:671-674`) | +| `sha2` | `Sha256` streaming digest, used only by the digest authority (`Cargo.toml:19`, `src/digest.rs`) | +| `toml` | `PackConfig::from_toml` (`Cargo.toml:20`, `:678`) | `command-group`, `tar`, and `flate2` (`Cargo.toml:21-23`) are declared for the sibling `finalization` stage, not for this file. diff --git a/architecture/core-qualification.md b/architecture/core-qualification.md index 4d076f7..6318370 100644 --- a/architecture/core-qualification.md +++ b/architecture/core-qualification.md @@ -2,228 +2,297 @@ Binds one fixed-argument smoke check per target, structurally inspects each candidate's exact bytes, runs a bounded execution on a host-matched or emulated -runtime, and records `QualificationEvidence` about those bytes. 2610 lines -(`src/qualification.rs`; `:1243-2610` is the inline test module). This is one of +runtime, and records `QualificationEvidence` about those bytes. 2981 lines +(`src/qualification.rs`; `:1316-2981` is the inline test module). This is one of four `eggpack-core` stage deep dives; `core.md` holds the crate-level orientation. ## Inputs and outputs -**Input** — `QualificationRequest<'a>` (`:477-494`) is all-or-nothing: a +**Input** — `QualificationRequest<'a>` (`:496-515`) is all-or-nothing: a `DistributionContract`, the invocation `ReleasePlan`, exactly one `PlannedTarget`, a successful `BuildAttempt`, `BuildBindingsV1`, `QualificationBindingsV1`, a `QualificationRuntime`, and a `BuildCancellation`. There is no partial or defaulted input and no output-directory parameter. -**Output** — `Result` (`:497-522`). +**Output** — `Result` (`:516-543`). The error variant means *the request was malformed*; it never means *the candidate was bad*. A structurally wrong candidate, a non-matching host, a -failed smoke, and a mid-run mutation all return `Ok` with a typed -`QualificationStatus::Failed` record (`:654-663`, `:689-698`, `:800-810`, -`:873-887`, `:910-913`). Failures are evidence; only refused work is an error. +failed smoke, a contradicted floor, and a mid-run mutation all return `Ok` with +a typed `QualificationStatus::Failed` record (`:677-687`, `:708-725`, +`:736-746`, `:932-946`, `:955-978`). Failures are evidence; only refused work is +an error. -**Rejected before any inspection** (`:574-641`), in order: plan/attempt identity +**Rejected before any inspection** (`:593-660`), in order: plan/attempt identity — schema version, non-empty `release_id`/`source_revision`, target membership, matching `release_id`/`source_revision`/`target`/`strategy`, a `Success` build -process, and 1..=256 candidates (`:574-589`); then `BuildBindingsV1::validate_for` -(`:590-592`) and `QualificationBindingsV1::validate_for` (`:593`), both re-run -internally rather than trusted from the caller; then the runtime (`:594`, `:982-994`); -then the QEMU-sysroot-requires-`Emulated` rule (`:595-599`); then an exact +process, and 1..=256 candidates (`:593-604`); then `BuildBindingsV1::validate_for` +(`:609-611`) and `QualificationBindingsV1::validate_for` (`:612`), both re-run +internally rather than trusted from the caller; then the runtime (`:613`, `:1047-1060`); +then the QEMU-sysroot-requires-`Emulated` rule (`:614-618`); then an exact selector/package/binary reconciliation of the attempt's candidates against the -build bindings (`:601-641`). +build bindings (`:620-660`). **Never in the evidence**: candidate paths, output contents, environment values. Only the canonicalized working directory and the absolute candidate path reach -the child process (`:790`, `:849`, `:861`); `:1724-1725` asserts the serialized -evidence contains no candidate path. +the child process (`:840-850`, `:901-913`, `:916-926`); `:1797-1798` asserts the +serialized evidence contains no candidate path. **Module bounds** (`:22-26`): 256 targets, 128 args, 4096 bytes per arg, 256 KiB retained capture, 4096-byte binary-header window. `schema_version` is exactly 1 -on both `QualificationBindingsV1` (`:138`) and `QualificationEvidence` (`:325`, -`:941`). +on both `QualificationBindingsV1` (`:138`) and `QualificationEvidence` (`:295`, +`:337`). ## The method taxonomy -Requested classification is `Qualification` (intent, `src/lib.rs:336-355`); -the method actually applied is `QualificationMethod` (`:180-193`). The pairing +Requested classification is `Qualification` (intent, `src/lib.rs:487-506`); +the method actually applied is `QualificationMethod` (`:182-197`). The pairing is closed — one classification admits exactly two or one methods, and any other -combination is rejected by `validate_for` (`:383-393`). +combination is rejected by `validate_for` (`:402-413`). -| Requested | Method (`:182-193`) | Executes | Proves | Does **not** prove | +| Requested | Method (`:182-197`) | Executes | Proves | Does **not** prove | |---|---|---|---|---| -| `Native` | `Native` | yes, direct | the exact pre-hashed bytes ran on a host whose OS/arch match the target triple, exited 0 under the fixed argv, and were byte-identical afterwards (`:683-701`, `:857-869`, `:896-916`) | that any other host runs it; that a declared floor is honoured | -| `DeferredNative` | `Deferred` | no | only that the bytes are structurally valid for the target, and that the required host has not yet run them (`:702-718`) | any execution — `Deferred` can never be `Passed` (`:400-401`, `:465`) | -| `DeferredNative` | `DeferredNativeOnNativeHost` | yes, direct | the same as `Native`, on the separately declared `qualification_host` (`:719-731`) | anything about the deferred hosts that were skipped | -| `Emulated` | `QemuUser` | yes, under QEMU | the target is `-linux-`, every candidate is ELF, the finite `qemu-*` mapping answers `--version`, and the bytes ran under it to a zero exit (`:733-767`, `:784-869`) | native execution on the target; performance; fidelity outside the emulated user-mode surface | -| `Structural` | `Structural` | never | file shape and header identity only: non-symlink regular file under a canonical root, size equal to the `BuildAttempt`, ELF/PE/thin-Mach-O header agreeing with the target's format and architecture, plus a SHA-256 (`:682`, `:769-780`, `:1087-1173`) | that the candidate runs anywhere | +| `Native` | `Native` | yes, direct | the exact pre-hashed bytes ran on a host whose OS/arch match the target triple, exited 0 under the fixed argv, and were byte-identical afterwards (`:730-749`, `:916-926`, `:955-978`) | that any other host runs it; that a declared floor is honoured | +| `DeferredNative` | `Deferred` | no | only that the bytes are structurally valid for the target, and that the required host has not yet run them (`:750-767`) | any execution — `Deferred` can never be `Passed` (`:419-420`) | +| `DeferredNative` | `DeferredNativeOnNativeHost` | yes, direct | the same as `Native`, on the separately declared `qualification_host` (`:768-781`) | anything about the deferred hosts that were skipped | +| `Emulated` | `QemuUser` | yes, under QEMU | the target is `-linux-`, every candidate is ELF, the finite `qemu-*` mapping answers `--version`, and the bytes ran under it to a zero exit (`:783-819`, `:837-886`) | native execution on the target; performance; fidelity outside the emulated user-mode surface | +| `Structural` | `Structural` | never | file shape and header identity only: non-symlink regular file under a canonical root, size equal to the `BuildAttempt`, ELF/PE/thin-Mach-O header agreeing with the target's format and architecture, plus a SHA-256 (`:729`, `:821-833`, `:1162-1246`) | that the candidate runs anywhere | **Structural inspection is not executed evidence.** `Structural` records zero processes and no `smoke_selector`, and that emptiness is a validated invariant -rather than an accident (`:402-403`, `:464`). A `Structural` pass is a statement +rather than an accident (`:421-422`). A `Structural` pass is a statement about bytes on disk; the three executing methods additionally carry `QualificationProcessEvidence` — and a `Passed` record must carry exactly the -right number of them (`:459-466`): 1 for native, 2 for QEMU (preflight plus +right number of them (`:478-485`): 1 for native, 2 for QEMU (preflight plus smoke), 0 for structural, never for deferred. The QEMU mapping is a closed table, not a template: `-linux-` targets only, `x86_64` → `qemu-x86_64`, `aarch64` → `qemu-aarch64`, `armv7` → `qemu-arm` -(`:1036-1046`), and the argv is built solely from the optional declared sysroot, -the candidate path, and the binding's fixed argv (`:1048-1060`, asserted at -`:2080-2088`). The optional sysroot must be an absolute, non-symlink directory -(`:982-994`). +(`:1101-1112`), and the argv is built solely from the optional declared sysroot, +the candidate path, and the binding's fixed argv (`:1113-1126`, asserted at +`:2154-2162` and `:2278-2286`). The optional sysroot must be an absolute, non-symlink directory +(`:1047-1060`). ## Host matching: native qualification is builder-independent `Qualification::Native` is host-matched proof about the exact candidate bytes, and it is **independent of which builder produced them**. The `Native` branch -(`:683-701`) matches on the host and the target triple only; the single +(`:730-749`) matches on the host and the target triple only; the single `strategy` reference in the module's production code is the identity check -`attempt.strategy != target.policy.strategy` (`:581`). There is no strategy +`attempt.strategy != target.policy.strategy` (`:600`). There is no strategy term in the method selection, so a `CargoZigbuild`-built candidate reaching this host is a legitimate `QualificationMethod::Native` record. `Qualification::Native`'s own rustdoc states the same -(`src/lib.rs:340-348`), and `cross_tool_built_candidate_qualifies_natively_on_the_matching_host` -(`:1770-1889`) proves it end to end, including through the public +(`src/lib.rs:489-496`), and `cross_tool_built_candidate_qualifies_natively_on_the_matching_host` +(`:1846-1965`) proves it end to end, including through the public `qualify_target` entry point. The rule, precisely: 1. The effective qualification host is `policy.qualification_host`, else the - build host `{policy.host_os, policy.host_arch}` (`:684-687`). + build host `{policy.host_os, policy.host_arch}` (`:731-734`). 2. Both conditions must hold: `host == required` **and** - `target_matches_host(&target.target, host)` (`:688`). - `target_matches_host` (`:1022-1034`) is a pure triple↔host mapping — OS by + `target_matches_host(&target.target, host)` (`:735`). + `target_matches_host` (`:1087-1100`) is a pure triple↔host mapping — OS by triple substring/suffix (`-linux-`, `-apple-darwin`, `-windows-`), arch by triple prefix (`x86_64-`, `aarch64-`, `armv7-`). 3. On failure the function returns `Ok` with `Failed(QualificationFailure::HostMismatch)`, method still `Native`, and - `processes: Vec::new()` (`:689-698`). **Never a pass, never a skip, never an + `processes: Vec::new()` (`:736-746`). **Never a pass, never a skip, never an executed smoke.** The failed record is itself valid evidence - (`:1863-1871`). + (`:2047-2052`). The same rule is re-enforced in reverse by `QualificationEvidence::validate_for`, so a hand-edited or forged pass record cannot survive: a pass on a native method -requires `target_matches_host` (`:410-415`) and requires any declared +requires `target_matches_host` (`:429-434`) and requires any declared `qualification_host` to equal the observed `actual_host` for all three executing -classifications (`:416-433`). `Deferred` is asymmetric by design and is -constrained the other way (`:394-399`): method `Deferred`, no processes, a +classifications (`:435-452`). `Deferred` is asymmetric by design and is +constrained the other way (`:414-418`): method `Deferred`, no processes, a declared `qualification_host` present, and it must *differ* from the actual host. The test `native_host_mismatch_is_a_failure_and_never_runs_smoke` -(`:1937-1978`) and the off-host/`Deferred` cases at `:1575-1613` and -`:1980-2056` cover both directions. +(`:2013-2053`) and the off-host/`Deferred` cases at `:1649-1708` and +`:2056-2164` cover both directions. -Observed host facts come from `actual_host()` (`:1005-1020`), which maps only +Observed host facts come from `actual_host()` (`:1070-1086`), which maps only `std::env::consts::OS`/`ARCH` for linux/macos/windows and x86_64/aarch64/ arm-v7, and returns an error for anything else. `qualify_target_for_host` -(`:525-556`) and `qualify_target_for_host_with_runner` (`:559-927`) exist so a +(`:544-577`) and `qualify_target_for_host_with_runner` (`:578-990`) exist so a host and a process runner can be injected deterministically in tests; the public `qualify_target` is a thin wrapper that supplies the real host. ## What native qualification does not prove A successful native run proves the exact candidate bytes execute on *this* -host's operating system and architecture. It is **not** independent proof that -the produced binary honours a declared `CompatibilityFloor` — a glibc or macOS -deployment floor. This is a documented, deliberate limitation: - -- `TargetPolicy::floor` is never read anywhere in this module. The only - occurrences are test fixtures (`:1753-1760`, `:2536`, `:2583`). Qualification - neither inspects GLIBC symbol versions nor any Mach-O load-command minimum - version. +host's operating system and architecture. It is **not** proof that the produced +binary honours a declared `CompatibilityFloor` — a glibc or macOS deployment +floor. The floor is never established by a smoke run: + +- The smoke's only observations are the exit status and the bounded output + capture (`:900-928`). Nothing in the execution path reads the floor. - The floor's own rustdoc says so: "Native qualification evidence proves that the exact candidate executes on the qualifying native host; it is not independent proof that the produced binary honours this declared minimum - runtime" (`src/lib.rs:433-439`). -- The accepted decision is recorded in - `plans/closure/build-qualification/006-status.md` (ADR-0005, Option A), which - lists independent GLIBC-symbol-floor verification as explicitly not attempted - and carried as residual risk. + runtime" (`src/lib.rs:581-587`). + +What *does* establish a floor is the separate, byte-level floor inspection +described below. It never infers a floor from execution. The other residual: `target_matches_host` compares OS family and CPU architecture only. It does not distinguish a Linux distribution or glibc version, so two hosts on the same triple are treated as interchangeable capabilities. This follows from `HostRequirement` carrying exactly -`{os, arch}` (`src/lib.rs:367-375`). +`{os, arch}` (`src/lib.rs:518-532`). + +## Compatibility floor verification status + +The floor status is the producer's record of *what was actually done* with a +declared floor. It is a finite, closed enum — `FloorVerificationStatus` +(`src/floor.rs:72-89`) — and it is **not** a free-form string and **not** an +`Option`. It is recorded in two places: + +- on the plan, as `PlannedTarget::floor_status` (`src/lib.rs:618-637`), so the + declared floor and its status are visible in the producer's intent artifact; +- on the evidence, as `QualificationEvidence::floor` (`:293-328`), so the + status is bound to the exact bytes of that one candidate. + +| Status | Concrete observation | +|---|---| +| `NotDeclared` | the target declares `CompatibilityFloor::None` | +| `ToolchainBound` | the floor was bound into the build toolchain by the cargo-zigbuild triple rewrite, and the toolchain is trusted to honour it | +| `Verified` | the produced bytes were independently inspected and their highest required `GLIBC_x.y` version is not newer than the declared floor | +| `Unverified(reason)` | a floor was declared and the bytes did not confirm it, for the bounded reason given | +| `NotSatisfied` | the produced bytes were independently inspected and require a newer runtime than the declared floor | + +`Unverified` carries a closed reason enum, `FloorUnverifiedReason` +(`src/floor.rs:30-71`): `PendingInspection`, `UnreadableCandidate`, +`MalformedCandidate`, `NoVersionRequirement`, `UnrecognizedVersionRequirement`, +`FloorKindNotVerifiable`. + +**The comparison direction is the point.** A candidate satisfies a declared +floor only when `required <= declared`: a binary that requires a *newer* glibc +than the floor declares does not satisfy it. `GLIBC_2.34` against a declared +`2.17` floor is `NotSatisfied`, not `Verified`. + +**The status is computed from bytes, never from execution.** The inspection +runs inside `inspect_candidate` (`:1162-1246`), on the same canonical path +whose bytes the crate's single file-digest authority then digests +(`:1211-1232`), so the recorded status describes the bytes the record +describes. The reader itself lives in `src/floor.rs`: the ELF header +(`:285-333`), the bounded program-header table (`:334-390`), the bounded +dynamic table (`:391-434`), the virtual-address mapping (`:435-451`), the +bounded version-name read (`:452-480`), and the version parse (`:481-508`). +Every table and every offset is bounded; an over-large program-header or +dynamic-entry count is refused rather than parsed. + +**Failure semantics.** A floor that is declared and *contradicted* by the bytes +is false, so it is a hard failure of the qualification for that target: +`Failed(QualificationFailure::FloorNotSatisfied)` with the floor status +`NotSatisfied` (`:705-725`). It is never reported as `Unverified`, and it is +detected before anything executes. A floor that is declared and merely +*unverifiable* — an unreadable, malformed, truncated, or non-ELF candidate, or +a candidate with no `GLIBC_` version requirement — is a recorded status, not a +failed release: the qualification still passes and the reason says exactly why +the floor was not confirmed. + +**Cross-checks.** A plan that declares a floor and does not state a status for +it is invalid: the status is a pure function of the policy +(`planned_floor_status`, `src/floor.rs:105-132`), so a document that omits it +is read as `NotDeclared` and then refused (`ReleasePlan::validate`, +`src/lib.rs:646-675`). An evidence record whose floor status contradicts the +plan's declared floor is likewise refused (`:350-360`): the status must be +admissible for the declared floor and strategy +(`floor_status_admissible`, `src/floor.rs:133-155`), and a `NotSatisfied` +status is admissible only together with the matching failure. + +**Scope.** A macOS deployment floor is not independently verified: reading the +Mach-O `minos` load command is a named follow-on, so a declared macOS floor is +recorded as `Unverified(FloorKindNotVerifiable)`. A `CargoZigbuild` target is +`ToolchainBound` — the floor was bound into the toolchain by the triple +rewrite, and the toolchain is trusted to honour it; no independent byte +inspection is claimed for it. ## The evidence lifecycle 1. **Pre-hash and structural inspection.** Every candidate is inspected before - anything executes (`inspect_candidate`, `:1087-1173`): absolute path, + anything executes (`inspect_candidate`, `:1162-1246`): absolute path, non-symlink regular file, non-empty, size equal to the `BuildAttempt`'s - recorded size (else `CandidateChanged`, `:1100-1102`); both parent - directories non-symlink directories (`:1105-1120`); the canonicalized path - contained by the canonicalized target directory (`:1121-1125`); the + recorded size (else `CandidateChanged`, `:1168-1177`); both parent + directories non-symlink directories (`:1180-1195`); the canonicalized path + contained by the canonicalized target directory (`:1196-1200`); the target-implied `(format, architecture)` matched against the parsed header - (`:1062-1085`, `:1126-1132`); then a streaming SHA-256 (`:1133-1149`) with a - post-read re-check of size, file type, and canonical identity (`:1150-1159`). -2. **Method selection and host gate** (`:681-768`). Structural failures - short-circuit here with an *empty* candidate list (`:654-663`), which + (`:1127-1154`, `:1201-1207`); then the compatibility-floor inspection + (`:1208-1215`) and a streaming SHA-256 (`:1216-1222`) with a + post-read re-check of size, file type, and canonical identity (`:1223-1232`). +2. **Method selection and host gate** (`:728-833`). Structural failures + short-circuit here with an *empty* candidate list (`:677-687`), which `validate_for` accommodates by relaxing the candidate-count equality for - `Failed` records (`:334-335`). -3. **Execution** (`:781-888`): preflight for QEMU, then the smoke. -4. **Status from the process** (`:889`, `:956-980`): `Success` → `Passed`; + `Failed` records (`:346-347`). A floor contradicted by the bytes + short-circuits here too (`:705-725`), before anything executes. +3. **Execution** (`:834-948`): preflight for QEMU, then the smoke. +4. **Status from the process** (`:949`, `:1021-1046`): `Success` → `Passed`; `TimedOut` → `SmokeTimedOut`, or `EmulatorFailed` under QEMU; `OutputLimitExceeded` → `OutputLimitExceeded` for either method; `Failed(_)`/`Cancelled` → `SmokeFailed`, or `EmulatorFailed` under QEMU. -5. **Post-hash** (`:896-916`). Only on `Passed` are all candidates re-inspected; +5. **Post-hash** (`:955-978`). Only on `Passed` are all candidates re-inspected; any size or digest difference — or any inspection error — downgrades the record to `Failed(CandidateChanged)`. This is what makes mid-run mutation detectable: the bytes that ran are bracketed by two independent hashes. -6. **Assembly** (`make_evidence`, `:930-954`): every record is built from the +6. **Assembly** (`make_evidence`, `:993-1020`): every record is built from the plan and the observed host. Nothing is inferred. -`validate_for` (`:319-473`) then re-reconciles a record against -`(plan, target, attempt)`: identity and bounds (`:325-342`), duplicate-selector -rejection (`:343-351`), per-candidate selector/package/binary/size agreement plus -digest *shape* (`:352-368`), strictly increasing selector order and process -bounds (`:369-382`), the method/classification pairing (`:383-393`), and the -status/method/process-count rules (`:394-466`). A deliberate limit: it checks +`validate_for` (`:331-492`) then re-reconciles a record against +`(plan, target, attempt)`: identity and bounds (`:337-365`), duplicate-selector +rejection (`:366-374`), per-candidate selector/package/binary/size agreement plus +digest *shape* (`:375-387`), strictly increasing selector order and process +bounds (`:388-401`), the method/classification pairing (`:402-413`), the +status/method/process-count rules (`:414-490`), and the floor-status agreement +with the plan's declared floor (`:350-360`). A deliberate limit: it checks the digest's format, not its value, and never compares `format`/`architecture` against the target. It reconciles evidence against the plan and attempt; it does not re-read bytes. Candidate bytes are proved by `inspect_candidate`. -Determinism: `candidates` is emitted in `BTreeMap` selector order (`:612`, -`:643-644`) and required to be strictly increasing on validation (`:369-372`); +Determinism: `candidates` is emitted in `BTreeMap` selector order (`:624-630`, +`:662-668`) and required to be strictly increasing on validation (`:388-392`); `processes` is in execution order. The record round-trips through JSON unchanged -(`:2265-2268`). +(`:2341-2344`). ## Bounded execution Every execution is a `CommandSpec` handed to the builder's bounded runner -(`:843-869`), with `env: BTreeMap::new()` and `expected_stdout: None` — a +(`:840-850`, `:901-926`), with `env: BTreeMap::new()` and `expected_stdout: None` — a cleared environment plus the builder's small allowlist, and no shell: the -candidate path and the fixed argv are separate OS arguments (`:859-860`). The +candidate path and the fixed argv are separate OS arguments (`:917-918`). The process is spawned as a group; on deadline or cancellation the whole group is killed and waited before the outcome is classified (`src/builder.rs532-581`). | Bound | Source | Value | |---|---|---| -| Smoke deadline | `timeout_ms` (`:851`, `:863`); validated `1..=86_400_000` (`:151-152`) | per-binding, ≤24 h | -| QEMU preflight deadline | hardcoded (`:792`) | 10 s | -| Retained stdout/stderr | per-binding (`:852-853`, `:864-865`); validated `1..=262_144` (`:153-156`) | ≤256 KiB each | -| Preflight capture | hardcoded (`:793-794`) | 8 KiB each | +| Smoke deadline | `timeout_ms` (`:908`, `:921`); validated `1..=86_400_000` (`:151-152`) | per-binding, ≤24 h | +| QEMU preflight deadline | hardcoded (`:845`) | 10 s | +| Retained stdout/stderr | per-binding (`:909-910`, `:922-923`); validated `1..=262_144` (`:155-156`) | ≤256 KiB each | +| Preflight capture | hardcoded (`:846-847`) | 8 KiB each | | Args | ≤128, ≤4096 B each, no NUL or ASCII control characters (`:157-162`) | fixed, never shell-expanded | | Executable allowlist | `src/builder.rs435-455` | candidate must be an absolute path; QEMU only `qemu-x86_64`/`qemu-aarch64`/`qemu-arm` | **Cancellation** is checked twice and both paths are typed. Before the smoke, an -already-cancelled flag yields `Failed(SmokeFailed)` (`:831-842`); during the run, +already-cancelled flag yields `Failed(SmokeFailed)` (`:887-898`); during the run, the builder's poll loop kills the group and returns `CommandOutcome::Cancelled` (`src/builder.rs555-563`), which `status_from_process` maps to `SmokeFailed` -(`:972-978`). There is deliberately no `Cancelled` failure variant — the +(`:1021-1046`). There is deliberately no `Cancelled` failure variant — the distinction lives in the bounded process evidence, not the status taxonomy. The four typed terminal outcomes (non-zero, timeout, cancellation, output limit) are asserted by `native_smoke_failure_timeout_cancellation_and_output_limit_are_typed` -(`:2404-2431`). +(`:2489-2516`). Two details: the smoke's working directory is the candidate's *grandparent*, -canonicalized (`:996-1003`) — the per-target root, not `release/`; and the +canonicalized (`:1061-1069`) — the per-target root, not `release/`; and the builder restores the candidate's exec bit before spawn (`src/builder.rs456-464`), a mode-only change that leaves the recorded size and digest unaffected. Information boundary: the runner closure discards process error detail — every runner error is mapped to `()` and then to a typed `QualificationFailure` -(`:536-543`), so spawn failure, bounds rejection, and process-group cleanup +(`:851-852`, `:929-931`), so spawn failure, bounds rejection, and process-group cleanup failure are indistinguishable in the evidence. The record says what happened, not why the harness could not report it. @@ -231,59 +300,63 @@ why the harness could not report it. **Bindings (producer intent):** -- `QualificationError(String)` (`:30-36`); private `qerr` (`:37-39`). +- `QualificationError(String)` (`:30-36`); private `qerr` (`:37-43`). - `CandidateSmokeBinding{selector, argv, timeout_ms, stdout_limit, stderr_limit}` - (`:44-56`). -- `TargetQualificationBinding{smoke?}` (`:61-65`). -- `QualificationBindingsV1{schema_version, targets}` (`:70-75`) + impl - (`:77-170`): `from_toml` (`:79-83`), `validate_for(plan, build_bindings)` + (`:44-60`). +- `TargetQualificationBinding{smoke?}` (`:61-69`). +- `QualificationBindingsV1{schema_version, targets}` (`:70-76`) + impl + (`:77-173`): `from_toml` (`:79-85`), `validate_for(plan, build_bindings)` (`:86-135`) — exact target-inventory equality with the plan, smoke present *iff* the classification executes (`:107-115`), the smoke selector must exist in the build bindings (`:116-127`), and `DeferredNative` requires - `qualification_host` (`:128-132`); private `validate_shape` (`:137-169`). -- `QualificationRuntime{qemu_sysroot?}` (`:174-177`) — the only runtime input. + `qualification_host` (`:128-132`); private `validate_shape` (`:137-173`). +- `QualificationRuntime{qemu_sysroot?}` (`:174-181`) — the only runtime input. **Method and outcome taxonomy:** - `QualificationMethod::Native | Deferred | DeferredNativeOnNativeHost | - QemuUser | Structural` (`:182-193`). + QemuUser | Structural` (`:182-197`). - `QualificationStatus::Passed | Deferred | Failed(QualificationFailure)` - (`:198-205`). + (`:198-209`). - `QualificationFailure::{StructuralMismatch, CandidateChanged, HostMismatch, SmokeFailed, SmokeTimedOut, OutputLimitExceeded, EmulatorUnavailable, - EmulatorFailed, InvalidRuntimeEnvironment}` (`:210-229`). -- `CandidateFormat::{Elf, PeCoff, MachO}` (`:234-241`); thin Mach-O only. -- `CandidateArchitecture::{X86_64, Aarch64, Armv7}` (`:246-253`). + EmulatorFailed, InvalidRuntimeEnvironment, FloorNotSatisfied}` (`:210-236`). + `FloorNotSatisfied` is the contradicted-floor failure; it is the only + failure a `NotSatisfied` floor status may accompany. +- `CandidateFormat::{Elf, PeCoff, MachO}` (`:237-248`); thin Mach-O only. +- `CandidateArchitecture::{X86_64, Aarch64, Armv7}` (`:249-260`). **Evidence:** - `QualifiedCandidateEvidence{selector, package, binary, size, sha256, format, - architecture}` (`:258-273`). -- `QualificationProcessEvidence{purpose, selector?, process}` (`:278-285`) — + architecture}` (`:261-280`). +- `QualificationProcessEvidence{purpose, selector?, process}` (`:281-292`) — `purpose` is `candidate_smoke` or `qemu_preflight`; no output contents, no environment. - `QualificationEvidence{schema_version, release_id, source_revision, target, - planned_classification, method, actual_host, support, status, candidates, - smoke_selector?, processes}` (`:290-315`) + impl (`:317-474`). + planned_classification, method, actual_host, support, status, floor, + candidates, smoke_selector?, processes}` (`:293-328`) + impl (`:329-493`). + `floor` is the compatibility-floor verification status of the inspected + bytes (`FloorVerificationStatus`, `src/floor.rs:72-89`). **Entry points and internals:** -- `QualificationRequest<'a>` (`:477-494`); `qualify_target` (`:497-522`). -- `qualify_target_for_host` (`:525-556`); `qualify_target_for_host_with_runner` - (`:559-927`) — the whole stage body. -- `make_evidence` (`:930-954`); `status_from_process` (`:956-980`); - `validate_runtime` (`:982-994`); `qualification_cwd` (`:996-1003`); - `actual_host` (`:1005-1020`); `target_matches_host` (`:1022-1034`); - `qemu_for_target` (`:1036-1046`); `qemu_args` (`:1048-1060`); - `target_identity` (`:1062-1085`); `inspect_candidate` (`:1087-1173`); - `parse_binary_header` (`:1175-1241`) — ELF magic/class/machine - (`:1182-1195`), `MZ` + bounded `PE\0\0` header offset (`:1196-1219`), thin - Mach-O magic plus `cputype` in either endianness (`:1220-1239`). The parser is +- `QualificationRequest<'a>` (`:496-515`); `qualify_target` (`:516-543`). +- `qualify_target_for_host` (`:544-577`); `qualify_target_for_host_with_runner` + (`:578-990`) — the whole stage body. +- `make_evidence` (`:993-1020`); `status_from_process` (`:1021-1046`); + `validate_runtime` (`:1047-1060`); `qualification_cwd` (`:1061-1069`); + `actual_host` (`:1070-1086`); `target_matches_host` (`:1087-1100`); + `qemu_for_target` (`:1101-1112`); `qemu_args` (`:1113-1126`); + `target_identity` (`:1127-1154`); `inspect_candidate` (`:1162-1246`); + `parse_binary_header` (`:1247-1314`) — ELF magic/class/machine + (`:1255-1266`), `MZ` + bounded `PE\0\0` header offset (`:1268-1291`), thin + Mach-O magic plus `cputype` in either endianness (`:1293-1310`). The parser is format-directed: it is told which format the target implies and fails when the - magic disagrees, so a fat/universal Mach-O is rejected (`:1476-1478`). + magic disagrees, so a fat/universal Mach-O is rejected (`:1549-1551`). -**Tests** (`:1243-2610`): host-adaptive fixtures using the test binary itself as -the candidate, minimal ELF/PE/Mach-O byte builders (`:1407-1445`), and coverage +**Tests** (`:1316-2981`): host-adaptive fixtures using the test binary itself as +the candidate, minimal ELF/PE/Mach-O byte builders (`:1480-1520`), and coverage for strict bindings, exact smoke selectors, inventory reconciliation, the cross-tool native pass, host mismatch, both deferred paths, the QEMU argv contract, cancellation/timeout/output-limit typing, symlink and relative-path @@ -292,8 +365,8 @@ rejection, and direct/bundle/archive inventories. ## Boundaries / non-goals - **Does not build.** It consumes a `BuildAttempt` and requires its process - outcome to be `Success` (`:582`). A build success never implies a - qualification pass: `inspect_candidate` always runs first (`:643-670`). + outcome to be `Success` (`:601`). A build success never implies a + qualification pass: `inspect_candidate` always runs first (`:662-694`). - **Does not finalize.** No output root, no copying, no archive, no manifest. Its only output is the evidence record. - **Does not assert authenticity or provenance.** SHA-256 and size are integrity @@ -304,32 +377,35 @@ rejection, and direct/bundle/archive inventories. - **No network, no cross-tool provisioning, no repository scripts.** The only executables that can run are the exact candidate path and the three fixed `qemu-*` names; the binding schema has no executable, environment, or command - field (`:44-56`). + field (`:44-60`). - **No `Qualification` growth.** Neither the classification nor the method enum gained a variant for any new topology, and `schema_version` stayed 1 (`plans/closure/build-qualification/006-status.md`). - **No degenerate records.** Every executing classification needs a bounded smoke - binding (`:781`, `:404-409`); `Structural` with a smoke is refused (`:111-115`); - a `Passed` record with a non-`Success` process is refused (`:434-438`). + binding (`:834`, `:423-428`); `Structural` with a smoke is refused (`:421-422`); + a `Passed` record with a non-`Success` process is refused (`:453-457`). ## Dependencies / dependents - Module dependencies: `crate::builder::{run_qemu_process, run_qualification_process, CandidateArtifact, CommandSpec, ProcessEvidence}` - (`:3-10`), the planning types (`BuildAttempt`, `BuildBindingsV1`, - `BuildCancellation`, `HostArch`, `HostOs`, `HostRequirement`, - `LogicalOutputSelector`, `PlannedTarget`, `Qualification`, `ReleasePlan`, - `SupportTier`), `eggpack_contract::DistributionContract`, `serde`, and `sha2` - (`:11-13`). Crate-level dependencies are `Cargo.toml:14-23`; this file has no + (`:3-8`), the planning types (`BuildAttempt`, `BuildBindingsV1`, + `BuildCancellation`, `FloorUnverifiedReason`, `FloorVerificationStatus`, + `HostArch`, `HostOs`, `HostRequirement`, `LogicalOutputSelector`, + `PlannedTarget`, `Qualification`, `ReleasePlan`, `SupportTier`), + `eggpack_contract::DistributionContract`, `serde`, and `std` (`:9-23`). The + candidate bytes are digested by the crate's single file-digest authority + (`crate::file_digest`), not by a private SHA-256 stream in this module. + Crate-level dependencies are `Cargo.toml:14-23`; this file has no independent set. - In-crate dependents: `finalization.rs` re-validates this record - (`finalization.rs:192-195`) and gates on it — `Passed`, or `Deferred` when the - support tier is not `Required` (`finalization.rs:196-200`). + (`finalization.rs:193-196`) and gates on it — `Passed`, or `Deferred` when the + support tier is not `Required` (`finalization.rs:197-200`). - External: `eggpack-ci` encodes, decodes, and aggregates `QualificationEvidence` (`eggpack-ci/src/lib.rs2727-2732`, `:2743-2785`); `eggpack-cli` drives it through the `ci _qualify-target` runner (`eggpack-cli/src/main.rs517-588`), which is why candidate paths are absolutized there (`main.rs522-524`) — - `inspect_candidate` requires absolute paths (`:1093`). + `inspect_candidate` requires absolute paths (`:1168`). - `eggpack-github` and `eggpack-bootstrap` do not use this module. ## Sibling deep dives diff --git a/crates/eggpack-ci/src/lib.rs b/crates/eggpack-ci/src/lib.rs index 6603a34..c4b0dd3 100644 --- a/crates/eggpack-ci/src/lib.rs +++ b/crates/eggpack-ci/src/lib.rs @@ -5802,6 +5802,7 @@ mod tests { }, support, status, + floor: eggpack_core::FloorVerificationStatus::NotDeclared, candidates: vec![], smoke_selector: None, processes: vec![], @@ -5982,6 +5983,7 @@ mod tests { }, support: SupportTier::Required, status: QualificationStatus::Passed, + floor: eggpack_core::FloorVerificationStatus::NotDeclared, candidates: qualified, smoke_selector: None, processes: vec![], diff --git a/crates/eggpack-core/README.md b/crates/eggpack-core/README.md index cd94851..309ae0c 100644 --- a/crates/eggpack-core/README.md +++ b/crates/eggpack-core/README.md @@ -1,6 +1,6 @@ # eggpack-core -Producer-side planning, bounded Cargo building and qualification, local finalization, and manifest aggregation. PackConfig/ReleasePlan planning is pure. The first-party builder accepts strict `BuildBindingsV1` package/bin mappings for contract logical slots, checks the declared Rust/cargo-zigbuild tool intent, executes direct Cargo process groups with time/output bounds, and returns exact non-empty candidate paths. Each `BuildAttempt` carries the release id and source revision from its `ReleasePlan`. `QualificationBindingsV1` selects one exact candidate smoke check per executable target; fixed argv is passed directly to that candidate, with no shell, executable field, environment map, or repository script. `qualify_target` reconciles the plan, build bindings, attempt, candidate inventory, and qualification bindings; validates ELF, PE/COFF, or thin Mach-O format and architecture; hashes exact candidate bytes before and after execution; and returns deterministic identity-bound evidence. Native and deferred-native matching-host runs plus finite Linux QEMU user-mode runs use bounded process groups. Evidence contains host/classification/support, per-candidate size/hash/format/architecture, and bounded process outcomes, never local paths, output contents, or environment values. +Producer-side planning, bounded Cargo building and qualification, local finalization, and manifest aggregation. PackConfig/ReleasePlan planning is pure. The first-party builder accepts strict `BuildBindingsV1` package/bin mappings for contract logical slots, checks the declared Rust/cargo-zigbuild tool intent, executes direct Cargo process groups with time/output bounds, and returns exact non-empty candidate paths. Each `BuildAttempt` carries the release id and source revision from its `ReleasePlan`. `QualificationBindingsV1` selects one exact candidate smoke check per executable target; fixed argv is passed directly to that candidate, with no shell, executable field, environment map, or repository script. `qualify_target` reconciles the plan, build bindings, attempt, candidate inventory, and qualification bindings; validates ELF, PE/COFF, or thin Mach-O format and architecture; hashes exact candidate bytes before and after execution; and returns deterministic identity-bound evidence. Native and deferred-native matching-host runs plus finite Linux QEMU user-mode runs use bounded process groups. Evidence contains host/classification/support, the compatibility-floor verification status, per-candidate size/hash/format/architecture, and bounded process outcomes, never local paths, output contents, or environment values. `finalize_release` accepts identity-matched build and qualification evidence for the exact planned target set, enforces required-target qualification gates, copies direct and bundle candidates under contract names, and creates SHA-256 sidecars from final bytes. Archive output currently accepts only an explicit `ArchiveEncoding::TarGzip`; the contract archive asset filename must end in `.tar.gz`. Archive member names come from contract member paths, while tar/gzip timestamps and ownership metadata are normalized for deterministic output. Manifest v1 is constructed only after all artifacts and sidecars are complete, so its artifact digests cover final release bytes and its member digests cover the bytes written into the archive. The finalizer writes only into a new output root beneath a caller-secured parent (mode 0700 on Unix; Windows inherits the parent ACL) and returns no successful aggregate on failure. This remains producer-side file construction: no extraction, installation, publication, or authenticity claim is performed. @@ -8,6 +8,8 @@ Producer-side planning, bounded Cargo building and qualification, local finaliza `BuildStrategy` and `Qualification` are independent producer axes. `Qualification::Native` is admissible for a `NativeCargo` **or** `CargoZigbuild` target, and requires the effective qualification host (`qualification_host`, else the build host) to match the target OS/architecture. This is what lets a cross-built candidate for a compatibility floor be proven by execution on a matching native host, including a separate qualification host for a cross-built candidate; a cross-tool-built candidate never earns native qualification merely by compiling, and a non-matching host records a failed `HostMismatch` outcome rather than a pass or a skip. A declared `CompatibilityFloor` remains a build-policy input carried into the cross-tool build command: native execution on a matching host proves the candidate runs there, and is not by itself independent proof that the produced binary honours the declared minimum glibc/macOS runtime. +A declared compatibility floor is now *recorded*, not merely implied. `FloorVerificationStatus` (`src/floor.rs`) is a finite, closed status — never a free-form string, never an `Option` — and it is carried both on the plan (`PlannedTarget::floor_status`) and on the qualification evidence (`QualificationEvidence::floor`). `NotDeclared` means the target declares no floor; `ToolchainBound` means the floor was bound into the build toolchain by the cargo-zigbuild triple rewrite and the toolchain is trusted to honour it; `Verified` means the produced bytes were independently inspected and satisfy the declared floor; `Unverified(reason)` means a floor was declared and the bytes did not confirm it, for a bounded reason; `NotSatisfied` means the bytes require a newer runtime than the declared floor. The status is computed from the inspected bytes — never from a smoke run — through a bounded ELF reader that reads the program headers, the dynamic table, and the `GLIBC_x.y` version requirements, and compares them in the direction that matters: a binary requiring a newer glibc than declared does not satisfy the floor. A contradicted floor is false, so it fails the qualification for that target rather than being reported as merely unverified; an unverifiable floor is a recorded status, not a failed release. A macOS deployment floor is not independently verified yet and is recorded as `Unverified(FloorKindNotVerifiable)`. + `cargo_command` exposes typed shell-free Cargo/CargoZigbuild intent for provider renderers. `execute_target` uses a caller-owned absolute repository root and a pre-existing private work root; each invocation/target gets a new Cargo target directory. The local process runner only launches Cargo, rustc, or Zig, clears inherited environment state except a small toolchain/path allowlist, and never returns captured output contents. Process-tree timeout cleanup uses `command-group` process groups/jobs. Windows Cargo builds require an initialized Visual Studio developer environment. The Windows CI lane runs `ilammy/msvc-dev-cmd` before builder qualification and verifies that `link.exe` resolves beneath `VCToolsInstallDir`; this supplies the MSVC linker, SDK, and library environment used by Cargo and build scripts. diff --git a/crates/eggpack-core/src/builder.rs b/crates/eggpack-core/src/builder.rs index 59a50d8..1538d5a 100644 --- a/crates/eggpack-core/src/builder.rs +++ b/crates/eggpack-core/src/builder.rs @@ -1073,6 +1073,7 @@ mod tests { support: SupportTier::Required, }, artifact_form: crate::PlannedAssetForm::Direct, + floor_status: crate::FloorVerificationStatus::NotDeclared, } } #[test] @@ -1149,6 +1150,74 @@ mod tests { ) .is_err()); } + /// The compatibility-floor build behaviour is unchanged by the floor + /// verification status: the cargo-zigbuild triple rewrite is pinned + /// byte-for-byte, and the macOS-under-zigbuild refusal keeps its exact + /// message. Recording a floor status must never move the refusal from + /// build-command time to declaration time. + #[test] + fn the_cargo_zigbuild_floor_rewrite_and_macos_refusal_are_unchanged() { + let mut t = target(); + t.policy.strategy = BuildStrategy::CargoZigbuild; + t.policy.toolchain.cargo_zigbuild = Some("0.23.3".into()); + t.policy.toolchain.zig = Some("0.14.1".into()); + t.policy.floor = CompatibilityFloor::Glibc { + major: 2, + minor: 17, + }; + let binding = BuildBinding { + selector: LogicalOutputSelector::Direct, + package: "demo".into(), + binary: "demo".into(), + }; + let command = cargo_command( + &t, + &binding, + Path::new("/repo"), + Path::new("/target"), + Duration::from_secs(10), + ) + .unwrap(); + assert_eq!( + command.args, + vec![ + "+1.89.0", + "zigbuild", + "--release", + "--locked", + "--target", + "x86_64-unknown-linux-gnu.2.17", + "--package", + "demo", + "--bin", + "demo", + ] + ); + // A macOS floor under cargo-zigbuild is refused at build-command time + // with the unchanged message. + t.policy.floor = CompatibilityFloor::Macos { + major: 13, + minor: 0, + }; + let refusal = cargo_command( + &t, + &binding, + Path::new("/repo"), + Path::new("/target"), + Duration::from_secs(10), + ) + .unwrap_err(); + assert_eq!(refusal.to_string(), "macOS floor cannot use cargo-zigbuild"); + // The refusal is not moved to declaration time: the policy still + // resolves, because only the canonical floor rule refuses it. + assert_eq!( + t.policy.floor, + CompatibilityFloor::Macos { + major: 13, + minor: 0 + } + ); + } #[test] fn binding_document_rejects_duplicate_and_unknown_fields() { let good = r#"schema_version = 1 diff --git a/crates/eggpack-core/src/finalization.rs b/crates/eggpack-core/src/finalization.rs index c4a4ca9..ccd5c71 100644 --- a/crates/eggpack-core/src/finalization.rs +++ b/crates/eggpack-core/src/finalization.rs @@ -635,6 +635,7 @@ mod tests { }, support: SupportTier::Required, status: QualificationStatus::Passed, + floor: crate::FloorVerificationStatus::NotDeclared, candidates: qualified, smoke_selector: None, processes: vec![], diff --git a/crates/eggpack-core/src/floor.rs b/crates/eggpack-core/src/floor.rs new file mode 100644 index 0000000..c6df625 --- /dev/null +++ b/crates/eggpack-core/src/floor.rs @@ -0,0 +1,1260 @@ +//! Compatibility-floor verification status and bounded ELF version-requirement inspection. +//! +//! The compatibility floor is producer policy. This module owns the finite +//! status model that says what was actually done with a declared floor, and +//! the bounded reader that computes the highest `GLIBC_x.y` symbol version a +//! produced ELF requires. +//! +//! Two rules bound everything here: +//! +//! - native execution is never floor proof (ADR-0005 §9), so the status is +//! computed from the produced bytes or from the toolchain binding, never +//! from a smoke run; +//! - the inspection is read-only, bounded at every table and offset, and +//! fails closed: an unreadable, malformed, truncated, or over-large +//! candidate is never `Verified`. + +use crate::{BuildStrategy, CompatibilityFloor, TargetPolicy}; +use serde::{Deserialize, Serialize}; +use std::fs::File; +use std::io::{Read, Seek, SeekFrom}; +use std::path::Path; + +/// Why a declared compatibility floor could not be independently verified. +/// +/// The reason set is closed: it is a bounded enumeration, never a free-form +/// string, so a recorded status always says exactly why a declared floor is +/// not independently confirmed. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum FloorUnverifiedReason { + /// The floor is declared and awaits independent inspection of the produced bytes. + /// + /// This is the plan-time disposition of a declared floor that the build + /// toolchain cannot bind: the bytes have not been inspected yet. + PendingInspection, + /// The candidate is not an ELF image, or its bytes could not be read. + UnreadableCandidate, + /// The candidate is a truncated, malformed, or over-large ELF image. + MalformedCandidate, + /// The inspected candidate declares no glibc symbol version requirement. + /// + /// Such a candidate is compatible with any declared floor, but it does not + /// *confirm* a floor, so it is recorded specifically rather than as a + /// generic pass. + NoVersionRequirement, + /// The candidate carries a glibc version requirement that is not a plain + /// numeric version, so it cannot be compared against the declared floor. + UnrecognizedVersionRequirement, + /// The declared floor kind has no independent byte-level verification. + /// + /// A macOS deployment floor would be read from the Mach-O `minos` field, + /// which this milestone does not implement. + FloorKindNotVerifiable, +} + +/// The verification status of a declared compatibility floor. +/// +/// This is the **single** producer-side floor status model. It is finite and +/// closed: it is neither a free-form string nor an `Option`, and every +/// variant maps to one concrete observation about the produced bytes or about +/// the toolchain that produced them. +/// +/// | Status | Concrete observation | +/// |---|---| +/// | `NotDeclared` | the target declares `CompatibilityFloor::None` | +/// | `ToolchainBound` | the floor was bound into the build toolchain by the cargo-zigbuild triple rewrite, and the toolchain is trusted to honour it | +/// | `Verified` | the produced bytes were independently inspected and their highest required `GLIBC_x.y` version is not newer than the declared floor | +/// | `Unverified(reason)` | a floor was declared and the produced bytes did not confirm it, for the bounded reason given | +/// | `NotSatisfied` | the produced bytes were independently inspected and require a newer runtime than the declared floor | +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum FloorVerificationStatus { + /// The target declares `CompatibilityFloor::None`. + NotDeclared, + /// The floor was bound into the build toolchain and the toolchain is + /// trusted to honour it. + ToolchainBound, + /// The produced bytes were independently inspected and satisfy the declared floor. + Verified, + /// A floor was declared but could not be independently verified. + Unverified(FloorUnverifiedReason), + /// The produced bytes contradict the declared floor: they require a newer + /// runtime than the floor declares. + /// + /// This is never reported as `Unverified`: a declared floor that the bytes + /// disprove is false, so it fails the qualification for that target. + NotSatisfied, +} + +impl Default for FloorVerificationStatus { + /// A document that omits the status is read as `NotDeclared`. + /// + /// The omission is then refused for any target that declares a floor, so + /// a missing status fails closed instead of defaulting to a claim. + fn default() -> Self { + FloorVerificationStatus::NotDeclared + } +} + +/// The floor verification status a plan states for its declared floor. +/// +/// The status is a pure function of the policy, so it is deterministic and +/// cannot be chosen by a caller: a plan either states the status its policy +/// implies or it is rejected. +pub fn planned_floor_status(policy: &TargetPolicy) -> FloorVerificationStatus { + match policy.floor { + CompatibilityFloor::None => FloorVerificationStatus::NotDeclared, + CompatibilityFloor::Glibc { .. } => match policy.strategy { + // The cargo-zigbuild triple rewrite binds the floor into the + // toolchain; the toolchain is trusted to honour it. + BuildStrategy::CargoZigbuild => FloorVerificationStatus::ToolchainBound, + // A native build cannot bind the floor into the toolchain, so the + // floor is only ever confirmed by inspecting the produced bytes. + BuildStrategy::NativeCargo => { + FloorVerificationStatus::Unverified(FloorUnverifiedReason::PendingInspection) + } + }, + // A macOS deployment floor is read from the Mach-O `minos` field, + // which this milestone does not implement. + CompatibilityFloor::Macos { .. } => { + FloorVerificationStatus::Unverified(FloorUnverifiedReason::FloorKindNotVerifiable) + } + } +} + +/// Whether a floor verification status is admissible for a declared floor and +/// build strategy. +/// +/// This is the cross-check that keeps a status from claiming more than the +/// declaration allows: a target without a declared floor can only be +/// `NotDeclared`, a toolchain-bound floor can only be `ToolchainBound`, and +/// only an independently inspected floor can be `Verified` or `NotSatisfied`. +pub fn floor_status_admissible( + floor: &CompatibilityFloor, + strategy: BuildStrategy, + status: FloorVerificationStatus, +) -> bool { + match (floor, strategy) { + (CompatibilityFloor::None, _) => status == FloorVerificationStatus::NotDeclared, + (CompatibilityFloor::Glibc { .. }, BuildStrategy::CargoZigbuild) => { + status == FloorVerificationStatus::ToolchainBound + } + (CompatibilityFloor::Glibc { .. }, BuildStrategy::NativeCargo) => matches!( + status, + FloorVerificationStatus::Verified + | FloorVerificationStatus::Unverified(_) + | FloorVerificationStatus::NotSatisfied + ), + (CompatibilityFloor::Macos { .. }, _) => { + matches!(status, FloorVerificationStatus::Unverified(_)) + } + } +} + +/// The largest ELF header window read from one candidate. +const MAX_ELF_HEADER: usize = 64; +/// The largest number of ELF program headers read from one candidate. +const MAX_ELF_PROGRAM_HEADERS: usize = 256; +/// The largest number of dynamic entries read from one candidate. +const MAX_ELF_DYNAMIC_ENTRIES: usize = 1024; +/// The largest number of version-requirement entries read from one candidate. +const MAX_ELF_VERSION_REQUIREMENTS: usize = 256; +/// The largest number of auxiliary version entries read for one requirement. +const MAX_ELF_VERSION_AUXILIARIES: usize = 256; +/// The largest version name read from the dynamic string table. +const MAX_ELF_VERSION_NAME: usize = 64; + +/// The `PT_LOAD` program header type. +const PT_LOAD: u32 = 1; +/// The `PT_DYNAMIC` program header type. +const PT_DYNAMIC: u32 = 2; +/// The dynamic tag that terminates the dynamic table. +const DT_NULL: u64 = 0; +/// The dynamic tag holding the address of the dynamic string table. +const DT_STRTAB: u64 = 5; +/// The dynamic tag holding the address of the version-requirement table. +const DT_VERNEED: u64 = 0x6ffffffe; +/// The dynamic tag holding the number of version-requirement entries. +const DT_VERNEEDNUM: u64 = 0x6fffffff; + +/// Why the version-requirement reader could not determine a requirement. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum FloorReadError { + /// The candidate is not an ELF image. + NotAnElf, + /// The candidate bytes could not be read. + Unreadable, + /// The candidate is truncated or structurally malformed. + Malformed, + /// The candidate exceeds a declared parsing bound. + BoundExceeded, + /// The candidate carries a glibc version requirement that is not numeric. + UnrecognizedVersion, +} + +/// A glibc symbol version requirement, compared component by component. +/// +/// The patch component is zero for a two-component version: `GLIBC_2.17` is +/// `2.17.0`, and `GLIBC_2.2.5` is `2.2.5`, which is newer than `2.2.0` and +/// older than `2.17.0`. +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] +struct GlibcVersion { + /// Major version. + major: u16, + /// Minor version. + minor: u16, + /// Patch version. + patch: u16, +} + +/// The parsed ELF header fields this reader needs. +struct ElfHeader { + /// Whether the image is a 64-bit ELF. + class64: bool, + /// Whether the image stores integers little-endian. + little_endian: bool, + /// File offset of the program header table. + program_header_offset: u64, + /// Size of one program header entry. + program_header_size: u16, + /// Number of program header entries. + program_header_count: u16, +} + +/// One program header segment. +struct ProgramSegment { + /// Segment type. + kind: u32, + /// File offset of the segment. + offset: u64, + /// Virtual address of the segment. + vaddr: u64, + /// Number of file-backed bytes in the segment. + filesz: u64, +} + +/// Read exactly `buffer.len()` bytes at `offset`. +/// +/// Every read in this module is exact-length and every offset is checked +/// against the file length before the read happens. +fn read_exact_at(file: &mut File, offset: u64, buffer: &mut [u8]) -> Result<(), FloorReadError> { + file.seek(SeekFrom::Start(offset)) + .map_err(|_| FloorReadError::Unreadable)?; + match file.read_exact(buffer) { + Ok(()) => Ok(()), + Err(error) if error.kind() == std::io::ErrorKind::UnexpectedEof => { + Err(FloorReadError::Malformed) + } + Err(_) => Err(FloorReadError::Unreadable), + } +} + +/// Read a `u16` from a fixed-width buffer. +fn u16_at(bytes: &[u8], offset: usize, little_endian: bool) -> u16 { + let raw = [bytes[offset], bytes[offset + 1]]; + if little_endian { + u16::from_le_bytes(raw) + } else { + u16::from_be_bytes(raw) + } +} + +/// Read a `u32` from a fixed-width buffer. +fn u32_at(bytes: &[u8], offset: usize, little_endian: bool) -> u32 { + let raw = [ + bytes[offset], + bytes[offset + 1], + bytes[offset + 2], + bytes[offset + 3], + ]; + if little_endian { + u32::from_le_bytes(raw) + } else { + u32::from_be_bytes(raw) + } +} + +/// Read a `u64` from a fixed-width buffer. +fn u64_at(bytes: &[u8], offset: usize, little_endian: bool) -> u64 { + let mut raw = [0u8; 8]; + raw.copy_from_slice(&bytes[offset..offset + 8]); + if little_endian { + u64::from_le_bytes(raw) + } else { + u64::from_be_bytes(raw) + } +} + +/// Parse the ELF header of one candidate. +fn parse_elf_header(file: &mut File, length: u64) -> Result { + let mut header = [0u8; MAX_ELF_HEADER]; + let wanted = length.min(MAX_ELF_HEADER as u64) as usize; + file.read_exact(&mut header[..wanted]) + .map_err(|_| FloorReadError::Malformed)?; + if wanted < 6 { + return Err(FloorReadError::Malformed); + } + if &header[..4] != b"\x7fELF" { + return Err(FloorReadError::NotAnElf); + } + let class64 = match header[4] { + 1 => false, + 2 => true, + _ => return Err(FloorReadError::Malformed), + }; + let little_endian = match header[5] { + 1 => true, + 2 => false, + _ => return Err(FloorReadError::Malformed), + }; + // The header must be complete for the class it claims. + let minimum = if class64 { 64 } else { 52 }; + if length < minimum as u64 || wanted < minimum { + return Err(FloorReadError::Malformed); + } + let (program_header_offset, program_header_size, program_header_count) = if class64 { + ( + u64_at(&header, 32, little_endian), + u16_at(&header, 54, little_endian), + u16_at(&header, 56, little_endian), + ) + } else { + ( + u32_at(&header, 28, little_endian) as u64, + u16_at(&header, 42, little_endian), + u16_at(&header, 44, little_endian), + ) + }; + Ok(ElfHeader { + class64, + little_endian, + program_header_offset, + program_header_size, + program_header_count, + }) +} + +/// Read the bounded program header table of one candidate. +fn read_program_segments( + file: &mut File, + header: &ElfHeader, + length: u64, +) -> Result, FloorReadError> { + if header.program_header_count == 0 { + return Ok(Vec::new()); + } + // `0xffff` marks the extended numbering scheme, which this reader does not + // implement; the real count lives in the section header table. + if header.program_header_count == 0xffff { + return Err(FloorReadError::Malformed); + } + if header.program_header_count as usize > MAX_ELF_PROGRAM_HEADERS { + return Err(FloorReadError::BoundExceeded); + } + let expected_size = if header.class64 { 56 } else { 32 }; + if header.program_header_size != expected_size { + return Err(FloorReadError::Malformed); + } + let count = header.program_header_count as u64; + let table_end = count + .checked_mul(header.program_header_size as u64) + .and_then(|bytes| header.program_header_offset.checked_add(bytes)) + .ok_or(FloorReadError::Malformed)?; + if table_end > length { + return Err(FloorReadError::Malformed); + } + let mut segments = Vec::with_capacity(count as usize); + for index in 0..count { + let offset = header.program_header_offset + index * header.program_header_size as u64; + let mut buffer = [0u8; 56]; + read_exact_at(file, offset, &mut buffer[..expected_size as usize])?; + let segment = if header.class64 { + ProgramSegment { + kind: u32_at(&buffer, 0, header.little_endian), + offset: u64_at(&buffer, 8, header.little_endian), + vaddr: u64_at(&buffer, 16, header.little_endian), + filesz: u64_at(&buffer, 32, header.little_endian), + } + } else { + ProgramSegment { + kind: u32_at(&buffer, 0, header.little_endian), + offset: u32_at(&buffer, 4, header.little_endian) as u64, + vaddr: u32_at(&buffer, 8, header.little_endian) as u64, + filesz: u32_at(&buffer, 16, header.little_endian) as u64, + } + }; + segments.push(segment); + } + Ok(segments) +} + +/// Read the bounded dynamic table of one candidate. +/// +/// Returns the `(tag, value)` pairs in table order, stopping at the +/// terminating `DT_NULL` entry. +fn read_dynamic_entries( + file: &mut File, + header: &ElfHeader, + dynamic: &ProgramSegment, + length: u64, +) -> Result, FloorReadError> { + let entry_size = if header.class64 { 16 } else { 8 }; + let count = dynamic.filesz / entry_size as u64; + if count > MAX_ELF_DYNAMIC_ENTRIES as u64 { + return Err(FloorReadError::BoundExceeded); + } + let table_bytes = count * entry_size as u64; + let table_end = dynamic + .offset + .checked_add(table_bytes) + .ok_or(FloorReadError::Malformed)?; + if table_end > length { + return Err(FloorReadError::Malformed); + } + let mut buffer = vec![0u8; table_bytes as usize]; + read_exact_at(file, dynamic.offset, &mut buffer)?; + let mut entries = Vec::new(); + for index in 0..count as usize { + let base = index * entry_size; + let (tag, value) = if header.class64 { + ( + u64_at(&buffer, base, header.little_endian), + u64_at(&buffer, base + 8, header.little_endian), + ) + } else { + ( + u32_at(&buffer, base, header.little_endian) as u64, + u32_at(&buffer, base + 4, header.little_endian) as u64, + ) + }; + if tag == DT_NULL { + break; + } + entries.push((tag, value)); + } + Ok(entries) +} + +/// Map a virtual address to a file offset through the loadable segments. +fn map_vaddr(segments: &[ProgramSegment], vaddr: u64) -> Result { + for segment in segments.iter().filter(|segment| segment.kind == PT_LOAD) { + let end = segment + .vaddr + .checked_add(segment.filesz) + .ok_or(FloorReadError::Malformed)?; + if vaddr >= segment.vaddr && vaddr < end { + return Ok(segment.offset + (vaddr - segment.vaddr)); + } + } + Err(FloorReadError::Malformed) +} + +/// Read one bounded version name from the dynamic string table. +fn read_version_name( + file: &mut File, + strtab_offset: u64, + name_offset: u64, + length: u64, +) -> Result { + let start = strtab_offset + .checked_add(name_offset) + .ok_or(FloorReadError::Malformed)?; + if start >= length { + return Err(FloorReadError::Malformed); + } + // The name is read within the file, never past its end, and never for + // more than the declared name bound. + let available = (length - start).min(MAX_ELF_VERSION_NAME as u64) as usize; + let mut buffer = [0u8; MAX_ELF_VERSION_NAME]; + read_exact_at(file, start, &mut buffer[..available])?; + let end = buffer[..available] + .iter() + .position(|byte| *byte == 0) + .ok_or(FloorReadError::Malformed)?; + Ok(String::from_utf8_lossy(&buffer[..end]).into_owned()) +} + +/// Parse a symbol version name into a glibc version requirement. +/// +/// A name that does not start with `GLIBC_` is not a glibc requirement. A +/// `GLIBC_` name that is not a plain numeric version cannot be compared +/// against a declared floor, so it is refused rather than ignored. +fn parse_glibc_version(name: &str) -> Result, FloorReadError> { + let Some(rest) = name.strip_prefix("GLIBC_") else { + return Ok(None); + }; + let parts: Vec<&str> = rest.split('.').collect(); + if parts.len() < 2 || parts.len() > 3 { + return Err(FloorReadError::UnrecognizedVersion); + } + let mut numbers = [0u16; 3]; + for (index, part) in parts.iter().enumerate() { + if part.is_empty() || part.len() > 5 || !part.bytes().all(|byte| byte.is_ascii_digit()) { + return Err(FloorReadError::UnrecognizedVersion); + } + numbers[index] = part + .parse::() + .map_err(|_| FloorReadError::UnrecognizedVersion)?; + } + Ok(Some(GlibcVersion { + major: numbers[0], + minor: numbers[1], + patch: numbers[2], + })) +} + +/// Read the highest glibc symbol version requirement of one ELF candidate. +/// +/// Returns `Ok(None)` when the candidate carries no glibc version +/// requirement at all. +fn read_glibc_requirement(path: &Path) -> Result, FloorReadError> { + let mut file = File::open(path).map_err(|_| FloorReadError::Unreadable)?; + let length = file + .metadata() + .map_err(|_| FloorReadError::Unreadable)? + .len(); + let header = parse_elf_header(&mut file, length)?; + let segments = read_program_segments(&mut file, &header, length)?; + let Some(dynamic) = segments.iter().find(|segment| segment.kind == PT_DYNAMIC) else { + return Ok(None); + }; + let entries = read_dynamic_entries(&mut file, &header, dynamic, length)?; + let find = |tag: u64| { + entries + .iter() + .find(|(entry, _)| *entry == tag) + .map(|(_, value)| *value) + }; + let Some(verneed_vaddr) = find(DT_VERNEED) else { + return Ok(None); + }; + let strtab_vaddr = find(DT_STRTAB).ok_or(FloorReadError::Malformed)?; + let requirement_count = find(DT_VERNEEDNUM); + if requirement_count.is_some_and(|count| count > MAX_ELF_VERSION_REQUIREMENTS as u64) { + return Err(FloorReadError::BoundExceeded); + } + let strtab_offset = map_vaddr(&segments, strtab_vaddr)?; + let verneed_offset = map_vaddr(&segments, verneed_vaddr)?; + if verneed_offset >= length { + return Err(FloorReadError::Malformed); + } + + let mut highest: Option = None; + let mut requirement_offset = verneed_offset; + let mut requirements = 0usize; + loop { + if requirements >= MAX_ELF_VERSION_REQUIREMENTS { + return Err(FloorReadError::BoundExceeded); + } + let mut requirement = [0u8; 16]; + read_exact_at(&mut file, requirement_offset, &mut requirement)?; + let auxiliary_count = u16_at(&requirement, 2, header.little_endian); + let auxiliary_offset = u32_at(&requirement, 8, header.little_endian) as u64; + let next_requirement = u32_at(&requirement, 12, header.little_endian) as u64; + let mut auxiliary_offset = requirement_offset + .checked_add(auxiliary_offset) + .ok_or(FloorReadError::Malformed)?; + for index in 0..auxiliary_count as usize { + if index >= MAX_ELF_VERSION_AUXILIARIES { + return Err(FloorReadError::BoundExceeded); + } + let mut auxiliary = [0u8; 16]; + read_exact_at(&mut file, auxiliary_offset, &mut auxiliary)?; + let name_offset = u32_at(&auxiliary, 8, header.little_endian) as u64; + let next_auxiliary = u32_at(&auxiliary, 12, header.little_endian) as u64; + let name = read_version_name(&mut file, strtab_offset, name_offset, length)?; + if let Some(version) = parse_glibc_version(&name)? { + if highest.is_none_or(|current| version > current) { + highest = Some(version); + } + } + if next_auxiliary == 0 { + break; + } + auxiliary_offset = auxiliary_offset + .checked_add(next_auxiliary) + .ok_or(FloorReadError::Malformed)?; + } + if next_requirement == 0 { + break; + } + requirement_offset = requirement_offset + .checked_add(next_requirement) + .ok_or(FloorReadError::Malformed)?; + requirements += 1; + } + Ok(highest) +} + +/// Inspect one candidate's bytes and compute its floor verification status. +/// +/// The inspection is read-only and holds no lock: two concurrent inspections +/// of the same candidate observe the same bytes or report a changed-file +/// error, and each observation is self-consistent. +pub(crate) fn inspect_candidate_floor( + path: &Path, + floor: &CompatibilityFloor, + strategy: BuildStrategy, +) -> FloorVerificationStatus { + match floor { + CompatibilityFloor::None => FloorVerificationStatus::NotDeclared, + CompatibilityFloor::Macos { .. } => { + FloorVerificationStatus::Unverified(FloorUnverifiedReason::FloorKindNotVerifiable) + } + CompatibilityFloor::Glibc { major, minor } => match strategy { + BuildStrategy::CargoZigbuild => FloorVerificationStatus::ToolchainBound, + BuildStrategy::NativeCargo => { + let declared = GlibcVersion { + major: *major, + minor: *minor, + patch: 0, + }; + match read_glibc_requirement(path) { + // The comparison direction is the point: a binary that + // requires a *newer* glibc than declared does not satisfy + // the declared floor. + Ok(Some(required)) => { + if required <= declared { + FloorVerificationStatus::Verified + } else { + FloorVerificationStatus::NotSatisfied + } + } + Ok(None) => FloorVerificationStatus::Unverified( + FloorUnverifiedReason::NoVersionRequirement, + ), + Err(FloorReadError::UnrecognizedVersion) => { + FloorVerificationStatus::Unverified( + FloorUnverifiedReason::UnrecognizedVersionRequirement, + ) + } + Err(FloorReadError::NotAnElf | FloorReadError::Unreadable) => { + FloorVerificationStatus::Unverified( + FloorUnverifiedReason::UnreadableCandidate, + ) + } + Err(FloorReadError::Malformed | FloorReadError::BoundExceeded) => { + FloorVerificationStatus::Unverified( + FloorUnverifiedReason::MalformedCandidate, + ) + } + } + } + }, + } +} + +/// The severity of an unverified reason, used to combine candidate results. +fn reason_rank(reason: FloorUnverifiedReason) -> u8 { + match reason { + FloorUnverifiedReason::UnreadableCandidate => 5, + FloorUnverifiedReason::MalformedCandidate => 4, + FloorUnverifiedReason::UnrecognizedVersionRequirement => 3, + FloorUnverifiedReason::NoVersionRequirement => 2, + FloorUnverifiedReason::FloorKindNotVerifiable => 1, + FloorUnverifiedReason::PendingInspection => 0, + } +} + +/// The severity of a floor status, used to combine candidate results. +fn status_rank(status: FloorVerificationStatus) -> (u8, u8) { + match status { + FloorVerificationStatus::NotSatisfied => (5, 0), + FloorVerificationStatus::Unverified(reason) => (4, reason_rank(reason)), + FloorVerificationStatus::Verified => (3, 0), + FloorVerificationStatus::ToolchainBound => (2, 0), + FloorVerificationStatus::NotDeclared => (1, 0), + } +} + +/// Combine the per-candidate floor statuses of one target into one status. +/// +/// The combination is deterministic and conservative: a contradiction +/// dominates, an unverified reason dominates a positive claim, and the most +/// severe reason wins among unverified candidates. +pub(crate) fn aggregate_floor_status( + statuses: &[FloorVerificationStatus], +) -> FloorVerificationStatus { + let mut combined: Option = None; + for status in statuses { + combined = Some(match combined { + None => *status, + Some(current) => { + if status_rank(*status) > status_rank(current) { + *status + } else { + current + } + } + }); + } + combined.unwrap_or(FloorVerificationStatus::Unverified( + FloorUnverifiedReason::UnreadableCandidate, + )) +} + +#[cfg(test)] +pub(crate) mod test_support { + use super::{DT_NULL, DT_STRTAB, DT_VERNEED, DT_VERNEEDNUM}; + + /// Builds minimal ELF images that carry symbol version requirements. + /// + /// The image is deliberately small and hand-built: one `PT_LOAD` segment + /// that maps the whole file, one `PT_DYNAMIC` segment, a dynamic table, + /// a version-requirement table, and a string table. + pub(crate) struct ElfBuilder { + class64: bool, + little_endian: bool, + versions: Vec, + program_header_count: Option, + dynamic_filesz: Option, + program_header_offset: Option, + } + + impl ElfBuilder { + /// Start a new image for the given ELF class and byte order. + pub(crate) fn new(class64: bool, little_endian: bool) -> Self { + Self { + class64, + little_endian, + versions: Vec::new(), + program_header_count: None, + dynamic_filesz: None, + program_header_offset: None, + } + } + + /// Set the version names carried by the version-requirement table. + pub(crate) fn versions(mut self, versions: &[&str]) -> Self { + self.versions = versions.iter().map(|value| (*value).to_owned()).collect(); + self + } + + /// Override the declared program header count. + pub(crate) fn program_header_count(mut self, count: u16) -> Self { + self.program_header_count = Some(count); + self + } + + /// Override the declared size of the dynamic segment. + pub(crate) fn dynamic_filesz(mut self, filesz: u64) -> Self { + self.dynamic_filesz = Some(filesz); + self + } + + /// Override the declared program header table offset. + pub(crate) fn program_header_offset(mut self, offset: u64) -> Self { + self.program_header_offset = Some(offset); + self + } + + fn put_u16(&self, bytes: &mut [u8], offset: usize, value: u16) { + let raw = if self.little_endian { + value.to_le_bytes() + } else { + value.to_be_bytes() + }; + bytes[offset..offset + 2].copy_from_slice(&raw); + } + + fn put_u32(&self, bytes: &mut [u8], offset: usize, value: u32) { + let raw = if self.little_endian { + value.to_le_bytes() + } else { + value.to_be_bytes() + }; + bytes[offset..offset + 4].copy_from_slice(&raw); + } + + fn put_u64(&self, bytes: &mut [u8], offset: usize, value: u64) { + let raw = if self.little_endian { + value.to_le_bytes() + } else { + value.to_be_bytes() + }; + bytes[offset..offset + 8].copy_from_slice(&raw); + } + + /// Build the image bytes. + pub(crate) fn build(self) -> Vec { + let header_size = if self.class64 { 64 } else { 52 }; + let program_header_size = if self.class64 { 56 } else { 32 }; + let dynamic_entry_size = if self.class64 { 16 } else { 8 }; + let dynamic_entries = if self.versions.is_empty() { 2 } else { 4 }; + + let mut bytes = vec![0u8; header_size]; + bytes.resize(bytes.len() + 2 * program_header_size, 0); + let dynamic_offset = bytes.len() as u64; + bytes.resize(bytes.len() + dynamic_entries * dynamic_entry_size, 0); + let verneed_offset = bytes.len() as u64; + let verneed_size = if self.versions.is_empty() { + 0 + } else { + 16 * (1 + self.versions.len()) + }; + bytes.resize(bytes.len() + verneed_size, 0); + let strtab_offset = bytes.len() as u64; + + let mut string_table = Vec::new(); + let mut name_offsets = Vec::new(); + for version in &self.versions { + name_offsets.push(string_table.len() as u32); + string_table.extend_from_slice(version.as_bytes()); + string_table.push(0); + } + bytes.extend_from_slice(&string_table); + let total = bytes.len() as u64; + + // ELF identification. + bytes[..4].copy_from_slice(b"\x7fELF"); + bytes[4] = if self.class64 { 2 } else { 1 }; + bytes[5] = if self.little_endian { 1 } else { 2 }; + bytes[6] = 1; + self.put_u16(&mut bytes, 16, 2); // e_type: ET_EXEC + self.put_u16(&mut bytes, 18, if self.class64 { 62 } else { 40 }); // e_machine + self.put_u32(&mut bytes, 20, 1); // e_version + let program_header_offset = self.program_header_offset.unwrap_or(header_size as u64); + if self.class64 { + self.put_u64(&mut bytes, 32, program_header_offset); + self.put_u16(&mut bytes, 52, header_size as u16); + self.put_u16(&mut bytes, 54, program_header_size as u16); + self.put_u16(&mut bytes, 56, self.program_header_count.unwrap_or(2)); + } else { + self.put_u32(&mut bytes, 28, program_header_offset as u32); + self.put_u16(&mut bytes, 40, header_size as u16); + self.put_u16(&mut bytes, 42, program_header_size as u16); + self.put_u16(&mut bytes, 44, self.program_header_count.unwrap_or(2)); + } + + // Program headers: one loadable segment and one dynamic segment. + let first = header_size; + let second = header_size + program_header_size; + let put_segment = |bytes: &mut Vec, + at: usize, + kind: u32, + offset: u64, + vaddr: u64, + filesz: u64| { + if self.class64 { + self.put_u32(bytes, at, kind); + self.put_u32(bytes, at + 4, 4); + self.put_u64(bytes, at + 8, offset); + self.put_u64(bytes, at + 16, vaddr); + self.put_u64(bytes, at + 24, vaddr); + self.put_u64(bytes, at + 32, filesz); + self.put_u64(bytes, at + 40, filesz); + self.put_u64(bytes, at + 48, 0x1000); + } else { + self.put_u32(bytes, at, kind); + self.put_u32(bytes, at + 4, offset as u32); + self.put_u32(bytes, at + 8, vaddr as u32); + self.put_u32(bytes, at + 12, vaddr as u32); + self.put_u32(bytes, at + 16, filesz as u32); + self.put_u32(bytes, at + 20, filesz as u32); + self.put_u32(bytes, at + 24, 4); + self.put_u32(bytes, at + 28, 0x1000); + } + }; + put_segment(&mut bytes, first, 1, 0, 0, total); + let dynamic_size = (dynamic_entries * dynamic_entry_size) as u64; + put_segment( + &mut bytes, + second, + 2, + dynamic_offset, + dynamic_offset, + self.dynamic_filesz.unwrap_or(dynamic_size), + ); + + // Dynamic table. + let dynamic_base = dynamic_offset as usize; + let put_dynamic = |bytes: &mut Vec, index: usize, tag: u64, value: u64| { + let at = dynamic_base + index * dynamic_entry_size; + if self.class64 { + self.put_u64(bytes, at, tag); + self.put_u64(bytes, at + 8, value); + } else { + self.put_u32(bytes, at, tag as u32); + self.put_u32(bytes, at + 4, value as u32); + } + }; + put_dynamic(&mut bytes, 0, DT_STRTAB, strtab_offset); + if self.versions.is_empty() { + put_dynamic(&mut bytes, 1, DT_NULL, 0); + } else { + put_dynamic(&mut bytes, 1, DT_VERNEED, verneed_offset); + put_dynamic(&mut bytes, 2, DT_VERNEEDNUM, 1); + put_dynamic(&mut bytes, 3, DT_NULL, 0); + } + + // Version-requirement table: one requirement with one auxiliary + // entry per version name. + if !self.versions.is_empty() { + let base = verneed_offset as usize; + self.put_u16(&mut bytes, base, 1); // vn_version + self.put_u16(&mut bytes, base + 2, self.versions.len() as u16); // vn_cnt + self.put_u32(&mut bytes, base + 4, 0); // vn_file + self.put_u32(&mut bytes, base + 8, 16); // vn_aux + self.put_u32(&mut bytes, base + 12, 0); // vn_next + for (index, name_offset) in name_offsets.iter().enumerate() { + let at = base + 16 + index * 16; + self.put_u32(&mut bytes, at, 0); // vna_hash + self.put_u16(&mut bytes, at + 4, 0); // vna_flags + self.put_u16(&mut bytes, at + 6, (index + 1) as u16); // vna_other + self.put_u32(&mut bytes, at + 8, *name_offset); // vna_name + // The auxiliary entries form a chain: each one points at + // the next, and the last one ends the chain. + self.put_u32( + &mut bytes, + at + 12, + if index + 1 < self.versions.len() { + 16 + } else { + 0 + }, + ); // vna_next + } + } + bytes + } + } +} + +#[cfg(test)] +mod tests { + use super::test_support::ElfBuilder; + use super::*; + use crate::{ + BuildStrategy, CompatibilityFloor, HostArch, HostOs, Qualification, SupportTier, + TargetPolicy, ToolchainRequirement, + }; + + fn policy(floor: CompatibilityFloor, strategy: BuildStrategy) -> TargetPolicy { + TargetPolicy { + target: "x86_64-unknown-linux-gnu".into(), + strategy, + host_os: HostOs::Linux, + host_arch: HostArch::X86_64, + qualification_host: None, + toolchain: ToolchainRequirement { + rust: "1.89.0".into(), + cargo_zigbuild: None, + zig: None, + }, + floor, + qualification: Qualification::Native, + support: SupportTier::Required, + } + } + + fn glibc(major: u16, minor: u16) -> CompatibilityFloor { + CompatibilityFloor::Glibc { major, minor } + } + + fn write(bytes: &[u8]) -> std::path::PathBuf { + let root = crate::test_temp_dir("floor"); + let path = root.join("candidate"); + std::fs::write(&path, bytes).unwrap(); + path + } + + fn status_for(bytes: &[u8], floor: CompatibilityFloor) -> FloorVerificationStatus { + let path = write(bytes); + let status = inspect_candidate_floor(&path, &floor, BuildStrategy::NativeCargo); + std::fs::remove_dir_all(path.parent().unwrap()).unwrap(); + status + } + + #[test] + fn reader_reports_the_highest_required_glibc_version() { + let image = ElfBuilder::new(true, true) + .versions(&["GLIBC_2.17", "GLIBC_2.34", "GLIBC_2.2.5"]) + .build(); + let path = write(&image); + let required = read_glibc_requirement(&path).unwrap(); + assert_eq!( + required, + Some(GlibcVersion { + major: 2, + minor: 34, + patch: 0 + }) + ); + std::fs::remove_dir_all(path.parent().unwrap()).unwrap(); + } + + #[test] + fn reader_reports_no_requirement_when_the_image_has_none() { + // No version-requirement table at all. + let image = ElfBuilder::new(true, true).build(); + let path = write(&image); + assert_eq!(read_glibc_requirement(&path).unwrap(), None); + std::fs::remove_dir_all(path.parent().unwrap()).unwrap(); + // A version requirement that is not a glibc requirement. + let image = ElfBuilder::new(true, true) + .versions(&["CXXABI_1.3"]) + .build(); + let path = write(&image); + assert_eq!(read_glibc_requirement(&path).unwrap(), None); + std::fs::remove_dir_all(path.parent().unwrap()).unwrap(); + } + + #[test] + fn reader_reads_32_bit_and_big_endian_images() { + let image = ElfBuilder::new(false, true) + .versions(&["GLIBC_2.17"]) + .build(); + let path = write(&image); + assert_eq!( + read_glibc_requirement(&path).unwrap(), + Some(GlibcVersion { + major: 2, + minor: 17, + patch: 0 + }) + ); + std::fs::remove_dir_all(path.parent().unwrap()).unwrap(); + + let image = ElfBuilder::new(true, false) + .versions(&["GLIBC_2.17"]) + .build(); + let path = write(&image); + assert_eq!( + read_glibc_requirement(&path).unwrap(), + Some(GlibcVersion { + major: 2, + minor: 17, + patch: 0 + }) + ); + std::fs::remove_dir_all(path.parent().unwrap()).unwrap(); + } + + #[test] + fn reader_refuses_truncated_malformed_and_non_elf_inputs() { + // Not an ELF image at all. + let path = write(b"this is not an elf image"); + assert_eq!(read_glibc_requirement(&path), Err(FloorReadError::NotAnElf)); + std::fs::remove_dir_all(path.parent().unwrap()).unwrap(); + + // A truncated dynamic table. + let image = ElfBuilder::new(true, true) + .versions(&["GLIBC_2.17"]) + .build(); + let path = write(&image[..image.len() - 8]); + assert!(read_glibc_requirement(&path).is_err()); + std::fs::remove_dir_all(path.parent().unwrap()).unwrap(); + + // Truncated program headers. + let image = ElfBuilder::new(true, true) + .versions(&["GLIBC_2.17"]) + .build(); + let path = write(&image[..80]); + assert!(read_glibc_requirement(&path).is_err()); + std::fs::remove_dir_all(path.parent().unwrap()).unwrap(); + + // A program header table offset beyond the file. + let image = ElfBuilder::new(true, true) + .versions(&["GLIBC_2.17"]) + .program_header_offset(1 << 30) + .build(); + let path = write(&image); + assert!(read_glibc_requirement(&path).is_err()); + std::fs::remove_dir_all(path.parent().unwrap()).unwrap(); + } + + #[test] + fn reader_refuses_oversized_tables_instead_of_parsing_them() { + let image = ElfBuilder::new(true, true) + .versions(&["GLIBC_2.17"]) + .program_header_count(4096) + .build(); + let path = write(&image); + assert_eq!( + read_glibc_requirement(&path), + Err(FloorReadError::BoundExceeded) + ); + std::fs::remove_dir_all(path.parent().unwrap()).unwrap(); + + let image = ElfBuilder::new(true, true) + .versions(&["GLIBC_2.17"]) + .dynamic_filesz(1 << 20) + .build(); + let path = write(&image); + assert_eq!( + read_glibc_requirement(&path), + Err(FloorReadError::BoundExceeded) + ); + std::fs::remove_dir_all(path.parent().unwrap()).unwrap(); + } + + #[test] + fn comparison_direction_requires_the_newest_version_to_fit_under_the_floor() { + let newer = ElfBuilder::new(true, true) + .versions(&["GLIBC_2.34"]) + .build(); + let equal = ElfBuilder::new(true, true) + .versions(&["GLIBC_2.17"]) + .build(); + let older = ElfBuilder::new(true, true) + .versions(&["GLIBC_2.2.5"]) + .build(); + assert_eq!( + status_for(&newer, glibc(2, 17)), + FloorVerificationStatus::NotSatisfied + ); + assert_eq!( + status_for(&equal, glibc(2, 17)), + FloorVerificationStatus::Verified + ); + assert_eq!( + status_for(&older, glibc(2, 17)), + FloorVerificationStatus::Verified + ); + // A binary that requires an older glibc satisfies a newer floor. + assert_eq!( + status_for(&older, glibc(2, 34)), + FloorVerificationStatus::Verified + ); + // A patch component is a real requirement: 2.2.5 is newer than 2.2. + assert_eq!( + status_for(&older, glibc(2, 2)), + FloorVerificationStatus::NotSatisfied + ); + } + + #[test] + fn an_image_without_a_version_requirement_is_recorded_specifically() { + let image = ElfBuilder::new(true, true).build(); + assert_eq!( + status_for(&image, glibc(2, 17)), + FloorVerificationStatus::Unverified(FloorUnverifiedReason::NoVersionRequirement) + ); + } + + #[test] + fn a_malformed_candidate_is_never_verified() { + assert_eq!( + status_for(b"not an elf", glibc(2, 17)), + FloorVerificationStatus::Unverified(FloorUnverifiedReason::UnreadableCandidate) + ); + let image = ElfBuilder::new(true, true) + .versions(&["GLIBC_2.17"]) + .build(); + assert_eq!( + status_for(&image[..image.len() - 8], glibc(2, 17)), + FloorVerificationStatus::Unverified(FloorUnverifiedReason::MalformedCandidate) + ); + } + + #[test] + fn an_unrecognized_version_name_is_never_verified() { + let image = ElfBuilder::new(true, true) + .versions(&["GLIBC_ABI_DT_RELR"]) + .build(); + assert_eq!( + status_for(&image, glibc(2, 17)), + FloorVerificationStatus::Unverified( + FloorUnverifiedReason::UnrecognizedVersionRequirement + ) + ); + } + + #[test] + fn the_plan_status_is_derived_from_the_policy() { + assert_eq!( + planned_floor_status(&policy( + CompatibilityFloor::None, + BuildStrategy::NativeCargo + )), + FloorVerificationStatus::NotDeclared + ); + assert_eq!( + planned_floor_status(&policy(glibc(2, 17), BuildStrategy::CargoZigbuild)), + FloorVerificationStatus::ToolchainBound + ); + assert_eq!( + planned_floor_status(&policy(glibc(2, 17), BuildStrategy::NativeCargo)), + FloorVerificationStatus::Unverified(FloorUnverifiedReason::PendingInspection) + ); + assert_eq!( + planned_floor_status(&policy( + CompatibilityFloor::Macos { + major: 13, + minor: 0 + }, + BuildStrategy::NativeCargo + )), + FloorVerificationStatus::Unverified(FloorUnverifiedReason::FloorKindNotVerifiable) + ); + } + + #[test] + fn admissible_statuses_are_closed_per_declaration() { + assert!(floor_status_admissible( + &CompatibilityFloor::None, + BuildStrategy::NativeCargo, + FloorVerificationStatus::NotDeclared + )); + assert!(!floor_status_admissible( + &CompatibilityFloor::None, + BuildStrategy::NativeCargo, + FloorVerificationStatus::Verified + )); + assert!(floor_status_admissible( + &glibc(2, 17), + BuildStrategy::CargoZigbuild, + FloorVerificationStatus::ToolchainBound + )); + assert!(!floor_status_admissible( + &glibc(2, 17), + BuildStrategy::CargoZigbuild, + FloorVerificationStatus::Verified + )); + assert!(floor_status_admissible( + &glibc(2, 17), + BuildStrategy::NativeCargo, + FloorVerificationStatus::Verified + )); + assert!(floor_status_admissible( + &glibc(2, 17), + BuildStrategy::NativeCargo, + FloorVerificationStatus::NotSatisfied + )); + assert!(!floor_status_admissible( + &glibc(2, 17), + BuildStrategy::NativeCargo, + FloorVerificationStatus::ToolchainBound + )); + } + + #[test] + fn combined_statuses_keep_the_most_severe_result() { + assert_eq!( + aggregate_floor_status(&[ + FloorVerificationStatus::Verified, + FloorVerificationStatus::NotSatisfied + ]), + FloorVerificationStatus::NotSatisfied + ); + assert_eq!( + aggregate_floor_status(&[ + FloorVerificationStatus::Verified, + FloorVerificationStatus::Unverified(FloorUnverifiedReason::NoVersionRequirement) + ]), + FloorVerificationStatus::Unverified(FloorUnverifiedReason::NoVersionRequirement) + ); + assert_eq!( + aggregate_floor_status(&[ + FloorVerificationStatus::Unverified(FloorUnverifiedReason::NoVersionRequirement), + FloorVerificationStatus::Unverified(FloorUnverifiedReason::UnreadableCandidate) + ]), + FloorVerificationStatus::Unverified(FloorUnverifiedReason::UnreadableCandidate) + ); + assert_eq!( + aggregate_floor_status(&[FloorVerificationStatus::Verified]), + FloorVerificationStatus::Verified + ); + } +} diff --git a/crates/eggpack-core/src/lib.rs b/crates/eggpack-core/src/lib.rs index 1fcb5d7..ed7d9a6 100644 --- a/crates/eggpack-core/src/lib.rs +++ b/crates/eggpack-core/src/lib.rs @@ -5,10 +5,12 @@ mod builder; pub mod digest; mod finalization; +mod floor; mod qualification; pub use builder::*; pub use digest::*; pub use finalization::*; +pub use floor::*; pub use qualification::*; use eggpack_contract::{ @@ -620,6 +622,15 @@ pub struct PlannedTarget { pub policy: TargetPolicy, /// Artifact identity derived exclusively from the contract. pub artifact_form: PlannedAssetForm, + /// Verification status of the declared compatibility floor. + /// + /// The status is derived from the policy by + /// [`planned_floor_status`], so a plan either states the status its + /// declaration implies or it is rejected. A document that omits the field + /// is read as `NotDeclared`, which is refused for any target that + /// declares a floor. + #[serde(default)] + pub floor_status: FloorVerificationStatus, } /// Contract-derived release artifact form. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] @@ -633,8 +644,13 @@ pub enum PlannedAssetForm { Archive, } impl ReleasePlan { - /// Serialize the canonically ordered plan as deterministic compact JSON. - pub fn to_json(&self) -> Result { + /// Validate the plan's bounds and the agreement between each declared + /// floor and the floor status the plan states for it. + /// + /// A plan that declares a floor and does not state a status for it is + /// invalid: the status is a pure function of the policy, so a missing or + /// contradictory status fails closed. + pub fn validate(&self) -> Result<(), CoreError> { if self.schema_version != 1 || self.release_id.is_empty() || self.source_revision.is_empty() @@ -642,6 +658,18 @@ impl ReleasePlan { { return Err(err("invalid ReleasePlan bounds")); } + for planned in &self.targets { + if planned.floor_status != planned_floor_status(&planned.policy) { + return Err(err( + "ReleasePlan floor status does not match the declared compatibility floor", + )); + } + } + Ok(()) + } + /// Serialize the canonically ordered plan as deterministic compact JSON. + pub fn to_json(&self) -> Result { + self.validate()?; serde_json::to_string(self).map_err(|_| err("ReleasePlan serialization failed")) } } @@ -718,10 +746,12 @@ impl PackConfig { eggpack_contract::AssetForm::Bundle { .. } => PlannedAssetForm::Bundle, eggpack_contract::AssetForm::Archive { .. } => PlannedAssetForm::Archive, }; + let floor_status = planned_floor_status(&policy); targets.push(PlannedTarget { target: t.triple.clone(), policy, artifact_form, + floor_status, }); } if targets.is_empty() { @@ -805,6 +835,71 @@ mod tests { .is_err()); } #[test] + fn a_native_cargo_glibc_floor_is_recorded_in_the_plan_and_still_resolves() { + let contract = DistributionContract::parse_toml_str(include_str!( + "../../eggpack-contract/tests/fixtures/simple-direct.toml" + )) + .unwrap(); + let config = PackConfig { + schema_version: 1, + targets: vec![TargetPolicy { + target: "x86_64-unknown-linux-gnu".into(), + strategy: BuildStrategy::NativeCargo, + host_os: HostOs::Linux, + host_arch: HostArch::X86_64, + qualification_host: None, + toolchain: ToolchainRequirement { + rust: "1.89.0".into(), + cargo_zigbuild: None, + zig: None, + }, + floor: CompatibilityFloor::Glibc { + major: 2, + minor: 17, + }, + qualification: Qualification::Native, + support: SupportTier::Required, + }], + }; + let selected = vec!["linux-x64".into()]; + // A declared glibc floor under native Cargo is still accepted, and it + // is no longer dropped: it survives into the plan with a status. + let plan = config + .resolve(&contract, "1.2.6", "abc", &selected) + .unwrap(); + assert_eq!( + plan.targets[0].policy.floor, + CompatibilityFloor::Glibc { + major: 2, + minor: 17 + } + ); + assert_eq!( + plan.targets[0].floor_status, + FloorVerificationStatus::Unverified(FloorUnverifiedReason::PendingInspection) + ); + assert!(plan.validate().is_ok()); + assert!(plan.to_json().is_ok()); + // A plan whose declared floor and stated status disagree is refused. + let mut contradictory = plan.clone(); + contradictory.targets[0].floor_status = FloorVerificationStatus::NotDeclared; + assert!(contradictory.validate().is_err()); + assert!(contradictory.to_json().is_err()); + // A cargo-zigbuild target binds the floor into the toolchain instead. + let mut cross_tool = config.clone(); + cross_tool.targets[0].strategy = BuildStrategy::CargoZigbuild; + cross_tool.targets[0].toolchain.cargo_zigbuild = Some("0.23.3".into()); + cross_tool.targets[0].toolchain.zig = Some("0.14.1".into()); + let plan = cross_tool + .resolve(&contract, "1.2.6", "abc", &selected) + .unwrap(); + assert_eq!( + plan.targets[0].floor_status, + FloorVerificationStatus::ToolchainBound + ); + assert!(plan.validate().is_ok()); + } + #[test] fn pack_config_toml_is_versioned_bounded_and_rejects_unknown_fields() { let source = r#"schema_version=1 [[targets]] diff --git a/crates/eggpack-core/src/qualification.rs b/crates/eggpack-core/src/qualification.rs index d49c94d..7ac0a0a 100644 --- a/crates/eggpack-core/src/qualification.rs +++ b/crates/eggpack-core/src/qualification.rs @@ -5,8 +5,9 @@ use crate::{ run_qemu_process, run_qualification_process, CandidateArtifact, CommandSpec, ProcessEvidence, }, - file_digest, BuildAttempt, BuildBindingsV1, BuildCancellation, DigestError, HostArch, HostOs, - HostRequirement, LogicalOutputSelector, PlannedTarget, Qualification, ReleasePlan, SupportTier, + file_digest, BuildAttempt, BuildBindingsV1, BuildCancellation, DigestError, + FloorUnverifiedReason, FloorVerificationStatus, HostArch, HostOs, HostRequirement, + LogicalOutputSelector, PlannedTarget, Qualification, ReleasePlan, SupportTier, }; use eggpack_contract::DistributionContract; use serde::{Deserialize, Serialize}; @@ -225,6 +226,9 @@ pub enum QualificationFailure { EmulatorFailed, /// Candidate could not be safely read or its runtime preconditions failed. InvalidRuntimeEnvironment, + /// The produced bytes require a newer runtime than the declared + /// compatibility floor, so the declared floor is false. + FloorNotSatisfied, } /// Supported executable file formats checked structurally. @@ -305,6 +309,15 @@ pub struct QualificationEvidence { pub support: SupportTier, /// Typed result. pub status: QualificationStatus, + /// Verification status of the declared compatibility floor. + /// + /// The status is bound to the exact bytes this record describes: it is + /// computed from the inspected candidate, never from a smoke run, because + /// native execution is never floor proof (ADR-0005 §9). A document that + /// omits the field is read as `NotDeclared`, which is refused for any + /// target that declares a floor. + #[serde(default)] + pub floor: FloorVerificationStatus, /// Per-candidate evidence ordered by logical selector. pub candidates: Vec, /// Configured smoke selector, if this mode has a smoke check. @@ -334,6 +347,17 @@ impl QualificationEvidence { && self.candidates.len() != attempt.candidates.len()) || self.candidates.len() > 256 || self.processes.len() > 1 + MAX_ARGS + || target.floor_status != crate::planned_floor_status(&target.policy) + || !crate::floor_status_admissible( + &target.policy.floor, + target.policy.strategy, + self.floor, + ) + || (self.floor == FloorVerificationStatus::NotSatisfied) + != matches!( + self.status, + QualificationStatus::Failed(QualificationFailure::FloorNotSatisfied) + ) { return Err(qerr( "qualification evidence identity or bounds are invalid", @@ -356,11 +380,7 @@ impl QualificationEvidence { || record.package != candidate.package || record.binary != candidate.binary || record.size != candidate.size - || record.sha256.len() != 64 - || !record - .sha256 - .bytes() - .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase()) + || crate::validate_sha256_hex(&record.sha256).is_err() { return Err(qerr("qualification evidence candidate identity is invalid")); } @@ -640,9 +660,13 @@ where } let mut evidence_candidates = Vec::new(); + let mut candidate_floors = Vec::new(); for (selector, (_, _, candidate)) in &actual { - match inspect_candidate(candidate, &target.target) { - Ok(value) => evidence_candidates.push(value), + match inspect_candidate(candidate, target) { + Ok(inspected) => { + candidate_floors.push(inspected.floor); + evidence_candidates.push(inspected.evidence); + } Err(failure) => { let method = match target.policy.qualification { Qualification::Native => QualificationMethod::Native, @@ -659,6 +683,7 @@ where Vec::new(), None, Vec::new(), + FloorVerificationStatus::Unverified(FloorUnverifiedReason::UnreadableCandidate), )); } } @@ -667,6 +692,7 @@ where Some(selector) ); } + let floor = crate::floor::aggregate_floor_status(&candidate_floors); let settings = qualification_bindings .targets .get(&target.target) @@ -676,6 +702,28 @@ where if smoke.is_some() && selected_smoke.is_none() { return Err(qerr("smoke selector is absent from candidate inventory")); } + // A declared floor that the produced bytes contradict is false, so it + // fails the qualification for this target before anything executes. It is + // never reported as merely unverified. + if floor == FloorVerificationStatus::NotSatisfied { + let method = match target.policy.qualification { + Qualification::Native => QualificationMethod::Native, + Qualification::DeferredNative => QualificationMethod::Deferred, + Qualification::Emulated => QualificationMethod::QemuUser, + Qualification::Structural => QualificationMethod::Structural, + }; + return Ok(make_evidence( + plan, + target, + host, + method, + QualificationStatus::Failed(QualificationFailure::FloorNotSatisfied), + evidence_candidates, + smoke.map(|s| s.selector.clone()), + Vec::new(), + floor, + )); + } let (method, should_execute) = match target.policy.qualification { Qualification::Structural => (QualificationMethod::Structural, false), @@ -694,6 +742,7 @@ where evidence_candidates, smoke.map(|s| s.selector.clone()), Vec::new(), + floor, )); } (QualificationMethod::Native, true) @@ -713,6 +762,7 @@ where evidence_candidates, smoke.map(|s| s.selector.clone()), Vec::new(), + floor, )); } if !target_matches_host(&target.target, host) { @@ -725,6 +775,7 @@ where evidence_candidates, smoke.map(|s| s.selector.clone()), Vec::new(), + floor, )); } (QualificationMethod::DeferredNativeOnNativeHost, true) @@ -744,6 +795,7 @@ where evidence_candidates, smoke.map(|s| s.selector.clone()), Vec::new(), + floor, )); } if target @@ -760,6 +812,7 @@ where evidence_candidates, smoke.map(|s| s.selector.clone()), Vec::new(), + floor, )); } (QualificationMethod::QemuUser, true) @@ -775,6 +828,7 @@ where evidence_candidates, None, Vec::new(), + floor, )); } let smoke = smoke.ok_or_else(|| qerr("execution qualification requires a smoke binding"))?; @@ -806,6 +860,7 @@ where evidence_candidates, Some(smoke.selector.clone()), processes, + floor, )) } }; @@ -825,6 +880,7 @@ where evidence_candidates, Some(smoke.selector.clone()), processes, + floor, )); } } @@ -838,6 +894,7 @@ where evidence_candidates, Some(smoke.selector.clone()), processes, + floor, )); } let (command, is_qemu) = if method == QualificationMethod::QemuUser { @@ -885,6 +942,7 @@ where evidence_candidates, Some(smoke.selector.clone()), processes, + floor, )) } }; @@ -897,13 +955,14 @@ where let mut status = status; if status == QualificationStatus::Passed { for (selector, (_, _, candidate)) in &actual { - match inspect_candidate(candidate, &target.target) { + match inspect_candidate(candidate, target) { Ok(after) => { let before = evidence_candidates .iter() .find(|evidence| &evidence.selector == selector) .expect("preflight candidate evidence"); - if after.size != before.size || after.sha256 != before.sha256 { + if after.evidence.size != before.size || after.evidence.sha256 != before.sha256 + { status = QualificationStatus::Failed(QualificationFailure::CandidateChanged); break; @@ -925,6 +984,7 @@ where evidence_candidates, Some(smoke.selector.clone()), processes, + floor, )) } @@ -938,6 +998,7 @@ fn make_evidence( candidates: Vec, smoke_selector: Option, processes: Vec, + floor: FloorVerificationStatus, ) -> QualificationEvidence { QualificationEvidence { schema_version: 1, @@ -949,6 +1010,7 @@ fn make_evidence( actual_host: host, support: target.policy.support, status, + floor, candidates, smoke_selector, processes, @@ -1086,10 +1148,20 @@ fn target_identity(target: &str) -> Option<(CandidateFormat, CandidateArchitectu Some((format, architecture)) } +/// One inspected candidate: its byte and structural identity, plus the floor +/// status computed from the same bytes. +#[derive(Debug, PartialEq, Eq)] +struct CandidateInspection { + /// Byte and structural identity of the candidate. + evidence: QualifiedCandidateEvidence, + /// Verification status of the declared compatibility floor. + floor: FloorVerificationStatus, +} + fn inspect_candidate( candidate: &CandidateArtifact, - target: &str, -) -> Result { + target: &PlannedTarget, +) -> Result { let metadata = fs::symlink_metadata(&candidate.path) .map_err(|_| QualificationFailure::InvalidRuntimeEnvironment)?; if !candidate.path.is_absolute() @@ -1126,12 +1198,20 @@ fn inspect_candidate( return Err(QualificationFailure::InvalidRuntimeEnvironment); } let (expected_format, expected_arch) = - target_identity(target).ok_or(QualificationFailure::StructuralMismatch)?; + target_identity(&target.target).ok_or(QualificationFailure::StructuralMismatch)?; let format_arch = parse_binary_header(&canonical, expected_format) .ok_or(QualificationFailure::StructuralMismatch)?; if format_arch != (expected_format, expected_arch) { return Err(QualificationFailure::StructuralMismatch); } + // The declared floor is inspected against these exact bytes, never + // against a smoke run: native execution is not floor proof (ADR-0005 §9). + // The status therefore describes the same bytes the digest below records. + let floor = crate::floor::inspect_candidate_floor( + &canonical, + &target.policy.floor, + target.policy.strategy, + ); // The candidate bytes are digested by the crate's single file-digest // authority, so qualification evidence and the release manifest describe // the same bytes under the same rules. @@ -1149,14 +1229,17 @@ fn inspect_candidate( { return Err(QualificationFailure::CandidateChanged); } - Ok(QualifiedCandidateEvidence { - selector: candidate.selector.clone(), - package: candidate.package.clone(), - binary: candidate.binary.clone(), - size, - sha256, - format: expected_format, - architecture: expected_arch, + Ok(CandidateInspection { + evidence: QualifiedCandidateEvidence { + selector: candidate.selector.clone(), + package: candidate.package.clone(), + binary: candidate.binary.clone(), + size, + sha256, + format: expected_format, + architecture: expected_arch, + }, + floor, }) } @@ -1318,6 +1401,7 @@ mod tests { support: SupportTier::Required, }, artifact_form: PlannedAssetForm::Direct, + floor_status: crate::FloorVerificationStatus::NotDeclared, }; let plan = ReleasePlan { schema_version: 1, @@ -1746,6 +1830,8 @@ stderr_limit = 1024 } else { crate::CompatibilityFloor::None }; + // The plan states the status its declaration implies. + target.floor_status = crate::planned_floor_status(&target.policy); attempt.strategy = BuildStrategy::CargoZigbuild; attempt.tool_summary = "rust 1.89.0 cargo-zigbuild 0.23.3 zig 0.14.1".into(); let plan = ReleasePlan { @@ -2099,6 +2185,7 @@ stderr_limit = 1024 support: SupportTier::NonGating, }, artifact_form: PlannedAssetForm::Direct, + floor_status: crate::FloorVerificationStatus::NotDeclared, }; let plan = ReleasePlan { schema_version: 1, @@ -2270,15 +2357,15 @@ stderr_limit = 1024 }; let (_contract, _plan, target, attempt, _builds, _quals, root) = fixture(Qualification::Structural, &bytes); - let before = inspect_candidate(&attempt.candidates[0], &target.target).unwrap(); + let before = inspect_candidate(&attempt.candidates[0], &target).unwrap(); let mut changed = bytes.clone(); // Keep the structural header intact on all host formats. The final // byte in the minimal PE fixture is part of its COFF machine field. changed[20] ^= 1; fs::write(&attempt.candidates[0].path, &changed).unwrap(); - let after = inspect_candidate(&attempt.candidates[0], &target.target).unwrap(); - assert_eq!(before.size, after.size); - assert_ne!(before.sha256, after.sha256); + let after = inspect_candidate(&attempt.candidates[0], &target).unwrap(); + assert_eq!(before.evidence.size, after.evidence.size); + assert_ne!(before.evidence.sha256, after.evidence.sha256); fs::remove_dir_all(root).unwrap(); } @@ -2296,14 +2383,14 @@ stderr_limit = 1024 fs::rename(&candidate.path, &original).unwrap(); symlink(&original, &candidate.path).unwrap(); assert_eq!( - inspect_candidate(candidate, &target.target), + inspect_candidate(candidate, &target), Err(QualificationFailure::InvalidRuntimeEnvironment) ); fs::remove_file(&candidate.path).unwrap(); fs::rename(original, &candidate.path).unwrap(); candidate.path = PathBuf::from("relative-candidate"); assert_eq!( - inspect_candidate(candidate, &target.target), + inspect_candidate(candidate, &target), Err(QualificationFailure::InvalidRuntimeEnvironment) ); fs::remove_dir_all(root).unwrap(); @@ -2466,9 +2553,29 @@ stderr_limit = 1024 path, size: bytes.len() as u64, }; - let evidence = inspect_candidate(&candidate, target_name).unwrap(); - assert_eq!(evidence.format, format); - assert_eq!(evidence.architecture, architecture); + let planned = PlannedTarget { + target: target_name.into(), + policy: TargetPolicy { + target: target_name.into(), + strategy: BuildStrategy::NativeCargo, + host_os: HostOs::Linux, + host_arch: HostArch::X86_64, + qualification_host: None, + toolchain: ToolchainRequirement { + rust: "stable".into(), + cargo_zigbuild: None, + zig: None, + }, + floor: crate::CompatibilityFloor::None, + qualification: Qualification::Structural, + support: SupportTier::Required, + }, + artifact_form: PlannedAssetForm::Direct, + floor_status: crate::FloorVerificationStatus::NotDeclared, + }; + let inspection = inspect_candidate(&candidate, &planned).unwrap(); + assert_eq!(inspection.evidence.format, format); + assert_eq!(inspection.evidence.architecture, architecture); fs::remove_dir_all(root).unwrap(); } } @@ -2534,6 +2641,7 @@ stderr_limit = 1024 support: SupportTier::Required, }, artifact_form: form, + floor_status: crate::FloorVerificationStatus::NotDeclared, }; let plan = ReleasePlan { schema_version: 1, @@ -2603,4 +2711,272 @@ stderr_limit = 1024 fs::remove_dir_all(root).unwrap(); } } + + /// A GNU/Linux target that declares a compatibility floor, with a + /// candidate that carries the given symbol version requirements. + /// + /// The target triple is pinned rather than host-adaptive: a glibc floor + /// only applies to a GNU/Linux triple, so the fixture must name one on + /// every host. + fn floor_fixture( + candidate_bytes: &[u8], + floor: crate::CompatibilityFloor, + ) -> ( + DistributionContract, + ReleasePlan, + PlannedTarget, + BuildAttempt, + BuildBindingsV1, + QualificationBindingsV1, + PathBuf, + ) { + let target_name = "x86_64-unknown-linux-gnu"; + let root = crate::test_temp_dir("floor-qualification"); + let path = candidate_path(&root, target_name); + fs::create_dir_all(path.parent().unwrap()).unwrap(); + fs::write(&path, candidate_bytes).unwrap(); + let policy = TargetPolicy { + target: target_name.into(), + strategy: BuildStrategy::NativeCargo, + host_os: HostOs::Linux, + host_arch: HostArch::X86_64, + qualification_host: None, + toolchain: ToolchainRequirement { + rust: "stable".into(), + cargo_zigbuild: None, + zig: None, + }, + floor, + qualification: Qualification::Structural, + support: SupportTier::Required, + }; + let floor_status = crate::planned_floor_status(&policy); + let target = PlannedTarget { + target: target_name.into(), + policy, + artifact_form: PlannedAssetForm::Direct, + floor_status, + }; + let plan = ReleasePlan { + schema_version: 1, + release_id: "v1".into(), + source_revision: "abc123".into(), + targets: vec![target.clone()], + }; + let build_bindings = BuildBindingsV1 { + schema_version: 1, + targets: [( + target_name.into(), + vec![crate::BuildBinding { + selector: LogicalOutputSelector::Direct, + package: "fixture".into(), + binary: "fixture".into(), + }], + )] + .into_iter() + .collect(), + }; + let qualification_bindings = QualificationBindingsV1 { + schema_version: 1, + targets: [( + target_name.into(), + TargetQualificationBinding { smoke: None }, + )] + .into_iter() + .collect(), + }; + let attempt = BuildAttempt { + release_id: plan.release_id.clone(), + source_revision: plan.source_revision.clone(), + target: target_name.into(), + strategy: BuildStrategy::NativeCargo, + tool_summary: "rust stable".into(), + process: ProcessEvidence { + outcome: CommandOutcome::Success, + stdout_bytes: 0, + stderr_bytes: 0, + }, + candidates: vec![CandidateArtifact { + target: target_name.into(), + selector: LogicalOutputSelector::Direct, + package: "fixture".into(), + binary: "fixture".into(), + path, + size: candidate_bytes.len() as u64, + }], + }; + ( + contract(target_name), + plan, + target, + attempt, + build_bindings, + qualification_bindings, + root, + ) + } + + fn glibc_floor(major: u16, minor: u16) -> crate::CompatibilityFloor { + crate::CompatibilityFloor::Glibc { major, minor } + } + + fn floor_candidate(versions: &[&str]) -> Vec { + crate::floor::test_support::ElfBuilder::new(true, true) + .versions(versions) + .build() + } + + fn qualify_floor_fixture( + bytes: &[u8], + floor: crate::CompatibilityFloor, + ) -> ( + QualificationEvidence, + ReleasePlan, + PlannedTarget, + BuildAttempt, + PathBuf, + ) { + let (contract, plan, target, attempt, builds, quals, root) = floor_fixture(bytes, floor); + let evidence = qualify_target_for_host( + &contract, + &plan, + &target, + &attempt, + &builds, + &quals, + &QualificationRuntime::default(), + &BuildCancellation::new(), + local_host(), + ) + .unwrap(); + (evidence, plan, target, attempt, root) + } + + #[test] + fn a_native_glibc_floor_is_verified_against_the_inspected_bytes() { + let bytes = floor_candidate(&["GLIBC_2.17"]); + let (evidence, plan, target, attempt, root) = + qualify_floor_fixture(&bytes, glibc_floor(2, 17)); + assert_eq!(evidence.floor, FloorVerificationStatus::Verified); + assert_eq!(evidence.status, QualificationStatus::Passed); + assert!(evidence.validate_for(&plan, &target, &attempt).is_ok()); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn a_glibc_floor_contradicted_by_the_bytes_fails_the_qualification() { + let bytes = floor_candidate(&["GLIBC_2.34"]); + let (evidence, plan, target, attempt, root) = + qualify_floor_fixture(&bytes, glibc_floor(2, 17)); + // The declared floor is false, so the qualification fails closed. It is + // never reported as merely unverified. + assert_eq!( + evidence.status, + QualificationStatus::Failed(QualificationFailure::FloorNotSatisfied) + ); + assert_eq!(evidence.floor, FloorVerificationStatus::NotSatisfied); + assert!(!matches!( + evidence.floor, + FloorVerificationStatus::Unverified(_) + )); + assert!(evidence.processes.is_empty()); + assert!(evidence.validate_for(&plan, &target, &attempt).is_ok()); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn a_candidate_without_a_version_requirement_records_that_specifically() { + let bytes = floor_candidate(&[]); + let (evidence, plan, target, attempt, root) = + qualify_floor_fixture(&bytes, glibc_floor(2, 17)); + // Compatible with any floor, but not a confirmation of one: the + // status says so specifically and is not a generic pass. + assert_eq!( + evidence.floor, + FloorVerificationStatus::Unverified(FloorUnverifiedReason::NoVersionRequirement) + ); + assert_ne!(evidence.floor, FloorVerificationStatus::Verified); + // An unverifiable floor is a recorded status, not a failed release. + assert_eq!(evidence.status, QualificationStatus::Passed); + assert!(evidence.validate_for(&plan, &target, &attempt).is_ok()); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn a_malformed_candidate_is_never_floor_verified() { + // A well-formed ELF header with a truncated dynamic table: the + // structural inspection still passes, the floor inspection cannot. + let mut bytes = floor_candidate(&["GLIBC_2.17"]); + bytes.truncate(bytes.len() - 8); + let (evidence, plan, target, attempt, root) = + qualify_floor_fixture(&bytes, glibc_floor(2, 17)); + assert_eq!( + evidence.floor, + FloorVerificationStatus::Unverified(FloorUnverifiedReason::MalformedCandidate) + ); + assert_ne!(evidence.floor, FloorVerificationStatus::Verified); + assert!(evidence.validate_for(&plan, &target, &attempt).is_ok()); + fs::remove_dir_all(root).unwrap(); + + // A candidate that is not an ELF image at all. + let (evidence, plan, target, attempt, root) = + qualify_floor_fixture(b"not an elf image", glibc_floor(2, 17)); + assert_eq!( + evidence.floor, + FloorVerificationStatus::Unverified(FloorUnverifiedReason::UnreadableCandidate) + ); + assert_ne!(evidence.floor, FloorVerificationStatus::Verified); + assert_eq!( + evidence.status, + QualificationStatus::Failed(QualificationFailure::StructuralMismatch) + ); + assert!(evidence.validate_for(&plan, &target, &attempt).is_ok()); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn a_plan_that_declares_a_floor_without_a_status_is_rejected() { + let bytes = floor_candidate(&["GLIBC_2.17"]); + let (_contract, plan, _target, _attempt, _builds, _quals, root) = + floor_fixture(&bytes, glibc_floor(2, 17)); + assert_eq!( + plan.targets[0].policy.floor, + glibc_floor(2, 17), + "the declared floor must survive into the plan" + ); + assert!(plan.validate().is_ok()); + // A document that omits the status is read as `NotDeclared`, which is + // refused for a target that declares a floor. + let mut document = + serde_json::from_str::(&plan.to_json().unwrap()).unwrap(); + document["targets"][0] + .as_object_mut() + .unwrap() + .remove("floor_status"); + let parsed: ReleasePlan = serde_json::from_value(document).unwrap(); + assert_eq!( + parsed.targets[0].floor_status, + FloorVerificationStatus::NotDeclared + ); + assert!(parsed.validate().is_err()); + assert!(parsed.to_json().is_err()); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn evidence_that_contradicts_the_plan_floor_is_rejected() { + let bytes = floor_candidate(&["GLIBC_2.17"]); + let (mut evidence, plan, target, attempt, root) = + qualify_floor_fixture(&bytes, glibc_floor(2, 17)); + // The plan declares a floor, so the evidence cannot claim that no + // floor was declared. + evidence.floor = FloorVerificationStatus::NotDeclared; + assert!(evidence.validate_for(&plan, &target, &attempt).is_err()); + // A contradiction is only admissible together with the matching + // failure, so a contradiction claimed with a passing record is + // refused too. + evidence.floor = FloorVerificationStatus::NotSatisfied; + assert!(evidence.validate_for(&plan, &target, &attempt).is_err()); + fs::remove_dir_all(root).unwrap(); + } } From 282430b69ff22e5893610b0fcf7604383d182e9b Mon Sep 17 00:00:00 2001 From: doc Date: Fri, 23 Oct 2026 15:49:04 +0000 Subject: [PATCH 08/46] plans: close Build/Qualification M008 compatibility floor verification Close Build/Qualification M008 on implementation `7e7cb6a`. A declared compatibility floor is no longer accepted and then silently dropped under `NativeCargo`. Every target declaring one now carries a finite, closed floor verification status on the `ReleasePlan` and on the `QualificationEvidence`, computed by bounded independent ELF `GLIBC_x.y` inspection of the exact bytes the digest authority hashes. A contradicted floor fails closed as `FloorNotSatisfied` and is never reported as merely unverified; a merely unverifiable floor is a recorded status, not a failed release. The `CargoZigbuild` triple rewrite and the macOS-under-zigbuild refusal are byte-unchanged, and the refusal still fires at build-command time rather than moving to declaration time. `ReleaseManifest` v1 and the published `eggpack-manifest` crate are untouched. This milestone also discharges the residual SHA-256 acceptance set ADR-0006 required `eggpack-core` to consume: `qualification.rs` now routes its candidate digest check through the canonical `validate_sha256_hex`, so the all-zeros digest is refused there like everywhere else in the producer. Mach-O deployment-target verification and publishing floor evidence to consumers are recorded as named follow-ons, not implicit omissions. --- .../closure/build-qualification/008-status.md | 177 ++++++++++++++++++ plans/registry.md | 12 +- .../subsystems/build-qualification-roadmap.md | 6 +- 3 files changed, 186 insertions(+), 9 deletions(-) create mode 100644 plans/closure/build-qualification/008-status.md diff --git a/plans/closure/build-qualification/008-status.md b/plans/closure/build-qualification/008-status.md new file mode 100644 index 0000000..bfee6cc --- /dev/null +++ b/plans/closure/build-qualification/008-status.md @@ -0,0 +1,177 @@ +# Build and Qualification Milestone 008 Closure — Compatibility Floor Verification Corrective + +Status: closed + +Source plan: `plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md` + +Roadmap: `plans/subsystems/build-qualification-roadmap.md` + +Related decisions: `plans/adrs/ADR-0005-native-qualification-for-cross-tool-builds.md` (§9 requires the independent floor verification this milestone implements); `plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md` (**accepted**, Option A — this milestone discharges the residual acceptance set ADR-0006 required `eggpack-core` to consume). + +Reviewed baseline: `9cf0bf8` (CI/Release M003l), on top of Build/Qualification M007 (`e3c6192`). + +Implementation SHA: `7e7cb6a` — `feat(core): record compatibility floor verification status`. + +## Executive finding + +M008 is closed. A declared compatibility floor is no longer silently dropped. Every target that declares a floor now carries a finite, closed **floor verification status** on both the producer's intent artifact (`ReleasePlan`) and the evidence for the exact candidate bytes (`QualificationEvidence`), and the status is computed by **independent bounded inspection of the produced ELF** rather than implied by the build strategy. + +The defect this corrects was specific and real: under `BuildStrategy::NativeCargo` a declared glibc floor was accepted at declaration and then dropped, and nothing downstream recorded that it went unverified. A native build on a modern host produces floor-compatible bytes by accident, and the producer's artifacts did not say so. + +Nothing was weakened. The `cargo-zigbuild` triple rewrite is byte-identical, the macOS-under-zigbuild refusal is byte-identical and still fires at build-command time rather than moving to declaration time, and `ReleaseManifest` v1 and the published `eggpack-manifest` crate are untouched. + +## The status model + +A finite, closed enum — not a free-form string, not an `Option`. Every variant maps to one concrete observation: + +| Status | Concrete observation | +|---|---| +| `NotDeclared` | the target declares `CompatibilityFloor::None` | +| `ToolchainBound` | the floor was bound into the build toolchain by the cargo-zigbuild triple rewrite, and the toolchain is trusted to honour it | +| `Verified` | the produced bytes were independently inspected and their highest required `GLIBC_x.y` version is not newer than the declared floor | +| `Unverified(reason)` | a floor was declared and the produced bytes did not confirm it, for a bounded reason | +| `NotSatisfied` | the produced bytes were independently inspected and require a newer runtime than the declared floor | + +`FloorUnverifiedReason` is likewise closed: `PendingInspection`, `UnreadableCandidate`, `MalformedCandidate`, `NoVersionRequirement`, `UnrecognizedVersionRequirement`, `FloorKindNotVerifiable`. + +The plan's §5.1 required **at least** `NotDeclared`, `ToolchainBound`, `Verified`, and `Unverified`. The fifth variant, `NotSatisfied`, exists because the plan's §7 requires a contradicted floor to **fail closed and MUST NOT be reported as `Unverified`**. Reporting a false declared floor as merely "unverified" would have been a weakening, so the contradiction is modelled as its own status and as its own hard failure. + +## Production implementation evidence + +| Location | Change | +|---|---| +| `crates/eggpack-core/src/floor.rs` (new, 1,260 lines) | The bounded ELF floor inspector and the status model: `FloorVerificationStatus` (`:72`), `FloorUnverifiedReason` (`:30`), `planned_floor_status` (`:105`) — the plan-time status, a pure function of the policy so a caller cannot choose it; `floor_status_admissible` (`:133`) — the plan/evidence cross-check; `inspect_candidate_floor` (`:591`); `aggregate_floor_status` (`:666`). | +| `crates/eggpack-core/src/floor.rs` | Bounded ELF reading: `MAX_ELF_HEADER` 64, `MAX_ELF_PROGRAM_HEADERS` 256, `MAX_ELF_DYNAMIC_ENTRIES` 1024, `MAX_ELF_VERSION_REQUIREMENTS` 256, `MAX_ELF_VERSION_AUXILIARIES` 256, `MAX_ELF_VERSION_NAME` 64. Every offset is checked against the file length and every read is exact-length, matching the existing `MAX_BINARY_HEADER` discipline. The reader locates `PT_DYNAMIC`, reads the dynamic table, and collects the `GLIBC_` symbol version names. | +| `crates/eggpack-core/src/lib.rs` | `PlannedTarget::floor_status` (`#[serde(default)]`) and `ReleasePlan::validate()` — public, and called by the plan's JSON serialization path. `resolve` derives the status from the policy. | +| `crates/eggpack-core/src/qualification.rs` | `QualificationEvidence::floor` records the status of the inspected bytes. `QualificationFailure::FloorNotSatisfied` is the hard failure for a contradicted floor. The inspection runs inside `inspect_candidate`, on the same canonical path the digest authority hashes, so the status is bound to the exact bytes that were digested. A contradicted floor short-circuits to `Failed(FloorNotSatisfied)` **before** any process executes. `validate_for` cross-checks the evidence's status against the plan's declared floor. | +| `crates/eggpack-core/src/qualification.rs:383` | The candidate digest acceptance check now calls `crate::validate_sha256_hex(&record.sha256).is_err()` instead of the inline 64-character lowercase-hex test. This discharges the residual ADR-0006 acceptance set. | +| `crates/eggpack-core/src/builder.rs`, `finalization.rs` | Fixture field additions only; the production `cargo_command` is untouched. | +| `crates/eggpack-ci/src/lib.rs` | The two named test fixtures only, one line each, adding `floor: eggpack_core::FloorVerificationStatus::NotDeclared`. No CI behaviour, rule, or message changed. | + +## The comparison direction, and why it is asserted + +The check compares `required_glibc <= declared_floor`. A binary requiring a **newer** glibc than declared does **not** satisfy the declared floor and fails it. The direction is the whole point of the rule, so it is asserted by test rather than left implicit. + +The three comparison cases the plan names: + +- required `2.34` against a declared `2.17` → `NotSatisfied` (fails the floor), **not** `Verified`; +- required `2.17` against a declared `2.17` → `Verified`; +- required older than declared → passes. + +A candidate with **no** `GLIBC_` version requirement is compatible with any declared floor, but it does not *confirm* one, so it is recorded as `Unverified(NoVersionRequirement)` — a distinct result, not a generic `Verified` and not an error. The plan required exactly this distinction. + +## ADR-0006 conformance — the residual acceptance set + +M003l's implementation audit found a **fourth** SHA-256 acceptance set that the original review inventory missed: `crates/eggpack-core/src/qualification.rs` validated a candidate's recorded digest inline with a 64-character lowercase-hex check and therefore **accepted the all-zeros digest**. + +ADR-0006 §5.1 item 1 requires the canonical SHA-256 hex validator — owned by `eggpack-manifest` — to be consumed by `eggpack-core`, `eggpack-ci`, and `eggpack-github`. This milestone owns `qualification.rs`, so it is here that the last in-core restatement of the rule was routed through `eggpack_core::validate_sha256_hex`. + +The acceptance set before and after: + +| | Before | After | +|---|---|---| +| 64 lowercase hex characters | accepted | accepted | +| all-zeros digest | **accepted** | **refused** | +| anything else | refused | refused | + +The diagnostic text was not changed: the refusal still reads `"qualification evidence candidate identity is invalid"`. + +## Requirement-to-evidence matrix + +| Plan requirement | Evidence and result | +|---|---| +| §12.1 — every target declaring a floor carries a finite, machine-readable status on the plan and the evidence; a missing or contradictory status is a validation error | `PlannedTarget::floor_status`, `QualificationEvidence::floor`, `ReleasePlan::validate()`, `floor_status_admissible`. A plan that declares a floor and omits the status deserializes as `NotDeclared` and is **rejected**. | +| §12.2 — the floor is no longer silently dropped under `NativeCargo`; the declared floor and its status are both present | `planned_floor_status` derives the plan-time status from the policy, including under `NativeCargo`; the regression test asserts a `NativeCargo` target with a declared glibc floor still resolves and still produces a valid plan. | +| §12.3 — the maximum required `GLIBC_x.y` is computed by bounded inspection and compared in the correct direction; a binary requiring a newer glibc fails closed | The bounded ELF reader and the `required <= declared` comparison; `NotSatisfied` plus `QualificationFailure::FloorNotSatisfied`. | +| §12.4 — a malformed or unreadable binary yields `Unverified` with a reason, never `Verified` | `UnreadableCandidate` and `MalformedCandidate`; a non-ELF input, a truncated dynamic table, and a truncated program header each produce a reason. | +| §12.5 — `ReleaseManifest` v1 and the published `eggpack-manifest` crate are unchanged | `git show --stat 7e7cb6a` lists no `eggpack-manifest` path; no `ReleaseManifest` field, shape, or `schema_version` changed anywhere. | +| §12.6 — the `CargoZigbuild` triple rewrite and the `Macos`-under-zigbuild refusal are byte-unchanged | The production `cargo_command` is untouched; the regression test `the_cargo_zigbuild_floor_rewrite_and_macos_refusal_are_unchanged` pins the rewritten triple byte-for-byte and asserts the message `"macOS floor cannot use cargo-zigbuild"`. `validate_policy` still applies only the triple half of the floor rule. | +| §7 — a contradicted floor is a hard failure and MUST NOT be reported as `Unverified` | `NotSatisfied` is a distinct status and `FloorNotSatisfied` is a distinct failure, asserted by test. | +| §7 — an unverifiable floor is a recorded status, not a hard failure of the release | `Unverified(reason)` is recorded on the evidence and does not fail the release. | +| §8 — no new dependency | `Cargo.toml` is untouched in every crate; the ELF reading uses the standard library and the existing `sha2` surface. | +| §8 — `PackConfig` v1 accepts the same documents | A target that declares a glibc floor under `NativeCargo` still resolves; it now carries a status. | +| §3 invariant — all parsing is bounded | Every table and offset has a fixed bound, and every read is exact-length. | +| ADR-0006 §5.1 — `eggpack-core` consumes the canonical SHA-256 validator | `qualification.rs:383`. | + +## Verification executed + +All verification below ran against implementation SHA `7e7cb6a`, scoped to the actual change as the maintainer directed for this stage: + +```text +cargo fmt --all -- --check passed +cargo check --workspace --all-targets --all-features --locked passed +cargo clippy --workspace --all-targets --all-features --locked -- -D warnings passed +cargo test -p eggpack-core --all-targets --all-features --locked passed (81 passed, 0 failed, 6 ignored; 61/6 before M008) +cargo test -p eggpack-ci --all-targets --all-features --locked passed (67 passed, 0 failed, 3 ignored) +cargo test -p eggpack-cli --all-targets --all-features --locked passed (27 passed + 8 passed, 0 failed) +git diff --check passed +``` + +The `eggpack-cli` test run was added because M008 changed the `ReleasePlan` and `QualificationEvidence` shapes that the CLI serializes; it proves the CLI still round-trips them. + +**Not run, by the maintainer's scope direction and by the absence of a push:** `./scripts/check-local.sh`, the `cargo +1.89.0` MSRV lane, the `cargo package` steps, and hosted CI. Plan §12.7 requires the full gate and a hosted run; neither was performed, and no hosted run is claimed here. The full local gate runs once at the end of the chain. + +## Observable behaviour changes + +1. **A glibc floor under `NativeCargo` is now independently inspected.** An ELF requiring a newer glibc than declared fails that target's qualification with `FloorNotSatisfied` instead of passing. +2. **`ReleasePlan` and `QualificationEvidence` JSON gain a `floor_status` / `floor` field.** A document that omits it deserializes as `NotDeclared` and is **rejected** when a floor is declared. A stale plan or evidence artifact produced before this commit now **fails closed**. Consumers that adopt the new shape must re-render and re-pin — this is recorded, as the plan's §8 requires. +3. **A `GLIBC_`-prefixed non-numeric version name** (for example `GLIBC_ABI_DT_RELR`) yields `Unverified(UnrecognizedVersionRequirement)`, never `Verified`. +4. **No refusal moved.** The macOS-under-zigbuild refusal still fires at *build-command* time with the byte-identical message `"macOS floor cannot use cargo-zigbuild"`. `validate_policy` still applies only the triple half of the floor rule, so `PackConfig::resolve` outcomes are unchanged. +5. `ReleaseManifest` v1 and `eggpack-manifest` are untouched. + +## Compatibility and no-regression evidence + +- **No `ReleaseManifest` change.** No field, no shape, no `schema_version` bump. The published `eggpack-manifest` crate needs no new release from this milestone. +- **No generated workflow byte changed.** No checked-in workflow declares a floor that changes meaning, so `eggpack ci check` drift status is unchanged for existing consumers. +- **No dependency added** in any crate. +- **No historical closure rewritten.** `plans/closure/build-qualification/001`–`007-status.md` and every other historical closure record are untouched. +- **Pre-existing tests stay green** across core, CI, and CLI. The CI crate's two test fixtures were the only CI-side change, one line each. + +## Security and reliability review + +- The change closes a **verification gap**, not a hole in a control. A declared floor previously produced no evidence at all under `NativeCargo`; it now produces evidence that says exactly what was and was not confirmed. +- The ELF reader is **bounded on every axis**: header size, program-header count, dynamic-entry count, version-requirement count, version-auxiliary count, and version-name length, with every offset checked against the file length and every read exact-length. A malformed or hostile binary cannot make the reader allocate or read without limit. +- The reader operates on the **same canonical path** the digest authority hashes, so the floor status and the recorded digest describe the same bytes. +- The comparison direction is asserted by test, so a future edit that inverts it fails the suite rather than silently passing a binary that requires a newer runtime than declared. +- No signature, provenance, or authenticity claim is introduced. The status is an **integrity fact about bytes against a declared policy**, not a claim about who produced them. +- No network, credential, privilege, archive, or publication surface is touched. + +## Failure and recovery review + +- A **contradicted** floor fails closed: the target's qualification fails with `FloorNotSatisfied` and no process executes against it. +- A merely **unverifiable** floor does not fail the release; it is recorded with a bounded reason, so a producer is not blocked by a binary it cannot inspect. +- A **missing** status is a validation error, not a default claim. +- A malformed, truncated, or non-ELF candidate yields `Unverified` with a reason, never `Verified`. +- The inspection is read-only and holds no lock; two concurrent inspections of the same candidate observe the same bytes or a changed-file error, each self-consistent. Restarting re-inspects from the beginning; no resumable state exists. +- Rollback is a revert of this single commit. The previously unrecorded floor returns, with no consumer impact beyond re-admitting an unverified floor silently. + +## Findings + +| Severity | Finding | Disposition | +|---|---|---| +| Resolved in this milestone (medium, plan accuracy) | The plan's §2 evidence inventory did not name the fourth SHA-256 acceptance set in `crates/eggpack-core/src/qualification.rs`, which accepted the all-zeros digest and therefore contradicted the ADR-0006 decision this chain implements. | Routed through `eggpack_core::validate_sha256_hex` in this milestone, which owns that file. Recorded in the M003l closure record as well, so neither record is silently inaccurate about it. | +| Medium (pre-existing gap, now named) | ADR-0005 §9 required independent floor verification to be planned. It now is, for GNU/Linux ELF. **Mach-O deployment-target verification is not implemented**: a macOS floor yields `Unverified(FloorKindNotVerifiable)`. | Recorded as a **named follow-on**, not an implicit omission, as the plan's §15 requires. | +| Low (pre-existing gap, now named) | Publishing floor evidence to consumers is not implemented. No `ReleaseManifest` field was added, because doing so is an ADR-triggering compatibility decision and the plan's §13 names it as a stop condition. | Recorded as a **named follow-on** requiring its own ADR. | +| Operational boundary | Verification ran on Linux x86-64 only. The macOS and Windows lanes are covered by hosted CI only, and no hosted run was performed because nothing was pushed. | Accepted; the same boundary every prior milestone recorded. Plan §12.7 is therefore **not** claimed as met. | +| None | No unresolved medium-or-higher defect in the corrected producer contract. | M008 acceptance criteria satisfied except §12.7, which is out of the maintainer's scoped verification. | + +## Roadmap disposition and dependency transitions + +| Milestone | Status after M008 | Reason | +|---|---|---| +| Build/Qualification M008 | closed | This record; implementation `7e7cb6a`. | +| Build/Qualification M009 | unblocked | Its plan-time surfaces (`ReleasePlan`, `QualificationEvidence`) are now stable, and its `plan` and `qualify` commands must call the new public `ReleasePlan::validate()`. | +| CI/Release M003m | ready | Unblocked by M003l; independent of this milestone. | +| CI/Release M003n | blocked | It follows CI M003m. | + +## Downstream-unblock answer + +Closing M008 unblocks **Build/Qualification M009**, which consumes the new `ReleasePlan::validate()` and the floor status shapes. It unblocks no CI milestone. + +## Eggstack references + +- Closed source plan: `plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md` +- Related accepted decisions: `plans/adrs/ADR-0005-native-qualification-for-cross-tool-builds.md` (§9), `plans/adrs/ADR-0006-release-evidence-digest-acceptance-set.md` (Option A) +- Predecessor in this chain: `plans/closure/build-qualification/007-status.md` (`e3c6192`), `plans/closure/ci-release-orchestration/003l-status.md` (`9cf0bf8`) +- Successor: `plans/implementation/build-qualification/009-local-producer-operator-commands.md` +- Named follow-ons: Mach-O deployment-target verification; publishing floor evidence to consumers (requires its own ADR). diff --git a/plans/registry.md b/plans/registry.md index 97dad0c..9303317 100644 --- a/plans/registry.md +++ b/plans/registry.md @@ -94,7 +94,7 @@ Distribution predecessor evidence: | Contract and conformance | **complete** | `plans/subsystems/contract-conformance-roadmap.md` | M001-M003 closed | M003 closed on `43fa2d7`; closure `plans/closure/contract-conformance/003-status.md`: additive local `eggpack contract expand` scalar projection over existing schema-v1 semantics, 18 new tests including a process-boundary stdout contract, parity proven against eggsact `d4e6e5c` and stegoeggo `v0.5.0` for every target/alias/field. Roadmap §11 completion definition fully met; no contract milestone remains registered | | External backend evaluation | closed | `plans/subsystems/external-backend-evaluation-roadmap.md` | M001 closed (C) | no production backend adopted; new evidence/plan required to reopen | | Release manifest | active | `plans/subsystems/release-manifest-roadmap.md` | M002/M003 closed; M003a closed | M003a closed as a docs-only post-publication downstream-closure reconciliation after Eggup M004 closed (`eggstack/eggup@ea1f1c5e29302e5feca4599db9342d3a5ac93915`; formal Eggup status cleanup `eggstack/eggup@3b82d5397e728649a666690868a1e2d0fe42460d`); closure `plans/closure/release-manifest/003a-status.md`; M003 remains closed and no runtime/package requalification was performed or implied | -| Build and qualification | active | `plans/subsystems/build-qualification-roadmap.md` | M001-M007 closed; M008 and M009 ready | M007 closed on `e3c6192`: one canonical bounded file-digest authority in `eggpack-core` (`crates/eggpack-core/src/digest.rs`), retiring core's three divergent digest implementations, including a third in-crate SHA-256 stream in `qualification.rs` that the plan's inventory had missed. M006 closed on `398cd43` + run 36484758546 under accepted ADR-0005 Option A. The 2026-10-23 post-implementation review registered M007 (evidence digest unification, closed), M008 (compatibility floor verification), and M009 (local producer operator commands) | +| Build and qualification | active | `plans/subsystems/build-qualification-roadmap.md` | M001-M008 closed; M009 ready | M008 closed on `7e7cb6a`: a declared compatibility floor is no longer silently dropped — every target declaring one carries a finite, closed floor verification status on both the `ReleasePlan` and the `QualificationEvidence`, computed by bounded independent ELF `GLIBC_x.y` inspection. M007 closed on `e3c6192`: one canonical bounded file-digest authority in `eggpack-core` (`crates/eggpack-core/src/digest.rs`), retiring core's three divergent digest implementations, including a third in-crate SHA-256 stream in `qualification.rs` that the plan's inventory had missed. M006 closed on `398cd43` + run 36484758546 under accepted ADR-0005 Option A | | Bootstrap installers | active; corrective closed | `plans/subsystems/bootstrap-installers-roadmap.md` | M002b closed; prior milestones closed | M002b implementation `88ddf2e`, hosted run `37806244313`; POSIX runtime remains on Unix and Windows PowerShell archive runtime passed. M003 completion definition remains satisfied | | CI/release orchestration | active; M003j closed, M003k closed, M003l closed, M003m ready | `plans/subsystems/ci-release-orchestration-roadmap.md` | M003m bounded process execution convergence | M003k merged to `main` at `a0fec98`; M003l closed on `9cf0bf8` under accepted ADR-0006 (Option A): one SHA-256 hex acceptance rule (the all-zeros sentinel is refused everywhere), one host/target match rule, one floor-applicability rule, one exact-tag safety rule (the union of two disjoint concern sets), and one file-digest authority. `eggpack-manifest` takes `0.1.1`; `ReleaseManifest` v1 unchanged. M003m is unblocked | | Eggup interoperability | active | `plans/subsystems/eggup-interoperability-roadmap.md` | Eggpack M001a + Eggup adapter M001/M001a + Eggup M003 real-consumer adoption + Eggup M004 registry promotion all closed | The whole producer/consumer package seam is closed end to end; Release Manifest M003a closed the remaining Eggpack-side planning drift, and no Eggpack work remains on this seam; Eggwork Operations M003 remains producer-only | @@ -107,7 +107,7 @@ Distribution predecessor evidence: Planning Hygiene M002, Ecosystem M003b, Bootstrap M002b, CI M003i, and CI M003j are closed. **Dependency-ready CI M003k:** `plans/implementation/ci-release-orchestration/003k-precheckout-tag-resolution-and-stage-environment.md`. It resolves the downstream wg-basic R001 pre-checkout and stage-environment gates while preserving M003j's safe dispatch handling. -The post-implementation review of 2026-10-23 registered a corrective chain. **Build/Qualification M007 is closed** (`e3c6192`): `eggpack-core` now has one canonical bounded file-digest authority. **ADR-0006 is accepted (Option A)**: the all-zeros SHA-256 sentinel is refused everywhere, `ReleaseManifest` stays at `schema_version: 1`, and the published `eggpack-manifest` crate takes a `0.1.1` patch release carrying the tightened rule. **CI M003l is closed** (`9cf0bf8`): the duplicate host-match, floor-applicability, exact-tag, SHA-256 acceptance, and file-digest rules are gone, and the two exact-tag rule sets — disjoint in both directions — are replaced by their union. **Build/Qualification M008 is in progress** and **CI M003m is ready**; **Build/Qualification M009** (ready) and **Planning Hygiene M003** (docs-only) are independent of both, and CI M003n follows behind M003m. +The post-implementation review of 2026-10-23 registered a corrective chain. **Build/Qualification M007 is closed** (`e3c6192`): `eggpack-core` now has one canonical bounded file-digest authority. **ADR-0006 is accepted (Option A)**: the all-zeros SHA-256 sentinel is refused everywhere, `ReleaseManifest` stays at `schema_version: 1`, and the published `eggpack-manifest` crate takes a `0.1.1` patch release carrying the tightened rule. **CI M003l is closed** (`9cf0bf8`): the duplicate host-match, floor-applicability, exact-tag, SHA-256 acceptance, and file-digest rules are gone, and the two exact-tag rule sets — disjoint in both directions — are replaced by their union. **Build/Qualification M008 is closed** (`7e7cb6a`): a declared compatibility floor is no longer silently dropped, and every target declaring one carries a finite, closed floor verification status computed by bounded independent ELF inspection. **Build/Qualification M009 is in progress** (the six operator commands the canonical specification names) and **CI M003m is ready**; **Planning Hygiene M003** (docs-only) is independent of both, and CI M003n follows behind M003m. The table below is the **milestone-to-closure index plus active ready work**, not an implication that every historical row is executable. @@ -136,8 +136,8 @@ The table below is the **milestone-to-closure index plus active ready work**, no | Build and qualification | M005 deterministic cross-tool provisioning | closed | `plans/implementation/build-qualification/005-deterministic-cross-tool-provisioning.md` | Closure `plans/closure/build-qualification/005-status.md`; implementation `7a206ba`; hosted run 36256831000 green; exact Zig 0.14.1 / cargo-zigbuild 0.23.3 provisioning, verified Zig path binding, private cargo-zigbuild cache | | Build and qualification | M006 native qualification for cross-tool builds | closed | `plans/implementation/build-qualification/006-native-qualification-for-cross-tool-builds.md` | Closure `plans/closure/build-qualification/006-status.md`; implementation `398cd43`; hosted run 36484758546 green; host-matched native qualification is now independent of the builder, with split-host qualification and eggsact-shaped five-target render evidence | | Build and qualification | M007 evidence digest unification corrective | **closed** | `plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md` | Closure `plans/closure/build-qualification/007-status.md`; implementation `e3c6192`. One canonical bounded file-digest authority in `crates/eggpack-core/src/digest.rs` with typed refusals; core's two planned duplicates and a third in-crate SHA-256 stream in `qualification.rs` retired; the hashed bytes, the golden digests, and `ReleaseManifest v1` are unchanged | -| Build and qualification | M008 compatibility floor verification corrective | **ready** | `plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md` | Unblocked by Build/Qualification M007 (`e3c6192`). A declared glibc floor is currently accepted and silently dropped under `NativeCargo`; M008 adds an explicit floor verification status and independent bounded ELF `GLIBC_x.y` inspection. `ReleaseManifest` v1 unchanged | -| Build and qualification | M009 local producer operator commands | **ready** | `plans/implementation/build-qualification/009-local-producer-operator-commands.md` | Confined to `crates/eggpack-cli/**`. Restores six of the nine operator commands named by `plans/000-long-term-specification.md` §5.4 (`check`, `plan`, `package`, `qualify`, `collect`, `manifest`); the `ci _*` runner family stays byte-for-byte unchanged | +| Build and qualification | M008 compatibility floor verification corrective | **closed** | `plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md` | Closure `plans/closure/build-qualification/008-status.md`; implementation `7e7cb6a`. A declared glibc floor is no longer accepted and silently dropped under `NativeCargo`: every target declaring one carries a finite, closed floor verification status on the plan and on the qualification evidence, computed by bounded independent ELF `GLIBC_x.y` inspection, with a contradicted floor failing closed. `ReleaseManifest` v1 and the published crate unchanged | +| Build and qualification | M009 local producer operator commands | **ready** | `plans/implementation/build-qualification/009-local-producer-operator-commands.md` | Confined to `crates/eggpack-cli/**` plus the minimal `eggpack-core` public surface. Restores six of the nine operator commands named by `plans/000-long-term-specification.md` §5.4 (`check`, `plan`, `package`, `qualify`, `collect`, `manifest`); the `ci _*` runner family stays byte-for-byte unchanged | | Bootstrap installers | M001 generator/direct fixtures | closed | `plans/implementation/bootstrap-installers/001-direct-installer-generator.md` | Closure `plans/closure/bootstrap-installers/001-status.md` | | CI orchestration | M001 CIPlan/GitHub renderer | closed | `plans/implementation/ci-release-orchestration/001-ci-plan-and-github-renderer.md` | Closure `plans/closure/ci-release-orchestration/001-status.md`; hosted run 36040032768 passes all lanes | | CI orchestration | M002 qualification/aggregation gates + drift CLI | closed historically; corrective closed | `plans/implementation/ci-release-orchestration/002-qualification-aggregation-gates-and-drift-cli.md` | Historical closure retained; executable generated-workflow defect corrected and qualified by M002a (`plans/closure/ci-release-orchestration/002a-status.md`) | @@ -292,11 +292,11 @@ ADR-0006 [ACCEPTED 2026-10-23, Option A: digest acceptance set] Build/Qualification M007 evidence digest unification [CLOSED: e3c6192] | - +--> Build/Qualification M008 compatibility floor verification [IN PROGRESS: core only] + +--> Build/Qualification M008 compatibility floor verification [CLOSED: 7e7cb6a] | +--> CI M003l (also depends on M007) [CLOSED: 9cf0bf8] -Build/Qualification M009 local producer operator commands [READY: cli only] +Build/Qualification M009 local producer operator commands [IN PROGRESS: cli only] Planning Hygiene M003 baseline reconciliation [READY: docs only] ``` diff --git a/plans/subsystems/build-qualification-roadmap.md b/plans/subsystems/build-qualification-roadmap.md index 89476f7..69ebab2 100644 --- a/plans/subsystems/build-qualification-roadmap.md +++ b/plans/subsystems/build-qualification-roadmap.md @@ -176,7 +176,7 @@ Eggpack can construct and qualify real direct/bundle/archive native releases loc M001 PackConfig and ReleasePlan is closed. Release Manifest M001/M001a and Contract M001/M002 are closed. Backend-evaluation evidence is closed with disposition C, which does not authorize a backend. M005 closed the provisioning prerequisite; M006 then closed the producer-policy gap that first-consumer review exposed, so `Qualification::Native` is now admissible for a `CargoZigbuild` candidate on a matching host. The build/qualification milestone chain through M006 is closed. Ecosystem M001 is unblocked and must re-review the current eggsact baseline and re-pin `eggpack_tool.revision` at the M006 implementation before it implements. -The 2026-10-23 post-implementation review registered three further milestones against this subsystem. **M007** unifies core's divergent file-digest helpers into one canonical helper, because the weaker copy is the one that produces the aggregated manifest evidence; it closed on `e3c6192`. **M008** plans the independent verification that a produced binary honours a declared glibc/macOS floor, which ADR-0005 §9 requires and which remains unplanned and unclaimed by M006; it adds an explicit floor verification status to the plan and the qualification evidence, because a floor declared under `NativeCargo` is currently accepted and then silently dropped, and nothing downstream records that it went unverified. It is now ready, unblocked by M007. **M009** restores six of the nine operator commands named by `plans/000-long-term-specification.md` §5.4, so a producer can construct, qualify, finalize, and aggregate a release on a workstation rather than only through a hosted workflow run. +The 2026-10-23 post-implementation review registered three further milestones against this subsystem. **M007** unifies core's divergent file-digest helpers into one canonical helper, because the weaker copy is the one that produces the aggregated manifest evidence; it closed on `e3c6192`. **M008** plans the independent verification that a produced binary honours a declared glibc/macOS floor, which ADR-0005 §9 requires and which M006 did not plan or claim; it adds an explicit floor verification status to the plan and the qualification evidence, because a floor declared under `NativeCargo` was accepted and then silently dropped, and nothing downstream recorded that it went unverified. It closed on `7e7cb6a`: a declared floor is now carried with a finite, closed status computed by bounded independent ELF `GLIBC_x.y` inspection, and a contradicted floor fails closed. Mach-O deployment-target verification and publishing floor evidence to consumers remain **named follow-ons**. **M009** restores six of the nine operator commands named by `plans/000-long-term-specification.md` §5.4, so a producer can construct, qualify, finalize, and aggregate a release on a workstation rather than only through a hosted workflow run. | Milestone | Status | Implementation plan | Closure record | Blockers / sequencing | |---|---|---|---|---| @@ -188,5 +188,5 @@ The 2026-10-23 post-implementation review registered three further milestones ag | M005 deterministic cross-tool provisioning | closed | `plans/implementation/build-qualification/005-deterministic-cross-tool-provisioning.md` | `plans/closure/build-qualification/005-status.md`; implementation `7a206ba`; hosted run 36256831000 green | exact Zig 0.14.1/cargo-zigbuild 0.23.3 provisioning, explicit verified-Zig binding/private cache | | M006 native qualification for cross-tool builds | closed | `plans/implementation/build-qualification/006-native-qualification-for-cross-tool-builds.md` | `plans/closure/build-qualification/006-status.md`; implementation `398cd43`; hosted run 36484758546 green | ADR-0005 Option A implemented; host-matched native qualification is independent of builder, including split-host qualification; Ecosystem M001 unblocked | | M007 evidence digest unification corrective | closed | `plans/implementation/build-qualification/007-evidence-digest-unification-corrective.md` | `plans/closure/build-qualification/007-status.md`; implementation `e3c6192` | One canonical bounded file-digest authority in `crates/eggpack-core/src/digest.rs` with typed refusals; core's two planned duplicates and a third in-crate SHA-256 stream in `qualification.rs` retired. Hashed bytes, golden digests, and `ReleaseManifest` v1 unchanged. No acceptance-set change | -| M008 compatibility floor verification corrective | ready | `plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md` | — | Unblocked by M007 (`e3c6192`). Plans the independent floor verification ADR-0005 §9 requires; adds a floor verification status to the plan and qualification evidence. `ReleaseManifest` v1 unchanged | -| M009 local producer operator commands | ready | `plans/implementation/build-qualification/009-local-producer-operator-commands.md` | — | Confined to `crates/eggpack-cli/**`. Restores six of the nine operator commands named by `plans/000-long-term-specification.md` §5.4; the `ci _*` runner family stays byte-for-byte unchanged | +| M008 compatibility floor verification corrective | closed | `plans/implementation/build-qualification/008-compatibility-floor-verification-corrective.md` | `plans/closure/build-qualification/008-status.md`; implementation `7e7cb6a` | A declared floor is no longer accepted and silently dropped under `NativeCargo`: every target declaring one carries a finite, closed floor verification status on the plan and on the qualification evidence, computed by bounded independent ELF `GLIBC_x.y` inspection; a contradicted floor fails closed. `ReleaseManifest` v1 and the published crate unchanged. Mach-O verification and publishing floor evidence to consumers remain named follow-ons | +| M009 local producer operator commands | ready | `plans/implementation/build-qualification/009-local-producer-operator-commands.md` | — | Confined to `crates/eggpack-cli/**` plus the minimal `eggpack-core` public surface. Restores six of the nine operator commands named by `plans/000-long-term-specification.md` §5.4; the `ci _*` runner family stays byte-for-byte unchanged | From eb77d1960be20bf466cbe369ae861a229f60e099 Mon Sep 17 00:00:00 2001 From: doc Date: Fri, 23 Oct 2026 16:24:37 +0000 Subject: [PATCH 09/46] feat(cli): add local producer operator commands --- crates/eggpack-cli/src/main.rs | 230 ++- crates/eggpack-cli/src/operator.rs | 730 +++++++++ crates/eggpack-cli/tests/operator_commands.rs | 1341 +++++++++++++++++ 3 files changed, 2231 insertions(+), 70 deletions(-) create mode 100644 crates/eggpack-cli/src/operator.rs create mode 100644 crates/eggpack-cli/tests/operator_commands.rs diff --git a/crates/eggpack-cli/src/main.rs b/crates/eggpack-cli/src/main.rs index 812b75d..9085ce5 100644 --- a/crates/eggpack-cli/src/main.rs +++ b/crates/eggpack-cli/src/main.rs @@ -5,6 +5,8 @@ use std::io::{Read, Write}; use std::path::{Path, PathBuf}; +mod operator; + fn main() { std::process::exit(run(std::env::args().skip(1).collect())); } @@ -21,32 +23,67 @@ fn run(args: Vec) -> i32 { fn dispatch(args: Vec) -> Result<(), String> { if args.is_empty() { - return Err(format!("{USAGE}\n{CONTRACT_USAGE}")); + return Err(help_text()); } if args[0] == "--version" || args[0] == "-V" { println!("eggpack {}", env!("CARGO_PKG_VERSION")); return Ok(()); } if args[0] == "--help" || args[0] == "-h" { - println!("{USAGE}"); - println!("{CONTRACT_USAGE}"); + println!("{}", help_text()); return Ok(()); } match args[0].as_str() { "ci" => ci_dispatch(&args[1..]), "contract" => contract_dispatch(&args[1..]), + command @ ("check" | "plan" | "package" | "qualify" | "collect" | "manifest") => { + operator::dispatch(command, &args[1..]) + } other => Err(format!( - "unknown command {other:?}: expected 'ci' or 'contract'\n{USAGE}\n{CONTRACT_USAGE}" + "unknown command {other:?}: expected 'check', 'plan', 'package', 'qualify', 'collect', 'manifest', 'ci' or 'contract'\n{}", + help_text() )), } } +/// Top-level usage line for the local producer operator command family. +const OPERATOR_USAGE: &str = + "usage: eggpack [options]"; + /// Top-level usage line for the generated-orchestration command family. const USAGE: &str = "usage: eggpack ci [options]"; /// Usage line for the bounded local contract-expansion family (M003). const CONTRACT_USAGE: &str = "usage: eggpack contract expand --contract --release-id --target --field "; +/// Render the top-level help: the command families, their classes, and the +/// historical `ci` and `contract` usage lines unchanged. +/// +/// The taxonomy the specification asks for lives here, where an operator reads +/// it: every local command declares its class, and the help states plainly +/// that no command in this set stages or publishes. +fn help_text() -> String { + let mut lines: Vec = Vec::new(); + lines.push(OPERATOR_USAGE.to_owned()); + lines.push(String::new()); + lines.push("local producer operator commands:".to_owned()); + for command in &operator::COMMANDS { + lines.push(format!( + " {:<9} {:<20} {}", + command.name, command.class, command.summary + )); + } + lines.push(String::new()); + lines.push( + "No command in this set stages or publishes; staging and publication stay".to_owned(), + ); + lines.push("separate, explicitly authorized actions.".to_owned()); + lines.push(String::new()); + lines.push(USAGE.to_owned()); + lines.push(CONTRACT_USAGE.to_owned()); + lines.join("\n") +} + /// Dispatch the `ci` family, preserving the historical subcommand set and /// the historical `unknown ci subcommand` diagnostic byte-for-byte. fn ci_dispatch(rest: &[String]) -> Result<(), String> { @@ -504,8 +541,7 @@ fn ci_resolve_release(args: &[String]) -> Result<(), String> { }; // Runtime documents land only in invocation-private workflow storage; // they are never written back into the repository by this command. - let plan_json = - serde_json::to_string(&plan).map_err(|_| "release plan encode failed".to_owned())?; + let plan_json = encode_release_plan(&plan)?; let graph_json = graph .to_json() .map_err(|_| "release graph encode failed".to_owned())?; @@ -674,6 +710,116 @@ fn atomic_write(output: &Path, bytes: &[u8]) -> Result<(), String> { } } +/// Encode one release plan as the canonical deterministic plan document. +/// +/// Shared by the `ci _resolve-release` runner and the `eggpack plan` operator +/// command so both surfaces emit byte-identical plans for one resolved plan. +fn encode_release_plan(plan: &eggpack_core::ReleasePlan) -> Result { + serde_json::to_string(plan).map_err(|_| "release plan encode failed".to_owned()) +} + +/// Encode one release manifest as the canonical deterministic manifest document. +/// +/// The document is decoded and re-encoded so the written bytes are exactly the +/// bytes that decode back to the same manifest. Shared by the `ci _aggregate` +/// runner and the `eggpack manifest` operator command. +fn encode_release_manifest(manifest: &eggpack_manifest::ReleaseManifest) -> Result { + let manifest_json = manifest + .to_json() + .map_err(|_| "manifest encode failed".to_owned())?; + let decoded = eggpack_manifest::ReleaseManifest::from_json(&manifest_json) + .map_err(|_| "manifest roundtrip failed".to_owned())?; + let decoded_json = decoded + .to_json() + .map_err(|_| "manifest roundtrip failed".to_owned())?; + if decoded_json != manifest_json { + return Err("staging manifest does not decode to exact manifest".to_owned()); + } + Ok(manifest_json) +} + +/// Read one target's handoff, evidence, and candidate bytes into a finalization +/// input. +/// +/// Inputs dir layout: `/build-handoff.json`, `/evidence.json`, +/// `/candidates/`. Shared by the `ci _aggregate` +/// runner and the `eggpack collect` operator command so both aggregate the +/// same per-target bytes. +fn collect_finalization_inputs( + inputs_dir: &Path, + plan: &eggpack_core::ReleasePlan, + targets: &[String], +) -> Result, String> { + let mut final_inputs = Vec::with_capacity(targets.len()); + for target in targets { + let target_dir = inputs_dir.join(target); + let handoff_text = read_bounded( + &target_dir.join("build-handoff.json"), + 1_000_000, + "build handoff", + )?; + let evidence_text = read_bounded(&target_dir.join("evidence.json"), 1_000_000, "evidence")?; + let handoff: eggpack_ci::BuildHandoffV1 = + eggpack_ci::BuildHandoffV1::from_json(&handoff_text) + .map_err(|_| "invalid handoff".to_owned())?; + let evidence = eggpack_ci::decode_qualification_evidence(&evidence_text) + .map_err(|_| "invalid evidence".to_owned())?; + let planned = plan + .targets + .iter() + .find(|t| &t.target == target) + .ok_or_else(|| "target is not in release plan".to_string())?; + let candidate_root = target_dir.join("candidates"); + let attempt = eggpack_ci::reconstruct_attempt(plan, planned, &handoff, &candidate_root) + .map_err(|_| "candidate reconstruction failed".to_owned())?; + final_inputs.push(eggpack_core::FinalizationTargetInput { + target: target.clone(), + attempt, + qualification: evidence, + }); + } + Ok(final_inputs) +} + +/// Stage the canonical qualification artifact directory for one target. +/// +/// The handoff document and the candidate bytes are written beside the +/// evidence so gate and aggregate consume one complete per-target directory. +/// Shared by the `ci _qualify-target` runner and the `eggpack qualify` operator +/// command. +fn stage_qualification_artifacts( + output_dir: &Path, + candidate_dir: &Path, + handoff_text: &str, +) -> Result<(), String> { + atomic_write( + &output_dir.join("build-handoff.json"), + handoff_text.as_bytes(), + )?; + // Canonical per-target layout keeps candidate bytes under `candidates/`. + let candidates_src = { + let nested = candidate_dir.join("candidates"); + if nested.exists() { + nested + } else { + candidate_dir.to_path_buf() + } + }; + let handoff: eggpack_ci::BuildHandoffV1 = eggpack_ci::BuildHandoffV1::from_json(handoff_text) + .map_err(|_| "invalid handoff".to_owned())?; + let dest_candidates = output_dir.join("candidates"); + std::fs::create_dir_all(&dest_candidates) + .map_err(|_| "output dir creation failed".to_owned())?; + for output in &handoff.outputs { + let source = candidates_src.join(&output.relative_path); + let dest = dest_candidates.join(&output.relative_path); + if std::fs::hard_link(&source, &dest).is_err() { + std::fs::copy(source, &dest).map_err(|_| "candidate staging failed".to_owned())?; + } + } + Ok(()) +} + fn ci_generate(args: &[String]) -> Result<(), String> { let policy_path = PathBuf::from(get_flag(args, "github-policy")?); let output_path = PathBuf::from(get_flag(args, "output")?); @@ -973,30 +1119,7 @@ fn ci_qualify_target(args: &[String]) -> Result<(), String> { // build-handoff and candidate bytes alongside the evidence so gate and // aggregate consume one complete per-target directory. let handoff_text = read_bounded(&handoff_path, 1_000_000, "build handoff")?; - atomic_write( - &output_dir.join("build-handoff.json"), - handoff_text.as_bytes(), - )?; - let candidates_src = { - let nested = candidate_dir.join("candidates"); - if nested.exists() { - nested - } else { - candidate_dir.clone() - } - }; - let handoff: eggpack_ci::BuildHandoffV1 = eggpack_ci::BuildHandoffV1::from_json(&handoff_text) - .map_err(|_| "invalid handoff".to_owned())?; - let dest_candidates = output_dir.join("candidates"); - std::fs::create_dir_all(&dest_candidates) - .map_err(|_| "output dir creation failed".to_owned())?; - for output in &handoff.outputs { - let source = candidates_src.join(&output.relative_path); - let dest = dest_candidates.join(&output.relative_path); - if std::fs::hard_link(&source, &dest).is_err() { - std::fs::copy(&source, &dest).map_err(|_| "candidate staging failed".to_owned())?; - } - } + stage_qualification_artifacts(&output_dir, &candidate_dir, &handoff_text)?; eggpack_ci::validate_qualification_artifact_dir(&output_dir) .map_err(|_| "staged qualification artifact validation failed".to_owned())?; println!("qualified {target}: {:?}", evidence.status); @@ -1280,34 +1403,12 @@ fn ci_aggregate(args: &[String]) -> Result<(), String> { // Inputs dir layout: /build-handoff.json, /evidence.json, // /candidates/. Candidate bytes are read from the // per-target candidate roots supplied alongside the handoffs. - let mut final_inputs = Vec::new(); - for qual in &graph.qualifications { - let target_dir = inputs_dir.join(&qual.target); - let handoff_text = read_bounded( - &target_dir.join("build-handoff.json"), - 1_000_000, - "build handoff", - )?; - let evidence_text = read_bounded(&target_dir.join("evidence.json"), 1_000_000, "evidence")?; - let handoff: eggpack_ci::BuildHandoffV1 = - eggpack_ci::BuildHandoffV1::from_json(&handoff_text) - .map_err(|_| "invalid handoff".to_owned())?; - let evidence = eggpack_ci::decode_qualification_evidence(&evidence_text) - .map_err(|_| "invalid evidence".to_owned())?; - let planned = plan - .targets - .iter() - .find(|t| t.target == qual.target) - .ok_or_else(|| "target is not in release plan".to_string())?; - let candidate_root = target_dir.join("candidates"); - let attempt = eggpack_ci::reconstruct_attempt(&plan, planned, &handoff, &candidate_root) - .map_err(|_| "candidate reconstruction failed".to_owned())?; - final_inputs.push(eggpack_core::FinalizationTargetInput { - target: qual.target.clone(), - attempt, - qualification: evidence, - }); - } + let aggregate_targets: Vec = graph + .qualifications + .iter() + .map(|qual| qual.target.clone()) + .collect(); + let final_inputs = collect_finalization_inputs(&inputs_dir, &plan, &aggregate_targets)?; let (outcome, finalized) = if graph.consumer_validators.is_empty() { // Stray consumer evidence without a configured validator fails // closed so validation can never be silently bypassed. @@ -1351,18 +1452,7 @@ fn ci_aggregate(args: &[String]) -> Result<(), String> { // manifest. This file lives beside the finalized root, never inside it, // so M004 release-root semantics remain unchanged. if let Some(finalized) = finalized.as_ref() { - let manifest_json = finalized - .manifest - .to_json() - .map_err(|_| "manifest encode failed".to_owned())?; - let decoded = eggpack_manifest::ReleaseManifest::from_json(&manifest_json) - .map_err(|_| "manifest roundtrip failed".to_owned())?; - let decoded_json = decoded - .to_json() - .map_err(|_| "manifest roundtrip failed".to_owned())?; - if decoded_json != manifest_json { - return Err("staging manifest does not decode to exact manifest".to_owned()); - } + let manifest_json = encode_release_manifest(&finalized.manifest)?; if let Some(parent) = output_path.parent() { if !parent.as_os_str().is_empty() { let manifest_path = parent.join("release-manifest.json"); diff --git a/crates/eggpack-cli/src/operator.rs b/crates/eggpack-cli/src/operator.rs new file mode 100644 index 0000000..c5430fe --- /dev/null +++ b/crates/eggpack-cli/src/operator.rs @@ -0,0 +1,730 @@ +//! Local producer operator commands (Build/Qualification M009). +//! +//! Six top-level commands — `check`, `plan`, `package`, `qualify`, `collect`, +//! and `manifest` — let a producer construct, qualify, finalize, and aggregate +//! a real release on a workstation, without a GitHub Actions run and without +//! the `ci _*` internal runner family. +//! +//! Every command here is deterministic wiring over an already-closed +//! `eggpack-core` API: it selects and validates local inputs, calls one +//! existing core function, and writes one artifact through the shared bounded +//! writer. No command in this set stages or publishes, so no command in this +//! set can mutate a public release. + +use std::collections::BTreeMap; +use std::path::{Path, PathBuf}; + +use crate::{ + absolutize_cli_path, atomic_write, bound_echo, collect_finalization_inputs, + encode_release_manifest, encode_release_plan, read_bounded, stage_qualification_artifacts, +}; + +/// Maximum bytes accepted for any single local input document. +const MAX_INPUT_BYTES: usize = 1_000_000; + +/// Private build scratch directory created under the caller's output root. +const BUILD_SCRATCH_DIR: &str = ".eggpack-build"; + +/// Stable invocation identity for the private Cargo target directories. +const BUILD_INVOCATION: &str = "package"; + +/// One operator command's declared identity for `--help`. +pub(crate) struct OperatorCommand { + /// Command name as typed on the command line. + pub(crate) name: &'static str, + /// Command class: validation, build, release aggregation, or final-bytes + /// evidence. + pub(crate) class: &'static str, + /// One-line description of the command's effect. + pub(crate) summary: &'static str, + /// Full usage line for the command. + pub(crate) usage: &'static str, +} + +/// The six local producer operator commands, in help order. +pub(crate) const COMMANDS: [OperatorCommand; 6] = [ + OperatorCommand { + name: "check", + class: "validation", + summary: "validate contract, policy, and bindings before anything is built", + usage: "usage: eggpack check --contract --pack-config --build-bindings --qualification-bindings --selected --release-id --source-revision ", + }, + OperatorCommand { + name: "plan", + class: "validation", + summary: "resolve the release identity and write a ReleasePlan", + usage: "usage: eggpack plan --contract --pack-config --build-bindings --qualification-bindings --selected --release-id --source-revision --output ", + }, + OperatorCommand { + name: "package", + class: "build", + summary: "build every planned target's candidates under an output root", + usage: "usage: eggpack package --release-plan --build-bindings --source-root --output-root ", + }, + OperatorCommand { + name: "qualify", + class: "build", + summary: "qualify built candidates and write qualification evidence", + usage: "usage: eggpack qualify --contract --release-plan --build-bindings --qualification-bindings --candidates-dir --output-dir ", + }, + OperatorCommand { + name: "collect", + class: "release aggregation", + summary: "aggregate qualified candidates into a finalized release tree", + usage: "usage: eggpack collect --contract --release-plan --build-bindings --qualification-bindings --candidates-dir --output-root ", + }, + OperatorCommand { + name: "manifest", + class: "final-bytes evidence", + summary: "derive release-manifest.json from a finalized release tree", + usage: "usage: eggpack manifest --contract --release-plan --finalized-root --output [--candidates-dir ]", + }, +]; + +/// Required flags of `eggpack check`. +const CHECK_FLAGS: [&str; 7] = [ + "contract", + "pack-config", + "build-bindings", + "qualification-bindings", + "selected", + "release-id", + "source-revision", +]; + +/// Required flags of `eggpack plan`. +const PLAN_FLAGS: [&str; 8] = [ + "contract", + "pack-config", + "build-bindings", + "qualification-bindings", + "selected", + "release-id", + "source-revision", + "output", +]; + +/// Required flags of `eggpack package`. +const PACKAGE_FLAGS: [&str; 4] = [ + "release-plan", + "build-bindings", + "source-root", + "output-root", +]; + +/// Required flags of `eggpack qualify`. +const QUALIFY_FLAGS: [&str; 6] = [ + "contract", + "release-plan", + "build-bindings", + "qualification-bindings", + "candidates-dir", + "output-dir", +]; + +/// Required flags of `eggpack collect`. +const COLLECT_FLAGS: [&str; 6] = [ + "contract", + "release-plan", + "build-bindings", + "qualification-bindings", + "candidates-dir", + "output-root", +]; + +/// Required flags of `eggpack manifest`. +const MANIFEST_FLAGS: [&str; 4] = ["contract", "release-plan", "finalized-root", "output"]; + +/// One operator command's parsed `--flag value` / `--flag=value` arguments. +/// +/// Every flag is accepted at most once, values must be non-empty, unknown +/// options and positional arguments are rejected, and each required flag must +/// be present exactly once. The same surface the historical `contract expand` +/// command established, applied to every command in this family. +struct OperatorArgs { + /// Parsed flag values, keyed by flag name without the leading dashes. + values: BTreeMap, +} + +impl OperatorArgs { + /// Parse one command's arguments against its required and optional flags. + fn parse( + args: &[String], + required: &[&str], + optional: &[&str], + command: &str, + ) -> Result { + let mut values: BTreeMap = BTreeMap::new(); + let mut index = 0usize; + while index < args.len() { + let arg = args[index].as_str(); + let Some(body) = arg.strip_prefix("--") else { + return Err(format!( + "unexpected argument {:?}: {} accepts only named options", + bound_echo(arg), + command + )); + }; + let (name, inline) = match body.split_once('=') { + Some((name, value)) => (name, Some(value.to_owned())), + None => (body, None), + }; + if !required.contains(&name) && !optional.contains(&name) { + return Err(format!("unknown option --{}", bound_echo(name))); + } + if values.contains_key(name) { + return Err(format!("--{name} may be given only once")); + } + let value = match inline { + Some(value) => value, + None => { + index += 1; + args.get(index) + .cloned() + .ok_or_else(|| format!("missing value for --{name}"))? + } + }; + if value.is_empty() { + return Err(format!("--{name} must not be empty")); + } + values.insert(name.to_owned(), value); + index += 1; + } + + let mut missing: Vec = required + .iter() + .filter(|name| !values.contains_key(**name)) + .map(|name| format!("--{name}")) + .collect(); + missing.sort_unstable(); + if !missing.is_empty() { + return Err(format!("missing required {}", missing.join(", "))); + } + Ok(Self { values }) + } + + /// One required flag's value. + fn get(&self, name: &str) -> String { + self.values.get(name).cloned().unwrap_or_default() + } + + /// One optional flag's value, when the caller supplied it. + fn get_optional(&self, name: &str) -> Option { + self.values.get(name).cloned() + } +} + +/// Dispatch one operator command by name. +pub(crate) fn dispatch(name: &str, args: &[String]) -> Result<(), String> { + if args.len() == 1 && (args[0] == "--help" || args[0] == "-h") { + print_help(name); + return Ok(()); + } + match name { + "check" => check(args), + "plan" => plan(args), + "package" => package(args), + "qualify" => qualify(args), + "collect" => collect(args), + "manifest" => manifest(args), + other => Err(format!("unknown operator command: {other}")), + } +} + +/// Print one command's name, class, and usage line. +fn print_help(name: &str) { + if let Some(command) = COMMANDS.iter().find(|command| command.name == name) { + println!("eggpack {} — {}", command.name, command.class); + println!("{}", command.usage); + println!("class: {}", command.class); + println!("No command in this set stages or publishes."); + } +} + +/// Read, resolve, and validate the whole planning input set. +/// +/// Resolution goes through the same function the `ci _resolve-release` runner +/// calls, so both surfaces derive one plan from one rule set. +fn resolve_planning_inputs(parsed: &OperatorArgs) -> Result { + { + let contract = read_contract(&parsed.get("contract"))?; + let pack_config = read_pack_config(&parsed.get("pack-config"))?; + let bindings = read_build_bindings(&parsed.get("build-bindings"))?; + let qualification_bindings = + read_qualification_bindings(&parsed.get("qualification-bindings"))?; + let selected = parse_selected(&parsed.get("selected"))?; + let release_id = parsed.get("release-id"); + let source_revision = parsed.get("source-revision"); + let plan = eggpack_ci::resolve_runtime_release_plan_with_mode( + &contract, + &pack_config, + &selected, + &release_id, + &source_revision, + eggpack_ci::ReleaseIdentityMode::ExactTag, + ) + .map_err(|error| format!("release plan resolution failed: {}", diagnostic(&error)))?; + // A plan that disagrees with its own declared floor is refused before + // it can be written or used. + plan.validate() + .map_err(|error| format!("release plan is invalid: {}", diagnostic(&error)))?; + bindings.validate_for(&contract, &plan).map_err(|error| { + format!( + "build bindings do not match the release plan: {}", + diagnostic(&error) + ) + })?; + qualification_bindings + .validate_for(&plan, &bindings) + .map_err(|error| { + format!( + "qualification bindings do not match the release plan: {}", + diagnostic(&error) + ) + })?; + Ok(plan) + } +} + +/// Read and parse one distribution contract. +fn read_contract(path: &str) -> Result { + let text = read_bounded(Path::new(path), MAX_INPUT_BYTES, "contract")?; + eggpack_contract::DistributionContract::parse_toml_str(&text) + .map_err(|error| format!("invalid contract: {}", diagnostic(&error))) +} + +/// Read and parse one producer policy document. +fn read_pack_config(path: &str) -> Result { + let text = read_bounded(Path::new(path), MAX_INPUT_BYTES, "pack config")?; + eggpack_core::PackConfig::from_toml(&text) + .map_err(|error| format!("invalid pack config: {}", diagnostic(&error))) +} + +/// Read and parse one build bindings document. +fn read_build_bindings(path: &str) -> Result { + let text = read_bounded(Path::new(path), MAX_INPUT_BYTES, "build bindings")?; + eggpack_core::BuildBindingsV1::from_toml(&text) + .map_err(|error| format!("invalid build bindings: {}", diagnostic(&error))) +} + +/// Read and parse one qualification bindings document. +fn read_qualification_bindings( + path: &str, +) -> Result { + let text = read_bounded(Path::new(path), MAX_INPUT_BYTES, "qualification bindings")?; + eggpack_core::QualificationBindingsV1::from_toml(&text) + .map_err(|error| format!("invalid qualification bindings: {}", diagnostic(&error))) +} + +/// Read and validate one release plan document. +fn read_release_plan(path: &str) -> Result { + let text = read_bounded(Path::new(path), MAX_INPUT_BYTES, "release plan")?; + let plan: eggpack_core::ReleasePlan = + serde_json::from_str(&text).map_err(|_| "invalid release plan".to_owned())?; + plan.validate() + .map_err(|error| format!("release plan is invalid: {}", diagnostic(&error)))?; + Ok(plan) +} + +/// Split the comma-separated selected target alias list. +fn parse_selected(raw: &str) -> Result, String> { + let selected: Vec = raw.split(',').map(str::to_owned).collect(); + if selected.is_empty() { + return Err("selected targets must not be empty".to_owned()); + } + Ok(selected) +} + +/// Validate the whole planning input set without writing anything. +fn check(args: &[String]) -> Result<(), String> { + let parsed = OperatorArgs::parse(args, &CHECK_FLAGS, &[], "check")?; + let _plan = resolve_planning_inputs(&parsed)?; + println!("check: ok"); + Ok(()) +} + +/// Resolve the release plan and write it as the canonical plan document. +fn plan(args: &[String]) -> Result<(), String> { + let parsed = OperatorArgs::parse(args, &PLAN_FLAGS, &[], "plan")?; + let plan = resolve_planning_inputs(&parsed)?; + let output = PathBuf::from(parsed.get("output")); + // The same encoder the `ci _resolve-release` runner writes with, so both + // surfaces emit byte-identical plans for one resolved plan. + let plan_json = encode_release_plan(&plan)?; + atomic_write(&output, plan_json.as_bytes())?; + println!("plan: ok"); + Ok(()) +} + +/// Build every planned target's candidates under the caller's output root. +fn package(args: &[String]) -> Result<(), String> { + let parsed = OperatorArgs::parse(args, &PACKAGE_FLAGS, &[], "package")?; + let plan = read_release_plan(&parsed.get("release-plan"))?; + let bindings = read_build_bindings(&parsed.get("build-bindings"))?; + let cwd = std::env::current_dir().map_err(|_| "working directory is unavailable".to_owned())?; + let source_root = absolutize_cli_path(Path::new(&parsed.get("source-root")), &cwd)?; + let output_root = absolutize_cli_path(Path::new(&parsed.get("output-root")), &cwd)?; + reject_symlink_dir(&output_root, "output root")?; + let work_root = output_root.join(BUILD_SCRATCH_DIR); + reset_build_scratch(&work_root)?; + + // Every target is built before any artifact is written, so a failed build + // leaves no half-written release behind. + let mut built = Vec::with_capacity(plan.targets.len()); + for planned in &plan.targets { + let target_bindings = bindings + .targets + .get(&planned.target) + .ok_or_else(|| format!("build bindings are missing target {}", planned.target))?; + let attempt = eggpack_core::execute_target( + &plan, + planned, + target_bindings, + &source_root, + &work_root, + BUILD_INVOCATION, + ) + .map_err(|error| { + format!( + "build failed for {}: {}", + planned.target, + diagnostic(&error) + ) + })?; + if attempt.process.outcome != eggpack_core::CommandOutcome::Success { + return Err(format!("build did not succeed for {}", planned.target)); + } + let handoff = eggpack_ci::project_build_handoff(&plan, &bindings, &planned.target) + .map_err(|error| format!("build handoff projection failed: {}", diagnostic(&error)))?; + built.push((planned.target.clone(), attempt, handoff)); + } + for (target, attempt, handoff) in built { + write_build_artifacts(&output_root, &target, &attempt, handoff)?; + } + println!("package: ok"); + Ok(()) +} + +/// One bounded, single-line diagnostic extracted from a parser or core error. +/// +/// The exit discipline is one `eggpack: ` line, so a multi-line +/// parser diagnostic is reduced to its most specific line. +fn diagnostic(error: &impl std::fmt::Display) -> String { + let text = error.to_string(); + let line = text + .lines() + .rev() + .find(|line| !line.trim().is_empty()) + .unwrap_or("invalid document") + .trim(); + bound_echo(line) +} + +/// Require one existing, real directory. +fn require_real_dir(path: &Path, label: &str) -> Result<(), String> { + let metadata = + std::fs::symlink_metadata(path).map_err(|_| format!("{label} is unavailable"))?; + if metadata.file_type().is_symlink() { + return Err(format!("{label} must not be a symlink")); + } + if !metadata.is_dir() { + return Err(format!("{label} is not a real directory")); + } + Ok(()) +} + +/// Reject an output directory that already exists as a symlink. +/// +/// An output root the caller names is written into directly, so a symlinked +/// directory is refused rather than followed. +fn reject_symlink_dir(path: &Path, label: &str) -> Result<(), String> { + match std::fs::symlink_metadata(path) { + Ok(metadata) => { + if metadata.file_type().is_symlink() { + return Err(format!("{label} must not be a symlink")); + } + if !metadata.is_dir() { + return Err(format!("{label} is not a real directory")); + } + Ok(()) + } + Err(_) => Ok(()), + } +} + +/// Recreate Eggpack's private build scratch directory under the output root. +/// +/// The scratch root holds the private Cargo target directories the core +/// builder creates. It is recreated on every run so a restarted stage starts +/// from a clean private build directory. +fn reset_build_scratch(work_root: &Path) -> Result<(), String> { + if let Ok(metadata) = std::fs::symlink_metadata(work_root) { + if metadata.file_type().is_symlink() { + return Err("build scratch root must not be a symlink".to_owned()); + } + if !metadata.is_dir() { + return Err("build scratch root is not a directory".to_owned()); + } + std::fs::remove_dir_all(work_root).map_err(|_| "build scratch reset failed".to_owned())?; + } + std::fs::create_dir_all(work_root).map_err(|_| "build scratch creation failed".to_owned())?; + Ok(()) +} + +/// Write one target's canonical build artifact directory. +fn write_build_artifacts( + output_root: &Path, + target: &str, + attempt: &eggpack_core::BuildAttempt, + mut handoff: eggpack_ci::BuildHandoffV1, +) -> Result<(), String> { + let dir = output_root.join(target); + let candidates_dir = dir.join("candidates"); + std::fs::create_dir_all(&candidates_dir) + .map_err(|_| "output dir creation failed".to_owned())?; + for output in &mut handoff.outputs { + let candidate = attempt + .candidates + .iter() + .find(|candidate| candidate.selector == output.selector) + .ok_or_else(|| "build attempt is missing a bound candidate".to_owned())?; + let metadata = std::fs::symlink_metadata(&candidate.path) + .map_err(|_| "candidate file unavailable".to_owned())?; + if metadata.file_type().is_symlink() || !metadata.is_file() || metadata.len() == 0 { + return Err("candidate is not a non-empty regular file".to_owned()); + } + output.size = metadata.len(); + let dest = candidates_dir.join(&output.relative_path); + if std::fs::hard_link(&candidate.path, &dest).is_err() { + std::fs::copy(&candidate.path, &dest) + .map_err(|_| "candidate staging failed".to_owned())?; + } + } + handoff + .validate() + .map_err(|_| "handoff validation failed".to_owned())?; + let handoff_json = handoff + .to_json() + .map_err(|_| "handoff serialization failed".to_owned())?; + atomic_write(&dir.join("build-handoff.json"), handoff_json.as_bytes())?; + eggpack_ci::validate_build_artifact_dir(&dir) + .map_err(|_| "staged build artifact validation failed".to_owned())?; + Ok(()) +} + +/// Qualify every planned target's candidates and write the evidence. +fn qualify(args: &[String]) -> Result<(), String> { + let parsed = OperatorArgs::parse(args, &QUALIFY_FLAGS, &[], "qualify")?; + let contract = read_contract(&parsed.get("contract"))?; + let plan = read_release_plan(&parsed.get("release-plan"))?; + let bindings = read_build_bindings(&parsed.get("build-bindings"))?; + let qualification_bindings = + read_qualification_bindings(&parsed.get("qualification-bindings"))?; + let candidates_dir = PathBuf::from(parsed.get("candidates-dir")); + let output_dir = PathBuf::from(parsed.get("output-dir")); + reject_symlink_dir(&output_dir, "output dir")?; + let cwd = std::env::current_dir().map_err(|_| "working directory is unavailable".to_owned())?; + let cancellation = eggpack_core::BuildCancellation::new(); + let runtime = eggpack_core::QualificationRuntime { qemu_sysroot: None }; + + // Every target is qualified before any artifact is written, so a failed + // qualification leaves no half-written release behind. + let mut qualified = Vec::with_capacity(plan.targets.len()); + for planned in &plan.targets { + let target_dir = candidates_dir.join(&planned.target); + let handoff_text = read_bounded( + &target_dir.join("build-handoff.json"), + MAX_INPUT_BYTES, + "build handoff", + )?; + let handoff = eggpack_ci::BuildHandoffV1::from_json(&handoff_text) + .map_err(|_| "invalid handoff".to_owned())?; + let candidate_dir = absolutize_cli_path(&target_dir.join("candidates"), &cwd)?; + let attempt = eggpack_ci::reconstruct_attempt(&plan, planned, &handoff, &candidate_dir) + .map_err(|_| "candidate reconstruction failed".to_owned())?; + let evidence = eggpack_core::qualify_target(eggpack_core::QualificationRequest { + contract: &contract, + plan: &plan, + target: planned, + attempt: &attempt, + build_bindings: &bindings, + qualification_bindings: &qualification_bindings, + runtime: &runtime, + cancellation: &cancellation, + }) + .map_err(|error| { + format!( + "qualification failed for {}: {}", + planned.target, + diagnostic(&error) + ) + })?; + qualified.push(( + planned.target.clone(), + handoff_text, + evidence, + candidate_dir, + )); + } + for (target, handoff_text, evidence, candidate_dir) in qualified { + let dir = output_dir.join(&target); + std::fs::create_dir_all(&dir).map_err(|_| "output dir creation failed".to_owned())?; + let evidence_json = eggpack_ci::encode_qualification_evidence(&evidence) + .map_err(|_| "evidence encode failed".to_owned())?; + atomic_write(&dir.join("evidence.json"), evidence_json.as_bytes())?; + stage_qualification_artifacts(&dir, &candidate_dir, &handoff_text)?; + eggpack_ci::validate_qualification_artifact_dir(&dir) + .map_err(|_| "staged qualification artifact validation failed".to_owned())?; + } + println!("qualify: ok"); + Ok(()) +} + +/// Aggregate qualified candidates into a finalized release tree. +fn collect(args: &[String]) -> Result<(), String> { + let parsed = OperatorArgs::parse(args, &COLLECT_FLAGS, &[], "collect")?; + let contract = read_contract(&parsed.get("contract"))?; + let plan = read_release_plan(&parsed.get("release-plan"))?; + let bindings = read_build_bindings(&parsed.get("build-bindings"))?; + let qualification_bindings = + read_qualification_bindings(&parsed.get("qualification-bindings"))?; + let candidates_dir = PathBuf::from(parsed.get("candidates-dir")); + let cwd = std::env::current_dir().map_err(|_| "working directory is unavailable".to_owned())?; + let output_root = absolutize_cli_path(Path::new(&parsed.get("output-root")), &cwd)?; + reject_symlink_dir(&output_root, "output root")?; + // The finalizer writes one new release root under a parent the caller + // already secures, and the manifest document lands beside that root. + let output_parent = output_root + .parent() + .filter(|parent| !parent.as_os_str().is_empty()) + .map(PathBuf::from) + .unwrap_or_else(|| PathBuf::from(".")); + require_real_dir(&output_parent, "output root parent")?; + + // The same graph projection the `ci _resolve-release` runner performs, so + // the local path aggregates the same targets with the same finalization + // settings the generated workflow would use. + let ci_plan = eggpack_ci::project_ci_plan(&contract, &plan, &bindings) + .map_err(|error| format!("ci projection failed: {}", diagnostic(&error)))?; + let graph = + eggpack_ci::project_release_plan(&ci_plan, &qualification_bindings, &bindings, &plan) + .map_err(|error| format!("release graph projection failed: {}", diagnostic(&error)))?; + let targets: Vec = graph + .qualifications + .iter() + .map(|qualification| qualification.target.clone()) + .collect(); + let inputs = collect_finalization_inputs(&candidates_dir, &plan, &targets)?; + // Stray consumer evidence without a configured validator fails closed so + // validation can never be silently bypassed. + for target in &targets { + if candidates_dir + .join(target) + .join("consumer-evidence.json") + .exists() + { + return Err("consumer evidence present without a configured validator".to_owned()); + } + } + let (outcome, finalized) = eggpack_ci::aggregate_finalize( + &contract, + &plan, + &graph, + &inputs, + &graph.finalization.evidence_references, + &output_root, + ) + .map_err(|_| "aggregation failed".to_owned())?; + let finalized = finalized.ok_or_else(|| "aggregation did not finalize a release".to_owned())?; + if outcome != eggpack_ci::AggregateOutcome::Complete { + return Err("aggregation did not complete".to_owned()); + } + // The manifest document lives beside the finalized root, never inside it. + let manifest_json = encode_release_manifest(&finalized.manifest)?; + atomic_write( + &output_parent.join("release-manifest.json"), + manifest_json.as_bytes(), + )?; + println!("collect: ok"); + Ok(()) +} + +/// Derive the release manifest from a finalized release tree's bytes. +fn manifest(args: &[String]) -> Result<(), String> { + let parsed = OperatorArgs::parse(args, &MANIFEST_FLAGS, &["candidates-dir"], "manifest")?; + let contract = read_contract(&parsed.get("contract"))?; + let plan = read_release_plan(&parsed.get("release-plan"))?; + let finalized_root = PathBuf::from(parsed.get("finalized-root")); + let output = PathBuf::from(parsed.get("output")); + let candidates_dir = parsed.get_optional("candidates-dir").map(PathBuf::from); + + let mut targets = Vec::with_capacity(plan.targets.len()); + for planned in &plan.targets { + let expanded = contract + .expand(&planned.target, &plan.release_id) + .map_err(|error| format!("contract expansion failed: {}", diagnostic(&error)))?; + let expected = + eggpack_contract::expected_release_files(&contract, &planned.target, &plan.release_id) + .map_err(|error| { + format!( + "expected inventory derivation failed: {}", + diagnostic(&error) + ) + })?; + let mut release_files = BTreeMap::new(); + for file in expected { + release_files.insert(file.file_name.clone(), finalized_root.join(&file.file_name)); + } + let mut archive_members = BTreeMap::new(); + if let eggpack_contract::ExpandedAssets::Archive(archive) = &expanded.assets { + // An archive's member digests are facts about the member bytes, + // which the finalized tree does not retain. They are read from the + // qualified candidate bytes instead. + let candidates_dir = candidates_dir + .as_ref() + .ok_or_else(|| "archive target requires --candidates-dir".to_owned())?; + let target_dir = candidates_dir.join(&planned.target); + let handoff_text = read_bounded( + &target_dir.join("build-handoff.json"), + MAX_INPUT_BYTES, + "build handoff", + )?; + let handoff = eggpack_ci::BuildHandoffV1::from_json(&handoff_text) + .map_err(|_| "invalid handoff".to_owned())?; + for member in &archive.members { + let selector = eggpack_core::LogicalOutputSelector::ArchiveMember { + source: member.source.clone(), + }; + let output = handoff + .outputs + .iter() + .find(|output| output.selector == selector) + .ok_or_else(|| "archive member is absent from the build handoff".to_owned())?; + archive_members.insert( + member.source.clone(), + target_dir.join("candidates").join(&output.relative_path), + ); + } + } + targets.push(eggpack_core::FinalizedTargetInput { + target: planned.target.clone(), + release_files, + archive_members, + }); + } + let manifest = eggpack_core::build_manifest( + &contract, + &eggpack_core::FinalizedReleaseInput { + product_id: contract.product.id.clone(), + release_id: plan.release_id.clone(), + source_revision: plan.source_revision.clone(), + targets, + evidence_references: Vec::new(), + }, + ) + .map_err(|error| format!("manifest construction failed: {}", diagnostic(&error)))?; + let manifest_json = encode_release_manifest(&manifest)?; + atomic_write(&output, manifest_json.as_bytes())?; + println!("manifest: ok"); + Ok(()) +} diff --git a/crates/eggpack-cli/tests/operator_commands.rs b/crates/eggpack-cli/tests/operator_commands.rs new file mode 100644 index 0000000..908dc9c --- /dev/null +++ b/crates/eggpack-cli/tests/operator_commands.rs @@ -0,0 +1,1341 @@ +//! Process-boundary and byte-identity tests for the local producer operator +//! commands (Build/Qualification M009). +//! +//! The documented stdout/stderr contract, the exit discipline, and the +//! byte-identity of the local plan and release artifacts against the existing +//! `ci _*` runner family are only observable from outside the process, so they +//! are asserted here. +//! +//! These tests are hermetic: they read fixtures checked into this repository +//! plus temporary directories. No network, no repository discovery, no release +//! selection, no staging, and no publication. + +use std::path::{Path, PathBuf}; +use std::process::Command; +use std::sync::atomic::{AtomicU64, Ordering}; + +/// Canonical contract fixture used by the validation-surface tests. +const SIMPLE_CONTRACT: &str = + include_str!("../../eggpack-contract/tests/fixtures/simple-direct.toml"); + +/// Bounded GitHub draft template the `ci _resolve-release` runner requires. +const TEMPLATE: &str = r#"{ + "schema_version": 1, + "owner": "acme", + "repository": "widget", + "title_prefix": "widget ", + "body": "notes", + "prerelease": false, + "token_env": "GITHUB_TOKEN", + "request_timeout_secs": 30, + "max_metadata_bytes": 1000000, + "max_list_pages": 5 +}"#; + +/// Bounded provider policy the `ci generate` and `ci check` commands consume. +const GITHUB_POLICY: &str = r#"{ + "preflight_runner": "ubuntu-latest", + "runners": [ + { + "os": "linux", + "arch": "x86_64", + "label": "ubuntu-latest", + "cargo_zigbuild": false, + "zig": false + } + ], + "checkout": {"reference": "actions/checkout@0123456789abcdef0123456789abcdef01234567"}, + "rust_toolchain": {"reference": "dtolnay/rust-toolchain@0123456789abcdef0123456789abcdef01234567"}, + "upload_artifact": {"reference": "actions/upload-artifact@0123456789abcdef0123456789abcdef01234567"}, + "download_artifact": {"reference": "actions/download-artifact@0123456789abcdef0123456789abcdef01234567"}, + "triggers": ["push", "workflow_dispatch"], + "timeout_minutes": 60, + "cancel_in_progress": true, + "artifact_retention_days": 7, + "eggpack_tool": { + "repo": "https://github.com/eggstack/eggpack", + "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "package": "eggpack-cli", + "install_timeout_minutes": 10 + }, + "release_inputs": { + "contract": "contracts/release.toml", + "release_plan": "plans/release-plan.json", + "build_bindings": "bindings/build.toml", + "qualification_bindings": "bindings/qualification.toml", + "ci_plan": "plans/release-ci-plan.json" + } +}"#; + +/// Canonical target triple used by the portable (no real build) tests. +const TRIPLE: &str = "x86_64-unknown-linux-gnu"; +/// Canonical alias of [`TRIPLE`]. +const ALIAS: &str = "linux-x64"; + +/// Release identity shared by the local path and the runner family. +const RELEASE_ID: &str = "v1.2.3"; + +/// A syntactically valid, non-existent source revision. +const REVISION: &str = "0123456789abcdef0123456789abcdef01234567"; + +static NEXT: AtomicU64 = AtomicU64::new(0); + +fn temp_root(label: &str) -> PathBuf { + loop { + let id = NEXT.fetch_add(1, Ordering::Relaxed); + let path = std::env::temp_dir().join(format!( + "eggpack-cli-operator-{label}-{}-{id}", + std::process::id() + )); + match std::fs::create_dir(&path) { + Ok(()) => return path, + Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue, + Err(error) => panic!("create test temp directory: {error}"), + } + } +} + +struct Output { + code: i32, + stdout: String, + stderr: String, +} + +fn eggpack(args: &[String]) -> Output { + let output = Command::new(env!("CARGO_BIN_EXE_eggpack")) + .args(args) + .output() + .expect("run eggpack binary"); + Output { + code: output.status.code().expect("process exited normally"), + stdout: String::from_utf8(output.stdout).expect("stdout is UTF-8"), + stderr: String::from_utf8(output.stderr).expect("stderr is UTF-8"), + } +} + +fn argv(values: &[&str]) -> Vec { + values.iter().map(|value| (*value).to_owned()).collect() +} + +fn write_file(path: &Path, contents: &str) -> String { + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent).unwrap(); + } + std::fs::write(path, contents).unwrap(); + path.to_string_lossy().into_owned() +} + +/// One release's producer input set. +struct Inputs { + /// Contract TOML path. + contract: String, + /// Producer policy TOML path. + pack_config: String, + /// Build bindings TOML path. + build_bindings: String, + /// Qualification bindings TOML path. + qualification_bindings: String, + /// GitHub draft template JSON path. + template: String, +} + +/// Write the canonical producer input set for one target. +fn write_inputs(root: &Path, triple: &str, alias: &str, host_os: &str, host_arch: &str) -> Inputs { + let contract = write_file( + &root.join("contract.toml"), + &format!( + "schema_version = 1\n\n[product]\nid = \"eggsact\"\ndisplay_name = \"eggsact\"\n\n[[targets]]\ntriple = \"{triple}\"\naliases = [\"{alias}\"]\n\n[targets.asset]\nkind = \"direct\"\nasset = \"{{product}}-{{version}}-{{target}}\"\ninstall = \"{{product}}\"\n\n[targets.checksum]\nsidecar = \"{{asset}}.sha256\"\n" + ), + ); + let pack_config = write_file( + &root.join("pack.toml"), + &format!( + "schema_version = 1\n\n[[targets]]\ntarget = \"{triple}\"\nstrategy = \"native_cargo\"\nhost_os = \"{host_os}\"\nhost_arch = \"{host_arch}\"\nqualification = \"structural\"\nsupport = \"required\"\n\n[targets.toolchain]\nrust = \"stable\"\n\n[targets.floor]\nkind = \"none\"\n" + ), + ); + let build_bindings = write_file( + &root.join("build.toml"), + &format!( + "schema_version = 1\n\n[[targets.\"{triple}\"]]\nselector = {{ kind = \"direct\" }}\npackage = \"eggsact\"\nbinary = \"bin0\"\n" + ), + ); + let qualification_bindings = write_file( + &root.join("qualification.toml"), + &format!("schema_version = 1\n\n[targets.\"{triple}\"]\n"), + ); + let template = write_file(&root.join("template.json"), TEMPLATE); + Inputs { + contract, + pack_config, + build_bindings, + qualification_bindings, + template, + } +} + +/// Initialize a git repository with one commit and one exact tag. +fn init_git_repo(root: &Path, tag: &str) -> String { + let run = |args: &[&str]| { + let status = Command::new("git") + .args(args) + .current_dir(root) + .env("GIT_AUTHOR_NAME", "Eggpack test") + .env("GIT_AUTHOR_EMAIL", "test@example.invalid") + .env("GIT_COMMITTER_NAME", "Eggpack test") + .env("GIT_COMMITTER_EMAIL", "test@example.invalid") + .status() + .unwrap(); + assert!(status.success(), "git command failed: {args:?}"); + }; + run(&["init", "-q"]); + std::fs::write(root.join("source.txt"), "revision").unwrap(); + run(&["add", "source.txt"]); + run(&["commit", "-q", "-m", "revision"]); + run(&["tag", tag]); + let output = Command::new("git") + .args(["rev-parse", "HEAD^{commit}"]) + .current_dir(root) + .output() + .unwrap(); + assert!(output.status.success()); + String::from_utf8(output.stdout).unwrap().trim().to_owned() +} + +/// Write a Cargo project that builds one binary named `bin0`. +fn write_cargo_fixture(root: &Path) { + std::fs::create_dir_all(root.join("src")).unwrap(); + std::fs::write( + root.join("Cargo.toml"), + "[package]\nname = \"eggsact\"\nversion = \"0.1.0\"\nedition = \"2021\"\n\n[[bin]]\nname = \"bin0\"\npath = \"src/main.rs\"\n", + ) + .unwrap(); + std::fs::write( + root.join("Cargo.lock"), + "version = 3\n\n[[package]]\nname = \"eggsact\"\nversion = \"0.1.0\"\n", + ) + .unwrap(); + std::fs::write(root.join("src/main.rs"), "fn main() {}\n").unwrap(); +} + +/// The host target triple, alias, operating system, and architecture. +fn host_target() -> (String, String, &'static str, &'static str) { + match (std::env::consts::OS, std::env::consts::ARCH) { + ("windows", "x86_64") => ( + "x86_64-pc-windows-msvc".to_owned(), + "windows-x64".to_owned(), + "windows", + "x86_64", + ), + ("macos", "x86_64") => ( + "x86_64-apple-darwin".to_owned(), + "macos-x64".to_owned(), + "macos", + "x86_64", + ), + ("macos", "aarch64") => ( + "aarch64-apple-darwin".to_owned(), + "macos-arm64".to_owned(), + "macos", + "aarch64", + ), + ("linux", "x86_64") => ( + "x86_64-unknown-linux-gnu".to_owned(), + "linux-x64".to_owned(), + "linux", + "x86_64", + ), + ("linux", "aarch64") => ( + "aarch64-unknown-linux-gnu".to_owned(), + "linux-arm64".to_owned(), + "linux", + "aarch64", + ), + other => panic!("unsupported host platform: {other:?}"), + } +} + +/// The valid argument vector of one command, with placeholder paths. +fn valid_args(command: &str) -> Vec { + match command { + "check" => argv(&[ + command, + "--contract", + "contract.toml", + "--pack-config", + "pack.toml", + "--build-bindings", + "build.toml", + "--qualification-bindings", + "qualification.toml", + "--selected", + ALIAS, + "--release-id", + RELEASE_ID, + "--source-revision", + REVISION, + ]), + "plan" => argv(&[ + command, + "--contract", + "contract.toml", + "--pack-config", + "pack.toml", + "--build-bindings", + "build.toml", + "--qualification-bindings", + "qualification.toml", + "--selected", + ALIAS, + "--release-id", + RELEASE_ID, + "--source-revision", + REVISION, + "--output", + "release-plan.json", + ]), + "package" => argv(&[ + command, + "--release-plan", + "release-plan.json", + "--build-bindings", + "build.toml", + "--source-root", + "source", + "--output-root", + "out", + ]), + "qualify" => argv(&[ + command, + "--contract", + "contract.toml", + "--release-plan", + "release-plan.json", + "--build-bindings", + "build.toml", + "--qualification-bindings", + "qualification.toml", + "--candidates-dir", + "candidates", + "--output-dir", + "qualified", + ]), + "collect" => argv(&[ + command, + "--contract", + "contract.toml", + "--release-plan", + "release-plan.json", + "--build-bindings", + "build.toml", + "--qualification-bindings", + "qualification.toml", + "--candidates-dir", + "candidates", + "--output-root", + "finalized", + ]), + "manifest" => argv(&[ + command, + "--contract", + "contract.toml", + "--release-plan", + "release-plan.json", + "--finalized-root", + "finalized", + "--output", + "release-manifest.json", + ]), + other => panic!("unknown command: {other}"), + } +} + +/// Every command in the operator family. +const COMMANDS: [&str; 6] = ["check", "plan", "package", "qualify", "collect", "manifest"]; + +/// Rewrite `--flag value` pairs into the `--flag=value` form. +fn to_equals_form(args: &[String]) -> Vec { + let mut out = Vec::with_capacity(args.len()); + let mut index = 0; + while index < args.len() { + let arg = &args[index]; + if arg.starts_with("--") && index + 1 < args.len() && !args[index + 1].starts_with("--") { + out.push(format!("{arg}={}", args[index + 1])); + index += 2; + } else { + out.push(arg.clone()); + index += 1; + } + } + out +} + +/// Assert a failing invocation: nonzero exit, one bounded diagnostic, and no +/// stdout at all. +fn assert_failure(out: &Output, context: &str) { + assert_eq!(out.code, 1, "{context} must exit with code one"); + assert_eq!(out.stdout, "", "{context} must not write to stdout"); + assert!( + out.stderr.starts_with("eggpack: "), + "{context} diagnostic: {}", + out.stderr + ); + assert_eq!( + out.stderr.lines().count(), + 1, + "{context} must emit exactly one diagnostic line" + ); + assert!( + out.stderr.len() < 1024, + "{context} diagnostic must stay bounded" + ); +} + +/// Every command exits zero on success and one on failure. +#[test] +fn every_command_exits_zero_on_success_and_one_on_failure() { + let root = temp_root("exit-codes"); + let inputs = write_inputs(&root, TRIPLE, ALIAS, "linux", "x86_64"); + let out = eggpack(&argv(&[ + "check", + "--contract", + &inputs.contract, + "--pack-config", + &inputs.pack_config, + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--selected", + ALIAS, + "--release-id", + RELEASE_ID, + "--source-revision", + REVISION, + ])); + assert_eq!(out.code, 0, "stderr: {}", out.stderr); + for command in COMMANDS { + let mut args = valid_args(command); + // Point the first document flag at a document that does not exist. + let index = args + .iter() + .position(|value| value == "--contract") + .or_else(|| args.iter().position(|value| value == "--release-plan")) + .expect("a document flag"); + args[index + 1] = root.join("absent.json").to_string_lossy().into_owned(); + let out = eggpack(&args); + assert_eq!(out.code, 1, "{command} must exit with code one"); + assert_eq!(out.stdout, "", "{command} must not write to stdout"); + } + std::fs::remove_dir_all(&root).unwrap(); +} + +/// `eggpack check` accepts a valid input set and reports one verdict line. +#[test] +fn check_accepts_a_valid_input_set() { + let root = temp_root("check-ok"); + let inputs = write_inputs(&root, TRIPLE, ALIAS, "linux", "x86_64"); + let out = eggpack(&argv(&[ + "check", + "--contract", + &inputs.contract, + "--pack-config", + &inputs.pack_config, + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--selected", + ALIAS, + "--release-id", + RELEASE_ID, + "--source-revision", + REVISION, + ])); + assert_eq!(out.code, 0, "stderr: {}", out.stderr); + assert_eq!(out.stdout, "check: ok\n"); + assert_eq!(out.stderr, ""); + std::fs::remove_dir_all(&root).unwrap(); +} + +/// `eggpack check` refuses a contract with an unknown field. +#[test] +fn check_rejects_a_contract_with_an_unknown_field() { + let root = temp_root("check-unknown-field"); + let inputs = write_inputs(&root, TRIPLE, ALIAS, "linux", "x86_64"); + let broken = write_file( + &root.join("broken.toml"), + &format!("{}\nunknown_field = 1\n", SIMPLE_CONTRACT), + ); + let out = eggpack(&argv(&[ + "check", + "--contract", + &broken, + "--pack-config", + &inputs.pack_config, + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--selected", + ALIAS, + "--release-id", + RELEASE_ID, + "--source-revision", + REVISION, + ])); + assert_failure(&out, "unknown contract field"); + std::fs::remove_dir_all(&root).unwrap(); +} + +/// `eggpack check` refuses a contract with the wrong schema version. +#[test] +fn check_rejects_a_contract_with_the_wrong_schema_version() { + let root = temp_root("check-schema-version"); + let inputs = write_inputs(&root, TRIPLE, ALIAS, "linux", "x86_64"); + let broken = write_file( + &root.join("broken.toml"), + &SIMPLE_CONTRACT.replacen("schema_version = 1", "schema_version = 2", 1), + ); + let out = eggpack(&argv(&[ + "check", + "--contract", + &broken, + "--pack-config", + &inputs.pack_config, + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--selected", + ALIAS, + "--release-id", + RELEASE_ID, + "--source-revision", + REVISION, + ])); + assert_failure(&out, "wrong contract schema version"); + std::fs::remove_dir_all(&root).unwrap(); +} + +/// `eggpack check` refuses a selected target the producer policy does not +/// cover. +#[test] +fn check_rejects_an_uncovered_selected_target() { + let root = temp_root("check-uncovered"); + let inputs = write_inputs(&root, TRIPLE, ALIAS, "linux", "x86_64"); + let out = eggpack(&argv(&[ + "check", + "--contract", + &inputs.contract, + "--pack-config", + &inputs.pack_config, + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--selected", + "macos-arm64", + "--release-id", + RELEASE_ID, + "--source-revision", + REVISION, + ])); + assert_failure(&out, "uncovered selected target"); + std::fs::remove_dir_all(&root).unwrap(); +} + +/// `eggpack check` refuses a binding for a target outside the release plan. +#[test] +fn check_rejects_an_extra_build_binding() { + let root = temp_root("check-extra-binding"); + let inputs = write_inputs(&root, TRIPLE, ALIAS, "linux", "x86_64"); + let extra = write_file( + &root.join("extra.toml"), + &format!( + "schema_version = 1\n\n[[targets.\"{TRIPLE}\"]]\nselector = {{ kind = \"direct\" }}\npackage = \"eggsact\"\nbinary = \"bin0\"\n\n[[targets.\"aarch64-apple-darwin\"]]\nselector = {{ kind = \"direct\" }}\npackage = \"eggsact\"\nbinary = \"bin0\"\n" + ), + ); + let out = eggpack(&argv(&[ + "check", + "--contract", + &inputs.contract, + "--pack-config", + &inputs.pack_config, + "--build-bindings", + &extra, + "--qualification-bindings", + &inputs.qualification_bindings, + "--selected", + ALIAS, + "--release-id", + RELEASE_ID, + "--source-revision", + REVISION, + ])); + assert_failure(&out, "extra build binding"); + std::fs::remove_dir_all(&root).unwrap(); +} + +/// `eggpack plan` writes the same bytes as the `ci _resolve-release` runner. +#[test] +fn plan_writes_the_same_bytes_as_ci_resolve_release() { + let root = temp_root("plan-bytes"); + let revision = init_git_repo(&root, RELEASE_ID); + let inputs = write_inputs(&root, TRIPLE, ALIAS, "linux", "x86_64"); + let runner_plan = root.join("runner-plan.json"); + let out = eggpack(&argv(&[ + "ci", + "_resolve-release", + "--contract", + &inputs.contract, + "--pack-config", + &inputs.pack_config, + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--selected", + ALIAS, + "--tag", + RELEASE_ID, + "--source-revision", + &revision, + "--template", + &inputs.template, + "--source-root", + &root.to_string_lossy(), + "--output-plan", + &runner_plan.to_string_lossy(), + "--output-ci-plan", + &root.join("runner-ci-plan.json").to_string_lossy(), + "--output-github-policy", + &root.join("runner-github.json").to_string_lossy(), + ])); + assert_eq!(out.code, 0, "stderr: {}", out.stderr); + + let local_plan = root.join("local-plan.json"); + let out = eggpack(&argv(&[ + "plan", + "--contract", + &inputs.contract, + "--pack-config", + &inputs.pack_config, + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--selected", + ALIAS, + "--release-id", + RELEASE_ID, + "--source-revision", + &revision, + "--output", + &local_plan.to_string_lossy(), + ])); + assert_eq!(out.code, 0, "stderr: {}", out.stderr); + assert_eq!(out.stdout, "plan: ok\n"); + assert_eq!( + std::fs::read(&local_plan).unwrap(), + std::fs::read(&runner_plan).unwrap(), + "eggpack plan and ci _resolve-release must write identical plan bytes" + ); + std::fs::remove_dir_all(&root).unwrap(); +} + +/// The local build → qualify → collect → manifest chain produces the same +/// release manifest bytes as the `ci _aggregate` runner, and the same bytes as +/// the manifest derived from the finalized tree. +#[test] +fn package_qualify_collect_manifest_matches_ci_aggregate() { + let root = temp_root("chain"); + let (triple, alias, host_os, host_arch) = host_target(); + let inputs = write_inputs(&root, &triple, &alias, host_os, host_arch); + let source = root.join("source"); + write_cargo_fixture(&source); + let repo = root.join("repo"); + std::fs::create_dir_all(&repo).unwrap(); + let revision = init_git_repo(&repo, RELEASE_ID); + + // The release plan the whole chain consumes. + let plan_path = root.join("release-plan.json"); + let out = eggpack(&argv(&[ + "plan", + "--contract", + &inputs.contract, + "--pack-config", + &inputs.pack_config, + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--selected", + &alias, + "--release-id", + RELEASE_ID, + "--source-revision", + &revision, + "--output", + &plan_path.to_string_lossy(), + ])); + assert_eq!(out.code, 0, "plan stderr: {}", out.stderr); + assert_eq!(out.stdout, "plan: ok\n"); + + // Build every planned target under the caller's output root. + let candidates = root.join("candidates"); + let out = eggpack(&argv(&[ + "package", + "--release-plan", + &plan_path.to_string_lossy(), + "--build-bindings", + &inputs.build_bindings, + "--source-root", + &source.to_string_lossy(), + "--output-root", + &candidates.to_string_lossy(), + ])); + assert_eq!(out.code, 0, "package stderr: {}", out.stderr); + assert_eq!(out.stdout, "package: ok\n"); + assert!(candidates.join(&triple).join("build-handoff.json").exists()); + + // Qualify the built candidates. + let qualified = root.join("qualified"); + let out = eggpack(&argv(&[ + "qualify", + "--contract", + &inputs.contract, + "--release-plan", + &plan_path.to_string_lossy(), + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--candidates-dir", + &candidates.to_string_lossy(), + "--output-dir", + &qualified.to_string_lossy(), + ])); + assert_eq!(out.code, 0, "qualify stderr: {}", out.stderr); + assert_eq!(out.stdout, "qualify: ok\n"); + assert!(qualified.join(&triple).join("evidence.json").exists()); + + // Aggregate the qualified candidates into a finalized release tree. + let local = root.join("local"); + std::fs::create_dir_all(&local).unwrap(); + let finalized = local.join("finalized"); + let out = eggpack(&argv(&[ + "collect", + "--contract", + &inputs.contract, + "--release-plan", + &plan_path.to_string_lossy(), + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--candidates-dir", + &qualified.to_string_lossy(), + "--output-root", + &finalized.to_string_lossy(), + ])); + assert_eq!(out.code, 0, "collect stderr: {}", out.stderr); + assert_eq!(out.stdout, "collect: ok\n"); + let collected_manifest = local.join("release-manifest.json"); + assert!(collected_manifest.exists()); + + // The manifest derived from the finalized tree is the same document. + let derived_manifest = root.join("derived-manifest.json"); + let out = eggpack(&argv(&[ + "manifest", + "--contract", + &inputs.contract, + "--release-plan", + &plan_path.to_string_lossy(), + "--finalized-root", + &finalized.to_string_lossy(), + "--output", + &derived_manifest.to_string_lossy(), + ])); + assert_eq!(out.code, 0, "manifest stderr: {}", out.stderr); + assert_eq!(out.stdout, "manifest: ok\n"); + assert_eq!( + std::fs::read(&derived_manifest).unwrap(), + std::fs::read(&collected_manifest).unwrap(), + "the derived manifest must equal the aggregated manifest" + ); + + // The runner family aggregates the same bytes into the same manifest. + let ci_plan = root.join("ci-plan.json"); + let out = eggpack(&argv(&[ + "ci", + "_resolve-release", + "--contract", + &inputs.contract, + "--pack-config", + &inputs.pack_config, + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--selected", + &alias, + "--tag", + RELEASE_ID, + "--source-revision", + &revision, + "--template", + &inputs.template, + "--source-root", + &repo.to_string_lossy(), + "--output-plan", + &root.join("runner-plan.json").to_string_lossy(), + "--output-ci-plan", + &ci_plan.to_string_lossy(), + "--output-github-policy", + &root.join("runner-github.json").to_string_lossy(), + ])); + assert_eq!(out.code, 0, "resolve stderr: {}", out.stderr); + let runner = root.join("runner"); + std::fs::create_dir_all(&runner).unwrap(); + let runner_finalized = runner.join("finalized"); + let out = eggpack(&argv(&[ + "ci", + "_aggregate", + "--contract", + &inputs.contract, + "--release-plan", + &plan_path.to_string_lossy(), + "--ci-plan", + &ci_plan.to_string_lossy(), + "--inputs-dir", + &qualified.to_string_lossy(), + "--output-root", + &runner_finalized.to_string_lossy(), + "--output", + &runner.join("summary.json").to_string_lossy(), + ])); + assert_eq!(out.code, 0, "aggregate stderr: {}", out.stderr); + assert_eq!( + std::fs::read(runner.join("release-manifest.json")).unwrap(), + std::fs::read(&collected_manifest).unwrap(), + "eggpack collect and ci _aggregate must write identical manifest bytes" + ); + std::fs::remove_dir_all(&root).unwrap(); +} + +/// Every command refuses an unknown flag. +#[test] +fn every_command_rejects_an_unknown_flag() { + for command in COMMANDS { + let mut args = valid_args(command); + args.push("--not-a-flag".to_owned()); + args.push("value".to_owned()); + let out = eggpack(&args); + assert_failure(&out, &format!("{command} unknown flag")); + assert!( + out.stderr.contains("unknown option"), + "{command} diagnostic: {}", + out.stderr + ); + } +} + +/// Every command refuses a duplicated flag. +#[test] +fn every_command_rejects_a_duplicate_flag() { + for command in COMMANDS { + let mut args = valid_args(command); + let first = args[1].clone(); + args.push(first); + args.push("value".to_owned()); + let out = eggpack(&args); + assert_failure(&out, &format!("{command} duplicate flag")); + assert!( + out.stderr.contains("only once"), + "{command} diagnostic: {}", + out.stderr + ); + } +} + +/// Every command refuses an empty flag value. +#[test] +fn every_command_rejects_an_empty_value() { + for command in COMMANDS { + let mut args = valid_args(command); + let index = args + .iter() + .position(|value| value == "--contract") + .or_else(|| args.iter().position(|value| value == "--release-plan")) + .expect("a value-bearing flag"); + args[index + 1] = String::new(); + let out = eggpack(&args); + assert_failure(&out, &format!("{command} empty value")); + assert!( + out.stderr.contains("must not be empty"), + "{command} diagnostic: {}", + out.stderr + ); + } +} + +/// Every command refuses a positional argument. +#[test] +fn every_command_rejects_a_positional_argument() { + for command in COMMANDS { + let mut args = valid_args(command); + args.push("positional".to_owned()); + let out = eggpack(&args); + assert_failure(&out, &format!("{command} positional argument")); + assert!( + out.stderr.contains("unexpected argument"), + "{command} diagnostic: {}", + out.stderr + ); + } +} + +/// Every command refuses a missing required flag. +#[test] +fn every_command_rejects_a_missing_flag() { + for command in COMMANDS { + let mut args = valid_args(command); + // Drop the first flag and its value. + args.remove(1); + args.remove(1); + let out = eggpack(&args); + assert_failure(&out, &format!("{command} missing flag")); + assert!( + out.stderr.contains("missing required"), + "{command} diagnostic: {}", + out.stderr + ); + } +} + +/// Every command accepts the `--flag=value` form. +#[test] +fn every_command_accepts_the_equals_flag_value_form() { + let root = temp_root("equals-form"); + let inputs = write_inputs(&root, TRIPLE, ALIAS, "linux", "x86_64"); + let out = eggpack(&to_equals_form(&argv(&[ + "check", + "--contract", + &inputs.contract, + "--pack-config", + &inputs.pack_config, + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--selected", + ALIAS, + "--release-id", + RELEASE_ID, + "--source-revision", + REVISION, + ]))); + assert_eq!(out.code, 0, "stderr: {}", out.stderr); + assert_eq!(out.stdout, "check: ok\n"); + for command in COMMANDS { + let out = eggpack(&to_equals_form(&valid_args(command))); + assert!( + !out.stderr.contains("unknown option") + && !out.stderr.contains("unexpected argument") + && !out.stderr.contains("missing required") + && !out.stderr.contains("only once") + && !out.stderr.contains("must not be empty"), + "{command} must accept the --flag=value form: {}", + out.stderr + ); + } + std::fs::remove_dir_all(&root).unwrap(); +} + +/// Every command refuses an oversized input document. +#[test] +fn every_command_rejects_an_oversized_input() { + let root = temp_root("oversized"); + let inputs = write_inputs(&root, TRIPLE, ALIAS, "linux", "x86_64"); + let oversized = write_file(&root.join("oversized.toml"), &"x".repeat(1_000_001)); + let oversized_plan = write_file(&root.join("oversized-plan.json"), &"x".repeat(1_000_001)); + let cases: Vec<(&str, Vec)> = vec![ + ( + "check", + argv(&[ + "check", + "--contract", + &oversized, + "--pack-config", + &inputs.pack_config, + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--selected", + ALIAS, + "--release-id", + RELEASE_ID, + "--source-revision", + REVISION, + ]), + ), + ( + "plan", + argv(&[ + "plan", + "--contract", + &oversized, + "--pack-config", + &inputs.pack_config, + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--selected", + ALIAS, + "--release-id", + RELEASE_ID, + "--source-revision", + REVISION, + "--output", + &root.join("plan.json").to_string_lossy(), + ]), + ), + ( + "package", + argv(&[ + "package", + "--release-plan", + &oversized_plan, + "--build-bindings", + &inputs.build_bindings, + "--source-root", + &root.to_string_lossy(), + "--output-root", + &root.join("out").to_string_lossy(), + ]), + ), + ( + "qualify", + argv(&[ + "qualify", + "--contract", + &oversized, + "--release-plan", + "release-plan.json", + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--candidates-dir", + "candidates", + "--output-dir", + "qualified", + ]), + ), + ( + "collect", + argv(&[ + "collect", + "--contract", + &oversized, + "--release-plan", + "release-plan.json", + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--candidates-dir", + "candidates", + "--output-root", + "finalized", + ]), + ), + ( + "manifest", + argv(&[ + "manifest", + "--contract", + &oversized, + "--release-plan", + "release-plan.json", + "--finalized-root", + "finalized", + "--output", + "release-manifest.json", + ]), + ), + ]; + for (command, args) in cases { + let out = eggpack(&args); + assert_failure(&out, &format!("{command} oversized input")); + } + std::fs::remove_dir_all(&root).unwrap(); +} + +/// Every command refuses a symlinked output path. +#[test] +#[cfg(unix)] +fn every_command_rejects_a_symlinked_output_path() { + use std::os::unix::fs::symlink; + + let root = temp_root("symlink"); + let inputs = write_inputs(&root, TRIPLE, ALIAS, "linux", "x86_64"); + let real = write_file(&root.join("real.json"), "{}"); + let link = root.join("link.json"); + symlink(&real, &link).unwrap(); + let cases: Vec<(&str, Vec)> = vec![ + ( + "plan", + argv(&[ + "plan", + "--contract", + &inputs.contract, + "--pack-config", + &inputs.pack_config, + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--selected", + ALIAS, + "--release-id", + RELEASE_ID, + "--source-revision", + REVISION, + "--output", + &link.to_string_lossy(), + ]), + ), + ( + "manifest", + argv(&[ + "manifest", + "--contract", + &inputs.contract, + "--release-plan", + "release-plan.json", + "--finalized-root", + "finalized", + "--output", + &link.to_string_lossy(), + ]), + ), + ]; + for (command, args) in cases { + let out = eggpack(&args); + assert_failure(&out, &format!("{command} symlinked output")); + } + // A symlinked output directory is refused too: the caller's root is + // written into directly, never followed. + let real_dir = root.join("real-dir"); + std::fs::create_dir_all(&real_dir).unwrap(); + let dir_link = root.join("link-dir"); + symlink(&real_dir, &dir_link).unwrap(); + let dir_cases: Vec<(&str, Vec)> = vec![ + ( + "package", + argv(&[ + "package", + "--release-plan", + "release-plan.json", + "--build-bindings", + &inputs.build_bindings, + "--source-root", + &root.to_string_lossy(), + "--output-root", + &dir_link.to_string_lossy(), + ]), + ), + ( + "qualify", + argv(&[ + "qualify", + "--contract", + &inputs.contract, + "--release-plan", + "release-plan.json", + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--candidates-dir", + "candidates", + "--output-dir", + &dir_link.to_string_lossy(), + ]), + ), + ( + "collect", + argv(&[ + "collect", + "--contract", + &inputs.contract, + "--release-plan", + "release-plan.json", + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--candidates-dir", + "candidates", + "--output-root", + &dir_link.to_string_lossy(), + ]), + ), + ]; + for (command, args) in dir_cases { + let out = eggpack(&args); + assert_failure(&out, &format!("{command} symlinked output directory")); + } + std::fs::remove_dir_all(&root).unwrap(); +} + +/// `--help` names every command and states its class. +#[test] +fn help_names_every_command_and_its_class() { + let out = eggpack(&argv(&["--help"])); + assert_eq!(out.code, 0, "stderr: {}", out.stderr); + for (command, class) in [ + ("check", "validation"), + ("plan", "validation"), + ("package", "build"), + ("qualify", "build"), + ("collect", "release aggregation"), + ("manifest", "final-bytes evidence"), + ] { + assert!( + out.stdout.contains(command), + "top-level help must name {command}: {}", + out.stdout + ); + assert!( + out.stdout.contains(class), + "top-level help must state the {command} class: {}", + out.stdout + ); + } + assert!( + out.stdout + .contains("No command in this set stages or publishes"), + "top-level help must state that nothing stages or publishes: {}", + out.stdout + ); + for command in COMMANDS { + let out = eggpack(&argv(&[command, "--help"])); + assert_eq!(out.code, 0, "{command} --help stderr: {}", out.stderr); + assert!( + out.stdout.contains(command), + "{command} --help must name the command: {}", + out.stdout + ); + assert!( + out.stdout + .contains("No command in this set stages or publishes"), + "{command} --help must state that nothing stages or publishes: {}", + out.stdout + ); + } +} + +/// The historical command families keep their documented behaviour. +#[test] +fn existing_command_families_still_behave() { + let root = temp_root("existing"); + let inputs = write_inputs(&root, TRIPLE, ALIAS, "linux", "x86_64"); + let repo = root.join("repo"); + std::fs::create_dir_all(&repo).unwrap(); + let revision = init_git_repo(&repo, RELEASE_ID); + + // `eggpack contract expand` still answers one scalar on stdout. + let out = eggpack(&argv(&[ + "contract", + "expand", + "--contract", + &inputs.contract, + "--release-id", + RELEASE_ID, + "--target", + ALIAS, + "--field", + "asset", + ])); + assert_eq!(out.code, 0, "stderr: {}", out.stderr); + assert_eq!(out.stdout, format!("eggsact-{RELEASE_ID}-{TRIPLE}\n")); + assert_eq!(out.stderr, ""); + + // `eggpack ci _resolve-release` still writes the three runtime documents. + let ci_plan = root.join("ci-plan.json"); + let policy = root.join("github.json"); + let out = eggpack(&argv(&[ + "ci", + "_resolve-release", + "--contract", + &inputs.contract, + "--pack-config", + &inputs.pack_config, + "--build-bindings", + &inputs.build_bindings, + "--qualification-bindings", + &inputs.qualification_bindings, + "--selected", + ALIAS, + "--tag", + RELEASE_ID, + "--source-revision", + &revision, + "--template", + &inputs.template, + "--source-root", + &repo.to_string_lossy(), + "--output-plan", + &root.join("plan.json").to_string_lossy(), + "--output-ci-plan", + &ci_plan.to_string_lossy(), + "--output-github-policy", + &policy.to_string_lossy(), + ])); + assert_eq!(out.code, 0, "stderr: {}", out.stderr); + assert!(ci_plan.exists()); + assert!(policy.exists()); + + // `eggpack ci generate` still writes a workflow, and `ci check` still + // accepts the unmodified workflow. + let provider_policy = write_file(&root.join("provider-policy.json"), GITHUB_POLICY); + let workflow = root.join("workflow.yml"); + let out = eggpack(&argv(&[ + "ci", + "generate", + "--ci-plan", + &ci_plan.to_string_lossy(), + "--github-policy", + &provider_policy, + "--output", + &workflow.to_string_lossy(), + ])); + assert_eq!(out.code, 0, "generate stderr: {}", out.stderr); + assert!(workflow.exists()); + assert!( + out.stdout.starts_with("generated "), + "generate stdout: {}", + out.stdout + ); + let out = eggpack(&argv(&[ + "ci", + "check", + "--ci-plan", + &ci_plan.to_string_lossy(), + "--github-policy", + &provider_policy, + "--workflow", + &workflow.to_string_lossy(), + ])); + assert_eq!(out.code, 0, "check stderr: {}", out.stderr); + assert!( + out.stdout.starts_with("ci check: match"), + "check stdout: {}", + out.stdout + ); + std::fs::remove_dir_all(&root).unwrap(); +} From 8950eb9c3253da80c3e48fbaacc6a2a25d471830 Mon Sep 17 00:00:00 2001 From: doc Date: Fri, 23 Oct 2026 16:42:18 +0000 Subject: [PATCH 10/46] docs(cli): document the local producer operator commands Rewrites docs/quickstart.md as a verified end-to-end walkthrough of the local producer path (check -> plan -> package -> qualify -> collect -> manifest) followed by the retained CI rendering and drift-check sections. Every command and quoted output in it was run verbatim. Rewrites crates/eggpack-cli/README.md as the actual full command reference it was already promised to be: every operator command, the ci family, the nine internal ci _* runners with their real flag surfaces, and contract expand. Documents the operator surface, the command taxonomy, and the explicit statement that this milestone adds no staging or publication command in architecture/cli.md, re-basing its file:line citations by symbol name. --- architecture/cli.md | 736 +++++++++++++++++++++-------------- crates/eggpack-cli/README.md | 521 ++++++++++++++++++++++++- docs/quickstart.md | 297 +++++++++++++- 3 files changed, 1247 insertions(+), 307 deletions(-) diff --git a/architecture/cli.md b/architecture/cli.md index adf639a..39891cd 100644 --- a/architecture/cli.md +++ b/architecture/cli.md @@ -2,12 +2,13 @@ The deterministic wiring layer of the workspace and the only binary the generated workflow actually invokes. `eggpack-cli` contributes exactly one -artifact — the `eggpack` binary (`crates/eggpack-cli/Cargo.toml11-13`) from a -single file, `crates/eggpack-cli/src/main.rs` (2940 lines) — and every release -decision in it is delegated to a library crate. +artifact — the `eggpack` binary (`crates/eggpack-cli/Cargo.toml11-13`) — built +from two source files: `crates/eggpack-cli/src/main.rs` (4531 lines) and +`crates/eggpack-cli/src/operator.rs` (730 lines). Every release decision in +both is delegated to a library crate. -All citations below are `crates/eggpack-cli/src/main.rs:LINE` unless another -file is named. +Citations below are `crates/eggpack-cli/src/main.rs:LINE` unless another file +is named; `operator.rs` citations are `crates/eggpack-cli/src/operator.rs:LINE`. ## Responsibility and the wiring rule @@ -17,72 +18,90 @@ planning, build, qualification, or finalization logic (`eggpack-core`), no rendering, gating, or aggregation logic (`eggpack-ci`), no draft-staging logic (`eggpack-github`), and no installer rendering (`eggpack-bootstrap`). -The boundary is verifiable rather than aspirational. There are zero `pub` items -in the file, so nothing here is a library API another crate can depend on. Every -semantic question is asked of a library call and the answer used verbatim: +The boundary is verifiable rather than aspirational. There are zero `pub` +items in `main.rs`, and the only visibility beyond the crate is three +`pub(crate)` items in `operator.rs` — a command descriptor and its table +(`operator.rs:32-42`, `operator.rs:45-82`) and the family dispatcher (`operator.rs:218`). +So nothing here is a library API another crate can depend on. Every semantic +question is asked of a library call and the answer used verbatim: `PackConfig::resolve` and `GitHubDraftTemplateV1::resolve` via -`resolve_runtime_release_plan_with_mode` (`441`, `449`), gate policy via -`evaluate_gate` (`1188`, `1227`), qualification via `qualify_target` (`900`), -finalization via `aggregate_finalize[_with_consumer]` (`1320`, `1338`). +`resolve_runtime_release_plan_with_mode` (`478`, `operator.rs:258`), gate policy +via `evaluate_gate` (`1350`, `1364`), qualification via `qualify_target` +(`1103`, `operator.rs:545`), finalization via `aggregate_finalize[_with_consumer]` +(`1421`, `1439`, `operator.rs:629`). What the crate does keep are fail-closed preconditions checked *before* delegation, plus path adapters. Neither is a release rule: | Local check | Line | Why it is wiring, not policy | |---|---|---| -| Argument arity caps | `374`, `569`, `592`, `623`, `654`, `971`, `1306`, `1367` | Rejects an invocation the renderer would never emit. No release meaning. | -| Paired-flag requirements | `690-695`, `1075-1077`, `1311-1316` | Selects between two library entry points. | -| Non-`Passed` evidence refused before a consumer script runs | `994-999` | A guard on the validator seam; the gate also fails closed on it. | -| Handoff/evidence identity cross-checks | `983-985`, `1000-1005`, `1006-1019` | Confirms the two files describe the same target, release, and revision. | -| Stray `consumer-evidence.json` rejected | `1099-1108`, `1196-1201` | Prevents validation being silently skipped. | -| Manifest round-trip byte comparison | `1240-1247` | Proves the sidecar is the same document, not a re-serialization. | -| `absolute_path` / `absolute_under_root` / `absolutize_cli_path` | `912`, `888`, `931` | Adapters between the renderer's portable relative paths and the absolute paths core requires (`921-930`). | -| `contract expand` 1 MiB input bound | `94`, `298` | Rejects an oversized local contract before parsing. No release meaning. | -| `contract expand` scalar output bound | `100`, `281-285` | Refuses to print a value it cannot bound. No release meaning. | -| `contract expand` exact argument set | `181-244` | A consumer script reads this output, so silently keeping the first of a repeated flag is not acceptable here. | +| Argument arity caps | `452`, `837`, `891`, `922`, `1212`, `1514`, `1575` | Rejects an invocation the renderer would never emit. No release meaning. | +| Paired-flag requirements | `954-959`, `1316-1318`, `1519-1524` | Selects between two library entry points. | +| Non-`Passed` evidence refused before a consumer script runs | `1235-1239` | A guard on the validator seam; the gate also fails closed on it. | +| Handoff/evidence identity cross-checks | `1224`, `1241-1246` | Confirms the two files describe the same target, release, and revision. | +| Stray `consumer-evidence.json` rejected | `1340-1349`, `1415-1419`, `operator.rs:620-628` | Prevents validation being silently bypassed. | +| Manifest round-trip byte comparison | `735-737` | Proves the sidecar is the same document, not a re-serialization. | +| `absolute_path` / `absolute_under_root` / `absolutize_cli_path` | `1153`, `1129`, `1172` | Adapters between the renderer's portable relative paths and the absolute paths core requires (`1269-1271`, `1090`). | +| Operator flag strictness | `operator.rs:151-204` | A consumer-facing surface: a repeated flag must not silently take the first value. | +| `contract expand` 1 MiB input bound | `133`, `346` | Rejects an oversized local contract before parsing. No release meaning. | +| `contract expand` scalar output bound | `140`, `330-334` | Refuses to print a value it cannot bound. No release meaning. | +| `contract expand` exact argument set | `230-293` | A consumer script reads this output, so silently keeping the first of a repeated flag is not acceptable here. | The rule of thumb: if the answer would change when a library changes, the check belongs in the library. The adapters are the only code here whose reason for existing is a mismatch between two other crates, and each says so at its call -site (`787-788`, `1145-1146`). +site (`1168-1171`, `1051-1052`, `1386-1387`). ## Argument parsing, hand-rolled -`dispatch` (`:21`) selects a command family and nothing else. Two usage -constants hold the help text — `USAGE` (`:44`) and `CONTRACT_USAGE` (`:47`) — -reused verbatim at `:23`, `:30`, `:31`, `:37`, `:38`, `:53`, and `:77`: +`dispatch` (`24`) selects a command family and nothing else. Three usage +constants hold the help text — `OPERATOR_USAGE` (`50`), `USAGE` (`54`), and +`CONTRACT_USAGE` (`57`) — reused verbatim at `67`, `82`, `83`, `115`, and in +the `help_text` body (`65-85`): ```text +usage: eggpack [options] + usage: eggpack ci [options] usage: eggpack contract expand --contract --release-id --target --field ``` -Order of decisions: empty argv is a usage error (`:22-24`); `--version`/`-V` -prints `eggpack ` and exits 0 (`:25-28`); `--help`/`-h` -prints both usage lines and exits 0 (`:29-32`); all three are handled *before* -the family match, so they work only as the first token. The family match at -`:34-40` accepts exactly `ci` and `contract`; any other first token is a usage -error naming the family. `ci_dispatch` (`:51`) preserves the historical -behaviour verbatim, including the `unknown ci subcommand` diagnostic (`:68`) and -the eleven subcommand arms (`:57-67`), plus a bare `ci` as a usage error -(`:52-54`). `contract_dispatch` (`:73`) accepts `expand` (`:75`), `help` -(`:76-79`), and rejects anything else (`:80`, `:81`). - -`contract expand` deliberately does **not** use the shared flag helper. -`parse_contract_expand_args` (`:181`) is command-local and exact: it accepts -`--name value` and `--name=value` (`:194-197`, `:204-212`), rejects positional -arguments (`:188-193`), unknown options (`:198-200`), a repeated flag rather -than keeping the first (`:201-203`), empty values (`:213-215`), and reports -every missing required flag in sorted order (`:220-228`). - -`get_flag` (`465`) accepts exactly two forms: `--name value` (`469-474`) and -`--name=value` (`475-477`). Its two error messages are `missing value for ---name` (`473`) and `missing required --name` (`479`). `get_flag_optional` -(`482`) is the same scan returning `Option`. Both scan left to right and return +Order of decisions: empty argv is a usage error (`25-27`); `--version`/`-V` +prints `eggpack ` and exits 0 (`28-31`); `--help`/`-h` +prints the full help and exits 0 (`32-35`); all three are handled *before* the +family match, so they work only as the first token. The family match at +`36-46` accepts exactly `ci`, `contract`, and the six operator commands +`check`, `plan`, `package`, `qualify`, `collect`, and `manifest` (`39-41`); +any other first token is a usage error naming the family. `ci_dispatch` (`89`) +preserves the historical behaviour verbatim, including the `unknown ci +subcommand` diagnostic (`106`) and the eleven subcommand arms (`95-105`), plus a +bare `ci` as a usage error (`90-92`). `contract_dispatch` (`111`) accepts +`expand` (`113`), `help` (`114-117`), and rejects anything else (`118`, `119`). + +There are now **two** parsers, and the difference is deliberate. + +`contract expand` does **not** use the shared flag helper. +`parse_contract_expand_args` (`230`) is command-local and exact: it accepts +`--name value` and `--name=value` (`243-246`, `253-260`), rejects positional +arguments (`237-242`), unknown options (`247-249`), a repeated flag rather +than keeping the first (`250-252`), empty values (`262-264`), and reports +every missing required flag in sorted order (`269-277`). + +The six operator commands use a second strict parser, `OperatorArgs::parse` +(`operator.rs:151`), with the same rules applied to their whole family: an +unknown option is rejected (`operator.rs:172-174`), a repeated flag is rejected +rather than silently taking the first (`operator.rs:175-177`), an empty value +is rejected (`operator.rs:187-189`), and missing required flags are listed in +sorted order (`operator.rs:194-201`). + +`get_flag` (`558`) accepts exactly two forms: `--name value` (`562-567`) and +`--name=value` (`568-570`). Its two error messages are `missing value for +--name` (`566`) and `missing required --name` (`572`). `get_flag_optional` +(`575`) is the same scan returning `Option`. Both scan left to right and return the first match, so a repeated flag silently takes the first occurrence. That is -why `contract expand` parses its own arguments rather than inheriting the -looseness of the shared helper. +why `contract expand` and the operator family parse their own arguments rather +than inheriting the looseness of the shared helper. In the `ci` family, unknown flags are **not** rejected. No function scans for unrecognised arguments; a typo is caught only if it pushes the argument count @@ -90,31 +109,152 @@ past a cap: | Command | Cap | Line | |---|---|---| -| `ci _resolve-release` | 30 | `415` | -| `ci generate` (reusable / exact) | 8 / 6 | `691` / `714` | -| `ci check` (reusable / exact) | 8 / 6 | `745` / `776` | -| `ci _validate-consumer` | 14 | `971` | -| `ci _prepare-stage` | 18 | `1306` | -| `ci _stage-github-draft` | 8 | `1367` | -| `ci _capture-build`, `ci _evaluate-gate` | none | paired-flag checks instead (`690-695`, `1075-1077`) | +| `ci _resolve-release` | 30 | `452` | +| `ci generate` (reusable / exact) | 8 / 6 | `837` / `860` | +| `ci check` (reusable / exact) | 8 / 6 | `891` / `922` | +| `ci _validate-consumer` | 14 | `1212` | +| `ci _prepare-stage` | 18 | `1514` | +| `ci _stage-github-draft` | 8 | `1575` | +| `ci _capture-build`, `ci _evaluate-gate` | none | paired-flag checks instead (`954-959`, `1316-1318`) | `#![forbid(unsafe_code)]` (`1`) holds workspace-wide. `#![deny(missing_docs)]` (`2`) has no target: the crate exposes no public items, so in a binary it is -inert. The three `///` blocks (`352-358`, `921-930`, `955-961`) document -handlers for internal readers, not for rustdoc. +inert. The `///` blocks document handlers for internal readers, not for +rustdoc. The trade-off is deliberate. No `clap` means no dependency, no derive expansion, and a parse whose behaviour is fully determined by the code above. The cost is hand-maintained parsing, flat usage strings as the only help, no completions, and — in the `ci` family — a typo diagnosed as `too many arguments for ci ...` -rather than by name. `contract expand` pays for a second, stricter parser -instead, because a consumer script reads its output. +rather than by name. `contract expand` and the operator family pay for a +stricter parser instead, because a consumer script and an operator read their +output. + +## The local producer operator commands + +Build/Qualification M009 added six top-level commands — `check`, `plan`, +`package`, `qualify`, `collect`, and `manifest` — so a producer can construct, +qualify, and finalize a release on a workstation without a GitHub Actions run +and without the `ci _*` internal runner family. They live in +`crates/eggpack-cli/src/operator.rs`. + +**This milestone adds no staging or publication command.** The six commands +are local-only: they read local paths, write local paths, and reach no +network. `operator.rs:1-12` states it in the module header, the per-command +help states it at `operator.rs:240`, and the top-level help states it at +`77-80`: *"No command in this set stages or publishes; staging and publication +stay separate, explicitly authorized actions."* Staging and publication remain +reachable only through the `ci _prepare-stage` / `ci _stage-github-draft` +runners, and publication is never performed by this binary at all. + +### The taxonomy + +Each command declares a **class**, and the class is part of the command's +identity rather than a comment: it appears in the command table +(`operator.rs:45-82`), in `eggpack --help` (`operator.rs:235-242`), and +in the top-level help listing (`main.rs:69-75`). + +| Command | Class | Effect | +|---|---|---| +| `check` | validation | validate contract, policy, and bindings before anything is built | +| `plan` | validation | resolve the release identity and write a ReleasePlan | +| `package` | build | build every planned target's candidates under an output root | +| `qualify` | build | qualify built candidates and write qualification evidence | +| `collect` | release aggregation | aggregate qualified candidates into a finalized release tree | +| `manifest` | final-bytes evidence | derive release-manifest.json from a finalized release tree | + +The three classes are the milestone's own vocabulary, and they line up with the +authority separation the workspace already keeps: `validation` produces intent +and refuses to write anything unvalidated; `build` produces candidates and +their qualification evidence; `release aggregation` produces a finalized tree; +`final-bytes evidence` produces the manifest over those final bytes. Nothing +in the set crosses from evidence back into intent, and nothing in the set +reaches the publication boundary. + +### The shared shape + +All six share one resolution path and one writer. + +`resolve_planning_inputs` (`operator.rs:248`) is the single place the planning +input set is read and validated: the contract (`operator.rs:250`), the policy +(`operator.rs:251`), the build bindings (`operator.rs:252`), the qualification +bindings (`operator.rs:253-254`), the selected targets (`operator.rs:255`), and the +release identity (`operator.rs:256-257`). It then +resolves through `resolve_runtime_release_plan_with_mode` with +`ReleaseIdentityMode::ExactTag` (`operator.rs:258-265`) — the same function +`ci _resolve-release` calls (`478`) — validates the plan against its own +declared floor (`operator.rs:269-270`), and checks that the build bindings +match the plan (`operator.rs:271-276`) and the qualification bindings match the +plan and the build bindings (`operator.rs:277-284`). `check` and `plan` differ only in what they do +with the result: `check` discards it (`operator.rs:341`), `plan` writes it +(`operator.rs:353-354`). + +Because the encoder is shared (`encode_release_plan`, `717-719`), `eggpack +plan` and `ci _resolve-release` write byte-identical plans for one resolved +plan. That is a property, not a coincidence: one rule set, one document. + +Every input document is read through the shared bounded reader at 1 MiB +(`operator.rs:23`, `operator.rs:290-317`), and every document the operator family writes +goes through the same atomic writer the `ci` family uses. + +### The per-command surface + +| Command | Reads | Writes | Success line | +|---|---|---|---| +| `check` | contract, pack config, build bindings, qualification bindings | nothing | `check: ok` (`operator.rs:342`) | +| `plan` | the same, plus the release identity | `--output` (plan JSON) | `plan: ok` (`operator.rs:355`) | +| `package` | release plan, build bindings; builds in `--source-root` | `//{build-handoff.json,candidates/}` | `package: ok` (`operator.rs:404`) | +| `qualify` | contract, release plan, both bindings, the per-target artifact root | `//{evidence.json,build-handoff.json,candidates/}` | `qualify: ok` (`operator.rs:579`) | +| `collect` | contract, release plan, both bindings, the per-target artifact root | the finalized tree under `--output-root`, plus `release-manifest.json` beside it | `collect: ok` (`operator.rs:648`) | +| `manifest` | contract, release plan, the finalized tree's bytes | `--output` (manifest JSON) | `manifest: ok` (`operator.rs:728`) | + +Three naming and placement details are worth stating plainly, because they are +where a reader's expectation and the implementation differ: + +- **`--candidates-dir` is the per-target artifact root**, not the + `candidates/` directory inside it. `qualify` reads + `//build-handoff.json` (`operator.rs:534-539`) and + `collect` reads the same layout through `collect_finalization_inputs` + (`operator.rs:617`, `main.rs:748-782`). The flag is named after what the directory + contains. +- **`collect` writes the manifest beside the finalized root**, in + `--output-root`'s parent (`operator.rs:597-601`, `operator.rs:644-647`), while + `ci _aggregate` writes it beside `--output` (`1456-1459`). The two are + different placements, described under *Where `release-manifest.json` is + written*. +- **`package` recreates its private build scratch on every run** + (`operator.rs:368-369`, `operator.rs:460-472`), so a restarted stage starts from a clean + Cargo target directory. + +`package` is the only command in the set that spawns a build. It delegates to +`eggpack_core::execute_target` (`operator.rs:379`) with the core builder's own +bounded, process-grouped execution, and the private Cargo target directory +lives under the caller's output root (`operator.rs:26`, `operator.rs:368`). + +### The local path and the CI path are the same rules + +`collect` projects the same graph the CI path projects: `project_ci_plan` +(`operator.rs:607`) and `project_release_plan` (`operator.rs:610`), the same two +calls `ci _resolve-release` makes (`522`, `525`). `qualify` calls +`qualify_target` (`operator.rs:545`), the same function `ci _qualify-target` +calls (`1103`). `package` calls `execute_target` (`operator.rs:379`), the same +builder the `ci _capture-build` runner's output is derived from. + +The one thing the local path does *not* do is verify a checkout. +`ci _resolve-release` verifies that `HEAD` under `--source-root` equals +`--source-revision` (`458`) and that the tag peels to the same revision +(`459`). The operator commands take `--source-revision` as an explicit value +and check its shape only (`operator.rs:257`, through the library's +`validate_source_revision`), and never run `git`. That is a deliberate +boundary: a local operator path that resolved a repository implicitly would +mean different things in different directories. A caller who needs the checkout +verified uses `ci _resolve-release`. ## `eggpack contract expand` Contract M003 added the crate's second command family and its first -caller-facing scalar projection. `contract_dispatch` (`:73`) reaches exactly one -subcommand, and `contract_expand` (`:295`) reads, expands, projects, and prints: +caller-facing scalar projection. `contract_dispatch` (`111`) reaches exactly one +subcommand, and `contract_expand` (`344`) reads, expands, projects, and prints: ```text --contract (required, once) local path, read through read_bounded with a 1 MiB bound @@ -124,13 +264,12 @@ subcommand, and `contract_expand` (`:295`) reads, expands, projects, and prints: ``` The semantic work is not here. `contract_expand` calls -`DistributionContract::parse_toml_str` (`:299`) and `DistributionContract::expand` -(`:301`) and uses their answers verbatim, which is what keeps this a projection +`DistributionContract::parse_toml_str` (`348`) and `DistributionContract::expand` +(`351`) and uses their answers verbatim, which is what keeps this a projection rather than a second implementation of schema-v1 semantics. `project_field` -(`:252`) is the only new semantic judgement: `canonical-target` answers for every -asset form (`:258-260`), and the three direct-only fields fail closed for -bundle/archive (`:261-269`) rather than picking a primary entry or archive -member. +(`301`) is the only new semantic judgement: `canonical-target` answers for every +asset form, and the three direct-only fields fail closed for bundle/archive +rather than picking a primary entry or archive member. Deliberately absent, each of which would be authority this crate has no business taking: @@ -144,10 +283,10 @@ taking: | updater, signature, provenance, install side effects | Outside the producer's first-install scope. The command writes neither the contract, nor its directory, nor anything else. | The stdout contract is the product: exactly one scalar plus one newline, nothing -on stderr, and a nonzero exit with an empty stdout on every failure (`:278-285`, -with `run`'s mapping at `:11-19`). Diagnostics are bounded twice over — the -contract library truncates its own error detail, and `bound_echo` (`:105`) caps -anything the CLI itself quotes from argv at `:100` bytes. +on stderr, and a nonzero exit with an empty stdout on every failure (`352-355`, +with `run`'s mapping at `14-22`). Diagnostics are bounded twice over — the +contract library truncates its own error detail, and `bound_echo` (`148`) caps +anything the CLI itself quotes from argv at `140` bytes. Consumer policy is not inferred from any of this. A caller reading `--field asset` still owns its own frozen public-name table, latest/exact selection, @@ -155,41 +294,39 @@ Cargo fallback, install destination, updater, and compatibility-floor checks. This milestone gives a consumer a way to stop re-implementing TOML parsing and template expansion; it gives no consumer a reason to move policy into Eggpack. - ## `ci generate` and `ci check` Both require `--github-policy` and take one of two mutually exclusive input -modes; supplying both is an error (`563-565`, `617-619`). +modes; supplying both is an error (`829-834`, `883-888`). | | Reusable mode | Exact mode | |---|---|---| -| `ci generate` (`555`) | `--workflow-shape` + `--contract` → `render_reusable_release_github` (`581`) | `--ci-plan` → `render_release_github` (`601`) | -| `ci check` (`612`) | same inputs + `--workflow` → `check_reusable_release_github` (`641`) | same + `--workflow` → `check_release_github` (`668`) | +| `ci generate` (`823`) | `--workflow-shape` + `--contract` → `render_reusable_release_github` (`849`) | `--ci-plan` → `render_release_github` (`869`) | +| `ci check` (`880`) | same inputs + `--workflow` → `check_reusable_release_github` (`904`) | same + `--workflow` → `check_release_github` (`932`) | `ci generate` writes exactly one file: `--output`, through `atomic_write` -(`583`, `603`). No directory creation, no second write, so a generate run +(`851`, `871`). No directory creation, no second write, so a generate run cannot touch anything the caller did not name. The output path is checked by `reject_symlink_output` and its parent must already be a real directory -(`530-534`). Inputs are read at 1 MiB each (`572-574`, `595-596`); success -prints `generated bytes to ` (`584-588`). +(`654`, `660-664`). Inputs are read at 1 MiB each (`840-842`, `863-864`); +success prints `generated bytes to ` (`852-856`, `872-876`). `ci check` never writes. There is no `atomic_write`, `fs::write`, or -`create_dir_all` anywhere in `605-673`; the only effect on success is one +`create_dir_all` anywhere in `880-944`; the only effect on success is one `println!`. It reads the existing workflow through `read_bounded` at 8 MiB -(`622`, `652`), so the bound is checked against file metadata *before* any +(`897`, `927`), so the bound is checked against file metadata *before* any allocation and the input is also refused if it is a symlink. This is the same gate every other input in the crate uses; the workflow is not a special case. Drift comparison is delegated. The CRLF→LF-only normalization lives in -`eggpack-ci` (`normalize_newlines`, `crates/eggpack-ci/src/lib.rs2072`, applied -at `lib.rs:3818-3819`), not here. The CLI branches on `report.matches` and, on -drift, returns `ci check: drift detected (expected N bytes, found N bytes, first -difference at ...)` (`647-651`, `674-678`). +`eggpack-ci` (`normalize_newlines`, `crates/eggpack-ci/src/lib.rs:1885`), not +here. The CLI branches on `report.matches` and, on drift, returns `ci check: +drift detected (expected N bytes, found N bytes, first difference at ...)` +(`915-918`, `938-941`). Read-only is what makes `ci check` safe in a pre-merge or scheduled job: a failing check cannot have mutated the tree it inspects, so a red run's only side -effect is a nonzero exit. The unit test pins both halves — a CRLF-converted -workflow still matches, one appended byte fails (`1678-1699`). +effect is a nonzero exit. ## The nine internal `ci _*` runner commands @@ -198,166 +335,174 @@ shape. Each row can be traced end to end from a rendered step. | Command | Handler | Reads | Writes | |---|---|---|---| -| `_verify-source` | `309` | `--release-plan` (`311`) | nothing; prints the pass line (`348`) | -| `_resolve-release` | `401` | `--contract`, `--pack-config`, `--build-bindings`, `--qualification-bindings`, optional `--consumer-validators`, `--template`; optional fixed `--identity-mode` from checked-in renderer policy (`402-415`) | `--output-plan`, `--output-ci-plan`, `--output-github-policy` (`412-414`) | -| `_capture-build` | `682` | `--release-plan`, `--build-bindings`, plus `--cargo-target-dir` **or** `--candidate-dir` (`696-729`) | `--output` (`776`) and/or `--output-dir`: `build-handoff.json` (`768`) + `candidates/` (`759-764`) | -| `_qualify-target` | `782` | `--release-plan`, `--build-bindings`, `--qualification-bindings`, `--build-handoff`, `--contract`, optional `--qemu-sysroot` (`796-825`) | `--output-dir`: `evidence.json` (`853`), `build-handoff.json` (`858-861`), `candidates/` (`872-881`) | -| `_validate-consumer` | `963` | `--consumer-validators`, `--build-handoff`, `--evidence`, `--source-root` (`974-1029`) | `--output` (consumer evidence, `1053`) | -| `_evaluate-gate` | `1070` | `--ci-plan`; per target `//evidence.json` (`1085`) or `/.json` (`1089`), plus `consumer-evidence.json` when validators exist (`1117`) | `--output` (gate outcome JSON, `1128`) | -| `_aggregate` | `1140` | `--contract`, `--release-plan`, `--ci-plan`, per target `//{build-handoff.json,evidence.json,candidates/}` (`1166-1191`), plus consumer evidence (`1214`) | `--output-root` finalized tree (via the library), `--output` summary (`1261`), `release-manifest.json` beside it (`1250-1251`) | -| `_prepare-stage` | `1296` | `--contract`, `--release-manifest`, `--finalized-root`, `--github-policy`, `--install-policy`, optional `--installer-presentation` + `--source-root` (`1317-1330`) | staging output dir via the library; `--output-payload` (`1356`) | -| `_stage-github-draft` | `1361` | `--payload`, `--github-policy`, optional `--staging-dir`; token from the environment (`1370-1378`) | `--output-receipt` (`1412`); the draft itself, in `eggpack-github` | +| `_verify-source` | `358` | `--release-plan` (`359`); optionally `--github-policy`, `--expected-tag`, `--source-root`, which are all-or-none (`363-370`) | nothing; prints the pass line (`426`) | +| `_resolve-release` | `438` | `--contract`, `--pack-config`, `--build-bindings`, `--qualification-bindings`, optional `--consumer-validators`, `--template`; optional fixed `--identity-mode` from checked-in renderer policy (`439-451`, `473-477`) | `--output-plan`, `--output-ci-plan`, `--output-github-policy` (`551-553`) | +| `_capture-build` | `946` | `--release-plan`, `--build-bindings`, `--target`, plus `--cargo-target-dir` **or** `--candidate-dir` (`947-959`) | `--output` (`1036-1041`) and/or `--output-dir`: `build-handoff.json` (`1032`) + `candidates/` (`1020-1028`) | +| `_qualify-target` | `1046` | `--release-plan`, `--build-bindings`, `--qualification-bindings`, `--contract`, `--target`, `--candidate-dir`, `--build-handoff`, optional `--qemu-sysroot` (`1047-1059`, `1085`) | `--output-dir`: `evidence.json` (`1117`), `build-handoff.json` (`1122`), `candidates/` (`1122`) | +| `_validate-consumer` | `1204` | `--consumer-validators`, `--target`, `--candidate-dir`, `--build-handoff`, `--evidence`, `--source-root` (`1205-1211`) | `--output` (consumer evidence, `1294`) | +| `_evaluate-gate` | `1311` | `--ci-plan`; per target `//evidence.json` (`1326`) or `/.json` (`1330`), plus `consumer-evidence.json` when validators exist (`1358`) | `--output` (gate outcome JSON, `1369`) | +| `_aggregate` | `1381` | `--contract`, `--release-plan`, `--ci-plan`, per target `//{build-handoff.json,evidence.json,candidates/}` (`1411`, `748-782`), plus consumer evidence (`1432-1438`) | `--output-root` finalized tree (via the library), `--output` summary (`1469`), `release-manifest.json` beside it (`1454-1462`) | +| `_prepare-stage` | `1504` | `--contract`, `--release-manifest`, `--finalized-root`, `--github-policy`, `--install-policy`, optional `--installer-presentation` + `--source-root` (`1505-1524`) | staging output dir via the library; `--output-payload` (`1564`) | +| `_stage-github-draft` | `1569` | `--payload`, `--github-policy`, optional `--staging-dir`; token from the environment (`1570-1572`, `1586`, `1597-1600`) | `--output-receipt` (`1620`); the draft itself, in `eggpack-github` | They are wrappers, not a scripting interface. The input grammar is: paths, a -target name that must already exist in the plan (`815-819`, `1179-1183`), and +target name that must already exist in the plan (`1079-1083`, `767-771`), and nothing else. There is no shell invocation, no caller-supplied program name, no expression evaluation, and no flag whose value is interpreted as a command. The single external program in the crate is the literal `"git"` with fixed arguments -(`326-327`). The one validator process is spawned inside `eggpack-ci` under a +(`402`, `421`). The one validator process is spawned inside `eggpack-ci` under a finite interpreter enum, not from a caller string. Invocations are rendered, not typed: `RunnerCommand::argv()` in -`eggpack-ci` (`crates/eggpack-ci/src/lib.rs1372`) is what the tests feed -straight into these handlers (argv[0] assertions at `lib.rs:5846`, `6722`, `6741`, -`8299`). +`eggpack-ci` (`crates/eggpack-ci/src/lib.rs:1152`) is what the tests feed +straight into these handlers. ## The file-safety helpers -`read_bounded` (`496`) guards every input: `symlink_metadata`, refuse a symlink -(`499-501`), refuse anything not a regular file (`502-504`), refuse a length -above the caller's bound (`505-507`), then read through a `take(max + 1)` reader -and reject any surplus (`510-522`). The read is bounded as well as the check: a +`read_bounded` (`589`) guards every input: `symlink_metadata`, refuse a symlink +(`592-594`), refuse anything not a regular file (`595-597`), refuse a length +above the caller's bound (`598-600`), then read through a `take(max + 1)` reader +and reject any surplus (`605-613`). The read is bounded as well as the check: a file that grows, or is replaced, between the two cannot be read past the bound. Failures are reported with the caller's `label`, so diagnostics name the input class rather than echo a path. Production bounds: | Bound | Inputs | Lines | |---|---|---| -| 1 MiB | release plan, contract, pack config, build/qualification bindings, ci plan, github policy (generate/check), workflow shape, build handoff, evidence | `311`, `381-384`, `415-421`, `572-574`, `595-596`, `626-628`, `657-658`, `696-697`, `796-799`, `980-986`, `1078`, `1152-1154`, `1168-1173` | -| 64 KiB | draft template, consumer validators, consumer evidence, installer presentation | `402`, `434`, `974`, `1118`, `1215`, `1284` | -| 256 KiB | install policy, github draft policy | `1272`, `1319`, `1371` | -| 1 MiB | release manifest, staging payload | `1318`, `1370` | -| 8 MiB | existing workflow, via `read_bounded` (checked before *and* during the read, symlink refused) | `622`, `652` | - -`reject_symlink_output` (`504`) refuses an existing symlink or directory at the -output path. It is reached only from `atomic_write` (`516`), so callers cannot +| 1 MiB | release plan, contract, pack config, build/qualification bindings, ci plan, github policy (generate/check), workflow shape, build handoff, evidence | `360`, `460-463`, `509`, `515`, `756`, `761`, `840-842`, `863-864`, `894-896`, `925-926`, `960-961`, `1060-1063`, `1086`, `1121`, `1221`, `1227`, `1319`, `1327`, `1331`, `1393-1395`, `1525` | +| 64 KiB | draft template, consumer validators, consumer evidence, installer presentation, github draft policy | `372`, `487`, `528`, `1215`, `1359`, `1434`, `1492` | +| 256 KiB | install policy, github draft policy | `1480`, `1527`, `1579` | +| 1 MiB | release manifest, staging payload | `1526`, `1578` | +| 8 MiB | existing workflow, via `read_bounded` (checked before *and* during the read, symlink refused) | `897`, `927` | + +`reject_symlink_output` (`617`) refuses an existing symlink or directory at the +output path. It is reached only from `atomic_write` (`654`), so callers cannot forget it; a non-existent path passes, which is the create case. `atomic_write` claims a fresh temporary sibling through `claim_temp`: `.eggpack-tmp--`, opened with `create_new` so two calls in one -process cannot collide and a pre-planted symlink is never followed. It writes -that file and renames it over the destination. Where rename does not replace -(Windows), it renames the destination *aside* to `.eggpack-prev--` -first and retries; if that retry fails it moves the destination back, so a -failed replace never leaves the caller's file deleted. +process cannot collide and a pre-planted symlink is never followed (`634-651`). +It writes that file and renames it over the destination (`665-675`). Where +rename does not replace (Windows), it renames the destination *aside* to +`.eggpack-prev--` first and retries; if that retry fails it moves +the destination back, so a failed replace never leaves the caller's file +deleted (`677-708`). What "atomic" buys: a concurrent reader of `--output` sees either the previous -file or the complete new one, never a truncated document. All 15 production -`atomic_write` call sites carry JSON control documents (`458-460`, `583`, -`603`, `768`, `776`, `853`, `858`, `1053`, `1128`, `1251`, `1261`, -`1356`, `1412`). +file or the complete new one, never a truncated document. All production +`atomic_write` call sites carry JSON control documents or build descriptors. What it does **not** protect against, stated plainly: -- No `fsync` of the temp file or directory (`538-539`), so a crash or power loss - can leave a truncated or missing destination. -- The Windows fallback is explicitly not atomic: between the failed rename - (`539`) and the `remove_file` (`545`) the path holds no file. +- No `fsync` of the temp file or directory, so a crash or power loss can leave + a truncated or missing destination. +- The Windows fallback is explicitly not atomic: between the failed rename and + the `remove_file` the path holds no file. - No `O_NOFOLLOW` / `linkat` re-check, and `#![forbid(unsafe_code)]` (`1`) rules - out adding one, so the check at `511` and the rename at `539` are separated - by a TOCTOU window. -- It protects exactly the path given. The parent must already be a real directory - (`530-534`), so commands staging a tree create it themselves: `create_dir_all` - at `752`, `850`, `873`. -- Candidate binaries bypass it entirely: `_capture-build` and `_qualify-target` - hard-link with a `copy` fallback (`761-763`, `878-880`). Only the JSON - descriptors are atomic; artifacts are staged before the descriptor naming them, - and the directory validators (`769-770`, `882-883`) run afterwards. + out adding one, so the symlink check and the rename are separated by a TOCTOU + window. +- It protects exactly the path given. The parent must already be a real + directory (`660-664`), so commands staging a tree create it themselves: + `create_dir_all` at `1016`, `1114`, `operator.rs:483`, and `operator.rs:571`. +- Candidate binaries bypass it entirely: `_capture-build`, `_qualify-target`, + and the operator family's `write_build_artifacts` hard-link with a `copy` + fallback (`1025-1027`, `operator.rs:498-501`). Only the JSON descriptors are + atomic; artifacts are staged before the descriptor naming them. ## Path absolutization Three helpers, three different contracts. -`absolute_path` (`912`) returns an absolute input unchanged and otherwise joins +`absolute_path` (`1153`) returns an absolute input unchanged and otherwise joins it to the current directory. No validation of any kind. Used for the consumer -candidate path (`1028`) and the validator work directory (`1030`). +candidate path (`1269`) and the validator work directory (`1271`). -`absolute_under_root` (`888`) requires the root to be a real directory -(`889-893`), then splits the relative validator script on `/` and rejects empty, -`.`, and `..` segments (`903-908`). This *is* a traversal rejection, scoped to -the consumer validator script path. The comment at `894-895` states the path was -already validated upstream; the segment loop is the second line of defence. +`absolute_under_root` (`1129`) requires the root to be a real directory +(`1130-1134`), then splits the relative validator script on `/` and rejects +empty, `.`, and `..` segments (`1144-1149`). This *is* a traversal rejection, +scoped to the consumer validator script path. The comment at `1135-1136` states +the path was already validated upstream; the segment loop is the second line of +defence. -`absolutize_cli_path` (`931`) rejects an empty path (`932-934`), passes -absolute inputs through (`935-937`), requires an absolute base (`938-940`), -drops `.` components (`944`), rejects `..` with `path must not contain -parent-directory components` (`945-947`), and rejects anything else with `path -has an unsupported component` (`949`). +`absolutize_cli_path` (`1172`) rejects an empty path (`1173-1175`), passes +absolute inputs through (`1176-1178`), requires an absolute base +(`1179-1181`), drops `.` components (`1185`), rejects `..` with `path must not +contain parent-directory components` (`1186-1188`), and rejects anything else +with `path has an unsupported component` (`1190`). It enforces **component-level escape rejection, not containment.** No canonicalisation, no symlink resolution, no check that the result resolves under the base — a symlinked component inside the base still points outside it, and existence is not tested. It is used for `--candidate-dir` in `_qualify-target` -(`789-792`) and `--output-root` in `_aggregate` (`1147-1150`); commands needing a -real directory check it separately (`714-727`, `828-833`). +(`1053-1056`) and `--output-root` in `_aggregate` (`1388-1391`), and by the +operator family for `--source-root`, `--output-root`, and `--output-dir` +(`operator.rs:365-366`, `operator.rs:542`, `operator.rs:593`); commands needing a real directory check +it separately. These helpers exist because core's `inspect_candidate` and `finalize_release` require absolute paths while the renderer deliberately emits portable relative -ones, so a checked-in workflow is location-independent (doc comment `921-930`, -call sites `787-788`, `1145-1146`). The explicit base parameter keeps unit tests -off the process working directory. `absolutize_cli_path_keeps_absolute_rejects_escape_and_joins_relative` -(`1440`) asserts absolute passthrough, `./`-relative joining, and rejection of +ones, so a checked-in workflow is location-independent. The explicit base +parameter keeps unit tests off the process working directory. +`absolutize_cli_path_keeps_absolute_rejects_escape_and_joins_relative` +(`1648`) asserts absolute passthrough, `./`-relative joining, and rejection of `../escape`, `a/../../escape`, the empty path, and a relative base. ## Where `release-manifest.json` is written -The aggregate path writes the sidecar at `1248-1253`, inside -`if let Some(finalized)` (`1235`): +There are now three writers of that filename, and they place it differently. + +The `ci _aggregate` path writes the sidecar at `1454-1462`, inside +`if let Some(finalized)` (`1454`): - It is derived from `--output`'s **parent**, not from `--output-root` - (`1248-1250`). The manifest therefore follows the summary file; if a caller - places `--output` outside the finalized root's parent, the sidecar lands there. + (`1456-1458`). The manifest therefore follows the summary file; if a caller + places `--output` outside the finalized root's parent, the sidecar lands + there. - It is written only when finalization returned a finalized root. An incomplete aggregate produces no manifest. -- It is skipped entirely when `--output` has no parent component (`1249`), so a +- It is skipped entirely when `--output` has no parent component (`1457`), so a bare filename writes the summary and no sidecar. - Before writing, the manifest is encoded, decoded through `eggpack_manifest::ReleaseManifest::from_json`, and re-encoded; a mismatch is - `staging manifest does not decode to exact manifest` (`1240-1247`). + `staging manifest does not decode to exact manifest` (`726-739`). -The rule, precisely: **the manifest is written beside the finalized output root, -never inside it.** The test pins both halves — `root/release-manifest.json` -decodes to the exact manifest, and `!output_root.join("release-manifest.json") -.exists()` guards M004 root semantics (`1931-1942`). +The operator `collect` command writes it from the **finalized root's parent** +(`operator.rs:597-601`, `operator.rs:644-647`), not from a summary file's parent. The +finalizer writes one new release root under a caller-secured parent, so the +manifest beside that root is the one an operator actually finds. + +The `eggpack manifest` command writes it where the caller says: `--output` +(`operator.rs:727`), and only there. -`eggpack-github` owns the same filename independently: +The rule, precisely: **the manifest is written beside the finalized output root, +never inside it.** `eggpack-github` owns the same filename independently: `FIXED_MANIFEST_NAME = "release-manifest.json"` -(`crates/eggpack-github/src/lib.rs:31`), written into its own staging output -directory with the same round-trip check (`lib.rs1031-1044`, `lib.rs1700-1713`). -So there are two writers of the same name, into two different directories: beside -the finalized root (this crate) and inside the staging payload directory -(`eggpack-github`). Neither writes it into the finalized root. The finalizer's +(`crates/eggpack-github/src/lib.rs:32`), written into its own staging output +directory with the same round-trip check. So the writers are: beside the +finalized root (`ci _aggregate`, `eggpack collect`), inside the staging payload +directory (`eggpack-github`), and at the caller's explicit `--output` +(`eggpack manifest`). None writes it into the finalized root. The finalizer's own containment rule is in [core-finalization.md](core-finalization.md). ## Policy and presentation loading -`read_install_policy` (`1271`) reads at most 256 KiB with the label `install +`read_install_policy` (`1479`) reads at most 256 KiB with the label `install policy` and tries `BootstrapInstallPolicyV1::from_toml` first, then -`from_json` (`1274-1278`). +`from_json` (`1480-1486`). -`read_installer_presentation` (`1281`) reads at most 64 KiB and tries +`read_installer_presentation` (`1489`) reads at most 64 KiB and tries `toml::from_str` first, calling `.validate()` explicitly on that branch -(`1286-1291`), then `InstallerPresentationV1::from_json` (`1292-1293`). The +(`1494-1499`), then `InstallerPresentationV1::from_json` (`1500-1501`). The explicit `validate()` call exists only on the TOML path; I did not verify that `from_json` performs the same checks internally. -Both are consumed only by `_prepare-stage` (`1326`, `1329`). +Both are consumed only by `_prepare-stage` (`1534`, `1537`). `--installer-presentation` and `--source-root` are paired: one without the other -is an error (`1311-1316`). The pair selects -`prepare_staging_payload_with_presentation` (`1330`) for product wrappers; -`GeneratedDefault` passes neither and calls `prepare_staging_payload` (`1342`). -Other bounds on that path: release manifest 1 MiB (`1318`), github draft policy -256 KiB (`1319`). +is an error (`1519-1524`). The pair selects +`prepare_staging_payload_with_presentation` (`1538`) for product wrappers; +`GeneratedDefault` passes neither and calls `prepare_staging_payload` (`1550`). +Other bounds on that path: release manifest 1 MiB (`1526`), github draft policy +256 KiB (`1527`). They are inputs, not derivations. Installer policy and presentation are decisions owned by the product repository and validated by `eggpack-bootstrap` and @@ -366,60 +511,63 @@ for installer content, so the CLI only reads and bounds them. ## Process execution: the `git` site -`verify_source_revision` (`373`) is the production HEAD verification spawn in +`verify_source_revision` (`410`) is the production HEAD verification spawn in this crate — and it no longer constructs a `Command` itself. It delegates to -`eggpack_core::run_git_bounded` (`384-385`), while mapped identity also calls -`run_git_tag_bounded` (`364-369`) for the exact local tag peel, so the bounded, process-grouped -spawn lives in `builder.rs`, not here. `grep -n 'Command::new'` in this file now -returns **only** test sites (`1482`, `1500`, `1507`, `2102`, `2117`); there -is no production `Command::new` in `eggpack-cli` at all. The file likewise reads -no named environment variable: its only `std::env` uses are `args()` (`8`) and -`current_dir()` (`780`, `888`, `905`, `1138`), plus a test-only `temp_dir()` -(`1418`). +`eggpack_core::run_git_bounded` (`421`), while `verify_source_tag` (`401`) +calls `run_git_tag_bounded` (`402`) for the exact local tag peel, so the +bounded, process-grouped spawn lives in `builder.rs`, not here. `grep -n +'Command::new'` in this file now returns **only** test sites; there is no +production `Command::new` in `eggpack-cli` at all. The file likewise reads no +named environment variable: its only `std::env` uses are `args()` (`11`), +`current_dir()`, and a test-only `temp_dir()`. What it does: it validates that the expected revision is 40 lowercase hex -characters (`326-332`), then delegates to `eggpack_core::run_git_bounded` -(`336-337`), which owns the spawn. That helper builds a `CommandSpec` for -`git rev-parse --verify HEAD^{commit}` (`builder.rs409-420`) and, for mapped -mode, `refs/tags/^{commit}` (`builder.rs422-479`); both use the same bounded -runner with a 30 s deadline (`builder.rs20`), a 4 KiB retained-output cap -(`builder.rs22`), a `command-group` process group, and a cleared environment -(`builder.rs484-528`). +characters (`411-416`), then delegates to `eggpack_core::run_git_bounded` +(`421`), which owns the spawn. That helper builds a `CommandSpec` for +`git rev-parse --verify HEAD^{commit}` (`builder.rs:417-427`) and, for the tag +peel, `git rev-parse --verify refs/tags/^{commit}` +(`builder.rs:430-449`); both use the same bounded runner with a 30 s deadline +(`builder.rs:20`), a 4 KiB retained-output cap (`builder.rs:22`), a +`command-group` process group, and a cleared environment (`builder.rs:464`). +See +[process-execution.md](process-execution.md) for the workspace spawn contract. Why it is load-bearing. A generated workflow renders concrete plans, paths, and -policies. If the checkout has moved — a rebase, a tag force-update, a detached job -at the wrong commit — the workflow would build and aggregate bytes for a commit -other than the one the plan was derived from, so every downstream artifact would -describe a release the plan does not describe. Two call sites pin the identity: -`ci _verify-source` (`321-361`) requires the plan's `source_revision` to be 40 -lowercase hex then verifies it against the inherited working directory (`373-389`); -`ci _resolve-release` (`401`) verifies the caller-supplied `--source-revision` -against the explicit `--source-root` before resolving anything. - -Mapped reusable mode also peels the exact local tag to that revision and -resolves the manifest ID under the fixed renderer-supplied identity mode. +policies. If the checkout has moved — a rebase, a tag force-update, a detached +job at the wrong commit — the workflow would build and aggregate bytes for a +commit other than the one the plan was derived from, so every downstream artifact +would describe a release the plan does not describe. Two call sites pin the +identity: `ci _verify-source` (`358`) requires the plan's `source_revision` to +be 40 lowercase hex then verifies it against the inherited working directory +(`383`, `398`); `ci _resolve-release` (`438`) verifies the caller-supplied +`--source-revision` against the explicit `--source-root` (`458`) and the tag +against the same revision (`459`) before resolving anything. + +The tag peel is not mapped-only: `ci _resolve-release` peels the exact local +tag in every identity mode (`459`). Mapped reusable mode additionally resolves +the manifest ID under the fixed renderer-supplied identity mode. `_verify-source` receives the runtime draft policy and event-selected tag, then -checks the tag, mapped ID, plan revision, HEAD, and tag peel as one tuple. These -extra arguments are absent in legacy exact-tag mode. +checks the tag, mapped ID, plan revision, HEAD, and tag peel as one tuple +(`371-385`); that branch requires the policy's mode to be +`VPrefixedStableSemver` (`376-377`). These extra arguments are absent in legacy +exact-tag mode. It fails closed. Anything other than `CommandOutcome::Success` is an error -(`384-388`): spawn failure, deadline, output-cap breach, non-zero status, and -mismatch all collapse to one message that carries no git output. Only exact -equality passes, and the pass path prints a fixed sentence carrying no revision -text (`389`). - -The expected object name is matched *inside* the runner -(`builder.rs850-856`) and never returned to this process, so the CLI cannot -leak stdout even by accident. The comparison is exact rather than containment: -`expected_stdout_exact` (`builder.rs388`) requires the trimmed stdout to equal -the expected value, which a substring check would not. This keeps the site -inside the workspace contract in -[process-execution.md](process-execution.md) rather than diverging from it. +(`404-406`, `423-425`): spawn failure, deadline, output-cap breach, non-zero +status, and mismatch all collapse to one message that carries no git output. +Only exact equality passes, and the pass path prints a fixed sentence carrying +no revision text (`426`). + +The expected object name is matched *inside* the runner and never returned to +this process, so the CLI cannot leak stdout even by accident. The comparison is +exact rather than containment: the `expected_stdout_exact` field of the +`CommandSpec` (`builder.rs:469`) requires stdout to equal the expected value, +which a substring check would not. ## Error and exit discipline -`main` (`7-9`) exits with the `i32` from `run` (`11-19`): `0` on `Ok(())`, -otherwise one `eprintln!("eggpack: {message}")` (`15`) and `1`. There is exactly +`main` (`10-12`) exits with the `i32` from `run` (`14-22`): zero on `Ok(())`, +otherwise one `eprintln!("eggpack: {message}")` (`18`) and `1`. There is exactly one `eprintln!` in the file, so every failure surfaces as one prefixed line on stderr. @@ -427,26 +575,32 @@ Handlers return `Result<(), String>`, and library errors are almost always collapsed to a fixed static message by `.map_err(|_| "…")` — `invalid release plan`, `handoff projection failed`, `gate evaluation failed`. A diagnostic therefore names a cause class rather than reproducing a library message. The one -deliberate exception is `_stage-github-draft` (`1408`), which interpolates the -inner `GithubError`; the comment at `1405-1407` records that the type carries +deliberate exception is `_stage-github-draft` (`1616`), which interpolates the +inner `GithubError`; the comment at `1613-1615` records that the type carries only static bounded text — no token, body, or URL — and that live diagnosis requires naming it. +The operator family collapses library errors the same way, but keeps the cause +class visible: `diagnostic` (`operator.rs:412-421`) reduces a multi-line parser +diagnostic to its last non-empty line and bounds it, so the exit discipline +stays one line. + Diagnostics never echo captured process output. `git` stdout is compared, not -printed (`337-348`). Consumer validator output is excluded from durable evidence by -type, and the CLI additionally refuses to write evidence whose JSON contains -`stdout` or `stderr` (`1049-1052`); a failed validation reports the reason variant -by `Debug` (`1063-1065`), naming the cause (interpreter, candidate identity, +printed. Consumer validator output is excluded from durable evidence by type, +and the CLI additionally refuses to write evidence whose JSON contains `stdout` +or `stderr` (`1291-1293`); a failed validation reports the reason variant by +`Debug` (`1300-1307`), naming the cause (interpreter, candidate identity, script, timeout, exit) and not the output. The GitHub token is read by name from the environment -(`eggpack_github::read_token(&policy.token_env)`, `1378`); absence fails before -any network I/O, and the token text is never serialized, logged, or included in an -error (`1376-1377`). +(`eggpack_github::read_token(&policy.token_env)`, `1586`); absence fails before +any network I/O, and the token text is never serialized, logged, or included in +an error. -Success output is a fixed set of bounded lines on stdout (`348`, `461`, -`584-588`, `604-608`, `644`, `671`, `778`, `884`, `1056`, `1132`, -`1264`, `1357`, `1413-1416`). +Success output is a fixed set of bounded lines on stdout (`354`, `426`, `554`, +`852`, `872`, `912`, `935`, `1042`, `1125`, `1297`, `1373`, `1472`, `1565`, +`1621`, and `operator.rs:342`, `355`, `404`, `579`, `648`, `728`). The operator +family's six lines are exactly `: ok`. Limitation worth stating: there are only two exit codes. A caller cannot distinguish drift from a malformed plan by status alone, only by message text. @@ -459,63 +613,72 @@ Dependencies (`crates/eggpack-cli/Cargo.toml:19-27`): `eggpack-contract`, feature only. Dev-dependency: `sha2` 0.10 (`:30`). No `clap`, no HTTP client, no `command-group`, no YAML emitter. -The crate has one integration-test file, -`crates/eggpack-cli/tests/contract_expand.rs`, added by Contract M003. It exists -because the `contract expand` stdout/stderr/exit-code contract is only observable -from outside the process: the unit tests inside `main.rs` can see -`contract_expand`'s `Result` but not what the binary actually wrote. +The crate has two integration-test files, `crates/eggpack-cli/tests/contract_expand.rs` +(Contract M003) and `crates/eggpack-cli/tests/operator_commands.rs` (M009). +They exist because the `contract expand` stdout/stderr/exit-code contract and +the operator commands' exit-code and argument contract are only observable from +outside the process: the unit tests inside `main.rs` can see a handler's +`Result` but not what the binary actually wrote. This is the only crate that depends on all six workspace crates, so it is the only place where the whole pipeline can be driven in one process. That is what -`generated_orchestration_cli_executes_capture_to_aggregate` (`1765`) does: it +`generated_orchestration_cli_executes_capture_to_aggregate` (`1978`) does: it builds argv from `RunnerCommand::argv()` and calls the handlers directly — -capture (`1857`), qualify (`1880`), gate (`1907`), aggregate (`1924`) — then -asserts the negative cases (tampered candidate bytes at `1950`, missing -required flags at `1955` and `1971`). +capture, qualify, gate, aggregate — then asserts the negative cases. The +operator family has the same property in the other direction: `eggpack plan` +and `ci _resolve-release` share one encoder (`717-719`), and +`package_qualify_collect_manifest_matches_ci_aggregate` +(`tests/operator_commands.rs:650`) asserts that the local path produces the +same bytes the CI path produces. To be precise about a common confusion: no workspace crate depends on -`eggpack-cli` — the CLI is a leaf, and `eggpack-ci` does *not* depend on it. What -[ci.md](ci.md) records is that `eggpack-ci`'s *own* dev-dependencies let *its* -tests drive downstream crates. The CLI's only non-Cargo coupling to `eggpack-ci` -is a fixture path read at `1531` (`../eggpack-ci/tests/fixtures/m002-direct.yml`). +`eggpack-cli` — the CLI is a leaf, and `eggpack-ci` does *not* depend on it. +What [ci.md](ci.md) records is that `eggpack-ci`'s *own* dev-dependencies let +*its* tests drive downstream crates. Dependents: end users, and the generated workflow, whose steps are invocations of this binary rendered by `eggpack-ci`'s `RunnerCommand` -(`crates/eggpack-ci/src/lib.rs1372`). +(`crates/eggpack-ci/src/lib.rs:1152`). ## Tests -Twenty-two `#[test]` functions in `mod tests` (`1410`). The twelve `ci` tests -call handler functions and `verify_source_revision` in-process rather than -spawning the binary; the ten `m003_*` tests also drive `run()` and `dispatch` -(`3741`), so the exit-code mapping is exercised for the `contract` family. The -eight tests in `crates/eggpack-cli/tests/contract_expand.rs` spawn the real -binary, which is the only way to observe its stdout contract. +Twenty-seven `#[test]` functions in `mod tests` (`1629`). The `ci` tests call +handler functions and `verify_source_revision` in-process rather than spawning +the binary; the `m003_*` tests also drive `run()` and `dispatch` (`4469`), so +the exit-code mapping is exercised for the `contract` family. The eight tests +in `crates/eggpack-cli/tests/contract_expand.rs` and the eighteen in +`crates/eggpack-cli/tests/operator_commands.rs` spawn the real binary, which is +the only way to observe its stdout contract. | Test | Line | Pins | |---|---|---| -| `absolutize_cli_path_keeps_absolute_rejects_escape_and_joins_relative` | `1429` | Path adapter: passthrough, `.` joining, `..`/empty/relative-base rejection | -| `stage_github_draft_accepts_rendered_four_flag_call` | `1453` | Arity bound admits the renderer's eight-argument call; ten fails | -| `source_verifier_accepts_tag_commit_and_rejects_other_checkout` | `1479` | `git` identity: matching HEAD passes, other revision and non-hex fail | -| `generate_equals_library_and_check_detects_drift` | `1633` | `generate` == library renderer; CRLF matches; one byte drifts; bad input errors | -| `generated_orchestration_cli_executes_capture_to_aggregate` | `1754` | Full capture → qualify → gate → aggregate path plus negative cases and manifest placement | -| `prepare_stage_materializes_exact_payload` | `1991` | Staging payload contents from a real finalized root | -| `resolve_release_emits_distinct_runtime_identity_per_tag` | `2232` | Per-tag resolution identity; wrong revision and malformed tag fail | -| `validate_consumer_executes_typed_command_end_to_end` | `2263` | Consumer validator against real candidate bytes | -| `validate_consumer_refuses_failed_qualification_evidence` | `2427` | Non-`Passed` evidence refused before execution (`994-999`) | -| `prepare_stage_with_product_wrappers_materializes_four_installers` | `2578` | Presentation + source-root pair produces the wrapper set | -| `shape_generate_check_round_trip_and_drift` | `2712` | Reusable shape mode round trip and drift | -| `shape_generate_and_check_accept_native_qualification_for_cross_tool_targets` | `2913` | Reusable mode with native qualification across tool targets | -| `m003_argument_parser_is_exact_and_rejects_ambiguity` | `3277` | Every accepted form; duplicate flag, unknown option, positional argument, missing value, empty value, missing-required set, unsupported field | -| `m003_expands_every_field_and_resolves_aliases` | `3350` | CLI equals `DistributionContract::expand` for all four fields, through both a triple and an alias | -| `m003_release_id_is_opaque_and_accepts_prerelease_punctuation` | `3408` | Opaque expansion input including `v1.2.3-rc.1+build.5`; path separators and empty rejected | -| `m003_fails_closed_for_bundle_and_archive_direct_fields` | `3462` | `canonical-target` answers for both non-direct forms; the three direct-only fields do not | -| `m003_rejects_invalid_schema_unknown_targets_and_missing_input` | `3494` | schema_version 2, unknown key, malformed TOML, unknown triples and aliases, absent file, directory input | -| `m003_rejects_oversized_and_symlink_contract_input` | `3556` | The 1 MiB bound and the symlink refusal | -| `m003_never_mutates_the_contract_and_is_deterministic` | `3597` | Five equal runs, identical bytes, contract untouched on success and on failure | -| `m003_consumer_shaped_contract_matches_frozen_public_names` | `3630` | The live consumer contract shape against the public names both consumers publish, including the `.exe` rule; ARMv7 absent | -| `m003_dispatch_adds_a_family_without_regressing_ci` | `3741` | `run()` exit mapping for both families; `unknown ci subcommand` unchanged | -| `m003_projects_fields_without_a_serialized_expansion_model` | `3772` | No record, list, or member selector exists | +| `absolutize_cli_path_keeps_absolute_rejects_escape_and_joins_relative` | `1648` | Path adapter: passthrough, `.` joining, `..`/empty/relative-base rejection | +| `stage_github_draft_accepts_rendered_four_flag_call` | `1672` | Arity bound admits the renderer's eight-argument call; ten fails | +| `source_verifier_accepts_tag_commit_and_rejects_other_checkout` | `1698` | `git` identity: matching HEAD passes, other revision and non-hex fail | +| `generate_equals_library_and_check_detects_drift` | `1853` | `generate` == library renderer; CRLF matches; one byte drifts; bad input errors | +| `generated_orchestration_cli_executes_capture_to_aggregate` | `1978` | Full capture → qualify → gate → aggregate path plus negative cases and manifest placement | +| `prepare_stage_materializes_exact_payload` | `2215` | Staging payload contents from a real finalized root | +| `resolve_release_emits_distinct_runtime_identity_per_tag` | `2461` | Per-tag resolution identity; wrong revision and malformed tag fail | +| `m003i_mapped_identity_survives_two_target_capture_qualification_finalize_and_stage` | `2551` | Mapped identity across a two-target capture → qualify → finalize → stage path | +| `validate_consumer_executes_typed_command_end_to_end` | `2873` | Consumer validator against real candidate bytes | +| `validate_consumer_refuses_failed_qualification_evidence` | `3037` | Non-`Passed` evidence refused before execution (`1235-1239`) | +| `prepare_stage_with_product_wrappers_materializes_four_installers` | `3188` | Presentation + source-root pair produces the wrapper set | +| `shape_generate_check_round_trip_and_drift` | `3326` | Reusable shape mode round trip and drift | +| `shape_generate_and_check_accept_native_qualification_for_cross_tool_targets` | `3529` | Reusable mode with native qualification across tool targets | +| `m003_argument_parser_is_exact_and_rejects_ambiguity` | `3895` | Every accepted form; duplicate flag, unknown option, positional argument, missing value, empty value, missing-required set, unsupported field | +| `echoed_argv_diagnostics_are_bounded_without_panicking` | `3968` | Diagnostics quoting argv stay bounded | +| `m003_expands_every_field_and_resolves_aliases` | `4008` | CLI equals `DistributionContract::expand` for all four fields, through both a triple and an alias | +| `m003_release_id_is_opaque_and_accepts_prerelease_punctuation` | `4066` | Opaque expansion input including `v1.2.3-rc.1+build.5`; path separators and empty rejected | +| `m003_fails_closed_for_bundle_and_archive_direct_fields` | `4120` | `canonical-target` answers for both non-direct forms; the three direct-only fields do not | +| `m003_rejects_invalid_schema_unknown_targets_and_missing_input` | `4152` | schema_version 2, unknown key, malformed TOML, unknown triples and aliases, absent file, directory input | +| `m003_rejects_oversized_and_symlink_contract_input` | `4214` | The 1 MiB bound and the symlink refusal | +| `atomic_write_replaces_in_place_and_leaves_no_temp_or_backup` | `4255` | The atomic writer replaces in place and leaves no temp or backup file | +| `atomic_write_refuses_a_symlinked_output` | `4275` | A symlinked output path is refused | +| `read_bounded_rejects_a_file_that_grows_past_the_bound` | `4293` | A file that grows past the bound mid-read is refused | +| `m003_never_mutates_the_contract_and_is_deterministic` | `4325` | Five equal runs, identical bytes, contract untouched on success and on failure | +| `m003_consumer_shaped_contract_matches_frozen_public_names` | `4358` | The live consumer contract shape against the public names both consumers publish, including the `.exe` rule; ARMv7 absent | +| `m003_dispatch_adds_a_family_without_regressing_ci` | `4469` | `run()` exit mapping for both families; `unknown ci subcommand` unchanged | +| `m003_projects_fields_without_a_serialized_expansion_model` | `4500` | No record, list, or member selector exists | | `contract_expand::success_prints_exactly_one_scalar_and_nothing_else` | `tests/contract_expand.rs:113` | stdout is the scalar plus one newline and stderr is empty, on both direct fixtures | | `contract_expand::repeated_invocations_are_byte_identical` | `tests/contract_expand.rs:163` | Determinism across processes | | `contract_expand::the_command_never_writes_to_the_contract_or_its_directory` | `tests/contract_expand.rs:176` | No file created or modified, on success and on every failure shape | @@ -524,10 +687,16 @@ binary, which is the only way to observe its stdout contract. | `contract_expand::argument_errors_exit_nonzero_without_a_scalar` | `tests/contract_expand.rs:250` | One defect per invocation; truncated invocations report `missing required`; `--flag=value` accepted | | `contract_expand::symlinked_and_oversized_contracts_are_refused` | `tests/contract_expand.rs:312` | Symlink and size-bound refusals at the process boundary | | `contract_expand::the_documented_readme_example_runs_verbatim` | `tests/contract_expand.rs:350` | The CLI README example, with its documented relative paths and working directory | +| `operator_commands::every_command_exits_zero_on_success_and_one_on_failure` | `tests/operator_commands.rs:395` | Exit-code mapping for all six commands | +| `operator_commands::check_accepts_a_valid_input_set` | `tests/operator_commands.rs:434` | The validation class accepts a resolvable input set | +| `operator_commands::plan_writes_the_same_bytes_as_ci_resolve_release` | `tests/operator_commands.rs:581` | One plan encoder, two surfaces | +| `operator_commands::package_qualify_collect_manifest_matches_ci_aggregate` | `tests/operator_commands.rs:650` | The local path's final bytes equal the CI path's | +| `operator_commands::help_names_every_command_and_its_class` | `tests/operator_commands.rs:1197` | The taxonomy is part of the help | +| `operator_commands::existing_command_families_still_behave` | `tests/operator_commands.rs:1244` | The `ci` and `contract` families are unregressed | The coverage shape follows from the crate's role. Most tests assert argument handling, arity, path helpers, and renderer parity, because that is where the -crate's own logic lives. The one substantial end-to-end path (`1754`) proves +crate's own logic lives. The one substantial end-to-end path (`1978`) proves that the handlers compose; the real proof that generated workflows run against real binaries lives in `eggpack-ci`'s own tests and in the hosted CI lanes. Contract M003 gave the crate an integration-test surface for the first time, @@ -537,12 +706,13 @@ it, the same shape as the earlier unguarded-example drift. The `the_documented_readme_example_runs_verbatim` guard exists so that cannot recur. Not covered here, and therefore guaranteed only by reading the code: the Windows -rename fallback in `atomic_write` (`532-545`), and `reject_symlink_output` -against a directory or symlink (`504-511`). `run()`'s exit-code mapping and -`dispatch`'s unknown-top-level-token rejection are now covered for the -`contract` family (`3741`, `tests/contract_expand.rs:250`) but still only -in-process for the `ci` family. See -[testing-and-portability.md](testing-and-portability.md) for the workspace view. +rename fallback in `atomic_write` (`677-708`), and `reject_symlink_output` +against a directory or symlink (`617-627`). `run()`'s exit-code mapping and +`dispatch`'s unknown-top-level-token rejection are covered for the `contract` +family (`4469`, `tests/contract_expand.rs:250`) and for the operator family +(`tests/operator_commands.rs:395`) but still only in-process for the `ci` +family. See [testing-and-portability.md](testing-and-portability.md) for the +workspace view. ## Related deep dives diff --git a/crates/eggpack-cli/README.md b/crates/eggpack-cli/README.md index 46339d4..4139a7f 100644 --- a/crates/eggpack-cli/README.md +++ b/crates/eggpack-cli/README.md @@ -1,15 +1,492 @@ # eggpack-cli -Minimal deterministic `eggpack` binary for CI generation and release orchestration. +`eggpack` is the deterministic wiring layer of the workspace: it parses +`argv`, reads bounded local files, calls into the library crates, and writes +files. It holds no layout, planning, build, qualification, finalization, +rendering, gating, staging, or installer logic of its own. -- `eggpack ci generate --ci-plan --github-policy --output ` renders deterministically, creates or atomically replaces only the explicit output path, rejects symlink outputs, performs no network or repository discovery, and prints a bounded summary. -- `eggpack ci check --ci-plan --github-policy --workflow ` renders in memory, compares with drift semantics (CRLF-to-LF only), exits 0 on exact match, nonzero on drift or invalid input, never modifies files, and prints a bounded diagnostic. -- Release-resolution runners. `ci _resolve-release --contract --pack-config --build-bindings --qualification-bindings --selected --tag --source-revision --template --source-root --output-plan --output-ci-plan --output-github-policy [--consumer-validators]` requires the checked-out `HEAD` under `--source-root` to equal `--source-revision`, then writes the `ReleasePlan` (intent), the `ReleaseCIPlanV1` (executable graph), and the resolved draft policy. `ci _verify-source --release-plan` re-checks that a plan's `source_revision` is 40 lowercase hex characters and that the inherited working directory matches it, so every later job in a generated workflow runs against the exact resolved source. -- Internal runner commands (`ci _capture-build`, `ci _qualify-target`, `ci _evaluate-gate`, `ci _aggregate`) are deterministic file-in/file-out wrappers over `eggpack-core` qualification/finalization APIs. They are not a generic scripting interface. `_capture-build` accepts `--cargo-target-dir` plus `--output-dir` to derive Cargo outputs and stage the canonical `build-handoff.json` + `candidates/` directory; `_qualify-target` copies the validated handoff and candidate bytes next to `evidence.json`; `_evaluate-gate` accepts `--inputs-dir` with the canonical per-target layout; `_qualify-target` accepts an optional `--qemu-sysroot` for Emulated targets. `_aggregate` additionally writes a standalone deterministic `release-manifest.json` beside `summary.json` (never inside the M004 root) and verifies it decodes back to the exact manifest. -- `ci _validate-consumer --consumer-validators --target --candidate-dir --build-handoff --evidence --source-root --output` runs the configured post-qualification consumer check for one target. It refuses fast unless the qualification evidence is `Passed` and its identity matches the handoff, so a failed candidate is never executed against. -- Draft staging commands (`ci _prepare-stage`, `ci _stage-github-draft`) are draft-only with no publication path. `_prepare-stage` materializes a complete deterministic staging payload (finalized assets, checksum sidecars, `release-manifest.json`, `install.sh`, `install.ps1`) with exact-tag origins. `_stage-github-draft` reconciles that payload into a GitHub draft via environment-only `GITHUB_TOKEN`, reusing exact drafts/assets and failing closed on mismatch; incomplete drafts may remain for maintainer inspection and later rerun. +This file is the full command reference. Every command, flag, output path, exit +code, and diagnostic below is taken from the implementation. -Internal artifacts are not public releases. Optional failures suppress release output. Generated staging is implemented (M003b): the rendered `stage` job calls `_prepare-stage` then `_stage-github-draft` with the exact aggregate handoff; reruns reconcile exact state without clobber, and publication stays manual. Tool provisioning in generated CI is pinned to the official Eggpack repository at an exact revision. `ci check` is non-mutating. +## Top-level help + +```text +usage: eggpack [options] + +local producer operator commands: + check validation validate contract, policy, and bindings before anything is built + plan validation resolve the release identity and write a ReleasePlan + package build build every planned target's candidates under an output root + qualify build qualify built candidates and write qualification evidence + collect release aggregation aggregate qualified candidates into a finalized release tree + manifest final-bytes evidence derive release-manifest.json from a finalized release tree + +No command in this set stages or publishes; staging and publication stay +separate, explicitly authorized actions. + +usage: eggpack ci [options] +usage: eggpack contract expand --contract --release-id --target --field +``` + +There are three families: + +| Family | Commands | Purpose | +|---|---|---| +| Local producer operator | `check`, `plan`, `package`, `qualify`, `collect`, `manifest` | Build, qualify, and finalize a release on a workstation. | +| CI generation | `ci generate`, `ci check`, and the nine `ci _*` runners | Render and drift-check the GitHub Actions workflow, and provide the file-in/file-out steps a rendered workflow invokes. | +| Contract projection | `contract expand` | Print one expanded contract field as a scalar. | + +## Exit codes and diagnostics + +Every command exits `0` on success and `1` on failure. There are only two +exit codes: a caller distinguishes failure causes by message text, not by +status. + +- **Success** prints its result on stdout. Nothing is written to stderr. +- **Failure** prints exactly one line on stderr, prefixed `eggpack: `, and + prints nothing at all on stdout. The message names a cause class; it never + echoes captured process output, credentials, or file contents. +- `eggpack --version` / `-V` prints `eggpack ` and exits `0`. +- `eggpack --help` / `-h` prints the top-level help above and exits `0`. + +## Local producer operator commands + +These six commands are the local producer path: `check` → `plan` → `package` → +`qualify` → `collect` → `manifest`. They read local paths, write local paths, +and make no network calls. + +Each command declares a **class** — `validation`, `build`, `release +aggregation`, or `final-bytes evidence` — and `eggpack --help` prints +the command name, its class, its usage line, `class: `, and the +statement that no command in this set stages or publishes. For example: + +```text +$ eggpack collect --help +eggpack collect — release aggregation +usage: eggpack collect --contract --release-plan --build-bindings --qualification-bindings --candidates-dir --output-root +class: release aggregation +No command in this set stages or publishes. +``` + +**Argument surface.** These six commands use a strict parser, not the loose +helper the `ci` family uses. Every flag is required exactly once (except +`manifest`'s optional `--candidates-dir`), may be written `--flag value` or +`--flag=value`, and must have a non-empty value. A repeated flag, an unknown +option, a positional argument, or a missing required flag is an error, and the +missing flags are listed in sorted order: + +```text +eggpack: missing required --build-bindings, --pack-config, --qualification-bindings, --release-id, --selected, --source-revision +``` + +**Input bounds.** Every input document is read through the shared bounded +reader at 1 MiB. A symlink, a non-regular file, or an oversized file is +refused before it is parsed. + +### `eggpack check` + +```text +usage: eggpack check --contract --pack-config --build-bindings --qualification-bindings --selected --release-id --source-revision +``` + +| Flag | Meaning | +|---|---| +| `--contract` | Distribution contract (schema-v1 TOML). | +| `--pack-config` | Producer policy: strategy, host, toolchain, floor, qualification, support. | +| `--build-bindings` | Logical output → package/binary mapping. | +| `--qualification-bindings` | Per-target qualification bindings (smoke checks). | +| `--selected` | Comma-separated contract target aliases or triples to plan. | +| `--release-id` | The release identity. Must pass the exact-tag safety rules. | +| `--source-revision` | The release's source revision: exactly 40 lowercase hex characters. | + +**Reads** the five documents above. **Writes** nothing. The command resolves +the release plan, validates it against its own declared floor, and checks that +the build bindings match the plan and that the qualification bindings match +the plan and the build bindings. + +`check` never runs `git`: `--source-revision` is an explicit value, checked for +shape only. Use `ci _resolve-release` when the checkout itself must be +verified. + +Success prints `check: ok`. + +### `eggpack plan` + +```text +usage: eggpack plan --contract --pack-config --build-bindings --qualification-bindings --selected --release-id --source-revision --output +``` + +Takes every `eggpack check` flag plus: + +| Flag | Meaning | +|---|---| +| `--output` | Where the canonical `ReleasePlan` JSON is written. | + +**Reads** the five documents above. **Writes** one file, `--output`, through +the atomic writer; its parent directory must already exist. + +The plan is the release's *intent* — release identity, source revision, and the +planned targets with their policies. It is not evidence that anything was +built. The encoder is shared with `ci _resolve-release`, so the two surfaces +write byte-identical plans for one resolved plan. + +Success prints `plan: ok`. + +### `eggpack package` + +```text +usage: eggpack package --release-plan --build-bindings --source-root --output-root +``` + +| Flag | Meaning | +|---|---| +| `--release-plan` | The `ReleasePlan` JSON written by `eggpack plan`. | +| `--build-bindings` | Build bindings document. | +| `--source-root` | The Cargo project root to build in. Absolute, or relative to the working directory; `..` components are rejected. | +| `--output-root` | The directory the build artifacts are written under. | + +**Reads** the plan and the bindings, and **builds** in `--source-root` with +`cargo +` (the toolchain pinned in the plan's policy) and +`--release --locked`. The build runs with a cleared environment, a process +group, a bounded deadline, and a bounded output cap. It is a real Cargo build: +the project must compile. + +**Writes**, under `--output-root`: + +- `/build-handoff.json` — the canonical build descriptor: release + identity, target, strategy, and one entry per logical output with its size. +- `/candidates/` — the candidate bytes. +- `.eggpack-build/` — a private Cargo scratch directory, recreated on every + run so a restarted stage starts from a clean target directory. + +`--output-root` is created if it does not exist. Every target is built before +any artifact is written, so a failed build leaves no half-written release +behind. + +Success prints `package: ok`. + +### `eggpack qualify` + +```text +usage: eggpack qualify --contract --release-plan --build-bindings --qualification-bindings --candidates-dir --output-dir +``` + +| Flag | Meaning | +|---|---| +| `--contract` | Distribution contract (schema-v1 TOML). | +| `--release-plan` | The `ReleasePlan` JSON. | +| `--build-bindings` | Build bindings document. | +| `--qualification-bindings` | Per-target qualification bindings. | +| `--candidates-dir` | The **per-target artifact root** to qualify: the directory holding `/build-handoff.json` and `/candidates/`. | +| `--output-dir` | Where the qualification artifact directories are written. | + +> `--candidates-dir` is named after what it contains, not after the directory +> it points at. It is the root written by `eggpack package`, not the +> `candidates/` directory inside it. + +**Reads** the four documents plus the handoff and candidate bytes under +`--candidates-dir`. **Writes**, under `--output-dir`, one directory per +target holding `evidence.json`, `build-handoff.json`, and `candidates/`. + +The evidence records the planned and actual classification, the actual host +the qualification ran on, the candidate digests and formats, and the bounded +process outcomes. A `native` qualification is host-matched proof; it does not +prove a declared glibc or macOS floor, and a host mismatch is recorded as a +failure, never as a pass or a skip. + +Every target is qualified before any artifact is written. + +Success prints `qualify: ok`. + +### `eggpack collect` + +```text +usage: eggpack collect --contract --release-plan --build-bindings --qualification-bindings --candidates-dir --output-root +``` + +| Flag | Meaning | +|---|---| +| `--contract` | Distribution contract (schema-v1 TOML). | +| `--release-plan` | The `ReleasePlan` JSON. | +| `--build-bindings` | Build bindings document. | +| `--qualification-bindings` | Per-target qualification bindings. | +| `--candidates-dir` | The **per-target artifact root** to aggregate: the directory written by `eggpack qualify`. | +| `--output-root` | The new release root to finalize into. | + +**Reads** the four documents plus the handoff, evidence, and candidate bytes +under `--candidates-dir`. **Writes** the finalized release tree under +`--output-root`, and `release-manifest.json` **beside** that root — never +inside it. + +The parent of `--output-root` must already exist: the finalizer writes one +*new* release root under a caller-secured parent and never overwrites an +existing one. The manifest therefore lands in `--output-root`'s parent. + +`collect` projects the same release graph the CI path projects, so the local +path aggregates the same targets with the same finalization settings the +generated workflow uses. + +Success prints `collect: ok`. + +### `eggpack manifest` + +```text +usage: eggpack manifest --contract --release-plan --finalized-root --output [--candidates-dir ] +``` + +| Flag | Meaning | +|---|---| +| `--contract` | Distribution contract (schema-v1 TOML). | +| `--release-plan` | The `ReleasePlan` JSON. | +| `--finalized-root` | The finalized release tree to read the final bytes from. | +| `--output` | Where the derived `release-manifest.json` is written. | +| `--candidates-dir` | Optional. The per-target artifact root. Required only for archive targets. | + +**Reads** the contract, the plan, and the finalized tree's bytes. **Writes** +one file, `--output`; its parent directory must already exist. + +The manifest is the *final-bytes evidence*: for each target it records the +asset form, the artifact name, its size, and its SHA-256. Those are integrity +facts about the bytes — not a signature and not a provenance claim. + +`--candidates-dir` is needed only for archive targets. An archive's member +digests are facts about the member bytes, which the finalized tree does not +retain, so they are read from the qualified candidate bytes instead. A direct +target needs no candidate bytes. + +Success prints `manifest: ok`. + +## `eggpack ci` + +The `ci` family renders the GitHub Actions workflow and provides the internal +runners a rendered workflow invokes. + +The `ci` family uses the **loose** flag helper: flags are read left to right +and the first occurrence wins, so a repeated flag is silently ignored. Unknown +flags are not rejected; a typo is caught only if it pushes the argument count +past the command's cap. Use the local operator commands when strict argument +handling matters. + +### `eggpack ci generate` + +Renders a workflow and writes exactly one file, `--output`, through the atomic +writer. The output path is refused if it is a symlink or a directory, and its +parent must already be a real directory. Nothing else is created, so a +generate run cannot touch anything the caller did not name. + +| Flag | Required | Meaning | +|---|---|---| +| `--github-policy` | yes | Caller-supplied runner labels, action pins, and release input paths. | +| `--output` | yes | Where the rendered workflow is written. | +| `--ci-plan` | one of two modes | A checked-in `ReleaseCIPlanV1` (exact mode). | +| `--workflow-shape` | one of two modes | A `ReleaseWorkflowShapeV1` (reusable mode). | +| `--contract` | with `--workflow-shape` | The distribution contract, in reusable mode. | + +The two modes are mutually exclusive: supplying both `--ci-plan` and +`--workflow-shape` is an error. + +Success prints `generated bytes to `. The rendering is deterministic: +the same inputs produce byte-identical output. + +### `eggpack ci check` + +Renders the workflow in memory and compares it with an existing file. It +**never writes**. The existing workflow is read through the bounded reader at +8 MiB. + +| Flag | Required | Meaning | +|---|---|---| +| `--github-policy` | yes | Caller-supplied policy, as for `ci generate`. | +| `--workflow` | yes | The existing workflow file to compare against. | +| `--ci-plan` | one of two modes | A checked-in `ReleaseCIPlanV1` (exact mode). | +| `--workflow-shape` | one of two modes | A `ReleaseWorkflowShapeV1` (reusable mode). | +| `--contract` | with `--workflow-shape` | The distribution contract, in reusable mode. | + +Comparison is CRLF→LF only. There is no fuzzy matching, so a +reformatted-but-equivalent file is drift too. + +Success prints `ci check: match ( bytes)` and exits `0`. Drift prints +`eggpack: ci check: drift detected (expected bytes, found bytes, +first difference at Some())` and exits `1`. + +### The nine internal `ci _*` runners + +These exist so a generated workflow step is a file-in/file-out call with a +fixed shape. They are **wrappers, not a scripting interface**: the input +grammar is paths, a target name that must already exist in the plan, and +nothing else. There is no shell invocation, no caller-supplied program name, +and no flag whose value is interpreted as a command. + +Invocations are rendered, not typed — `RunnerCommand::argv()` in +`eggpack-ci` is what produces them. + +#### `ci _verify-source` + +| Flag | Required | Meaning | +|---|---|---| +| `--release-plan` | yes | The plan whose `source_revision` is checked. | +| `--github-policy` | all three or none | The resolved draft policy. | +| `--expected-tag` | all three or none | The tag the policy must carry. | +| `--source-root` | all three or none | The checkout to verify. | + +With only `--release-plan`, the command checks that the plan's +`source_revision` is 40 lowercase hex characters and that the inherited +working directory is at that revision. With all three of the optional flags, +it additionally checks the tag, the mapped identity, and that the tag peels to +the plan's revision. + +Writes nothing. Prints `checked-out source matches release plan`. + +#### `ci _resolve-release` + +| Flag | Required | Meaning | +|---|---|---| +| `--contract` | yes | Distribution contract. | +| `--pack-config` | yes | Producer policy. | +| `--build-bindings` | yes | Build bindings. | +| `--qualification-bindings` | yes | Qualification bindings. | +| `--selected` | yes | Comma-separated target aliases to plan. | +| `--tag` | yes | The exact existing tag. | +| `--source-revision` | yes | 40 lowercase hex characters. | +| `--template` | yes | The static draft template. | +| `--source-root` | yes | The checkout the revision is verified against. | +| `--output-plan` | yes | Where the `ReleasePlan` is written. | +| `--output-ci-plan` | yes | Where the `ReleaseCIPlanV1` is written. | +| `--output-github-policy` | yes | Where the resolved draft policy is written. | +| `--consumer-validators` | no | Consumer validator configuration. | +| `--identity-mode` | no | `exact_tag` (default) or `v_prefixed_stable_semver`. | + +Verifies that the checked-out `HEAD` under `--source-root` equals +`--source-revision` **and** that the tag peels to the same revision; either +check failing fails the command closed. The three output documents are written +only after both checks pass. + +Prints two lines: + +```text +checked-out source matches release plan +resolved runtime release identity for tag +``` + +#### `ci _capture-build` + +| Flag | Required | Meaning | +|---|---|---| +| `--release-plan` | yes | The `ReleasePlan` JSON. | +| `--build-bindings` | yes | Build bindings. | +| `--target` | yes | The target to capture. | +| `--cargo-target-dir` | one of two | A Cargo target root; candidate paths are derived from it. | +| `--candidate-dir` | one of two | A directory of already-staged candidate bytes. | +| `--output` | one of two | Where the handoff JSON is written. | +| `--output-dir` | one of two | Where the canonical build artifact directory is written. | + +At least one of `--cargo-target-dir`/`--candidate-dir` and at least one of +`--output`/`--output-dir` are required. `--output-dir` receives +`build-handoff.json` plus `candidates/` bytes. + +Prints `captured build handoff for `. + +#### `ci _qualify-target` + +| Flag | Required | Meaning | +|---|---|---| +| `--release-plan` | yes | The `ReleasePlan` JSON. | +| `--build-bindings` | yes | Build bindings. | +| `--qualification-bindings` | yes | Qualification bindings. | +| `--contract` | yes | Distribution contract. | +| `--target` | yes | The target to qualify. | +| `--candidate-dir` | yes | The candidate bytes to qualify. | +| `--build-handoff` | yes | The build handoff describing those bytes. | +| `--output-dir` | yes | Where the qualification artifact directory is written. | +| `--qemu-sysroot` | no | The sysroot for an `emulated` target. | + +Writes `evidence.json`, `build-handoff.json`, and `candidates/` into +`--output-dir`. Prints `qualified : `. + +#### `ci _validate-consumer` + +| Flag | Required | Meaning | +|---|---|---| +| `--consumer-validators` | yes | The consumer validator configuration. | +| `--target` | yes | The target to validate. | +| `--candidate-dir` | yes | The candidate bytes to validate against. | +| `--build-handoff` | yes | The build handoff. | +| `--evidence` | yes | The qualification evidence. | +| `--source-root` | yes | The source tree the validator runs in. | +| `--output` | yes | Where the consumer evidence is written. | + +Refuses fast unless the qualification evidence is `Passed` and its identity +matches the handoff, so a failed candidate is never executed against. + +Prints `consumer validation passed for `. + +#### `ci _evaluate-gate` + +| Flag | Required | Meaning | +|---|---|---| +| `--ci-plan` | yes | The `ReleaseCIPlanV1`. | +| `--output` | yes | Where the gate outcome JSON is written. | +| `--evidence-dir` | one of two | A flat directory of `.json` files. | +| `--inputs-dir` | one of two | The canonical per-target layout `//evidence.json`. | + +At least one of `--evidence-dir`/`--inputs-dir` is required. Stray +`consumer-evidence.json` in the inputs directory, with no configured +validator, fails closed so validation can never be silently bypassed. + +Prints `gate outcome: `. An outcome that is not complete or +suppressed is an error. + +#### `ci _aggregate` + +| Flag | Required | Meaning | +|---|---|---| +| `--contract` | yes | Distribution contract. | +| `--release-plan` | yes | The `ReleasePlan` JSON. | +| `--ci-plan` | yes | The `ReleaseCIPlanV1`. | +| `--inputs-dir` | yes | The per-target layout `//{build-handoff.json,evidence.json,candidates/}`. | +| `--output-root` | yes | The new release root to finalize into. | +| `--output` | yes | Where the aggregate summary JSON is written. | + +Writes the finalized release tree under `--output-root`, the summary at +`--output`, and `release-manifest.json` beside `--output`'s parent — never +inside the finalized root. + +Prints `aggregate: Complete`. + +#### `ci _prepare-stage` + +| Flag | Required | Meaning | +|---|---|---| +| `--contract` | yes | Distribution contract. | +| `--release-manifest` | yes | The `release-manifest.json`. | +| `--finalized-root` | yes | The finalized release tree. | +| `--github-policy` | yes | The GitHub draft policy. | +| `--install-policy` | yes | The installer policy. | +| `--output-dir` | yes | Where the staging payload directory is written. | +| `--output-payload` | yes | Where the payload document is written. | +| `--installer-presentation` | paired | Presentation for product installer wrappers. | +| `--source-root` | paired | The source tree the wrappers are rendered from. | + +`--installer-presentation` and `--source-root` are paired: one without the +other is an error. The pair selects the product-wrapper rendering; neither +selects the generated default. + +Prints `prepare-stage: assets`. + +#### `ci _stage-github-draft` + +| Flag | Required | Meaning | +|---|---|---| +| `--payload` | yes | The staging payload document. | +| `--github-policy` | yes | The GitHub draft policy. | +| `--output-receipt` | yes | Where the staging receipt is written. | +| `--staging-dir` | no | The directory the payload's relative paths resolve against. Defaults to the payload file's parent. | + +The GitHub token is read from the environment only, under the name the policy +declares. Its absence fails before any network I/O, and the token text is +never serialized, logged, or included in an error. + +Prints `stage-github-draft: release draft staged`. ## `eggpack contract expand` (Contract M003) @@ -63,3 +540,31 @@ The example above is executable and guarded by `crates/eggpack-cli/tests/contract_expand.rs::the_documented_readme_example_runs_verbatim`, which runs it with these exact relative paths from a temporary working directory. + +## Staging and publication + +**No command in this file stages or publishes.** The six local producer +operator commands are local-only: they read local paths, write local paths, +and reach no network. The `ci` family can render a workflow and can prepare +and reconcile a GitHub **draft**, but staging is draft-only and publication is +never performed by this binary. + +Staging and publication remain separate, explicitly authorized actions: + +- Staging writes into a staging payload and reconciles it into a draft on the + exact existing tag. There is no clobber, no tag mutation, and no overwrite + of an existing draft. +- Publication is a human action performed outside this binary. An internal + artifact is not a public release. + +A failed or optional stage suppresses release output rather than failing the +run. + +## See also + +- [../../docs/quickstart.md](../../docs/quickstart.md) — a verified + end-to-end walkthrough of the local producer path and the CI rendering path. +- [../../architecture/cli.md](../../architecture/cli.md) — the command + taxonomy and the wiring boundary. +- [../../architecture/overview.md](../../architecture/overview.md) — the + workspace-level module map. diff --git a/docs/quickstart.md b/docs/quickstart.md index f0496a5..90ab0f4 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,11 +1,29 @@ -# Quickstart: resolve a release and render its workflow +# Quickstart: build a release locally, and render its workflow -This guide resolves a one-target Linux release and renders its GitHub Actions -workflow using the `eggpack` CLI. Every command below was run verbatim against -the workspace and produces the quoted output. No network access, no real -build, no GitHub token: resolution and rendering are pure file-in/file-out. +This guide builds a one-target Linux release end to end on a workstation with +the `eggpack` CLI, then renders the GitHub Actions workflow that replays the +same steps in CI. Every command below was run verbatim against the workspace +and produces the quoted output. -Prerequisites: Rust stable (MSRV 1.89), git, and a checkout of this repo. +The first half is the **local producer operator path**: `check` → `plan` → +`package` → `qualify` → `collect` → `manifest`. It performs a real Cargo +build, but no network access and no GitHub token. The second half is the +**CI rendering path**: it is pure file-in/file-out. + +Prerequisites: Rust (MSRV 1.89) and git, plus the Rust toolchain named in +`pack-config.toml` installed — `package` invokes `cargo +`: + +```sh +rustup toolchain install 1.89.0 +``` + +**Host scope of this walkthrough.** Steps 2–7 below build and qualify a +**Linux x86_64** release: `pack-config.toml` pins `host_os = "linux"` and +`host_arch = "x86_64"`, and a `native` qualification is host-matched proof, so +on a macOS or Windows host the `qualify` step records a host mismatch and +fails by design. Steps 1–3 and 8–9 are host-independent — the plan document and +the rendered workflow bytes are the same on every host. The commands below are +POSIX-shell commands; on Windows, run them from Git Bash or WSL. Build the CLI once: @@ -17,8 +35,11 @@ $EGGPACK --version # eggpack 0.1.0 ## 1. Create a scratch release repo -The resolver binds the release to an exact git commit: `HEAD` under -`--source-root` must equal `--source-revision`, else it fails closed. +`ci _resolve-release` binds the release to an exact git commit: `HEAD` under +`--source-root` must equal `--source-revision`, and the tag must peel to the +same commit, else it fails closed. The local operator commands do not inspect a +checkout at all — they take `--source-revision` as an explicit value — but the +CI rendering path below does, so the scratch repo is a git repository. ```sh mkdir -p eggdemo/out && cd eggdemo @@ -118,14 +139,248 @@ templating language): {"preflight_runner":"ubuntu-latest","runners":[{"os":"linux","arch":"x86_64","label":"ubuntu-latest","cargo_zigbuild":false,"zig":false}],"checkout":{"reference":"actions/checkout@0123456789abcdef0123456789abcdef01234567"},"rust_toolchain":{"reference":"dtolnay/rust-toolchain@0123456789abcdef0123456789abcdef01234567"},"upload_artifact":{"reference":"actions/upload-artifact@0123456789abcdef0123456789abcdef01234567"},"download_artifact":{"reference":"actions/download-artifact@0123456789abcdef0123456789abcdef01234567"},"triggers":["push"],"timeout_minutes":60,"cancel_in_progress":true,"artifact_retention_days":7,"eggpack_tool":{"repo":"https://github.com/eggstack/eggpack","revision":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","package":"eggpack-cli","install_timeout_minutes":10},"release_inputs":{"contract":"contract.toml","release_plan":"out/release-plan.json","build_bindings":"build-bindings.toml","qualification_bindings":"qualification-bindings.toml","ci_plan":"out/release-ci-plan.json"}} ``` -Commit, then record `HEAD` — it becomes the release's source revision: +Finally the project `package` will build. It is a trivial Cargo binary with no +dependencies, so the build needs no network and no registry access: + +```sh +mkdir -p demo/src +cat > demo/Cargo.toml <<'EOF' +[package] +name = "demo" +version = "0.1.0" +edition = "2021" +EOF +cat > demo/Cargo.lock <<'EOF' +version = 3 + +[[package]] +name = "demo" +version = "0.1.0" +EOF +printf 'fn main() {}\n' > demo/src/main.rs +``` + +Commit, then record `HEAD` — it becomes the release's source revision — and +tag it, because `ci _resolve-release` peels the tag: ```sh git add . && git commit -qm demo REV=$(git rev-parse HEAD) # 40 lowercase hex chars +git tag 1.2.6 +``` + +## 2. Validate the input set + +`eggpack check` resolves the whole planning input set and writes nothing. It +reads the contract, the producer policy, and both bindings documents, and +fails closed if the policy does not resolve for the selected identity, if the +build bindings do not match the plan, or if the qualification bindings do not +match the plan and the build bindings. + +```sh +$EGGPACK check \ + --contract contract.toml \ + --pack-config pack-config.toml \ + --build-bindings build-bindings.toml \ + --qualification-bindings qualification-bindings.toml \ + --selected linux-x64 \ + --release-id 1.2.6 \ + --source-revision "$REV" +``` + +Expected output: + +```text +check: ok +``` + +`--source-revision` must be 40 lowercase hex characters and `--release-id` must +be exact-tag safe; both are checked. `check` does not inspect the checkout — +it never runs `git`. + +## 3. Resolve the release plan + +`eggpack plan` takes the same inputs and writes the `ReleasePlan` — the +release's *intent*, not evidence of anything built. + +```sh +$EGGPACK plan \ + --contract contract.toml \ + --pack-config pack-config.toml \ + --build-bindings build-bindings.toml \ + --qualification-bindings qualification-bindings.toml \ + --selected linux-x64 \ + --release-id 1.2.6 \ + --source-revision "$REV" \ + --output out/release-plan.json +``` + +Expected output: + +```text +plan: ok +``` + +`out/release-plan.json` is a schema-v1 JSON document carrying the +`release_id`, the `source_revision`, and one entry per planned target with its +policy, asset form, and floor status. Its bytes vary with the revision, so +the document is not quoted here. + +## 4. Build the candidates + +`eggpack package` performs a real Cargo build of every planned target and +stages the candidates under the output root. + +```sh +$EGGPACK package \ + --release-plan out/release-plan.json \ + --build-bindings build-bindings.toml \ + --source-root demo \ + --output-root out/build +``` + +Expected output: + +```text +package: ok +``` + +The output root now holds one directory per target: + +```text +$ ls out/build +x86_64-unknown-linux-gnu +$ ls out/build/x86_64-unknown-linux-gnu +build-handoff.json +candidates +$ ls out/build/x86_64-unknown-linux-gnu/candidates +candidate-direct ``` -## 2. Resolve the release plan +`build-handoff.json` is the canonical build descriptor (release identity, target, +strategy, and one entry per logical output with its size). `candidates/` holds +the candidate bytes under their canonical relative names. The build itself runs +in a private scratch directory, `out/build/.eggpack-build/`, which is recreated +on every run so a restarted stage starts from a clean Cargo target directory. + +## 5. Qualify the candidates + +`eggpack qualify` runs the configured qualification for every planned target +and writes the evidence. + +```sh +$EGGPACK qualify \ + --contract contract.toml \ + --release-plan out/release-plan.json \ + --build-bindings build-bindings.toml \ + --qualification-bindings qualification-bindings.toml \ + --candidates-dir out/build \ + --output-dir out/qualification +``` + +Expected output: + +```text +qualify: ok +``` + +`--candidates-dir` is the **per-target artifact root** written by `package` — +the directory that holds `/build-handoff.json` and `/candidates/`, +not the `candidates/` directory itself. The output directory mirrors that +layout: + +```text +$ ls out/qualification/x86_64-unknown-linux-gnu +build-handoff.json +candidates +evidence.json +``` + +`evidence.json` records the planned and actual classification, the actual host +the qualification ran on, the candidate digests and formats, and the bounded +process outcomes. This run used `qualification = "native"`, so the evidence +records the host it matched; a native run is host-matched proof and does not +prove a declared glibc or macOS floor. + +## 6. Aggregate the finalized release tree + +`eggpack collect` aggregates the qualified candidates into a finalized release +tree. + +```sh +mkdir -p out/release +$EGGPACK collect \ + --contract contract.toml \ + --release-plan out/release-plan.json \ + --build-bindings build-bindings.toml \ + --qualification-bindings qualification-bindings.toml \ + --candidates-dir out/qualification \ + --output-root out/release/finalized +``` + +Expected output: + +```text +collect: ok +``` + +```text +$ ls out/release +finalized +release-manifest.json +$ ls out/release/finalized +eggsact-1.2.6-x86_64-unknown-linux-gnu +eggsact-1.2.6-x86_64-unknown-linux-gnu.sha256 +``` + +The parent of `--output-root` must already exist — `out/release` is created +here — because the finalizer writes one *new* release root under a +caller-secured parent and never overwrites an existing one. `--candidates-dir` +is again the per-target artifact root, this time the one `qualify` wrote. + +`release-manifest.json` lands **beside** the finalized root, never inside it. + +## 7. Derive the release manifest + +`eggpack manifest` derives the release manifest independently, from the +finalized tree's bytes. + +```sh +mkdir -p out/manifest +$EGGPACK manifest \ + --contract contract.toml \ + --release-plan out/release-plan.json \ + --finalized-root out/release/finalized \ + --output out/manifest/release-manifest.json +``` + +Expected output: + +```text +manifest: ok +``` + +The two manifests are the same document: + +```text +$ diff out/release/release-manifest.json out/manifest/release-manifest.json +(identical) +``` + +`--output`'s parent directory must already exist, as for every command that +writes a file. `--candidates-dir` is optional and is needed only for archive +targets, whose member digests are facts about the member bytes the finalized +tree does not retain. + +The manifest carries the product, release, and source revision, and for each +target the asset form, the artifact name, its size, and its SHA-256. Those +are integrity facts about the bytes — not a signature and not a provenance +claim. + +## 8. Render the workflow + +The CI path resolves its own runtime identity, so it verifies the checkout and +the tag that the local operator commands take as explicit values. ```sh $EGGPACK ci _resolve-release \ @@ -152,10 +407,12 @@ resolved runtime release identity for tag 1.2.6 This writes `out/release-plan.json` (intent, not evidence), `out/release-ci-plan.json` (executable graph), and `out/draft-policy.json` -(draft identity). A wrong `--source-revision` or uncommitted `HEAD` fails -closed here. +(draft identity). The plan it writes is byte-identical to the one +`eggpack plan` wrote to the same path: both surfaces share one plan encoder. +A wrong `--source-revision`, an uncommitted `HEAD`, or a tag that does not peel +to the revision fails closed here. -## 3. Render the workflow +Now render the workflow: ```sh $EGGPACK ci generate \ @@ -176,7 +433,7 @@ read-only (`contents: read`): jobs `preflight` → `build_x86_64_unknown_linux_g No tag or revision is baked in — the same static shape serves future tags via the runtime `resolve` job (see `../crates/eggpack-ci/README.md`). -## 4. Check for drift +## 9. Check for drift ```sh $EGGPACK ci check \ @@ -207,11 +464,19 @@ eggpack: ci check: drift detected (expected 6831 bytes, found 6845 bytes, first bytes. Comparison is CRLF→LF only; there is no fuzzy matching, so a reformatted-but-equivalent file is drift too. +## What this walkthrough does not do + +No command above stages or publishes. Draft staging and publication remain +separate, explicitly authorized actions — see +[../crates/eggpack-cli/README.md](../crates/eggpack-cli/README.md) for the +staging runners and +[../architecture/cli.md](../architecture/cli.md) for the command taxonomy. + ## Next steps - Full command reference: [../crates/eggpack-cli/README.md](../crates/eggpack-cli/README.md). - What each stage means: [../architecture/overview.md](../architecture/overview.md) (pipeline), [../architecture/core.md](../architecture/core.md), [../architecture/ci.md](../architecture/ci.md). -- After planning come build → qualify → finalize → stage; the generated - workflow replays exactly these steps in CI. +- The generated workflow replays exactly these steps in CI; after planning + come build → qualify → finalize → stage. From 6a7cb4cabeddc925cf730859ff4178abc7956ddd Mon Sep 17 00:00:00 2001 From: doc Date: Fri, 23 Oct 2026 16:37:30 +0000 Subject: [PATCH 11/46] fix(ci): converge consumer-validator execution onto the bounded runner The CI crate's consumer validator had its own process runner: it killed only the direct child and joined its reader threads without a bound, so a descendant holding an inherited stdout/stderr pipe open past the deadline wedged the CI job indefinitely, defeating the timeout, the cancellation flag, and the output bound the same function implemented. Route the consumer validator through the one bounded runner in eggpack-core. The CI crate builds an InterpreterCommandSpec (OS-native argv, so a validated absolute path reaches the interpreter byte-exact) and calls the new run_interpreter_bounded entry point; the CI-local reader helpers, the direct-child kill, and the CI-local environment allowlist are removed. The shared runner gains the CI's prompt output-limit detection: an over-limit stream is noticed at the moment of excess and the whole process group is terminated then, instead of at the deadline. The observable outcome (OutputLimitExceeded) is unchanged; only the moment of termination moves earlier. No new dependency in any crate; no change to the consumer validator's contract, to the generated workflow bytes, or to any schema. --- architecture/ci.md | 13 +- architecture/core-build.md | 286 ++++++----- architecture/overview.md | 6 +- architecture/process-execution.md | 268 ++++++----- crates/eggpack-ci/README.md | 16 + crates/eggpack-ci/src/lib.rs | 749 ++++++++++++++++++++--------- crates/eggpack-core/README.md | 16 + crates/eggpack-core/src/builder.rs | 286 ++++++++--- 8 files changed, 1101 insertions(+), 539 deletions(-) diff --git a/architecture/ci.md b/architecture/ci.md index b33f82f..24a91f1 100644 --- a/architecture/ci.md +++ b/architecture/ci.md @@ -192,9 +192,12 @@ crate's own end-to-end orchestration tests can drive the real downstream crates without a network. Notably absent: `command-group` and any YAML emitter. The process-execution -contract that core enforces is **not** shared with this crate — the consumer -validator has its own independent runner. See `process-execution.md` for that -gap. +contract is nevertheless **shared**: the consumer validator runs through +`eggpack_core::run_interpreter_bounded` (`crates/eggpack-ci/src/lib.rs:4892`), +so the crate gets core's process-group (or job-object) termination, bounded +reader-thread joins, the shared environment allowlist, and the shared output +bounds without taking a `command-group` dependency of its own. See +`process-execution.md`. Dependents: `eggpack-cli`, which exposes `ci generate` and `ci check` and the nine internal `ci _*` runner commands that the generated workflow invokes. @@ -211,8 +214,8 @@ nine internal `ci _*` runner commands that the generated workflow invokes. YAML emitter - [validation-model.md](validation-model.md) — the fail-closed rules enforced on every document in this crate -- [process-execution.md](process-execution.md) — the independent runner used by - the consumer validator +- [process-execution.md](process-execution.md) — the shared bounded runner the + consumer validator runs through - [github.md](github.md) — where staging intent is actually performed - [testing-and-portability.md](testing-and-portability.md) — the golden corpus and the Windows lane for this crate diff --git a/architecture/core-build.md b/architecture/core-build.md index 8a9549e..676ab6e 100644 --- a/architecture/core-build.md +++ b/architecture/core-build.md @@ -6,20 +6,20 @@ discovery. One of four `eggpack-core` stage deep dives (planning, build, qualifi finalization); the stage between `ReleasePlan` (intent) and `QualificationEvidence` (proof). Single file `crates/eggpack-core/src/builder.rs` (1734 lines, `#![forbid(unsafe_code)]` inherited from the workspace), re-exported wholesale at crate -root (`crates/eggpack-core/src/lib.rs:10`). +root (`crates/eggpack-core/src/lib.rs:11`). ## Inputs and outputs - in: `&ReleasePlan`, `&PlannedTarget` — from `PackConfig::resolve` - (`crates/eggpack-core/src/lib.rs:709`, `:618`). + (`crates/eggpack-core/src/lib.rs:867`, `:758`). - in: `&[BuildBinding]` — the caller's per-target slice, **not** coverage-validated here. -- in: `&DistributionContract` — only via `BuildBindingsV1::validate_for` (`:284`). +- in: `&DistributionContract` — only via `BuildBindingsV1::validate_for` (`:341`). - in: `repository_root`, `work_root`, `invocation`, `&BuildCancellation`. -- out: `BuildAttempt` (`:227`) — identity, bounded `ProcessEvidence`, `Vec`. -- out: `ProcessEvidence` (`:199`) — outcome plus retained byte **counts** only. +- out: `BuildAttempt` (`:284`) — identity, bounded `ProcessEvidence`, `Vec`. +- out: `ProcessEvidence` (`:256`) — outcome plus retained byte **counts** only. -`BuildAttempt` is identity-bound to `release_id` + `source_revision` (`:229`, `:231`) and to -the one `target` / `strategy` it ran (`:233`, `:235`). It records what was attempted, not +`BuildAttempt` is identity-bound to `release_id` + `source_revision` (`:286`, `:288`) and to +the one `target` / `strategy` it ran (`:290`, `:292`). It records what was attempted, not what was proved: this module never inspects a candidate's format, architecture, or runtime behaviour, so `Success` means a command exited zero — never that the candidate qualifies. @@ -28,170 +28,191 @@ behaviour, so `Success` means a command exited zero — never that the candidate A contract output slot is not a filesystem path, so each slot is bound by hand to a Cargo package and binary target. -- `LogicalOutputSelector` (`:68`), tagged and `deny_unknown_fields` (`:67`): `Direct` - (`:70`); `BundleEntry{index}` indexed by **contract order** (`:71-75`); - `ArchiveMember{source}` keyed by the **exact contract source string** (`:76-80`). -- `BuildBinding{selector, package, binary}` (`:86-93`) pairs a slot with one Cargo +- `LogicalOutputSelector` (`:76`), tagged and `deny_unknown_fields` (`:75`): `Direct` + (`:78`); `BundleEntry{index}` indexed by **contract order** (`:79-83`); + `ArchiveMember{source}` keyed by the **exact contract source string** (`:84-88`). +- `BuildBinding{selector, package, binary}` (`:94-101`) pairs a slot with one Cargo `--package` / `--bin` pair. - `BuildBindingsV1{schema_version, targets: BTreeMap>}` - (`:98-103`), strict version 1. `from_toml` (`:246-251`) parses via `toml::from_str` then runs - `validate_shape` (`:252-282`). + (`:106-111`), strict version 1. `from_toml` (`:303-308`) parses via `toml::from_str` then runs + `validate_shape` (`:309-339`). -`validate_shape` (`:252-282`) is the fail-closed bound layer: `schema_version == 1` and -1..=256 targets (`:253-255`); per target a non-empty key and 1..=256 bindings (`:256-259`); unique -selectors plus `valid_identifier` package/binary (`:260-267`), where -`valid_identifier` (`:326-331`) allows only `[A-Za-z0-9_.-]`, ≤128 bytes. +`validate_shape` (`:309-339`) is the fail-closed bound layer: `schema_version == 1` and +1..=256 targets (`:310-312`); per target a non-empty key and 1..=256 bindings (`:313-316`); unique +selectors plus `valid_identifier` package/binary (`:317-324`), where +`valid_identifier` (`:383-388`) allows only `[A-Za-z0-9_.-]`, ≤128 bytes. `ArchiveMember.source` must be a non-empty ≤255-byte relative path with no leading `/` -and no empty/`.`/`..` component (`:268-278`). +and no empty/`.`/`..` component (`:325-335`). -**Exact plan coverage** is `validate_for` (`:284-324`). For every `plan.targets` entry it -looks up `self.targets[&target.target]` (`:291-294`, else `missing target bindings`), -expands the contract (`:295-297`), and derives the expected slot set from the expanded +**Exact plan coverage** is `validate_for` (`:341-381`). For every `plan.targets` entry it +looks up `self.targets[&target.target]` (`:348-351`, else `missing target bindings`), +expands the contract (`:352-354`), and derives the expected slot set from the expanded `ExpandedAssets` variant — `Direct` ⇒ `{Direct}`; `Bundle` ⇒ `BundleEntry{0..entries.len()}`; -`Archive` ⇒ `ArchiveMember{source}` per member (`:298-308`). The binding selectors must -then be **equal as sets** (`:309-310`): equality in both directions means neither a +`Archive` ⇒ `ArchiveMember{source}` per member (`:355-365`). The binding selectors must +then be **equal as sets** (`:366-367`): equality in both directions means neither a missing nor an extra slot is accepted, reported as the single `bindings do not exactly -cover contract Cargo slots` (`:311-314`). Any binding target key absent from the plan is -rejected as `bindings include target outside ReleasePlan` (`:316-322`). Contract expansion +cover contract Cargo slots` (`:368-371`). Any binding target key absent from the plan is +rejected as `bindings include target outside ReleasePlan` (`:373-379`). Contract expansion is the authority: a `BuildBinding` cannot redefine layout, only map an already-contractual slot onto a Cargo target. ## Command construction by build strategy -`cargo_command` (`:334-401`) is the only builder and is total over the two -`BuildStrategy` variants. It re-validates both identifiers (`:341-343`), so it is safe to +`cargo_command` (`:391-458`) is the only builder and is total over the two +`BuildStrategy` variants. It re-validates both identifiers (`:398-400`), so it is safe to call with a hand-built binding. -| Aspect | `NativeCargo` (`:351`) | `CargoZigbuild` (`:352`) | +| Aspect | `NativeCargo` (`:408`) | `CargoZigbuild` (`:409`) | | --- | --- | --- | | subcommand | `build` | `zigbuild` | | shared args | `+`, `--release`, `--locked`, `--target ` | identical | -| glibc floor | not encoded | `args[5]` rewritten to `..` (`:358-361`) | -| macOS floor | n/a | rejected: `macOS floor cannot use cargo-zigbuild` (`:362-372`) | - -Both append exactly `--package --bin ` (`:379-384`). The executable is -always the bare tool name `cargo` (`:391`); executable and argv are separate OS arguments, so -no shell is involved (`:126`). One environment variable is injected, `CARGO_TARGET_DIR` = -the private target directory (`:385-389`); `cwd` is the caller's (`:393`), both stream limits -are `MAX_OUTPUT` (256 KiB, `:18-19`, `:396-397`), and `expected_stdout` is `None` (`:398`). -`execute_target_cancellable` supplies a fixed 1800 s build timeout (`:891`). - -`preflight` (`:732-831`) runs before any build: `rustc + --version` (`:739`) and -`cargo + --version` (`:759`), each 10 s / 1024 bytes, failing closed on any -non-`Success` outcome (`:754-756`, `:774-776`). Under `CargoZigbuild` it also requires both -cross-tool versions to be declared (`:777-789`) and requires each declared pin to be a complete +| glibc floor | not encoded | `args[5]` rewritten to `..` (`:415-418`) | +| macOS floor | n/a | rejected: `macOS floor cannot use cargo-zigbuild` (`:419-429`) | + +Both append exactly `--package --bin ` (`:436-441`). The executable is +always the bare tool name `cargo` (`:448`); executable and argv are separate OS arguments, so +no shell is involved (`:158`). One environment variable is injected, `CARGO_TARGET_DIR` = +the private target directory (`:442-446`); `cwd` is the caller's (`:450`), both stream limits +are `MAX_OUTPUT` (256 KiB, `:20-28`, `:453-454`), and `expected_stdout` is `None` (`:455`). +`execute_target_cancellable` supplies a fixed 1800 s build timeout (`:1058`). + +`preflight` (`:899-998`) runs before any build: `rustc + --version` (`:906`) and +`cargo + --version` (`:926`), each 10 s / 1024 bytes, failing closed on any +non-`Success` outcome (`:921-923`, `:941-943`). Under `CargoZigbuild` it also requires both +cross-tool versions to be declared (`:944-956`) and requires each declared pin to be a complete `MAJOR.MINOR.PATCH` version. `cargo zigbuild --version` and `zig version` are matched by **trimmed equality** (`expected_stdout_exact`), not by substring, so a pin of `0.23.3` is not satisfied by a reported `0.23.30`; mismatch yields `cargo-zigbuild version mismatch` / `Zig version mismatch`. The expected value is compared internally and never -surfaced (`:143-149`). +surfaced (`:175-181`). ## Bounded cancellable process execution -All execution funnels through the private `run_bounded_inner` (`:488-690`). Three entry -points select an `ExecutableAllowance` (`:119-124`): +All execution funnels through the private `run_bounded` (`:628-848`), reached through +`run_bounded_inner` (`:608-626`). Five entry points select an `ExecutableAllowance` +(`:127-156`): | Entry | Allowance | Executable rule | | --- | --- | --- | -| `run_bounded_cancellable` (`:405`) | `Builder` | `cargo` \| `rustc` \| `zig` (`:494-496`) | -| `run_qualification_process` (`:474`) | `Candidate` | must be an **absolute path** (`:497`) | -| `run_qemu_process` (`:481`) | `Qemu` | `qemu-x86_64` \| `qemu-aarch64` \| `qemu-arm` (`:498-501`) | +| `run_bounded_cancellable` (`:461`) | `Builder` | `cargo` \| `rustc` \| `zig` (`:634-636`) | +| `run_qualification_process` (`:569`) | `Candidate` | must be an **absolute path** (`:637`) | +| `run_qemu_process` (`:580`) | `Qemu` | `qemu-x86_64` \| `qemu-aarch64` \| `qemu-arm` (`:638-640`) | +| `run_git_bounded` (`:512`) | `Git` | exactly `git` (`:641`) | +| `run_interpreter_bounded` (`:485`) | `Interpreter` | exactly `python3` \| `python` (`:642`) | + +The `Interpreter` entry point is the consumer-validator case: it takes an +`InterpreterCommandSpec` (`:203-227`) whose argument vector is OS-native, so a validated +absolute path reaches the interpreter byte-exact, and it observes a caller-owned atomic +cancellation flag (`Cancellation::Flag`, `:143-146`) on the same cadence as the deadline. This is the ADR-0004 adapter restriction enforced at the exec boundary: not a command DSL, -and callers cannot widen the set at runtime. `test :1111-1113` pins it by rewriting the +and callers cannot widen the set at runtime. `test :1278-1284` pins it by rewriting the executable to `sh` and asserting rejection. -**Bound validation** (`:504-513`) rejects the whole call unless the executable is allowed, -`timeout` is non-zero and ≤86 400 s (`:505-506`), and both limits are non-zero and ≤`MAX_OUTPUT` -(`:507-510`). **Process-group control** uses `command_group::CommandGroup` (`:4`): -`group_spawn()` (`:591`) places the child in its own group/job, and `kill()` + `wait()` -(`:614-619`, `:623-628`) terminate the **group**, so build scripts and descendants die with +**Bound validation** (`:644-653`) rejects the whole call unless the executable is allowed, +`timeout` is non-zero and ≤86 400 s (`:645-646`), and both limits are non-zero and ≤ the +runner ceiling `MAX_PROCESS_OUTPUT` (`:647-650`, `:27`). The builder commands keep their own +tighter default of `MAX_OUTPUT` (`:20`). **Process-group control** uses +`command_group::CommandGroup` (`:4`): +`group_spawn()` (`:731`) places the child in its own group/job, and `kill()` + `wait()` +(`:754-759`, `:763-768`) terminate the **group**, so build scripts and descendants die with the driver; termination failure is an error, not a swallowed outcome. The **poll loop** -(`:612-639`, 20 ms granularity at `:638`) tests cancellation **first** (`:613-621` → -`Cancelled`), then the deadline (`:622-630` → `TimedOut`), then child exit (`:631-637`), so -cancellation wins over a concurrent timeout. - -**Bounded capture**: stdout and stderr are taken from the group child (`:529-530`) and -drained on two threads by `drain` (`:607-610`, `:713-729`), which retains at most `limit` bytes and -raises an overflow flag on truncation (`:719-724`). Reader threads are always joined -(`:651-652`, `:698-712`), so nothing is lost before the pipes are read. - -**Contents never returned.** `ProcessEvidence` (`:199-206`) carries only `outcome`, +(`:752-791`, 20 ms granularity at `:790`) tests cancellation **first** (`:753-761` → +`Cancelled`), then the deadline (`:762-770` → `TimedOut`), then the **output bound** +(`:771-782` → `OutputLimitExceeded`), then child exit (`:783-789`), so cancellation wins +over a concurrent timeout. + +**Prompt output-limit detection.** `stream_over_limit` (`:876-878`) reads the same flag the +drain thread sets, so an over-limit stream is noticed at the moment of excess and the whole +group is terminated then (`:774-782`) instead of at the deadline. This was the CI validator's +own behaviour and it is now the shared runner's. The observable outcome is unchanged +(`OutputLimitExceeded`); only the moment of termination moves earlier. + +**Bounded capture**: stdout and stderr are taken from the group child (`:669-670`) and +drained on two threads by `drain` (`:747-750`, `:880-896`), which retains at most `limit` bytes and +raises an overflow flag on truncation (`:886-891`). Reader threads are joined under a bounded +budget (`:803-804`, `:856-879`), so a descendant that inherited a pipe cannot park the run +past the caller's deadline; a reader still parked at its budget is detached and the run is +failed closed — and the group is then terminated (`:805-811`), so the descendant that held +the pipe does not outlive the run either. + +**Contents never returned.** `ProcessEvidence` (`:256-263`) carries only `outcome`, `stdout_bytes`, `stderr_bytes` — counts, never bytes. The captured buffers are local to -`run_bounded_inner` and dropped at return (`:657-664`), which is what lets -`expected_stdout` be checked internally (`:665-671`) without becoming a side channel, so a +`run_bounded` and dropped at return (`:816-823`), which is what lets +`expected_stdout` be checked internally (`:824-829`) without becoming a side channel, so a failure is diagnosable only by outcome and counts. -**Outcome classification** (`:672-684`), in precedence order: `TimedOut` → `Cancelled` → -`OutputLimitExceeded` → `Failed(-1)` when an `expected_stdout` substring is absent -(`:678-679`) → `Success` → `Failed(status.code().unwrap_or(-1))`. A signal-terminated child +**Outcome classification** (`:830-842`), in precedence order: `TimedOut` → `Cancelled` → +`OutputLimitExceeded` (over-limit, or a reader still parked at its budget) → +`Failed(-1)` when an `expected_stdout` substring is absent +(`:836-837`) → `Success` → `Failed(status.code().unwrap_or(-1))`. A signal-terminated child also lands on `-1`, so a missing substring is indistinguishable from signal death. The timeout/cancel path re-reads status after `wait()` and fails closed if unavailable -(`process cleanup incomplete`, `:653-656`). `BuildCancellation` (`:182`) is a `Clone` handle -over `Arc` whose `cancel()` is `SeqCst` and idempotent (`:183-198`). +(`process cleanup incomplete`, `:812-815`). `BuildCancellation` (`:239`) is a `Clone` handle +over `Arc` whose `cancel()` is `SeqCst` and idempotent (`:240-255`). ## Environment handling and Windows requirements -`env_clear()` (`:527`) is unconditional: the child starts from an empty environment, -re-populated only from a fixed allowlist. `stdin` is `Stdio::null()` (`:528`), so a child +`env_clear()` (`:667`) is unconditional: the child starts from an empty environment, +re-populated only from a fixed allowlist. `stdin` is `Stdio::null()` (`:668`), so a child can never block on input or prompt. The `Candidate` and `Qemu` allowances get `PATH`, -`SystemRoot`, `WINDIR`, `TEMP`, `TMP` (`:546`); `Builder` gets those five plus `HOME`, +`SystemRoot`, `WINDIR`, `TEMP`, `TMP` (`:686`); `Builder` gets those five plus `HOME`, `USERPROFILE`, `CARGO_HOME`, `RUSTUP_HOME`, `LIB`, `LIBPATH`, `INCLUDE`, `VCToolsInstallDir`, `VisualStudioVersion`, `VCINSTALLDIR`, `WindowsSdkDir`, `WindowsSDKVersion`, -`UniversalCRTSdkDir`, and `UCRTVersion` (`:548-568`). Each key is copied only if present in -the parent (`:571-575`); the rustup and MSVC homes are needed because `cargo`/`rustup` -resolve toolchains and the linker through them. `spec.env` is applied last (`:589`), so the +`UniversalCRTSdkDir`, and `UCRTVersion` (`:688-708`). Each key is copied only if present in +the parent (`:711-715`); the rustup and MSVC homes are needed because `cargo`/`rustup` +resolve toolchains and the linker through them. `spec.env` is applied last (`:729`), so the module's own override — in practice only `CARGO_TARGET_DIR` — wins. **Windows Cargo builds require an already-initialized MSVC environment.** This module neither provisions nor validates one; it only preserves one. On `#[cfg(windows)]`, when `VCToolsInstallDir` is set, `$VCToolsInstallDir/bin/Hostx64/x64` is prepended to `PATH` -(`:576-588`) so `link.exe` resolves from the active VCTools instance. If the environment was +(`:716-728`) so `link.exe` resolves from the active VCTools instance. If the environment was never initialized, those keys are simply absent, `cargo` cannot find a linker, and the failure surfaces as a bounded non-`Success` `ProcessEvidence` (`Failed(code)`) or, if the toolchain -itself is unreachable, as `configured Rust toolchain preflight failed` (`:754-756`) — never as +itself is unreachable, as `configured Rust toolchain preflight failed` (`:921-923`) — never as captured linker diagnostics, since output contents are not returned. The obligation is met outside this crate: CI uses `ilammy/msvc-dev-cmd@v1` and asserts `link.exe` resolves under -`VCToolsInstallDir` (`.github/workflows/ci.yml:44-56`). On naming, `discover_candidate` -appends `.exe` when the triple contains the `-windows-` component (`:1015-1019`). +`VCToolsInstallDir` (`.github/workflows/ci.yml:52-64`). On naming, `discover_candidate` +appends `.exe` when the triple contains the `-windows-` component (`:1182-1186`). The match is anchored on that component rather than a bare `windows` substring, so a hypothetical `x86_64-unknown-notwindowsish` triple does not pick up a Windows suffix; and the suffix is appended to the whole binary name via `set_file_name`, so a dotted name such as `tool.cli` resolves to `tool.cli.exe` as Cargo produces it, not to the truncating `tool.exe` that `set_extension` -would have yielded. `valid_identifier` (`:326-331`) admits `.`, so this case is +would have yielded. `valid_identifier` (`:383-388`) admits `.`, so this case is reachable rather than hypothetical. ## Candidate discovery and private target directories -`private_target_dir` (`:951-992`) establishes per-invocation storage isolation: +`private_target_dir` (`:1118-1159`) establishes per-invocation storage isolation: `work_root` must be absolute and must pre-exist as a real directory, and a symlink work -root is rejected (`:956-969`). The name is `{safe(invocation)}-{safe(target)}` (`:972`), -where `safe_component` (`:993-1003`) maps every character outside `[A-Za-z0-9_-]` to `_`, so +root is rejected (`:1123-1136`). The name is `{safe(invocation)}-{safe(target)}` (`:1139`), +where `safe_component` (`:1160-1170`) maps every character outside `[A-Za-z0-9_-]` to `_`, so no caller string can traverse or inject a path; `invocation` is bounded to ≤128 bytes -(`:957-958`). `create_dir` makes an existing path a hard error, so invocations are private -rather than reused (`:974-980`); the created path is then re-canonicalized and must stay +(`:1124-1125`). `create_dir` makes an existing path a hard error, so invocations are private +rather than reused (`:1141-1147`); the created path is then re-canonicalized and must stay under the canonicalized work root, which is defence against a pre-existing symlink inside -the root (`:981-985`). A `.eggpack-owner` marker records `1\n\n\n` -(`:986-990`). +the root (`:1148-1152`). A `.eggpack-owner` marker records `1\n\n\n` +(`:1153-1157`). -The function is **not** pure: it mutates the filesystem. It returns `/target` (`:991`), +The function is **not** pure: it mutates the filesystem. It returns `/target` (`:1158`), the directory handed to Cargo as `CARGO_TARGET_DIR`; the marker lives in the parent, not in -the returned path, which `execute_target_cancellable` then creates explicitly (`:876-878`) -and passes to `cargo_command` (`:886-892`). Isolation provided: no ambient or shared Cargo +the returned path, which `execute_target_cancellable` then creates explicitly (`:1043-1045`) +and passes to `cargo_command` (`:1053-1059`). Isolation provided: no ambient or shared Cargo target directory is ever written, so builds cannot contaminate one another or the caller's tree. -`discover_candidate` (`:1006-1047`) resolves exactly one path, -`//release/[.exe]` (`:1014-1019`) and validates before trusting -it: `binary` must be a valid identifier (`:1011-1013`); the entry must exist as a **non-empty -regular file, not a symlink** (`symlink_metadata` plus type and length checks, `:1020-1024`); -the canonicalized file must be contained in the canonicalized target directory (`:1025-1031`), +`discover_candidate` (`:1173-1214`) resolves exactly one path, +`//release/[.exe]` (`:1181-1186`) and validates before trusting +it: `binary` must be a valid identifier (`:1178-1180`); the entry must exist as a **non-empty +regular file, not a symlink** (`symlink_metadata` plus type and length checks, `:1187-1191`); +the canonicalized file must be contained in the canonicalized target directory (`:1192-1198`), since the symlink check alone would not stop a hardlink or a raced path; and both parents -(`` and `release`) must be real directories, not symlinks (`:1032-1045`). +(`` and `release`) must be real directories, not symlinks (`:1199-1212`). -It returns `(path, metadata.len())` (`:1046`); nothing is read or hashed here, so the `size` on -`CandidateArtifact` (`:222`) is metadata only. A `CandidateArtifact` (`:210-223`) is bytes +It returns `(path, metadata.len())` (`:1213`); nothing is read or hashed here, so the `size` on +`CandidateArtifact` (`:279`) is metadata only. A `CandidateArtifact` (`:267-280`) is bytes plus identity (target, slot, package, binary); the build stage never installs, archives, publishes, or authenticates. @@ -201,28 +222,29 @@ Paths are `crates/eggpack-core/src/builder.rs` unless noted. | Line | Item | Note | | --- | --- | --- | -| `:18-19` | `MAX_OUTPUT` | `256 * 1024`; ceiling on each captured stream | -| `:43` | `ensure_candidate_executable` | private; unix-only; `mode \|= 0o111` on a non-symlink regular file (mode is not part of recorded size/digest) | -| `:68` `:86` `:98` | `LogicalOutputSelector`, `BuildBinding`, `BuildBindingsV1` | slot / slot+package+bin / strict version-1 document | -| `:107` `:114` | `BuildError`, `build_err` | `Display` + `Error`; fixed internal message only, never process text | -| `:119` `:128` `:154` | `ExecutableAllowance`, `CommandSpec`, `BoundCommand` | `ExecutableAllowance` private; **`BoundCommand` is declared public but never constructed anywhere in the workspace** | -| `:167` `:182` `:199` | `CommandOutcome`, `BuildCancellation`, `ProcessEvidence` | `BuildCancellation` = `Clone` `Arc`, `new` `:185` / `cancel` `:189` / `is_cancelled` `:192` | -| `:210` `:227` | `CandidateArtifact`, `BuildAttempt` | the two public result types | -| `:246` `:252` `:284` `:326` | `from_toml`, `validate_shape`, `validate_for`, `valid_identifier` | first two private; `[A-Za-z0-9_.-]`, ≤128 bytes | -| `:334` `:732` | `cargo_command`, `preflight` | `preflight` private | -| `:405` `:474` `:481` `:488` `:713` | `run_bounded_cancellable`, `run_qualification_process`, `run_qemu_process`, `run_bounded_inner`, `drain` | the middle two are `pub(crate)`; `run_bounded_inner` private and holds all enforcement | -| `:832` `:852` `:951` `:993` `:1006` | `execute_target`, `execute_target_cancellable`, `private_target_dir`, `safe_component`, `discover_candidate` | `safe_component` private | - -**Tests (`:1050-1734`):** explicit non-shell command and `sh` rejection (`:1080-1114`); zigbuild -glibc rewrite and macOS-floor rejection (`:1116-1157`) plus the byte-unchanged regression pin for -the triple rewrite and the macOS-under-zigbuild refusal (`:1159-1223`); binding duplicate and -unknown-field rejection (`:1225-1238`); exact direct-slot coverage (`:1240-1269`); candidate -regularity and non-emptiness (`:1271-1286`); relative and reused work roots rejected -(`:1415-1421`); bounded output, nonzero exit, and overflow classified `OutputLimitExceeded` -(`:1423-1489`); timeout and cancellation each killing and waiting for a real Cargo build -script over three iterations (`:1491-1619`), plus the parked-descendant and parked-reader -cases (`:1621-1676`); a real local Cargo fixture producing a direct candidate -(`:1678-1734`). +| `:20-28` | `MAX_OUTPUT`, `MAX_PROCESS_OUTPUT` | `256 * 1024` builder default; `8 MiB` runner ceiling | +| `:51` | `ensure_candidate_executable` | private; unix-only; `mode \|= 0o111` on a non-symlink regular file (mode is not part of recorded size/digest) | +| `:76` `:94` `:106` | `LogicalOutputSelector`, `BuildBinding`, `BuildBindingsV1` | slot / slot+package+bin / strict version-1 document | +| `:115` `:122` | `BuildError`, `build_err` | `Display` + `Error`; fixed internal message only, never process text | +| `:127` `:160` `:186` | `ExecutableAllowance`, `CommandSpec`, `BoundCommand` | `ExecutableAllowance` private; **`BoundCommand` is declared public but never constructed anywhere in the workspace** | +| `:224` `:239` `:256` | `CommandOutcome`, `BuildCancellation`, `ProcessEvidence` | `BuildCancellation` = `Clone` `Arc`, `new` `:242` / `cancel` `:246` / `is_cancelled` `:249` | +| `:267` `:284` | `CandidateArtifact`, `BuildAttempt` | the two public result types | +| `:303` `:309` `:341` `:383` | `from_toml`, `validate_shape`, `validate_for`, `valid_identifier` | first two private; `[A-Za-z0-9_.-]`, ≤128 bytes | +| `:391` `:899` | `cargo_command`, `preflight` | `preflight` private | +| `:461` `:485` `:569` `:580` `:608` `:628` `:880` | `run_bounded_cancellable`, `run_interpreter_bounded`, `run_qualification_process`, `run_qemu_process`, `run_bounded_inner`, `run_bounded`, `drain` | the middle two are `pub(crate)`; `run_bounded_inner` and `run_bounded` are private and hold all enforcement | +| `:203` `:127` `:143` | `InterpreterCommandSpec`, `ExecutableAllowance`, `Cancellation` | the interpreter spec carries OS-native arguments | +| `:999` `:1019` `:1118` `:1160` `:1173` | `execute_target`, `execute_target_cancellable`, `private_target_dir`, `safe_component`, `discover_candidate` | `safe_component` private | + +**Tests (`:1217-1902`):** explicit non-shell command and `sh` rejection (`:1247-1284`); zigbuild +glibc rewrite and macOS-floor rejection (`:1286-1327`) plus the byte-unchanged regression pin for +the triple rewrite and the macOS-under-zigbuild refusal (`:1329-1393`); binding duplicate and +unknown-field rejection (`:1395-1408`); exact direct-slot coverage (`:1410-1439`); candidate +regularity and non-emptiness (`:1441-1456`); relative and reused work roots rejected +(`:1585-1591`); bounded output, nonzero exit, and overflow classified `OutputLimitExceeded` +(`:1593-1660`); timeout and cancellation each killing and waiting for a real Cargo build +script over three iterations (`:1662-1790`), plus the parked-descendant and parked-reader +cases (`:1792-1848`); a real local Cargo fixture producing a direct candidate +(`:1847-1902`). ## Boundaries / non-goals @@ -230,26 +252,26 @@ cases (`:1621-1676`); a real local Cargo fixture producing a direct candidate not qualification; `qualification.rs` owns that) and **does not finalize** (no contract-named copying, archiving, manifest aggregation, or `release-manifest.json`). - **Does not touch the network directly** — but it also does not forbid the child from - reaching it. `cargo_command` passes `--locked`, not `--offline` (`:348-356`); the in-file - fixture test adds `--offline` explicitly (`:1512`), which production does not. + reaching it. `cargo_command` passes `--locked`, not `--offline` (`:405-413`); the in-file + fixture test adds `--offline` explicitly (`:1683`), which production does not. - **No shell and no generic command DSL.** Executable and argv are separate OS arguments, and the executable set is a closed per-allowance enumeration checked at spawn - (`:493-513`), per ADR-0004. A `CommandSpec` is a description, not an interpreter; there + (`:633-653`), per ADR-0004. A `CommandSpec` is a description, not an interpreter; there is no plugin or scripting seam. -- **No binding-coverage validation inside the build path.** `validate_for` (`:284`) is +- **No binding-coverage validation inside the build path.** `validate_for` (`:341`) is caller-invoked; `execute_target_cancellable` validates only plan membership, - `schema_version == 1`, and non-empty `release_id` / `source_revision` (`:861-869`). An + `schema_version == 1`, and non-empty `release_id` / `source_revision` (`:1028-1036`). An empty `bindings` slice therefore yields `Ok(BuildAttempt)` whose `process.outcome` is the - `Success` initializer (`:880-884`) with zero candidates. + `Success` initializer (`:1047-1051`) with zero candidates. - **No output evidence** (failures are not diagnosable from captured text, by design), no cross-tool provisioning (`preflight` requires declared versions to be present; it does not install them), and no archive encoding, extraction, publication, signing, or install. ## Dependencies / dependents -- Own dependencies used here: `command-group 5.0.1` (`Cargo.toml:21`, process groups), `toml - 0.8` (`Cargo.toml:20`, `from_toml` at `builder.rs:246`), `serde` derive (`Cargo.toml:17`), - `eggpack-contract` (`Cargo.toml:15`, `DistributionContract` + `ExpandedAssets` at +- Own dependencies used here: `command-group 5.0.1` (`Cargo.toml:30`, process groups), `toml + 0.8` (`Cargo.toml:29`, `from_toml` at `builder.rs:303`), `serde` derive (`Cargo.toml:18`), + `eggpack-contract` (`Cargo.toml:16`, `DistributionContract` + `ExpandedAssets` at `builder.rs:5`), and `std` process/thread/IO primitives. `sha2` is a **crate-level** dependency but is not used in this file (it is used by the digest authority in `src/digest.rs`). @@ -258,7 +280,7 @@ cases (`:1621-1676`); a real local Cargo fixture producing a direct candidate and `BuildCancellation`; `finalization.rs:4` imports `BuildAttempt`, `CandidateArtifact`, and `LogicalOutputSelector`. - External dependents: `eggpack-ci` calls `cargo_command` to render the build command into - generated workflows and its drift check (`eggpack-ci/src/lib.rs:164`, `:348`), and + generated workflows and its drift check (`eggpack-ci/src/lib.rs:221`, `:405`), and reconstructs `BuildAttempt` / `CandidateArtifact` in memory from CI handoff data rather than executing a build (`eggpack-ci/src/lib.rs:2010`, `:2034`). `eggpack-github` and `eggpack-cli` depend on `eggpack-core` transitively. diff --git a/architecture/overview.md b/architecture/overview.md index 9625426..0b90021 100644 --- a/architecture/overview.md +++ b/architecture/overview.md @@ -323,9 +323,9 @@ These are the review units that cut across crates. Each has a dedicated file. - **Safety:** `#![forbid(unsafe_code)]` workspace-wide (`unsafe_code = "deny"`), no shell interpretation of generated inputs, bounded process execution with timeouts/output limits/cancellation, environment allowlists, symlink - rejection on output paths. No production spawn site is unbounded: `core` and - `cli` share one bounded runner, and `ci`'s independent reimplementation is the - only site without process-group kill. + rejection on output paths. No production spawn site is unbounded: `core`, + `cli`, and `ci` share one bounded runner, and every supervised process is + terminated as a process group or job object. ## Review paths diff --git a/architecture/process-execution.md b/architecture/process-execution.md index 1d6fd9e..fd9a53f 100644 --- a/architecture/process-execution.md +++ b/architecture/process-execution.md @@ -3,61 +3,66 @@ This is the cross-cutting contract for spawning external tools in the Eggpack workspace: bounded wall time, whole-group termination, capped output, a cleared environment with a small allowlist, and captured output that never crosses the -API boundary. The contract is implemented in more than one crate, and the -implementations are not equivalent. +API boundary. The contract has one implementation: `eggpack-core` owns the +bounded runner, and `eggpack-cli` and `eggpack-ci` both delegate to it. No +production spawn site is unbounded. ## Where external processes are spawned -There are exactly two production execution implementations. `eggpack-core` owns -the bounded runner and `eggpack-cli` delegates to it, so the two share one; -`eggpack-ci` carries a fully independent reimplementation. No production spawn -site is unbounded. +There is exactly one production execution implementation. `eggpack-core` owns +the bounded runner; `eggpack-cli` and `eggpack-ci` call into it, so all three +share one set of guarantees. | Site | Entry point | Spawn call | Deadline | Group handling | Environment | | --- | --- | --- | --- | --- | --- | -| Core build + preflight | `run_bounded_cancellable` (`crates/eggpack-core/src/builder.rs:381`) | `group_spawn()` at `builder.rs:533` | `spec.timeout`, ≤ 86 400 s (`builder.rs:448`) | `command-group` group/job, `kill()` + `wait()` (`builder.rs:556-571`) | `env_clear()` + 20-var allowlist (`builder.rs:469`, `490-511`) | -| Core qualification smoke (native) | `run_qualification_process` (`builder.rs:416`) | same `run_bounded_inner` | `smoke.timeout_ms` | same shared path | narrower 5-var allowlist (`builder.rs:487-488`) | -| Core qualification smoke (QEMU) | `run_qemu_process` (`builder.rs:423`) | same `run_bounded_inner` | `smoke.timeout_ms` | same shared path | narrower 5-var allowlist | -| Core git revision verification | `run_git_bounded` (`builder.rs:393`) | same `run_bounded_inner` | 30 s (`GIT_TIMEOUT`, `builder.rs:20`) | same shared path | 7-var allowlist incl. `HOME` (`builder.rs:473-485`) | +| Core build + preflight | `run_bounded_cancellable` (`crates/eggpack-core/src/builder.rs:461`) | `group_spawn()` at `builder.rs:731` | `spec.timeout`, ≤ 86 400 s (`builder.rs:646`) | `command-group` group/job, `kill()` + `wait()` (`builder.rs:754-768`) | `env_clear()` + 20-var allowlist (`builder.rs:667`, `687-710`) | +| Core qualification smoke (native) | `run_qualification_process` (`builder.rs:569`) | same `run_bounded` | `smoke.timeout_ms` | same shared path | narrower 5-var allowlist (`builder.rs:685-686`) | +| Core qualification smoke (QEMU) | `run_qemu_process` (`builder.rs:580`) | same `run_bounded` | `smoke.timeout_ms` | same shared path | narrower 5-var allowlist | +| Core git revision verification | `run_git_bounded` (`builder.rs:512`) | same `run_bounded` | 30 s (`GIT_TIMEOUT`, `builder.rs:29`) | same shared path | 7-var allowlist incl. `HOME` (`builder.rs:675-684`) | | CLI source verification | `verify_source_revision` (`crates/eggpack-cli/src/main.rs:71`) | delegates to `run_git_bounded` | same 30 s | same shared path | same 7-var allowlist | -| CI consumer validator | `run_consumer_validator` (`crates/eggpack-ci/src/lib.rs4153`) → `run_validator_process` (`lib.rs:4627`) | `command.spawn()` at `lib.rs:4640` | `validator.timeout_ms`, 1 000–600 000 ms (`lib.rs:3919`) | **none** — `Child::kill()` only (`lib.rs:4667`, `4672`, `4680`, `4687`) | `env_clear()` + `PATH` (+ `SYSTEMROOT` on Windows) (`lib.rs:4349-4356`) | -| CI interpreter preflight | `run_interpreter_preflight` (`lib.rs:4374`) | `command.spawn()` at `lib.rs:4380` | `timeout_ms.min(30_000)` (`lib.rs:4389`) | **none** — `Child::kill()` at `lib.rs:4395` | same as above | +| CI consumer validator | `run_consumer_validator` (`crates/eggpack-ci/src/lib.rs:4468`) → `run_validator_process` (`lib.rs:4892`) | delegates to `run_interpreter_bounded` (`builder.rs:485`) | `validator.timeout_ms`, 1 000–600 000 ms (`lib.rs:4232`) | same shared path — group/job kill on every failure path | same narrow 5-var allowlist, plus the caller's explicit `PATH` override (`lib.rs:4444-4445`) | +| CI interpreter preflight | `run_interpreter_preflight` (`lib.rs:4633`) | delegates to `run_interpreter_bounded` | `timeout_ms.min(30_000)` (`lib.rs:4644`) | same shared path | same as above | ### What is shared and what is independent -The four `eggpack-core` entry points are thin wrappers over one private -function, `run_bounded_inner` (`builder.rs:430`), differing only in the -`ExecutableAllowance` passed: `Builder` (`builder.rs:385`), `Candidate` -(`builder.rs:420`), `Qemu` (`builder.rs:427`), `Git` (`builder.rs:413`). One -implementation, one place to audit, one set of guarantees. The allowance is what -keeps the set narrow: `Git` admits only the literal `git` (`builder.rs:444`), -exactly as `Qemu` admits only the three named QEMU binaries. - -`eggpack-ci` does **not** share it. `crates/eggpack-ci/Cargo.toml` declares no -`command-group` dependency, and the validator uses `std::process::Command` -directly (`lib.rs:4345`, `4380`, `4640`), reimplementing bounds checking, output -capping, the poll loop, and the kill path. It matches the core contract on -timeout bounds, output bounds, null stdin, environment clearing, and wait-after- -kill; it does not match on process groups. This is the largest risk difference in -the workspace: a reimplementation that will not fail a compile-time or test-time -check when core's contract drifts. +The five `eggpack-core` entry points are thin wrappers over one private +function, `run_bounded` (`builder.rs:628`), reached through `run_bounded_inner` +(`builder.rs:608`), differing only in the `ExecutableAllowance` passed: +`Builder` (`builder.rs:128`), `Candidate`, `Qemu`, `Git`, and `Interpreter` +(`builder.rs:132`). One implementation, one place to audit, one set of +guarantees. The allowance is what keeps the set narrow: `Git` admits only the +literal `git` (`builder.rs:641`), exactly as `Qemu` admits only the three named +QEMU binaries and `Interpreter` admits only `python3` and `python` +(`builder.rs:642`). + +`eggpack-ci` shares it. The crate still declares no `command-group` +dependency; it reaches the runner through `eggpack-core`, which already owns +it. The consumer validator builds an `InterpreterCommandSpec` +(`builder.rs:203`) — the interpreter name, an OS-native argument vector, the +working directory, the explicit environment overrides, the deadline, the output +bounds, and the optional version substring — and calls `run_interpreter_bounded` +(`builder.rs:485`). The interpreter argv is OS-native so a validated absolute +path reaches the interpreter byte-exact. Everything else — bounds checking, +output capping, the poll loop, the group kill, the bounded reader joins, and +the environment allowlist — is the shared implementation, so the crate cannot +drift from the core contract without failing a compile-time check. The CLI `git` invocation no longer diverges. `verify_source_revision` (`main.rs:71`) validates the expected object name, then delegates to -`eggpack_core::run_git_bounded` (`builder.rs:393`) and reads only the resulting +`eggpack_core::run_git_bounded` (`builder.rs:512`) and reads only the resulting `CommandOutcome`. It inherits the deadline, the process group, the environment clear, and the output cap, and it never receives captured bytes. The runner matches an exact expected value internally rather than returning it. `CommandSpec::expected_stdout` is a substring containment check, which is right -for a tool banner (`builder.rs:128`) but too weak for a revision identity; the -new `expected_stdout_exact` field (`builder.rs:134`) compares the trimmed stdout -for equality (`builder.rs:596-602`), and a miss becomes -`CommandOutcome::Failed(-1)` (`builder.rs:610`) rather than an error carrying +for a tool banner (`builder.rs:175-176`) but too weak for a revision identity; the +new `expected_stdout_exact` field (`builder.rs:177-181`) compares the trimmed stdout +for equality (`builder.rs:824-829`), and a miss becomes +`CommandOutcome::Failed(-1)` (`builder.rs:836-837`) rather than an error carrying output. The Git allowlist deliberately keeps `HOME` and `USERPROFILE` -(`builder.rs:479-480`) that the narrower candidate and QEMU allowlists drop. +(`builder.rs:677-678`) that the narrower candidate and QEMU allowlists drop. `git` resolves helpers from `PATH`, and `safe.directory` is commonly set in the global config; clearing `HOME` would make self-hosted runners fail closed for a reason unrelated to release integrity. @@ -77,7 +82,7 @@ the job's build directory. The workspace therefore never uses bare `Child::kill` on a build or qualification path; it uses `command-group` 5.0.1 (`crates/eggpack-core/Cargo.toml:22`, pinned in `Cargo.lock:61-64`). -`group_spawn()` (`builder.rs533`) returns a `GroupChild` owning a group/job with +`group_spawn()` (`builder.rs:731`) returns a `GroupChild` owning a group/job with two different implementations: - **Unix:** the child is spawned with `process_group(0)`, i.e. `setpgid(0, 0)`, @@ -91,69 +96,73 @@ two different implementations: Killing is not enough. The group must then be *waited for*, twice over. In the timeout and cancellation branches, `kill()` is immediately followed by `wait()` -(`builder.rs559-561` for cancellation, `builder.rs568-570` for the deadline). On +(`builder.rs:754-759` for cancellation, `builder.rs:763-768` for the deadline). On Unix that `wait()` loops `waitpid` over the negated pgid precisely so that already-exited group members are reaped rather than left as zombies (`command-group` `src/stdlib/child/unix.rs:71-78`); on Windows it drains the job completion port with `INFINITE` before waiting on the child (`src/stdlib/child/windows.rs:97-99`). Second, after the loop breaks, `run_bounded_inner` requires a final `try_wait()` to return `Some`; a `None` is -the error `process cleanup incomplete` (`builder.rs584-587`). Skipping either +the error `process cleanup incomplete` (`builder.rs:812-815`). Skipping either wait is what leaves orphans and zombies behind a timeout, and both are present. -The CI validator waits after killing (`lib.rs:4394`, `4666`, `4671`, `4679`, -`4686`) but only reaps the direct child, because it never created a group. +The CI validator creates no group of its own: it delegates to the shared +runner, which creates the group or job object and kills and waits for it. ## Timeouts and cancellation `run_bounded_inner` validates its own bounds before spawning and fails closed -with `invalid process bounds or executable` (`builder.rs446-455`): timeout must +with `invalid process bounds or executable` (`builder.rs:644-653`): timeout must be non-zero and at most 86 400 s, and both output limits must be in `1..=MAX_OUTPUT` -where `MAX_OUTPUT = 256 * 1024` (`builder.rs:18`). +where `MAX_OUTPUT = 256 * 1024` (`builder.rs:20`). -The deadline is `Instant::now() + spec.timeout` (`builder.rs553`) enforced by a -poll loop (`builder.rs554-581`), not a blocking wait: each iteration calls -`child.try_wait()` (`builder.rs573-576`) and sleeps 20 ms (`builder.rs580`). +The deadline is `Instant::now() + spec.timeout` (`builder.rs:751`) enforced by a +poll loop (`builder.rs:752-791`), not a blocking wait: each iteration calls +`child.try_wait()` (`builder.rs:783-788`) and sleeps 20 ms (`builder.rs:790`). Polling is what makes cancellation observable at all — a blocking `wait()` would only notice a flag after the child had already exited. Ordering inside the loop is the contract. Cancellation is tested first -(`builder.rs555`), the deadline second (`builder.rs564`), exit status last. When -both apply in the same iteration, the run breaks with `(false, true)` and is -classified `Cancelled` (`builder.rs562`, `549`). A cancelled build therefore never -reports as timed out. The CI validator uses the same precedence: cancellation at -`lib.rs:4661`, over-limit at `4669`, deadline at `4677`, each returning its own -typed failure. A pre-loop cancellation check also exists in -`qualification.rs832-843`, so a cancelled qualification does not spawn at all. - -Timeouts in use: builds get 1800 s (`builder.rs797`); toolchain preflights get -10 s each (`builder.rs655`, `617`, `646`, `662`); the QEMU emulator preflight -gets 10 s (`qualification.rs:792`); smoke runs get `smoke.timeout_ms` bounded to +(`builder.rs:753`), the deadline second (`builder.rs:762`), the output bound +third (`builder.rs:771`), exit status last (`builder.rs:783`). When cancellation +and the deadline apply in the same iteration, the run breaks with +`(false, true, false)` and is classified `Cancelled` (`builder.rs:760`, +`builder.rs:232`). A cancelled build therefore never reports as timed out, and +an over-limit run is reported as an output-limit failure rather than as a build +failure. The CI validator inherits that precedence unchanged and maps each +runner outcome onto its own typed failure. A pre-loop cancellation check also +exists in `qualification.rs832-843`, so a cancelled qualification does not spawn +at all. + +Timeouts in use: builds get 1800 s (`builder.rs:1058`); toolchain preflights get +10 s each (`builder.rs:913`, `builder.rs:933`, `builder.rs:963`, +`builder.rs:982`); the QEMU emulator preflight gets 10 s +(`qualification.rs:792`); smoke runs get `smoke.timeout_ms` bounded to `1..=86_400_000` (`qualification.rs:151-152`); CI validator runs get -`1_000..=600_000` ms (`lib.rs:3917`) with the preflight further capped at 30 s -(`lib.rs:4387`). +`1_000..=600_000` ms (`lib.rs:4232`) with the preflight further capped at 30 s +(`lib.rs:4644`). How a timeout reaches the caller: never as an error. `run_bounded_inner` returns -`Ok(ProcessEvidence)` with `CommandOutcome::TimedOut` (`builder.rs603-604`, -enum at `builder.rs152-163`). The build path converts any non-`Success` outcome +`Ok(ProcessEvidence)` with `CommandOutcome::TimedOut` (`builder.rs:830-831`, +enum at `builder.rs:224-235`). The build path converts any non-`Success` outcome into a `BuildAttempt` carrying the evidence and no candidates -(`builder.rs800-810`). A timeout is therefore a recorded, typed, +(`builder.rs:1061-1088`). A timeout is therefore a recorded, typed, non-success *result*, not a raised error — which is what keeps a hung build from looking like a crash. One fidelity caveat in that classification: a failed `expected_stdout` check maps -to `CommandOutcome::Failed(-1)` (`builder.rs609-610`), and a signal-terminated +to `CommandOutcome::Failed(-1)` (`builder.rs:836-837`), and a signal-terminated process also maps to `Failed(-1)` via `status.code().unwrap_or(-1)` -(`builder.rs614`). Callers cannot distinguish a version mismatch from a +(`builder.rs:841`). Callers cannot distinguish a version mismatch from a signal kill by outcome alone. ## Output bounding and the no-output-leak rule Both stdout and stderr are piped and drained by dedicated threads -(`builder.rs470-471`, threads at `builder.rs549` and `498`). `drain` -(`builder.rs622-638`) reads in 8 KiB chunks, keeps at most +(`builder.rs:669-670`, threads at `builder.rs:747` and `498`). `drain` +(`builder.rs:880-896`) reads in 8 KiB chunks, keeps at most `limit - already_captured` bytes, and sets an overflow flag when a chunk does not -fit (`builder.rs629-633`). Oversized output is *dropped*, not buffered to disk +fit (`builder.rs:886-891`). Oversized output is *dropped*, not buffered to disk and not truncated-with-a-tail. Both reader threads are joined before the outcome is computed, under a bounded budget (`join_drained`, `builder.rs`): a reader returns only at pipe EOF, which needs every write end closed, so a descendant @@ -165,29 +174,29 @@ removes a false-success path: a child that exits zero while a descendant holds the pipe used to be reported as a success with incomplete captured output. Overflow is a first-class failure. If either flag is set, the outcome is -`CommandOutcome::OutputLimitExceeded` (`builder.rs607-608`), ranked below +`CommandOutcome::OutputLimitExceeded` (`builder.rs:834-835`), ranked below timeout and cancellation but above exit status — an over-limit run is never reported as a build failure, so an unbounded log flood cannot be mistaken for a compiler error. -The CI validator caps the same way (`read_limited` at `lib.rs:4097`, -`read_limited_stderr` at `lib.rs:4121`) and additionally detects the overflow -*promptly* rather than at the deadline: `take_finished_over` -(`lib.rs:4418-4425`) joins only finished readers, and a completed over-limit -reader kills the run at once (`lib.rs:4671-4675`). Both CI readers compare the bound *before* retaining the chunk -(`lib.rs:4119-4127`), so retained bytes never exceed the configured limit even -transiently, matching `drain`. Both are also joined on every early exit -(`drain_readers`): the child is killed first, so the joins return, and a -detached reader would otherwise keep a pipe alive that nobody drains. +The CI validator used to cap the same way with readers of its own and to detect +the overflow *promptly* rather than at the deadline. It no longer has readers +of its own: the shared `drain` (`builder.rs:880`) does the capping, and the +shared runner detects the overflow promptly — `stream_over_limit` +(`builder.rs:876`) reads the same flag the drain thread sets, and the runner +terminates the whole group at the moment of excess (`builder.rs:771-782`). +That prompt detection was CI's strength and it is now the shared runner's: a +process that exceeds its output bound is killed when it exceeds it, not when +its deadline arrives. The observable outcome is unchanged. The decisive rule is that **captured output contents never cross the API boundary.** `ProcessEvidence` carries only an outcome and two byte counts -(`builder.rs184-189`, constructed at `builder.rs616-620`); it has no output +(`builder.rs:256-263`, constructed at `builder.rs:843-847`); it has no output fields at all. The `expected_stdout` version substring is compared inside -`run_bounded_inner` (`builder.rs:542-545`) and is never stored, logged, or -returned — the field's own doc comment says so (`builder.rs128-129`). +`run_bounded_inner` (`builder.rs:824-829`) and is never stored, logged, or +returned — the field's own doc comment says so (`builder.rs:175-176`). `ConsumerValidationEvidenceV1` is built from identity, interpreter, outcome, -size, and digest only (`lib.rs:4080-4090`). +size, and digest only (`lib.rs:4406-4425`). This is a secrecy rule, not a size optimization. A captured compiler error can contain absolute build paths, environment values, and — on a misconfigured host — @@ -198,14 +207,15 @@ failure text anywhere. ## Environment clearing and the allowlist -Every bounded spawn begins with `env_clear()` (`builder.rs469`; CI at -`lib.rs:4347`). Nothing is inherited implicitly. Each variable is then re-added -only if it is present in the parent (`builder.rs513-517`), and finally the +Every bounded spawn begins with `env_clear()` (`builder.rs:667`); the CI +validator reaches that same call through the shared runner. Nothing is +inherited implicitly. Each variable is then re-added +only if it is present in the parent (`builder.rs:711-715`), and finally the per-spec explicit overrides are applied with `command.envs(&spec.env)` -(`builder.rs531`) — for a build, that is exactly `CARGO_TARGET_DIR` -(`builder.rs361-365`). +(`builder.rs:729`) — for a build, that is exactly `CARGO_TARGET_DIR` +(`builder.rs:442-446`). -The builder allowlist (`builder.rs490-511`): +The builder allowlist (`builder.rs:687-710`): | Variable | Why it is allowed | | --- | --- | @@ -226,7 +236,7 @@ The builder allowlist (`builder.rs490-511`): | `UniversalCRTSdkDir`, `UCRTVersion` | Universal CRT root and version. | Candidate and QEMU runs get a deliberately narrower set — `PATH`, `SystemRoot`, -`WINDIR`, `TEMP`, `TMP` (`builder.rs:433-434`). The untrusted binary being +`WINDIR`, `TEMP`, `TMP` (`builder.rs:685-686`). The untrusted binary being smoke-tested gets no `CARGO_HOME`, no `RUSTUP_HOME`, and no MSVC variables. This is the meaningful containment: a candidate that can observe the toolchain roots learns where the build machine's toolchain lives. @@ -236,25 +246,26 @@ such as `RUSTFLAGS`, `CARGO_BUILD_*`, or a developer's `~/.cargo/config` export does not silently alter a build. That is a determinism property as much as a security one. -The CI validator allowlist is `PATH` always (`lib.rs:4348`) plus `SYSTEMROOT` on -Windows only (`lib.rs:4349-4354`), which CPython needs to locate its runtime. -`PATH` may be replaced wholesale by a caller-supplied directory list -(`lib.rs:4240-4253`), which is what keeps missing-interpreter tests hermetic; -that override is a test-and-fixture facility, and its value is fully -caller-controlled. +The CI validator no longer restates an allowlist. It runs under the narrow +five-variable allowance that the candidate and QEMU runs use — `PATH`, +`SystemRoot`, `WINDIR`, `TEMP`, `TMP` (`builder.rs:685-686`) — which is the +same allowance the interpreter needs to locate its runtime. `PATH` may be +replaced wholesale by a caller-supplied directory list (`lib.rs:4444-4445`), +which is what keeps missing-interpreter tests hermetic; that override is a +test-and-fixture facility, and its value is fully caller-controlled. ## Windows and MSVC eggpack does not provision a Windows C toolchain and does not pretend to. The MSVC variables in the allowlist are *preserved if already present* and otherwise -simply absent (`builder.rs513-516`). Provisioning is the caller's and CI's +simply absent (`builder.rs:711-715`). Provisioning is the caller's and CI's responsibility: `.github/workflows/ci.yml:43-46` runs `ilammy/msvc-dev-cmd@v1` with `arch: x64` before any Windows build, and `ci.yml:47-56` then verifies that `VCToolsInstallDir` is set and that `link.exe` resolves underneath it. The one adjustment eggpack makes is path ordering. On Windows, if -`VCToolsInstallDir` is set, `builder.rs518-530` prepends +`VCToolsInstallDir` is set, `builder.rs:716-728` prepends `%VCToolsInstallDir%/bin/Hostx64/x64` to the copied `PATH`. `env_clear()` has discarded the environment `msvc-dev-cmd` carefully assembled, and this restores the single entry that determines which `link.exe` is used; the wider MSVC @@ -263,25 +274,25 @@ about them. The consequence on an uninitialized Windows host is bounded and quiet. `cargo` is found through `PATH`, finds no `link.exe`, exits non-zero, and the run is recorded -as `CommandOutcome::Failed(code)` (`builder.rs613-614`) — or `Failed(-1)` if the +as `CommandOutcome::Failed(code)` (`builder.rs:840-841`) — or `Failed(-1)` if the tool was signal-terminated. The diagnostic that would explain *why* the link failed stays inside the discarded stderr buffer: only `stderr_bytes` is reported -(`builder.rs619`). An operator sees "build failed, N bytes of stderr", and the +(`builder.rs:846`). An operator sees "build failed, N bytes of stderr", and the missing-environment diagnosis has to come from the CI step that checks for it, not from the captured linker output. ## The executable allowlist (ADR-0004 boundary) -`ExecutableAllowance` (`builder.rs103-109`) is the per-strategy restriction on -what may be executed. It is evaluated at `builder.rs435-455`, *before* any +`ExecutableAllowance` (`builder.rs:127-132`) is the per-strategy restriction on +what may be executed. It is evaluated at `builder.rs:633-643`, *before* any `Command` is constructed, and a non-matching executable is rejected with -`invalid process bounds or executable` (`builder.rs446-454`). +`invalid process bounds or executable` (`builder.rs:644-653`). | Allowance | Permitted executable | Enforcement | | --- | --- | --- | -| `Builder` | exactly `cargo`, `rustc`, or `zig` | `matches!(spec.executable.as_str(), ...)` (`builder.rs437`) | -| `Candidate` | any **absolute** path, which must then be made executable | `Path::new(&spec.executable).is_absolute()` (`builder.rs439`) | -| `Qemu` | exactly `qemu-x86_64`, `qemu-aarch64`, or `qemu-arm` | `matches!(...)` (`builder.rs440-443`) | +| `Builder` | exactly `cargo`, `rustc`, or `zig` | `matches!(spec.executable.as_str(), ...)` (`builder.rs:634-636`) | +| `Candidate` | any **absolute** path, which must then be made executable | `Path::new(&spec.executable).is_absolute()` (`builder.rs:637`) | +| `Qemu` | exactly `qemu-x86_64`, `qemu-aarch64`, or `qemu-arm` | `matches!(...)` (`builder.rs:638-640`) | This is the enforcement point for ADR-0004's rejection of a generic shell DSL and of a "run whatever" escape hatch (`architecture/principles-roadmap.md:94-98`). @@ -301,32 +312,34 @@ executable is `candidate.path` from a discovered candidate artifact (`qualification.rs860-861`), which was itself produced by a bounded build, re-verified, and made executable. So the candidate allowance trusts a path's origin, not its name. That is a deliberate difference in mechanism, and it is -why `ensure_candidate_executable` runs at `builder.rs460-464` and a failure +why `ensure_candidate_executable` runs at `builder.rs:658-662` and a failure there is a build error rather than a spawn. -The CI side closes the same hole by construction rather than by allowlist. The -interpreter is a single-variant enum, `ValidatorInterpreterV1::Python3`, and -anything else is rejected (`lib.rs:3913-3915`); `python_interpreter_exe` -(`lib.rs:4032`) maps it to `python3` or `python` by host -(`lib.rs:4037-4042`). The argv is then fixed at exactly two arguments — script -path, candidate path — or one `--version` (`lib.rs:4359-4368`). There is no -field in `ConsumerValidatorV1` for a caller-chosen executable, so there is -nothing for an allowlist to filter. +The CI side closes the same hole twice over. The interpreter is a +single-variant enum, `ValidatorInterpreterV1::Python3`, and anything else is +rejected; `python_interpreter_exe` (`lib.rs:4364`) maps it to `python3` or +`python` by host (`lib.rs:4369`). The argv is then fixed at exactly two +arguments — script path, candidate path — or one `--version` (`lib.rs:4642`, +`lib.rs:4901-4904`). There is no field in `ConsumerValidatorV1` for a +caller-chosen executable. And the shared runner enforces the allowance anyway: +the `Interpreter` allowance (`builder.rs:132`) admits only `python3` and +`python`, so a spec that named anything else is refused before any `Command` is +constructed. ## Preflight checks and their strength -`preflight` (`builder.rs641-735`) runs before any build, called from -`execute_target_cancellable` at `builder.rs781`. The checks are not of uniform +`preflight` (`builder.rs:899-997`) runs before any build, called from +`execute_target_cancellable` at `builder.rs:1042`. The checks are not of uniform strength, and stating otherwise would misrepresent the guarantee. | Tool | Command | `expected_stdout` | Strength | | --- | --- | --- | --- | -| `rustc` | `+ --version` (`builder.rs646-662`) | `None` (`builder.rs658`) | **Exit status only** | -| `cargo` | `+ --version` (`builder.rs666-682`) | `None` (`builder.rs678`) | **Exit status only** | -| `cargo-zigbuild` | `zigbuild --version` (`builder.rs699-712`) | `Some("cargo-zigbuild ")` (`builder.rs708`) | **Substring verified** | -| `zig` | `version` (`builder.rs716-729`) | `Some()` (`builder.rs725`) | **Substring verified** | +| `rustc` | `+ --version` (`builder.rs:905-918`) | `None` (`builder.rs:916`) | **Exit status only** | +| `cargo` | `+ --version` (`builder.rs:925-938`) | `None` (`builder.rs:936`) | **Exit status only** | +| `cargo-zigbuild` | `zigbuild --version` (`builder.rs:958-971`) | `Some("cargo-zigbuild ")` (`builder.rs:969`) | **Substring verified** | +| `zig` | `version` (`builder.rs:977-990`) | `Some()` (`builder.rs:987`) | **Substring verified** | | QEMU | ` --version` (`qualification.rs787-797`) | `None` (`qualification.rs:795`) | **Exit status only** | -| Python 3 | `--version` (`lib.rs:4365`, run at `lib.rs:4372`) | checked at `lib.rs:4412` | **Substring verified** (`"Python 3"`) | +| Python 3 | `--version` (`lib.rs:4642`, run at `lib.rs:4648`) | `expected_stdout` = `"Python 3"` (`lib.rs:4647`) | **Substring verified** (`"Python 3"`) | So the Zig toolchain is version-verified; the Rust toolchain is not. For `rustc` and `cargo`, the preflight asserts only that the rustup proxy resolved the @@ -339,32 +352,33 @@ exit-status-only, though there tool identity is a fixed finite mapping (`qualification.rs:785-786`). A missing interpreter is a failure, never a skip: an unusable `python3` returns -`InterpreterUnavailable` (`lib.rs:4256-4261`) rather than passing validation +`InterpreterUnavailable` (`lib.rs:4922-4925`) rather than passing validation vacuously. A missing cargo-zigbuild or Zig declaration is rejected before spawn -(`builder.rs691`, `638`). +(`builder.rs:950`, `builder.rs:956`). ## No shell interpretation Every production spawn passes an argument vector to `Command::new` plus `.args`/`.arg`. There is no `sh -c`, no `cmd /C`, and no shell string anywhere in -a spawn path. Core: `Command::new(&spec.executable).args(&spec.args)` -(`builder.rs465-468`). CI: `Command::new(exe)` then `command.arg(script)` and -`command.arg(candidate)` (`lib.rs:4343`, `4361-4362`). +a spawn path. Core: `Command::new(run.executable).args(run.args)` +(`builder.rs:663-666`). CI: the same shared call, with the argv built as +OS-native arguments — script path and candidate path (`lib.rs:4901-4904`). Because no shell is involved, the workspace does not need to escape, quote, or reject shell metacharacters. Instead it validates the *inputs*: - Cargo identifiers are restricted to ASCII alphanumerics, `_`, `-`, `.`, and at - most 128 bytes (`valid_identifier`, `builder.rs311-316`), applied to package - and binary before an argv is built (`builder.rs326-327`). + most 128 bytes (`valid_identifier`, `builder.rs:383-388`), applied to package + and binary before an argv is built (`builder.rs:436-441`). - Smoke argv is length- and count-capped and rejects NUL and all ASCII control characters (`qualification.rs:157-162`). - The CI script path must be absolute, and the interpreter is not configurable. -`RunnerCommand::to_shell` / `argv` (`lib.rs:1120`) do produce shell text, but +`RunnerCommand::to_shell` / `argv` (`lib.rs:1443`, `lib.rs:1152`) do produce shell +text, but only as rendered YAML for GitHub Actions to execute. That text is never executed by eggpack, and its command enum is closed by construction — the doc comment at -`lib.rs:969-970` records that no generic arbitrary-command DSL is authorized. +`lib.rs:993-994` records that no generic arbitrary-command DSL is authorized. ## Related deep dives diff --git a/crates/eggpack-ci/README.md b/crates/eggpack-ci/README.md index 211ed5a..712f14c 100644 --- a/crates/eggpack-ci/README.md +++ b/crates/eggpack-ci/README.md @@ -67,6 +67,22 @@ the stage job (`--installer-presentation` plus `--source-root` from staging inputs; absent for M003c-compatible staging). Graphs without validators or wrappers render byte-identical to M003c. +The consumer validator's execution is not this crate's own: it runs through +`eggpack_core::run_interpreter_bounded`, the shared bounded runner. The +interpreter is restricted to the finite `python3`/`python` names, the argument +vector is OS-native so a validated absolute path reaches the interpreter +byte-exact, the environment is cleared except for the shared allowlist plus the +caller's explicit `PATH` override, the whole process group (or job object) is +terminated on every failure path so no descendant outlives the run, and the +reader-thread joins are bounded by the run's own deadline so a descendant that +inherited a pipe cannot wedge the job. The runner outcome maps onto the +consumer-validation outcome exactly: success is `Passed`, a non-zero exit is +`Failed(NonZeroExit)`, an exceeded deadline is `Failed(Timeout)`, an exceeded +output bound is `Failed(OutputLimit)`, an observed cancellation is +`Failed(Cancelled)`, and an interpreter that cannot be launched is +`Failed(InterpreterUnavailable)`. No script output is recorded, and the +diagnostics are unchanged. + This crate owns no producer rule of its own. The host/target match, the compatibility floor, the exact-tag safety rule, and the file digest belong to `eggpack-core`; the SHA-256 hex acceptance set belongs to `eggpack-manifest`. diff --git a/crates/eggpack-ci/src/lib.rs b/crates/eggpack-ci/src/lib.rs index c4b0dd3..0bec904 100644 --- a/crates/eggpack-ci/src/lib.rs +++ b/crates/eggpack-ci/src/lib.rs @@ -4424,63 +4424,46 @@ fn consumer_evidence_shell( Ok(evidence) } -fn read_limited(stream: Option, limit: usize) -> (Vec, bool) { - use std::io::Read; - let Some(mut stream) = stream else { - return (Vec::new(), false); - }; - let mut bytes = Vec::new(); - let mut chunk = [0u8; 8192]; - loop { - match stream.read(&mut chunk) { - Ok(0) => break, - Ok(count) => { - // The bound is checked before the bytes are retained, so the - // accumulator never grows past `limit` even transiently. - if bytes.len().saturating_add(count) > limit { - // Drain is abandoned; caller kills the child and the - // pipe closes on drop. - return (bytes, true); - } - bytes.extend_from_slice(&chunk[..count]); - } - Err(_) => break, - } - } - (bytes, false) -} +/// Retained-output bound for the bounded `--version` interpreter preflight. +const PREFLIGHT_OUTPUT_LIMIT: usize = 8192; -fn read_limited_stderr(stream: Option, limit: usize) -> (Vec, bool) { - use std::io::Read; - let Some(mut stream) = stream else { - return (Vec::new(), false); - }; - let mut bytes = Vec::new(); - let mut chunk = [0u8; 8192]; - loop { - match stream.read(&mut chunk) { - Ok(0) => break, - Ok(count) => { - if bytes.len().saturating_add(count) > limit { - return (bytes, true); - } - bytes.extend_from_slice(&chunk[..count]); - } - Err(_) => break, - } +/// Build the bounded command spec for one consumer-validator invocation. +/// +/// The argument vector is OS-native so a validated absolute path reaches the +/// interpreter byte-exact, and the explicit environment override carries the +/// caller's PATH so a hermetic interpreter lookup stays hermetic. Everything +/// else — the deadline, the output bounds, the environment allowlist, the +/// process-group termination, and the bounded reader joins — belongs to the +/// shared runner in `eggpack-core`. +fn validator_spec( + exe: &str, + path_value: &str, + request: &ConsumerValidationRequest<'_>, + args: Vec, +) -> eggpack_core::InterpreterCommandSpec { + let mut env = std::collections::BTreeMap::new(); + env.insert("PATH".to_owned(), path_value.to_owned()); + eggpack_core::InterpreterCommandSpec { + executable: exe.to_owned(), + args, + cwd: request.work_dir.to_path_buf(), + env, + timeout: Duration::from_millis(request.validator.timeout_ms), + stdout_limit: request.validator.stdout_limit, + stderr_limit: request.validator.stderr_limit, + expected_stdout: None, } - (bytes, false) } /// Execute one consumer validator against the exact candidate. /// /// Shell-free fixed invocation `Python3