diff --git a/.skills/contract-and-manifest-surface/SKILL.md b/.skills/contract-and-manifest-surface/SKILL.md index 6255cc3..6702645 100644 --- a/.skills/contract-and-manifest-surface/SKILL.md +++ b/.skills/contract-and-manifest-surface/SKILL.md @@ -39,11 +39,16 @@ So "it's optional, so it's safe" is false here. A shape change to the published manifest is a compatibility event, not a convenience. It needs a plan, an ADR if it establishes a public compatibility contract, and downstream coordination. -`eggpack-manifest 0.1.0` is live on crates.io and consumed by `eggup-eggpack` -downstream. The published `src/lib.rs` is byte-identical to the -consumer-qualified pin the consumer was tested against — that equality is a -deliberate, recorded property, not an accident. The other six workspace crates -are unpublished; do not publish one as a side effect of unrelated work. +`eggpack-manifest 0.1.1` is live on crates.io. `0.1.0` remains published and +resolvable. `0.1.1` carries two narrowings of the published acceptance set — +the ADR-0006 all-zeros digest refusal and the document bound that +`ReleaseManifest::validate` now measures — and both are recorded as +compatibility events in +`plans/closure/release-manifest/004-status.md`. `eggup-eggpack` consumes +`=0.1.0` and is the named affected consumer; it pins an exact version, so it +does not pick up `0.1.1` automatically, and its bump needs a plan registered +in the Eggup repository. The other six workspace crates are unpublished; do +not publish one as a side effect of unrelated work. ## The two documents say different things diff --git a/.skills/planning-and-closure/SKILL.md b/.skills/planning-and-closure/SKILL.md index 6e12e26..acaf246 100644 --- a/.skills/planning-and-closure/SKILL.md +++ b/.skills/planning-and-closure/SKILL.md @@ -12,10 +12,11 @@ requires contract-level acceptance evidence. `plans/003-planning-process.md` is ## Before you open anything -1. Read `plans/registry.md` §"Next handoff". As of the last review **no - implementation milestone is `ready`** — the next three lines (Contract M003, - Bootstrap M003, Ecosystem M003 eggsearch) are *research/plan decisions*, not - execution. If your idea is one of them, the deliverable is a plan, not code. +1. Read the current `plans/registry.md` status tables and §"Next handoff". + Milestone status changes over time; use the registry and linked subsystem + roadmap as the authority instead of relying on remembered status snapshots. + If no implementation milestone is `ready`, author or update a plan before + implementing work that has not been handed off. 2. Check the subsystem roadmap (`plans/subsystems/-roadmap.md`). A plan may already exist under a name you did not guess. 3. Only then write anything. diff --git a/AGENTS.md b/AGENTS.md index c8b4001..791185a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -66,7 +66,7 @@ Read the index in `overview.md` and follow one link. Grouped by what they cover: | Area | Document | |---|---| -| Vocabulary, authority, phases, ADRs 0001–0005, `dist` (disposition C: prior art only) | [principles-roadmap.md](architecture/principles-roadmap.md) | +| Vocabulary, authority, phases, ADRs 0001–0006, `dist` (disposition C: prior art only) | [principles-roadmap.md](architecture/principles-roadmap.md) | | Planning process, closure discipline, registry | [planning-and-governance.md](architecture/planning-and-governance.md) | | Layout authority, schema-v1, conformance validators | [contract.md](architecture/contract.md) | | Final-bytes evidence, bounds, collision rules, publication status | [manifest.md](architecture/manifest.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 (source: `plans/registry.md`): no milestone is **in progress** and none is registered **ready**; the last open obligation of the 2026-10-23 review chain — Release Manifest M004, the ADR-0006 `eggpack-manifest 0.1.1` patch release and the compatibility record ADR-0006 §5.4 requires — is **closed**: `0.1.1` is published to crates.io (checksum `352c3e327159615b763298e911e239f1decc4a2c9e28c28be8ddd28e50515e37`, tagged `eggpack-manifest-v0.1.1`), and both narrowings the package carries — the ADR-0006 digest rule and the `3ef806f` document bound — are recorded as compatibility events. The 2026-10-23 post-implementation review chain is closed (Build/Qualification M007, M008, M009; CI/Release M003l, M003m, M003n; Planning Hygiene M003; Bootstrap M003a), and **ADR-0006 is accepted** (Option A), having gated CI M003l's digest-acceptance work package only. A follow-up review of that chain's own output registered and closed a second corrective chain: Build/Qualification M007a (digest zero-length read refusal), M008a (floor contradiction mask and ELF offset overflow), M009a (local producer operator defects, including an input-destroying staging path), and CI/Release M003o (renderer panic and digest diagnostics). **The chain's first hosted CI run failed on macOS and registered a third corrective, CI/Release M003p**: the shared bounded runner treated a failed process-group signal as fatal, but macOS refuses to signal a group holding the unreaped zombie of an exited child and reports `EPERM` where Linux signals it successfully, so an output-bound violation was reported as a launch failure. M003p decides by observing whether the child has exited rather than by reading the errno, and hosted run `40263176191` is green on all four lanes. Both review chains left one obligation open — ADR-0006 §5.2/§9's `eggpack-manifest 0.1.1` publication and the release-manifest compatibility record — and M004 owns it; the `0.1.1` package carries **two** narrowings of the published acceptance set, the ADR-0006 digest rule and the `3ef806f` document bound, and only the first had been recorded. **Blocked** are Ecosystem M004 (Gregg sibling bundle), Ecosystem M005 (CodeGG runfile bundle), and Ecosystem M006 (Egress archive pair), each on its named adoption evidence and bundle/archive review; the provenance/authenticity line is **planned** pending a dedicated trust ADR, and Python/wheel adapters are **planned** behind broader native adoption. 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/Cargo.lock b/Cargo.lock index b8c7002..bb78dc3 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -202,8 +202,10 @@ dependencies = [ "eggpack-core", "eggpack-github", "eggpack-manifest", + "flate2", "serde_json", "sha2", + "tar", "tokio", "toml", ] @@ -224,6 +226,7 @@ dependencies = [ "eggpack-contract", "eggpack-manifest", "flate2", + "libc", "serde", "serde_json", "sha2", @@ -251,7 +254,7 @@ dependencies = [ [[package]] name = "eggpack-manifest" -version = "0.1.0" +version = "0.1.1" dependencies = [ "serde", "serde_json", diff --git a/README.md b/README.md index 4542198..98a17cf 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,10 @@ EGGPACK=./target/debug/eggpack $EGGPACK --version # eggpack 0.1.0 ``` -A release is three pure file-in/file-out commands — no network, no token, no -real build. These need six input files: a contract, a pack config, build -bindings, qualification bindings, a draft template, and a GitHub policy. +The `ci` family's rendering path is three pure file-in/file-out commands — no +network, no token, no real build. These need six input files: a contract, a pack +config, build bindings, qualification bindings, a draft template, and a GitHub +policy. [docs/quickstart.md](docs/quickstart.md) writes all six and runs the whole flow end to end (~5 minutes, no network); every command and expected output there was executed verbatim. @@ -53,35 +54,108 @@ The rendered workflow is read-only (`contents: read`) and chains `generate` and `check` are the only user-facing commands in the `ci` family. The nine `ci _*` runners are the file-in/file-out steps the generated workflow replays inside -CI. A bare `eggpack` prints every subcommand. - -There is one other user-facing family, `contract expand`: a bounded, local-only -projection that reads one producer contract and prints one scalar, so a consumer -repository can read a producer fact instead of re-implementing TOML parsing and -template expansion. - +CI. A bare `eggpack` prints every subcommand; its usage line leads with the +operator family — `usage: eggpack [options]`. + +There are two other user-facing families. + +## The operator family — build a release locally + +Six commands drive the producer on a workstation: `check` → `plan` → `package` → +`qualify` → `collect` → `manifest`. Unlike the `ci` rendering path, this family +**performs a real Cargo build** — `package` invokes `cargo +` on +every planned target — but it still performs no network access and needs no +GitHub token. The six commands share one implementation with the `ci _*` +runners, so both surfaces derive one plan from one rule set. + +| Command | Class | What it does | +|---|---|---| +| `check` | validation | Resolves the whole planning input set and writes nothing. | +| `plan` | validation | Writes the `ReleasePlan` — the release identity, the selected targets, and their policies. | +| `package` | build | Builds every planned target's candidates under an output root. | +| `qualify` | build | Qualifies the built candidates and writes qualification evidence. | +| `collect` | release aggregation | Aggregates the qualified candidates into a finalized release tree. | +| `manifest` | final-bytes evidence | Derives `release-manifest.json` from the finalized release tree — and checks it against the finalized tree it describes. | + +Three optional flags are available on the family: `--qemu-sysroot` (the QEMU +sysroot for an emulated target), `--identity-mode` (a caller-chosen +release-identity mode), and `--consumer-validators` (a checked-in consumer +validator map). The producer policy and both bindings documents may be given as +**TOML or JSON**. `qualify` refuses `--output-dir == --artifacts-dir`, because +staging the qualification artifacts into the directory the candidates were read +from would rewrite the very bytes the qualification is about; and `manifest` +reads every archive member back out of the finalized `.tar.gz` and compares it +against the collected manifest, so a manifest that disagrees with its archive is +refused rather than emitted. ```sh -$EGGPACK contract expand --contract contract.toml --release-id 1.2.6 \ - --target linux-x64 --field asset -# eggsact-1.2.6-x86_64-unknown-linux-gnu +# 1. validate the planning inputs — writes nothing +$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" +# 2. resolve the release identity — writes the plan +$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 +# 3. build every planned target — a real Cargo build +$EGGPACK package --release-plan out/release-plan.json \ + --build-bindings build-bindings.toml --source-root demo --output-root out/build +# 4. qualify the candidates +$EGGPACK qualify --contract contract.toml --release-plan out/release-plan.json \ + --build-bindings build-bindings.toml --qualification-bindings qualification-bindings.toml \ + --artifacts-dir out/build --output-dir out/qualification +# 5. aggregate the qualified candidates into a finalized release tree +$EGGPACK collect --contract contract.toml --release-plan out/release-plan.json \ + --build-bindings build-bindings.toml --qualification-bindings qualification-bindings.toml \ + --artifacts-dir out/qualification --output-root out/release/finalized +# 6. derive the final-bytes evidence — the manifest sits beside the finalized root +$EGGPACK manifest --contract contract.toml --release-plan out/release-plan.json \ + --finalized-root out/release/finalized --output out/manifest/release-manifest.json ``` +[docs/quickstart.md](docs/quickstart.md) runs this path end to end with the +exact inputs and the quoted output of every step. +## The `contract` family +`contract expand` is a bounded, local-only projection that reads one producer +contract and prints one scalar, so a consumer repository can read a producer +fact instead of re-implementing TOML parsing and template expansion. -It performs no network access, no repository discovery, and no release -selection, and it fails closed on bundle/archive targets for direct-only fields. -See [crates/eggpack-cli/README.md](crates/eggpack-cli/README.md). +```sh +# 1. validate the planning inputs — writes nothing +$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" -## Verify +# 2. resolve the release identity — writes the plan +$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 -```sh -scripts/check-local.sh # fmt, check, clippy, tests, doc, package, MSRV +# 3. build every planned target — a real Cargo build +$EGGPACK package --release-plan out/release-plan.json \ + --build-bindings build-bindings.toml --source-root demo --output-root out/build + +# 4. qualify the candidates +$EGGPACK qualify --contract contract.toml --release-plan out/release-plan.json \ + --build-bindings build-bindings.toml --qualification-bindings qualification-bindings.toml \ + --artifacts-dir out/build --output-dir out/qualification + +# 5. aggregate the qualified candidates into a finalized release tree +$EGGPACK collect --contract contract.toml --release-plan out/release-plan.json \ + --build-bindings build-bindings.toml --qualification-bindings qualification-bindings.toml \ + --artifacts-dir out/qualification --output-root out/release/finalized + +# 6. derive the final-bytes evidence — the manifest sits beside the finalized root +$EGGPACK manifest --contract contract.toml --release-plan out/release-plan.json \ + --build-bindings build-bindings.toml --qualification-bindings qualification-bindings.toml \ + --finalized-root out/release/finalized --output out/manifest/release-manifest.json ``` -## Docs +[docs/quickstart.md](docs/quickstart.md) runs this path end to end with the +exact inputs and the quoted output of every step. + +## The `contract` family -- [docs/quickstart.md](docs/quickstart.md) — the runnable walkthrough, in full -- [docs/release-identity-policy.md](docs/release-identity-policy.md) — opt-in - source-tag and manifest-ID mapping policy -- [docs/](docs/) — user guides and the workspace layout -- [crates/eggpack-cli/README.md](crates/eggpack-cli/README.md) — command reference -- [architecture/overview.md](architecture/overview.md) — pipeline, crate boundaries, invariants -- [AGENTS.md](AGENTS.md) — operating contract, verification, planning conventions +`contract expand` is a bounded, local-only projection that reads one producer +contract and prints one scalar, so a consumer repository can read a producer +fact instead of re-implementing TOML parsing and template expansion. diff --git a/architecture/bootstrap.md b/architecture/bootstrap.md index d7d62b6..4a16798 100644 --- a/architecture/bootstrap.md +++ b/architecture/bootstrap.md @@ -19,7 +19,7 @@ no environment probing at render time. `render_posix` (`:140-144`) and `render_powershell` (`:193-197`) take the first three; `render_posix_with_policy` (`:657-662`) and -`render_powershell_with_policy` (`:872-877`) take all four. +`render_powershell_with_policy` (`:884-889`) take all four. The boundary is structural, not conventional. The origin is a single fixed base URL (`:14`) validated as `https://`, or loopback `http://` when `fixture_http` @@ -44,7 +44,7 @@ signature logic at all. | `BootstrapInstallPolicyV1` | `:280-286` | Strict versioned policy; `deny_unknown_fields`. | | `empty` / `from_toml` / `from_json` / `validate_shape` | `:294-337` | Constructors, bounded parsers, shape validation. | | `render_posix_with_policy` | `:657-860` | Direct + bundle + archive POSIX renderer (policy pair). | -| `render_powershell_with_policy` | `:872-1048` | Direct + bundle + archive PowerShell renderer (policy pair). | +| `render_powershell_with_policy` | `:884-1064` | Direct + bundle + archive PowerShell renderer (policy pair). | Internal machinery: `Item` (`:30-37`), `project` (`:38-112`, direct-only), `safe_segment` (`:113-117`), `runtime_pair` (`:118-138`), `shq` (`:189-191`), @@ -52,7 +52,7 @@ Internal machinery: `Item` (`:30-37`), `project` (`:38-112`, direct-only), `ArchiveMemberProjection` (`:367-373`), `TargetProjection` (`:376-398`), `project_all` (`:400-622`), `posix_mode` (`:624-629`), `POSIX_SHA_SNIPPET` (`:631`), `posix_verify_block` (`:633-645`), `posix_download_block` -(`:647-654`), `ps_verify_block` (`:862-869`). +(`:647-654`), `ps_verify_block` (`:862-873`). ## The two-layer render API @@ -68,15 +68,15 @@ policy layer adds multi-entry placement with rollback, per-entry POSIX mode from `InstallMode`, archive extraction with per-member verification, and a strict cross-check of policy against contract. Policy is mandatory for bundle and archive targets (`:466`, `:527`) and optional for direct targets. Callers outside -this crate use only the policy pair (`crates/eggpack-github/src/lib.rs:802`, -`:808`, `:1471`, `:1477`); the spec pair has no caller outside its own tests. +this crate use only the policy pair (`crates/eggpack-github/src/lib.rs:668`, +`:695`, `:1017`, `:1296`); the spec pair has no caller outside its own tests. ## Install modes and the shell/PowerShell matrix `InstallMode` is keyed by install name, not by target. `posix_mode` (`:624-629`) maps `Executable` to `755` and `Data` to `644`. The PowerShell renderers never -consult the mode: they move verified bytes with `[IO.File]::Move` (`:942`, -`:1015`), preserving content and inheriting the destination directory ACL, as +consult the mode: they move verified bytes with `[IO.File]::Move` (`:954`, +`:1031`), preserving content and inheriting the destination directory ACL, as the `InstallMode` doc comments state (`:251`, `:253`). Policy is still required and validated for Windows targets, so a policy valid for POSIX is valid for PowerShell. `BundleArchiveEncoding` has one variant, and the archive filename @@ -84,18 +84,18 @@ must end in `.tar.gz` (`:533-535`). | Form | POSIX (`render_posix_with_policy`) | PowerShell (`render_powershell_with_policy`) | | --- | --- | --- | -| Direct | Download to `"$tmp/payload"`, size + SHA-256, `chmod 755`, `ln` (`:676-684`). | `Invoke-WebRequest -OutFile`, `Get-FileHash`, `[IO.File]::Move` (`:890-900`). No chmod. | -| Bundle | All destinations pre-checked absent; per-entry download + size + SHA-256; re-check; per-entry `chmod 755`/`644`; sequential `ln` with `rm -f` rollback of prior links (`:687-744`). | Same pre-check / verify / re-check order; sequential `[IO.File]::Move` appending to `$created` (`:903-947`); rollback via the shared `catch` (`:1040-1042`). | -| Archive | Requires `tar` (`:768`); outer verify (`:770-776`); expected-inventory `printf` (`:778-783`); `tar -tzf` (`:784`); member-path guard (`:785`); `LC_ALL=C sort` + `cmp -s` exact inventory (`:786-788`); extract to `"$tmp/extracted"` (`:789-790`); per-member symlink + regular-file check (`:793`), size + SHA-256 (`:796-803`), `chmod` (`:804-807`); re-check; `ln` with rollback (`:815-834`). | Requires `tar.exe` (`:971`); outer verify (`:976-981`); `$expected` vs `tar.exe -tzf` with `$missing`/`$extra` (`:982-993`); extract to `$extractDir` (`:994`); per-member `LinkType` and `-PathType Leaf` (`:997`) plus size + SHA-256 (`:1000-1005`); `[IO.File]::Move` with `$created` (`:1013-1019`). | +| Direct | Download to `"$tmp/payload"`, size + SHA-256, `chmod 755`, `ln` (`:676-684`). | `Invoke-WebRequest -OutFile`, `Get-FileHash`, `[IO.File]::Move` (`:902-912`). No chmod. | +| Bundle | All destinations pre-checked absent; per-entry download + size + SHA-256; re-check; per-entry `chmod 755`/`644`; sequential `ln` with `rm -f` rollback of prior links (`:687-744`). | Same pre-check / verify / re-check order; sequential `[IO.File]::Move` appending to `$created` (`:915-959`); rollback via the shared `catch` (`:1056-1058`). | +| Archive | Requires `tar` (`:768`); outer verify (`:770-776`); expected-inventory `printf` (`:778-783`); `tar -tzf` (`:784`); member-path guard (`:785`); `LC_ALL=C sort` + `cmp -s` exact inventory (`:786-788`); extract to `"$tmp/extracted"` (`:789-790`); per-member symlink + regular-file check (`:793`), size + SHA-256 (`:796-803`), `chmod` (`:804-807`); re-check; `ln` with rollback (`:815-834`). | Requires `tar.exe` (`:983`); outer verify (`:988-993`); `$expected` vs `tar.exe -tzf` with `$missing`/`$extra` (`:994-1009`); extract to `$extractDir` (`:1010`); per-member `LinkType` and `-PathType Leaf` (`:1013`) plus size + SHA-256 (`:1016-1021`); `[IO.File]::Move` with `$created` (`:1029-1035`). | Archive members declare a `source` inside the archive and an `install` name at the destination. Nested sources flatten: the test fixture uses -`bin/egress-helper` installing as `egress-helper` (`:1914-1921`), and `bin/` is -never created in the destination (`:818`, `:1015`; asserted at `:3178`). A +`bin/egress-helper` installing as `egress-helper` (`:1930-1937`), and `bin/` is +never created in the destination (`:818`, `:1031`; asserted at `:3317`). A missing member fails the inventory comparison (`archive member inventory -mismatch`, `exit 6` at `:788`; `throw` at `:992-993`); a member that is present +mismatch`, `exit 6` at `:788`; `throw` at `:1008-1009`); a member that is present but not a regular file is rejected after extraction (`symlink member rejected` / -`member is not a regular file`, `:793`, `:997`). +`member is not a regular file`, `:793`, `:1013`). ## `BootstrapInstallPolicyV1` and per-target policy @@ -110,7 +110,7 @@ mode key passing `safe_segment` (`[A-Za-z0-9._+-]+`, `:113-117`). What a caller may override per target is deliberately narrow: the mode of each install name and, for archive targets only, the required encoding. It cannot override the install location (fixed to the single positional argument, `:848` / -`:1031`), the download URL (fixed by contract + manifest + origin), the artifact +`:1047`), the download URL (fixed by contract + manifest + origin), the artifact names, or the digests. Policy cannot contradict the contract; every contradiction is a hard error before any text is emitted: @@ -154,13 +154,13 @@ POSIX policy script (emitted at `:841-856`): listing, path, and inventory gates below before extraction. 7. `exit 0` per branch (`:743`, `:835`), so the `case` is terminal. -PowerShell policy script (emitted at `:1026-1043`): `$ErrorActionPreference = +PowerShell policy script (emitted at `:1042-1059`): `$ErrorActionPreference = 'Stop'`; OS/arch from `$env:OS`, `$IsMacOS`, and -`[Runtime.InteropServices.RuntimeInformation]::OSArchitecture` (`:1027-1029`); -`$origin`, `$dest = $args[0]`, `New-Item -Force` (`:1030-1032`); GUID temp dir -under `$dest` (`:1033-1034`); `$created = @()` (`:1035`); `try { switch ... }` -(`:1036-1039`); `catch` removes only `$created` paths and rethrows -(`:1040-1042`); `finally` removes the temp dir (`:1043`). +`[Runtime.InteropServices.RuntimeInformation]::OSArchitecture` (`:1043-1045`); +`$origin`, `$dest = $args[0]`, `New-Item -Force` (`:1046-1048`); GUID temp dir +under `$dest` (`:1049-1050`); `$created = @()` (`:1051`); `try { switch ... }` +(`:1052-1055`); `catch` removes only `$created` paths and rethrows +(`:1056-1058`); `finally` removes the temp dir (`:1059`). There is no PATH wiring in either renderer: no profile editing, no symlink into a `bin` directory, no shell rc modification. The installer places files and @@ -168,18 +168,18 @@ exits. The scripts explicitly do not: fetch or parse a release index; check for a newer version; install over an existing file; remove a pre-existing file; escalate -privilege (`sudo`, `RunAs`, `Start-Process` absent, asserted at `:3122-3123`); -follow redirects (`-MaximumRedirection 0` at `:228`, `:891`, `:919`, `:973`); +privilege (`sudo`, `RunAs`, `Start-Process` absent, asserted at `:3261-3262`); +follow redirects (`-MaximumRedirection 0` at `:228`, `:903`, `:931`, `:985`); or verify a signature. ## Integrity, not authenticity `sha2` is a **dev-dependency** (`crates/eggpack-bootstrap/Cargo.toml:21-24`) -used only by the test helper `sha_hex` (`:1403-1409`). The renderer never +used only by the test helper `sha_hex` (`:1419-1425`). The renderer never computes a digest: it copies the manifest's `sha256` string into the script (`:80`, `:461`, `:504`, `:579`, `:596`) and emits a comparison (`:639-643`, `:864`). Likewise `tar` and `flate2` are dev-dependencies used to *build* -deterministic fixture archives in tests (`:1757-1780`, `:2758-2780`), not to +deterministic fixture archives in tests (`:1773-1796`, `:2897-2919`), not to unpack anything. What the emitted check proves: the bytes the script received are the bytes the @@ -208,12 +208,12 @@ hostname, no user name, no random identifier, no locale-dependent formatting. pairs contract and manifest entries (`:474`, `:547`); policy mode maps are `BTreeMap` (`:271`), so lookup and serialization are ordered. - Randomness exists only at run time: `mktemp -d` (`:850`) and - `[Guid]::NewGuid()` (`:1033`) are fixed source text in the script and resolve + `[Guid]::NewGuid()` (`:1049`) are fixed source text in the script and resolve when the script runs. - The legacy `project` (`:38-112`) deliberately preserves manifest order. That is input-derived and stable, not host-derived. -- Asserted directly: `render_posix` equality at `:1122-1123`, - `render_powershell_with_policy` equality at `:3116-3120`. +- Asserted directly: `render_posix` equality at `:1138-1139`, + `render_powershell_with_policy` equality at `:3255-3259`. Cross-reference `determinism.md`. @@ -221,21 +221,21 @@ Cross-reference `determinism.md`. **Fail-closed exits.** Size mismatch exits 6 (`:635`, `:178`); SHA-256 mismatch exits 8 (`:641`, `:180`); missing tooling exits 5 (`curl is required` `:649` / -`:176`, `tar is required` `:768`, `tar.exe is required` `:971`); missing +`:176`, `tar is required` `:768`, `tar.exe is required` `:983`); missing SHA-256 tooling exits 7 (`:631`); every branch ends in `exit 0` (`:743`, `:835`) so execution cannot fall through. PowerShell throws instead, under -`$ErrorActionPreference = 'Stop'` (`:1026`). +`$ErrorActionPreference = 'Stop'` (`:1042`). **Unwritable targets.** Destinations are checked absent before any download and -re-checked immediately before placement (`:696-699` + `:712-717`; `:965-970` + -`:1007-1012`). Final placement is the authoritative guard: POSIX `ln` (`:677`, +re-checked immediately before placement (`:696-699` + `:712-717`; `:977-982` + +`:1023-1028`). Final placement is the authoritative guard: POSIX `ln` (`:677`, `:728`, `:737`, `:818`, `:828`) and PowerShell `[IO.File]::Move` (`:232`, -`:942`, `:1015`) both refuse to overwrite, reporting `destination already exists +`:954`, `:1031`) both refuse to overwrite, reporting `destination already exists or filesystem does not support safe placement`. A failure after the first successful placement rolls back only files this invocation created — `rm -f` of -prior links (`:737`, `:828`) or the `$created` list (`:1040-1042`) — and never +prior links (`:737`, `:828`) or the `$created` list (`:1056-1058`) — and never deletes anything pre-existing. Because the temp dir lives under the destination -(`:850`, `:1033`), placement is a same-filesystem link or same-volume move by +(`:850`, `:1049`), placement is a same-filesystem link or same-volume move by construction; a cross-device layout surfaces as a placement failure, not a silent copy. @@ -245,29 +245,29 @@ quotes with `''` doubling). Values reaching unquoted positions are additionally constrained by `safe_segment` (`:113-117`) to `[A-Za-z0-9._+-]`, and the origin is rejected if it contains any character that could escape quoting (`:47-48`, `:345-346`). Install names, artifact names, and archive sources all go through -the quoting helpers (`:677`, `:690`, `:757`, `:794`, `:818`, `:891`, `:906`, -`:960`, `:998`, `:1017`). One coupling worth recording: `ps_verify_block` -formats the expected digest with `shq` and lowercases it (`:867`), which is safe +the quoting helpers (`:677`, `:690`, `:757`, `:794`, `:818`, `:903`, `:918`, +`:972`, `:1014`, `:1033`). One coupling worth recording: `ps_verify_block` +formats the expected digest with `shq` and lowercases it (`:871`), which is safe only because `m.validate()` enforces 64 lowercase hex characters -(`crates/eggpack-manifest/src/lib.rs:268-275`); a digest containing a quote +(`crates/eggpack-manifest/src/lib.rs:98-116`); a digest containing a quote would be mis-escaped for PowerShell. Real dependency, currently unreachable. **No `eval`-style constructs.** No `eval`, `Invoke-Expression`, `iex`, `bash -c`, `sh -c`, or `Start-Process` appears in either renderer, and absence -is asserted (`:1125`, `:3122-3123`). Branching uses `case` / `switch` over +is asserted (`:1141`, `:3261-3262`). Branching uses `case` / `switch` over literal arms. **Archive path traversal.** The guard is emitted into the script, not delegated to `tar`, and it runs *before* extraction. The POSIX listing gate (`:785`) rejects, per listed member: the empty string, a leading `/`, any backslash, any -colon, and any occurrence of `..`. The PowerShell gate (`:991`) is the same five +colon, and any occurrence of `..`. The PowerShell gate (`:1003`) is the same five checks. Extraction then happens into a fresh private temp directory (`:789-790`, -`:994`), and only afterwards is each expected member resolved, checked for -symlink and regular-file type (`:793`, `:997`), verified by size and SHA-256 -(`:796-803`, `:1000-1005`), and linked or moved to its install name. No +`:1010`), and only afterwards is each expected member resolved, checked for +symlink and regular-file type (`:793`, `:1013`), verified by size and SHA-256 +(`:796-803`, `:1016-1021`), and linked or moved to its install name. No archive-derived path is ever used as a write target inside the destination, so even a guard bypass could not place a file outside `$dest`. Independently, the -exact-inventory comparison (`:786-788` via `sort` + `cmp -s`; `:992-993` via +exact-inventory comparison (`:786-788` via `sort` + `cmp -s`; `:1008-1009` via `$missing`/`$extra`) rejects any member not named by the contract and manifest, which subsumes traversal as a special case. The `..` test is substring-based (`*'..'*` / `-match '\.\.'`) and so also rejects legitimate names containing @@ -275,63 +275,63 @@ which subsumes traversal as a special case. The `..` test is substring-based `safe_segment`-checked (`:567`) but `source` is not re-validated here; traversal-shaped `source` values are rejected upstream by `validate_member_source` in the contract -(`crates/eggpack-contract/src/lib.rs:707-751`, which rejects control +(`crates/eggpack-contract/src/lib.rs:747-791`, which rejects control characters, braces, backslashes, leading `/`, `:`, and any `.` or `..` component). Tests build raw ustar fixtures the `tar` crate would refuse to -construct, specifically to exercise the consumer guard (`:1780-1850`; -traversal `:2594-2609`, absolute `:2611-2627`, backslash `:2629-2646`). +construct, specifically to exercise the consumer guard (`:1796-1866`; +traversal `:2733-2748`, absolute `:2750-2766`, backslash `:2768-2785`). ## Windows and PowerShell specifics The PowerShell renderers need a host that provides a PowerShell exposing -`$IsMacOS` and `[Runtime.InteropServices.RuntimeInformation]` (`:1027-1029`) — -hence the pwsh 7 requirement — and, for archive targets, `tar.exe` (`:971`). +`$IsMacOS` and `[Runtime.InteropServices.RuntimeInformation]` (`:1043-1045`) — +hence the pwsh 7 requirement — and, for archive targets, `tar.exe` (`:983`). POSIX archive targets need `tar` (`:768`). `cargo test -p eggpack-bootstrap` refuses to skip on the Windows lane: under `cfg!(windows)` the test fails unless `pwsh_available()` and -`tar_exe_available()` both hold (`:3089-3094`, helpers `:1862-1905`); other -platforms print a skip note and return (`:3095-3098`). The Windows CI lane +`tar_exe_available()` both hold (`:3228-3233`, helpers `:1878-1921`); other +platforms print a skip note and return (`:3234-3237`). The Windows CI lane independently asserts `pwsh -Version` and `tar.exe --version` (`.github/workflows/ci.yml:70-75`) and then runs `m002a_powershell_archive_runtime` as a focused step (`.github/workflows/ci.yml:76-77`). -`m002a_powershell_archive_runtime` (`:3084-3436`) is real runtime evidence: it +`m002a_powershell_archive_runtime` (`:3223-3587`) is real runtime evidence: it serves fixture bytes over loopback HTTP, renders the archive installer, executes it with `pwsh -NoProfile -NonInteractive -File`, and asserts exact -installed bytes (`:3176-3177`), nested-source flattening (`:3178`), no-overwrite -on re-run (`:3180-3183`), outer size and digest rejection (`:3186-3202`), the six -inner guards (`:3311-3349`), member-evidence rejection (`:3352-3371`), the -`tar.exe` tool boundary (`:3373-3399`), rollback of an invocation-created file -while preserving a pre-existing sentinel (`:3401-3421`), and preservation of a -pre-existing first destination (`:3423-3432`). +installed bytes (`:3315-3316`), nested-source flattening (`:3317`), no-overwrite +on re-run (`:3319-3322`), outer size and digest rejection (`:3325-3341`), the six +inner guards (`:3462-3500`), member-evidence rejection (`:3503-3522`), the +`tar.exe` tool boundary (`:3524-3550`), rollback of an invocation-created file +while preserving a pre-existing sentinel (`:3552-3572`), and preservation of a +pre-existing first destination (`:3574-3583`). Cross-reference `testing-and-portability.md`. ## Tests and coverage shape -This crate has 8 `#[test]` functions (`:1077`, `:1160`, `:1185`, `:1991`, -`:2201`, `:2440`, `:2964`, `:3084`) — the lowest test count in the workspace -against 3436 source lines, and the test module spans `:1050-3436`, so roughly +This crate has 8 `#[test]` functions (`:1093`, `:1176`, `:1201`, `:2007`, +`:2217`, `:2579`, `:3103`, `:3223`) — the lowest test count in the workspace +against 3436 source lines, and the test module spans `:1066-3587`, so roughly 70% of the file is tests. The dev-dependencies make fixtures real: `sha2` -computes fixture digests (`:1403-1409`); `tar` plus `flate2` build deterministic +computes fixture digests (`:1419-1425`); `tar` plus `flate2` build deterministic `.tar.gz` archives with `mtime(0)`, `uid/gid 0`, and -`tar::HeaderMode::Deterministic` (`:1757-1780`). A hand-written ustar writer -(`:1780-1850`) produces archives with names the `tar` crate rejects, so the +`tar::HeaderMode::Deterministic` (`:1773-1796`). A hand-written ustar writer +(`:1796-1866`) produces archives with names the `tar` crate rejects, so the traversal and type guards run against bytes an attacker could actually serve. Honest assessment. The strong part: the direct-only renderers execute for real -against a loopback fixture server (`:1185`), the POSIX bundle and archive -renderers run full positive and negative matrices end to end (`:2201`, `:2440`), +against a loopback fixture server (`:1201`), the POSIX bundle and archive +renderers run full positive and negative matrices end to end (`:2217`, `:2579`), and the PowerShell archive lane runs actual `pwsh`. The weak part: most of this crate is emitted text and several assertions are substring checks -(`assert!(a.contains("--connect-timeout 10 --max-time 120"))` at `:1124`; -`assert!(script.contains("tar.exe"))` at `:3121`). A substring assertion can +(`assert!(a.contains("--connect-timeout 10 --max-time 120"))` at `:1140`; +`assert!(script.contains("tar.exe"))` at `:3260`). A substring assertion can pass while unrelated parts of the same script are wrong. POSIX policy coverage is behavioural, strong but only for the platform and tool combinations that ran; the spec pair is covered by substring, parse, and one runtime direct test. -PowerShell non-archive forms have static coverage only (`:2964`), making +PowerShell non-archive forms have static coverage only (`:3103`), making `m002_powershell_static_and_runtime` the weakest M002 test by construction. Nothing asserts the full text of a rendered script, and nothing exercises `render_posix` / `render_powershell` output on Windows. diff --git a/architecture/ci-consumer-seam.md b/architecture/ci-consumer-seam.md index e0123bc..d250a3d 100644 --- a/architecture/ci-consumer-seam.md +++ b/architecture/ci-consumer-seam.md @@ -1,31 +1,33 @@ # `eggpack-ci` — Consumer Seam, Handoffs, and Runtime Identity — Deep Dive -The half of `eggpack-ci` (`crates/eggpack-ci/src/lib.rs`, 10256 lines) concerned -with agreeing on artifacts and identities rather than doing release work: the -build/qualification handoff documents, the external consumer validator and its -private process runner, the Zig/cross-tool provisioning contract, and the -reusable-workflow runtime identity. It divides from [ci.md](ci.md) (projection -model, job vocabulary, gates, aggregation) and [ci-rendering.md](ci-rendering.md) -(policy types, renderers, drift checking). Regions: `:487-713`, `:941-963`, -`:1837-2207`, `:3840-4705`. - -> **Known-stale citations in this file.** Commit `61b2c03` moved -> `crates/eggpack-cli/src/main.rs` and `crates/eggpack-core/src/builder.rs` -> substantially, and this file's anchors into those two were not re-based — see -> [overview.md](overview.md) §Citation-verification state. Anchors into -> `crates/eggpack-ci/src/lib.rs` are current; the `:1837-2207` and -> `:3840-4705` region bounds above are the pre-`61b2c03` values and are now -> `:1837-2209` and `:3840-4707`. Treat the `main.rs` and `builder.rs` line -> references as indicative until someone re-bases them by symbol name. The prose, -> the handoff constant names, and the seam contract itself are unaffected. +The half of `eggpack-ci` concerned with agreeing on artifacts and identities +rather than doing release work: the build/qualification handoff documents, the +external consumer validator and its bounded runner call, the Zig/cross-tool +provisioning contract, and the reusable-workflow runtime identity. It divides +from [ci.md](ci.md) (projection model, job vocabulary, gates, aggregation) and +[ci-rendering.md](ci-rendering.md) (policy types, renderers, drift checking). + +The crate is a module tree, so this file names the module that holds each +construct: `handoff.rs` (handoff documents), `consumer_validator.rs` (external +validator), `identity.rs` (runtime identity), `policy.rs` (shared constants, +Zig provisioning, path rules), `release_plan.rs` (orchestration graph), +`planning.rs` (`CIPlan`), `validate.rs` (shared string rules), `drift.rs` +(drift checking), and `render_release.rs` (rendering). + +> **Citation state.** The anchors below were re-based by symbol name in the +> 2026-10-23 post-implementation review pass and read against the tree at the +> SHA pinned in [overview.md](overview.md) §Baseline. `crates/eggpack-ci/src/lib.rs` +> is now the 59-line crate root; the only anchor in this file that points into it +> is the `mod tests;` declaration at `:18-19`. Every other anchor names a module +> in the crate's module tree. ## Responsibility -| Job | Region | Problem it solves | +| Job | Module | Problem it solves | |---|---|---| -| Build/qualification handoff | `:1837-2207` | The generated workflow does not call library functions; it shells out to the `eggpack` binary. Two independently versioned processes must agree on artifact layout and document shape. | -| External consumer validator | `:3840-4705` | A third party needs to assert something about a release without eggpack claiming it. The seam runs caller-supplied code and returns bounded evidence. | -| Runtime identity | `:4425-4623` | A checked-in reusable workflow cannot hardcode a release id, source revision, or tag, or it would be regenerated per release. The shape is identity-free; the plan is resolved per invocation. | +| Build/qualification handoff | `handoff.rs` | The generated workflow does not call library functions; it shells out to the `eggpack` binary. Two independently versioned processes must agree on artifact layout and document shape. | +| External consumer validator | `consumer_validator.rs` | A third party needs to assert something about a release without eggpack claiming it. The seam runs caller-supplied code and returns bounded evidence. | +| Runtime identity | `identity.rs` | A checked-in reusable workflow cannot hardcode a release id, source revision, or tag, or it would be regenerated per release. The shape is identity-free; the plan is resolved per invocation. | All three are *agreement* mechanisms, not security boundaries against a hostile caller: the caller supplies the contracts, and validation is fail-closed against @@ -33,9 +35,11 @@ malformed or out-of-bounds documents, not against a determined adversary. ## The build/qualification handoff formats -`BUILD_HANDOFF_FILE` = `build-handoff.json` (`:941`), `QUALIFICATION_EVIDENCE_FILE` -= `evidence.json` (`:943`), `CANDIDATES_DIR` = `candidates` (`:945`), -`GATE_OUTCOME_FILE` = `gate-outcome.json` (`:947`, serialized at `:3528`). These +`BUILD_HANDOFF_FILE` = `build-handoff.json` +(`crates/eggpack-ci/src/policy.rs:542`), `QUALIFICATION_EVIDENCE_FILE` = +`evidence.json` (`policy.rs:545`), `CANDIDATES_DIR` = `candidates` +(`policy.rs:548`), `GATE_OUTCOME_FILE` = `gate-outcome.json` (`policy.rs:551`, +written by the gate job at `crates/eggpack-ci/src/render_release.rs:1047`). These four strings are the entire contract between the rendered workflow and the `eggpack` binary. A change to a name, a JSON shape, or a validation rule here survives compilation and fails at CI runtime: nothing in the type system ties a @@ -43,79 +47,87 @@ producer write to a consumer read. | Document | Type | Producer | Consumer | Validated on read | |---|---|---|---|---| -| build handoff | `BuildHandoffV1` (`:1862`) | `project_build_handoff` (`:1944`), written by CLI `_capture-build` | `validate_build_artifact_dir` (`:2062`), `reconstruct_attempt` (`:2005`) | `from_json` (`:1885`) + `validate` (`:1896`), on every read | -| candidate bytes | files under `candidates/` | `stage_build_artifact_dir` (`:2152`) / CLI staging | same | size, regular non-symlink file, exact inventory, no extras (`:2073-2105`) | -| qualification evidence | `QualificationEvidence` (core) | qualification job | `validate_qualification_artifact_dir` (`:2111`) | identity must equal the handoff (`:2118-2123`) | -| consumer evidence | `ConsumerValidationEvidenceV1` (`:3968`) | `run_consumer_validator` (`:4151`) | `decode_consumer_evidence` (`:2586`), `evaluate_gate_with_consumer` (`:2600`) | `from_json` (`:3997`) + `validate` (`:4008`); gate re-validates at `:2607` | -| workflow shape | `ReleaseWorkflowShapeV1` (`:4472`) | checked in | `render_reusable_release_github` (`:2947`), `check_reusable_release_github` (`:3048`) | `from_json` (`:4493`) + `validate` (`:4511`) | - -`BuildHandoffOutput` (`:1844`) carries the contract logical selector, an explicit -Cargo package and binary, a relative path below the handoff root, an exact size, -and a deterministic `handoff_identity`; `BuildHandoffV1` (`:1862`) adds -`schema_version`, `release_id`, `source_revision`, the canonical target, the build -`strategy`, and canonically ordered outputs, all under `deny_unknown_fields`. -`validate` (`:1896`) enforces `schema_version == 1`; `safe_metadata(.., 256)` -identities; `safe_target` (`:371`); 1..=256 outputs in strictly ascending +| build handoff | `BuildHandoffV1` (`handoff.rs:43`) | `project_build_handoff` (`handoff.rs:125`), written by CLI `_capture-build` | `validate_build_artifact_dir` (`handoff.rs:243`), `reconstruct_attempt` (`handoff.rs:186`) | `from_json` (`handoff.rs:66`) + `validate` (`handoff.rs:77`), on every read | +| candidate bytes | files under `candidates/` | `stage_build_artifact_dir` (`handoff.rs:333`) / CLI staging | same | size, regular non-symlink file, exact inventory, no extras (`handoff.rs:253-286`) | +| qualification evidence | `QualificationEvidence` (core) | qualification job | `validate_qualification_artifact_dir` (`handoff.rs:292`) | identity must equal the handoff (`handoff.rs:299-304`) | +| consumer evidence | `ConsumerValidationEvidenceV1` (`consumer_validator.rs:138`) | `run_consumer_validator` (`consumer_validator.rs:323`) | `decode_consumer_evidence` (`release_plan.rs:406`), `evaluate_gate_with_consumer` (`release_plan.rs:420`) | `from_json` (`consumer_validator.rs:172`) + `validate` (`consumer_validator.rs:183`); gate re-validates at `release_plan.rs:426-428` | +| workflow shape | `ReleaseWorkflowShapeV1` (`identity.rs:65`) | checked in | `render_reusable_release_github` (`render_release.rs:276`), `check_reusable_release_github` (`drift.rs:88`) | `from_json` (`identity.rs:86`) + `validate` (`identity.rs:104`) | + +`BuildHandoffOutput` (`handoff.rs:25`) carries the contract logical selector, an +explicit Cargo package and binary, a relative path below the handoff root, an +exact size, and a deterministic `handoff_identity`; `BuildHandoffV1` +(`handoff.rs:43`) adds `schema_version`, `release_id`, `source_revision`, the +canonical target, the build `strategy`, and canonically ordered outputs, all +under `deny_unknown_fields`. `validate` (`handoff.rs:77`) enforces +`schema_version == 1`; `safe_metadata(.., 256)` identities; `safe_target` +(`crates/eggpack-ci/src/validate.rs:5`); 1..=256 outputs in strictly ascending `LogicalOutputSelector` order with no duplicates; unique non-empty -`handoff_identity` bounded to 256 bytes; `safe_identifier` (`:377`) package and -binary; non-zero sizes; and `validate_relative_path` (`:1928`) per path, rejecting -absolute roots, drive colons, NUL, `..`, empty segments, and >512 bytes. -`from_json` bounds the document at `MAX_HANDOFF_JSON` (`:1838`, 1 MiB) before -parsing; `to_json` validates before serializing. - -`project_build_handoff` (`:1944`) is pure — no I/O. It derives a deterministic -`relative_path` per selector (`candidate-direct`, `candidate-bundle-{index}`, -`candidate-archive-{sha256(source)}`, `:1960-1973`) and sorts outputs canonically -(`:1987`), setting `size: 1` as a non-zero placeholder (`:1983`) with an explicit -comment that callers must not treat it as evidence (`:1974-1977`). The runner -replaces it with the observed size and re-validates — the CLI does exactly that at -`crates/eggpack-cli/src/main.rs470`, then `validate_build_artifact_dir` -(`main.rs504`). +`handoff_identity` bounded to 256 bytes; `safe_identifier` (`validate.rs:12`) +package and binary; non-zero sizes; and `validate_relative_path` +(`handoff.rs:109`) per path, rejecting absolute roots, drive colons, NUL, `..`, +empty segments, and >512 bytes. `from_json` bounds the document at +`MAX_HANDOFF_JSON` (`handoff.rs:20`, 1 MiB) before parsing +(`handoff.rs:67-68`); `to_json` validates before serializing. + +`project_build_handoff` (`handoff.rs:125`) is pure — no I/O. It derives a +deterministic `relative_path` per selector (`candidate-direct`, +`candidate-bundle-{index}`, `candidate-archive-{sha256(source)}`, +`handoff.rs:141-153`) and sorts outputs canonically (`handoff.rs:168`), setting +`size: 1` as a non-zero placeholder (`handoff.rs:164`) with an explicit comment +that callers must not treat it as evidence (`handoff.rs:155-158`). The runner +replaces it with the observed size and re-validates — the CLI does exactly that +at `crates/eggpack-cli/src/main.rs:1077`, then re-validates at +`main.rs:1002-1004` and `validate_build_artifact_dir` (`main.rs:1033`). ### `reconstruct_attempt` -`reconstruct_attempt` (`:2005`) turns a validated handoff plus downloaded files -back into an in-memory `eggpack_core::BuildAttempt`, requiring the handoff identity -to equal the plan's release id, source revision, target, and strategy -(`:2011-2018`) and each output to be a non-symlink, regular, non-empty file. What -it deliberately does **not** re-verify: +`reconstruct_attempt` (`handoff.rs:186`) turns a validated handoff plus +downloaded files back into an in-memory `eggpack_core::BuildAttempt`, requiring +the handoff identity to equal the plan's release id, source revision, target, and +strategy (`handoff.rs:192-199`) and each output to be a non-symlink, regular, +non-empty file. What it deliberately does **not** re-verify: - It does not hash the candidate. No SHA-256 appears in the handoff at all; the reconstructed `CandidateArtifact` carries the observed size only. Byte identity is established later, by the qualification job and by the consumer validator's expected digest. - It accepts a handoff whose `size` is still the placeholder `1` without comparing - it to the observed length (`:2029-2033`), while `validate_build_artifact_dir` - (`:2080`) has no such exception and requires exact size equality. **The two - readers of the same document disagree about size enforcement.** + it to the observed length (`handoff.rs:210-214`), while + `validate_build_artifact_dir` (`handoff.rs:261`) has no such exception and + requires exact size equality. **The two readers of the same document disagree + about size enforcement.** - It synthesizes process evidence rather than observing any: `tool_summary` is - `format!("ci-handoff {target}")` (`:2049`) and `ProcessEvidence` is a literal - `CommandOutcome::Success` with `stdout_bytes: 0, stderr_bytes: 0` (`:2050-2054`). - A reconstructed attempt therefore always claims a successful process. The doc - (`:2000-2004`) says the result must still pass M003/M004 validation; these - fabricated fields are not evidence. + `format!("ci-handoff {}", target.target)` (`handoff.rs:230`) and `ProcessEvidence` + is a literal `CommandOutcome::Success` with `stdout_bytes: 0, stderr_bytes: 0` + (`handoff.rs:231-235`). A reconstructed attempt therefore always claims a + successful process. The doc (`handoff.rs:181-185`) says the result must still + pass M003/M004 validation; these fabricated fields are not evidence. ### Directory validators and path derivation -`validate_build_artifact_dir` (`:2062`) requires `candidates/` to be a real -directory (not a symlink), every handoff output present as a non-symlink regular -file with exact size, and — importantly — **no extra entries**: any non-file entry -or unlisted name is rejected, and the final count must equal the inventory -(`:2086-2105`). `validate_qualification_artifact_dir` (`:2111`) runs that first, then -decodes `evidence.json` and requires the evidence identity to match the handoff's -release id, source revision, and target (`:2118-2123`). - -`stage_build_artifact_dir` (`:2152`) creates or reuses a real output directory, -hard-links each candidate (falling back to copy, `:2144`), writes the handoff, then -**re-validates the directory it just wrote** (`:2177`), so a size mismatch fails -here. Two caveats: the handoff write is a plain `std::fs::write` (`:2175`), not an -atomic replace, unlike the CLI's `atomic_write` (`main.rs503`); and this function -has no caller outside this crate's own tests — the CLI stages inline at -`main.rs491-505` using the literals `"candidates"` and `"build-handoff.json"` -rather than the constants. `cargo_output_path` (`:2183`) derives -`//release/` after `validate_canonical_target_dir` -(`:951`), appending `.exe` for targets whose triple contains the `-windows-` -component (`:2201-2203`). The suffix is appended to the full binary name, so a +`validate_build_artifact_dir` (`handoff.rs:243`) requires `candidates/` to be a +real directory (not a symlink), every handoff output present as a non-symlink +regular file with exact size, and — importantly — **no extra entries**: any +non-file entry or unlisted name is rejected, and the final count must equal the +inventory (`handoff.rs:267-286`). `validate_qualification_artifact_dir` +(`handoff.rs:292`) runs that first, then decodes `evidence.json` and requires the +evidence identity to match the handoff's release id, source revision, and target +(`handoff.rs:299-304`). + +`stage_build_artifact_dir` (`handoff.rs:333`) creates or reuses a real output +directory, hard-links each candidate (falling back to copy, +`handoff.rs:309-331`), writes the handoff, then **re-validates the directory it +just wrote** (`handoff.rs:358`), so a size mismatch fails here. Two caveats: the +handoff write is a plain `std::fs::write` (`handoff.rs:356`), not an atomic +replace, unlike the CLI's `atomic_write` +(`crates/eggpack-cli/src/main.rs:1108`); and this function has no caller outside +this crate's own tests — the CLI stages inline at `main.rs:1020-1034` using the +literals `"candidates"` and `"build-handoff.json"` rather than the constants. +`cargo_output_path` (`handoff.rs:364`) derives +`//release/` after +`validate_canonical_target_dir` (`crates/eggpack-ci/src/policy.rs:555`), +appending `.exe` for targets whose triple contains the `-windows-` component +(`handoff.rs:380-384`). The suffix is appended to the full binary name, so a dotted name resolves to `tool.cli.exe`; this agrees with `discover_candidate` in `eggpack-core` and with Cargo's own naming. @@ -123,60 +135,69 @@ dotted name resolves to `tool.cli.exe`; this agrees with The one place the producer runs foreign, caller-supplied code. -`ConsumerValidatorV1` (`:3873`) can specify `schema_version`, one -`LogicalOutputSelector`, an interpreter, a repository-relative `script` path, a +`ConsumerValidatorV1` (`consumer_validator.rs:43`) can specify `schema_version`, +one `LogicalOutputSelector`, an interpreter, a repository-relative `script` path, a timeout, and stdout/stderr limits. There is deliberately no arbitrary executable field, no shell string, no environment map, and no caller-supplied argument vector -(`:3864-3870`). `ValidatorInterpreterV1` (`:3859`) has exactly one variant, -`Python3`, and host mapping is finite — `python3` on Linux/macOS, `python` on -Windows — via `python_interpreter_exe` (`:4032`) delegating to the `cfg!`-testable -`python_interpreter_exe_for_windows` (`:4037`). `validate` (`:3909`) enforces +(`consumer_validator.rs:34-40`). `ValidatorInterpreterV1` +(`consumer_validator.rs:29`) has exactly one variant, `Python3`, and host mapping +is finite — `python3` on Linux/macOS, `python` on Windows — via +`python_interpreter_exe` (`consumer_validator.rs:219`) delegating to the +`cfg!`-testable `python_interpreter_exe_for_windows` +(`consumer_validator.rs:224`). `validate` (`consumer_validator.rs:79`) enforces `schema_version == 1`; interpreter is `Python3`; `validate_release_input_path` -(`:924`) on the script (bounded relative, no absolute root, no drive colon, no -backslash, no `.`/`..`/empty segments, per-segment ≤128, total ≤512); `timeout_ms` -in 1 000..=600 000; both output limits in 1..=8 000 000. `from_json` (`:3892`) -bounds the document at `MAX_VALIDATOR_JSON` (`:3846`, 64 KiB). Separately, -`project_release_plan_with_consumer` (`:2536`) requires ≤256 validators, each -target to exist in the `CIPlan`, and each selector to be an actual build output of -that target's bindings (`:2546-2567`). - -`ConsumerValidationRequest` (`:4046`) supplies the validator plus absolute -`script_path`, `candidate_path`, `work_dir`, the `expected_size` and +(`crates/eggpack-ci/src/policy.rs:525`) on the script (bounded relative, no +absolute root, no drive colon, no backslash, no `.`/`..`/empty segments, +per-segment ≤128, total ≤512); `timeout_ms` in 1 000..=600 000; both output limits +in 1..=8 000 000. `from_json` (`consumer_validator.rs:62`) bounds the document at +`MAX_VALIDATOR_JSON` (`consumer_validator.rs:14`, 64 KiB). Separately, +`project_release_plan_with_consumer` (`crates/eggpack-ci/src/release_plan.rs:356`) +requires ≤256 validators (`release_plan.rs:363-365`), each target to exist in the +`CIPlan` (`release_plan.rs:368-374`), and each selector to be an actual build +output of that target's bindings (`release_plan.rs:375-386`). + +`ConsumerValidationRequest` (`consumer_validator.rs:233`) supplies the validator +plus absolute `script_path`, `candidate_path`, `work_dir`, the `expected_size` and `expected_sha256` to verify against, release identity strings, an optional -`AtomicBool` cancellation flag, and an optional exact PATH override (`:4071`). The -CLI populates it at `main.rs766-778` with the size and digest taken from the -**qualification evidence**, not from the handoff (`main.rs770-771`), and refuses -outright to run if that evidence is not `Passed` (`main.rs729-734`). - -Candidate identity is observed *before* any execution (`:4198-4200`) so evidence -always carries validated linkage; a synthetic `evidence_size.max(1)` / all-zero -digest stand-in is substituted when the candidate is itself the failure point -(`:4206-4211`). `run_consumer_validator` (`:4151`) is then fail-closed throughout. -Caller *misuse* returns `Err(CiError)`; validator *outcomes* return bounded -evidence. +`AtomicBool` cancellation flag, and an optional exact PATH override +(`consumer_validator.rs:254-258`). The CLI populates it at +`crates/eggpack-cli/src/main.rs:1354-1366` with the size and digest taken from the +**qualification evidence**, not from the handoff (`main.rs:1276-1277`), and +refuses outright to run if that evidence is not `Passed` (`main.rs:1235-1240`). + +Candidate identity is observed *before* any execution +(`consumer_validator.rs:369`) so evidence always carries validated linkage. A +candidate that could not be read is recorded as **absent** — size `0`, digest +`None` (`consumer_validator.rs:378-381`) — never as a synthetic digest. +`run_consumer_validator` (`consumer_validator.rs:323`) is then fail-closed +throughout. Caller *misuse* returns `Err(CiError)`; validator *outcomes* return +bounded evidence. | Step | Citation | Result on failure | |---|---|---| -| re-validate config; script, candidate, work dir absolute; work dir a real directory; `expected_sha256` 64 lowercase hex; identity strings in bounds | `:4154-4184` | `Err` | -| candidate hashed, size and digest compared to expected | `:4200-4219` | `Failed(CandidateMismatch)` | -| script is a regular non-symlink file of 1 B..=1 MiB | `:4190-4197`, `:4220` | `Failed(ScriptUnavailable)` | -| restore POSIX exec bits on the transferred candidate | `:4230-4237`, `:4281` | `Failed(CandidateMismatch)` | -| bounded `python --version` preflight must contain "Python 3" | `:4256-4264`, `:4372` | `Failed(InterpreterUnavailable)` | -| fixed `python3