Skip to content

Consolidate producer correctives and reconcile plans - #3

Merged
dbowm91 merged 47 commits into
mainfrom
feat/producer-convergence-correctives
Nov 17, 2026
Merged

dbowm91 merged 47 commits into
mainfrom
feat/producer-convergence-correctives

Conversation

@dbowm91

@dbowm91 dbowm91 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Consolidate the M003j planning closure with producer corrective work on feat/producer-convergence-correctives.
  • Reconcile the registry, subsystem status labels, stale implementation-plan statuses, strict M003k closure record, and citation counts.
  • Make the SHA-256 rejection assertions Clippy-compatible without changing behavior.
  • Shorten CLI fixture temp roots so Windows Cargo builds do not inherit long test-name paths; keep failed-build diagnostics limited to typed process evidence and byte counts.

Verification

  • scripts/check-local.sh passed under native arm64.
  • cargo test -p eggpack-cli --test operator_commands --locked: 30 passed.
  • PR CI run 43528692083 passed all four lanes; matching push run 43528684918 also passed all four lanes.
  • Rebased the affected architecture citations by test function name and checked all 64 citation ranges into eggpack-ci/src/tests.rs.
  • Confirmed the six stale branch tips were ancestors of the consolidated commit, then deleted those remote refs after CI passed.

doc and others added 30 commits October 9, 2026 20:43
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.
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.
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.
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) <noreply@anthropic.com>
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.
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.
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.
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.
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.
Close Build/Qualification M009. The canonical specification names nine
operator commands; the binary now exposes six of them — check, plan, package,
qualify, collect, manifest — so a producer can construct, qualify, finalize,
and aggregate a release on a workstation without a hosted workflow run.

The new commands and the existing `ci _*` runners call the same core
functions and the same serialization helpers, and the byte-identity between
them is proven by test. `eggpack-core` needed no change at all, which is the
strongest available evidence that the new surface is thin wiring over closed
APIs rather than a second implementation of the pipeline.

Close CI/Release M003m. The CI crate's consumer-validator execution no longer
has its own process runner: it routes through the workspace's single bounded
runner, which terminates the whole process group and bounds its reader-thread
joins. The CI-local runner, its bounded readers, and its unbounded drain are
deleted. The consumer validator's contract, the outcome mapping, and the
generated workflow bytes are unchanged.

Both records carry their residual findings explicitly: the interpreter banner
is now matched on stdout only, the CI consumer validator's environment is the
shared narrow allowlist, output-limit termination moves earlier for the build
and git paths, and the quickstart walkthrough is verified on Linux only.
Build/Qualification M009 and CI/Release M003m are closed. The registry, the
build/qualification roadmap, and the CI/release-orchestration roadmap are
reconciled to the new state: CI M003n is in progress and Planning Hygiene M003
is the only remaining ready milestone.
`qualify`, `collect`, and `manifest` take the per-target artifact root --
the directory holding one subdirectory per target, each with that
target's build-handoff.json, evidence.json, and candidates/ -- but the
flag was named `--candidates-dir`, after the `candidates/` directory
inside it. A user who read the flag literally got
`eggpack: build handoff is unavailable`, with no hint about what was
expected.

Rename the flag to `--artifacts-dir` and rename the locals that hold
the artifact root to match. The CLI is not published and has no
external consumers, so the rename is clean. `write_build_artifacts`'s
`candidates_dir` is the real candidates directory and is left alone.

Rename only: the flag's meaning, accepted values, and every command's
outcome are unchanged.
The quickstart's §1 told the reader to create the scratch project with
`mkdir -p eggdemo/out && cd eggdemo`, which places it inside the Eggpack
checkout when followed from the repository root. Cargo then treats the
scratch package as an undeclared workspace member and the `package` step
fails with "current package believes it's in a workspace when it's not".

The walkthrough now says to create the scratch project outside the Eggpack
checkout, and says why. The command sequence itself is unchanged and was
re-verified.

Also corrects a now-stale framing sentence in architecture/cli.md: the
`--artifacts-dir` naming detail is no longer a place where the flag and the
implementation disagree, so the lead-in no longer claims that it is.
Three closure records wrote a historical range as two code spans, so the first
span read as a literal path that does not exist. Each now names the directory
instead.
M003n (consolidation half). Three producer implementations were duplicated
byte-for-byte; this makes each of them one implementation without changing a
single rendered byte.

- eggpack-ci: the three drift check functions now render and delegate to one
  private comparison, `compare_workflow_bytes`, which keeps the size bound,
  the CRLF-to-LF-only normalization of both sides, the equality test, the
  first-difference offset with the shorter length as the fallback, and the
  `DriftReport` construction in that order.
- eggpack-ci: `render_release_github_inner` is decomposed into named private
  helpers, one per concern: policy and shape validation, release-identity
  mode resolution, trigger and input cross-checks, tool-pin and
  emulated-runtime validation, workflow header and permission emission, one
  helper per job, step emission, and the static output guards. The public
  `render_release_github` / `render_reusable_release_github` signatures are
  unchanged and the rendered bytes are byte-identical.
- eggpack-github: there is now one staging-payload builder.
  `prepare_staging_payload` and `prepare_staging_payload_with_presentation` are
  thin entry points into it; the presentation selects only the installer
  surface, and every other step exists once.

No public item changed in either crate, no schema change, no dependency
change, and `Cargo.toml` / `Cargo.lock` are untouched.

Evidence: the pre-change rendered workflows, drift reports, and staging
payloads were captured as byte-exact baselines before any edit and compared
against the post-change output; all are identical. The baselines are now
pinned by committed golden tests.

Architecture citations in architecture/ci.md, architecture/ci-rendering.md,
and architecture/github.md were re-based by symbol name for the regions this
change moved.
Close CI/Release M003n on implementations `bf0acfe` and `028db4a`.

The three duplicated implementations the post-implementation review found are
gone: one drift comparison replaces three byte-identical check bodies, one
staging-payload builder replaces two copies that were 85.5% identical, and the
845-line `render_release_github_inner` is decomposed into named private helpers
by concern.

The CI crate's single 12,221-line source file is now a 14-file module tree,
with the crate root reduced to 59 lines. The public API did not change: a
cargo public-api dump is byte-identical before and after, 27 items were
widened to pub(crate) for sibling access, and nothing became pub.

The milestone's defining constraint was that no output may change. That was
met by construction: baselines were captured before any edit and compared
after, byte for byte, for every rendered workflow, every drift report, and
every staging payload.
Re-base the `architecture/` citation set and per-crate line counts by symbol
name against the measured tree SHA fa82486, so the documents describe the
review chain's result rather than the tree before it landed.

- `architecture/overview.md` pins the baseline SHA, restates the per-crate
  counts (measured, not estimated), gives the CI crate's 14-file breakdown in
  its own card, closes the two standing gap notes, and appends the
  citation-verification entry for this pass. Earlier entries are unchanged.
- `architecture/ci-consumer-seam.md` is re-based onto the CI crate's module
  tree, and its "independent process runner" section is rewritten: CI M003m
  replaced that runner with core's shared bounded runner.
- `architecture/testing-and-portability.md` is re-measured: the CI crate's test
  topology, the ignored-test count, and the CLI crate's integration targets
  all changed under the chain.
- `determinism.md`, `validation-model.md`, `core-finalization.md`,
  `manifest.md`, `bootstrap.md`, `contract.md`, `cli.md`, `github.md`,
  `core.md`, and `process-execution.md` are re-based anchor by anchor.
- `AGENTS.md`'s current handoff is rewritten as a single statement sourced
  from `plans/registry.md`.
- `crates/eggpack-cli/README.md` is verified rather than rewritten; two
  incorrect outputs are corrected to the observed ones.
- The registry, the three affected subsystem roadmaps, and the ADR index
  register ADR-0006 and all seven review-chain milestones.

No production code, manifest, dependency, schema, or existing closure record
changed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CI/Release M003l implemented accepted ADR-0006 and made the all-zeros SHA-256
sentinel illegal in a release manifest. Five bootstrap test fixtures used that
value as the stand-in for "a digest that does not match the bytes being
installed", so the manifest no longer validated: three tests aborted at setup
and the installers' own size-and-digest check was silently not running.

The fixtures now use a well-formed but wrong digest, so the manifest validates
and the installer's own check is what rejects the artifact. Each site still
asserts that the installer refuses the artifact and leaves nothing behind, so
the coverage the tests were written for is intact. A well-formed mismatch is
also the realistic case; the all-zeros case is now caught earlier, by the
manifest validator.

The acceptance rule did not move: the all-zeros sentinel stays refused
everywhere, and `eggpack-manifest` and ADR-0006 are untouched.

Verified with the full local gate: ./scripts/check-local.sh exits 0 (fmt,
check, clippy -D warnings, the per-crate and workspace test suites, doc, tree,
package for all seven crates, and the 1.89.0 MSRV lane). The workspace suite
is 337 passed, 0 failed.
…gth gap

A post-implementation review of Build/Qualification M007 and M008 found two
defects in the newly written code, plus one latent gap that the change from
the pre-change helpers introduced.

The floor reader treated a `GLIBC_`-prefixed version name that is not a plain
numeric version as a reason to abandon the whole scan. `GLIBC_PRIVATE` and
`GLIBC_ABI_DT_RELR` are real and common, so the abandonment happened on
ordinary system binaries — and it discarded every other requirement in the
image, including one that contradicts the declared floor. A binary requiring
glibc 2.38 was therefore recorded as `Unverified` against a 2.17 floor, and
`Unverified` is admissible, so the target passed qualification with a false
declared floor. This directly contradicts the milestone's own rule that a
contradicted floor must fail closed and must not be reported as `Unverified`.

The reader now visits every requirement: an unrecognized name is recorded and
the scan continues, and a numeric requirement that contradicts the declared
floor decides the status on its own. An image whose numeric requirements fit
the floor but that also carries an unrecognized name is still `Unverified`,
because the floor is then not proven.

The virtual-address translation added an unchecked `u64` addition whose
operand comes straight from an ELF program header and is not bounded against
the file length. A crafted image overflowed it, which panics in a dev or test
build and wraps in a release build. Every other offset computation in the
module is overflow-checked; this one now is too.

The digest helper checked for an empty file before the read but never
refused a read that produced zero bytes, so a file truncated in between could
produce a zero-length digest record where the pre-change helper refused one.
A zero-length read result is now refused on its own terms.

Verified with `cargo test -p eggpack-core --all-targets --all-features
--locked` (85 passed, 0 failed) and `cargo clippy -p eggpack-core
--all-targets --all-features --locked -- -D warnings` (clean). The floor fix
was additionally checked against real system binaries: `/usr/bin/getent`,
`/usr/bin/iconv`, and `/usr/bin/gencat` now report `NotSatisfied` against a
2.17 floor, where they previously reported `Unverified` and passed.
D1: `eggpack qualify` no longer destroys its own input candidates when
`--output-dir` names the same location as `--artifacts-dir`. The command
refuses the collision before anything is written, and every staging site
(`qualify`, `ci _qualify-target`, `ci _capture-build`, `write_build_artifacts`)
now stages through one helper that copies through a fresh temporary sibling
and renames it into place, so a destination that resolves to its source can
never lose the source's bytes to a copy.

D2: `eggpack qualify` accepts `--qemu-sysroot` and threads it into the
qualification runtime, exactly as `ci _qualify-target` does, so an emulated
target is not qualified with weaker evidence than the CI path produces.

D3: the operator family accepts `--identity-mode` and `--consumer-validators`.
A v-prefixed stable semver release and a consumer-validated release are now
planned and aggregated locally: `collect` projects the consumer-aware graph
and aggregates with the consumer evidence, exactly as `ci _aggregate` does.

D4: the producer policy and both bindings documents are read as TOML or JSON,
the same two encodings the CI path accepts. The JSON document is normalized
into the canonical document shape and re-read by the same strict core parser,
so one validator stays authoritative for both encodings.

D5: `eggpack manifest` is now self-checking. Every archive member is read back
out of the finalized `.tar.gz` and compared with the candidate bytes the
manifest records, and the derived document is compared with the collected
`release-manifest.json` when it is present beside the finalized root. A stale
or tampered artifacts directory fails closed instead of yielding a manifest
that describes bytes the release does not contain.

D6: `collect` names the reason its aggregation failed.

D7: `absolutize_cli_path` rejects `..` in absolute paths as well as relative
ones: one rule for both forms.

D8: `--selected` refuses an empty alias element with a clear diagnostic
instead of failing downstream as an out-of-bounds alias.

D9: `manifest` re-projects the release graph the way `collect` does and
forwards its evidence references, so the derived and the collected manifest
cannot drift apart.

D10: the crate README qualifies its one-line-failure claim: the operator
commands print exactly one line on stderr, while the top-level dispatch
prints the usage block.

`eggpack manifest` now requires the build and qualification bindings so it
can project the same graph `collect` projects.

Cargo.lock gains `tar`, `flate2`, and `sha2` as dependencies of `eggpack-cli`;
all three were already in the workspace lock through `eggpack-core` and
`eggpack-bootstrap`.
…refusal

The post-implementation review of the CI/Release chain found one reachable
panic and two diagnostics that had become inaccurate.

The renderer asserted that every generated working-directory name is a fixed
safe relative path of at most 128 characters. The consumer-evidence directory
is `./eggpack-consumer/{build_job_id}`, and the build job id is derived from
the contract's target triple. A contract may legally declare a triple at the
contract's own name bound of 128 characters, which produces a 153-character
directory name and tripped the assertion. A caller-supplied contract could
therefore panic the renderer. The check is now a refusal that returns an
error, so the renderer fails closed on a document it cannot represent
safely.

Two digest diagnostics said a refused digest "must be lowercase hex" or "must
be 64 lowercase hex characters". ADR-0006 narrowed the acceptance set, so a
refused digest is not always a formatting problem: the all-zeros digest is
perfectly good lowercase hex and is refused for a different reason. The
diagnostic now names the actual reason, so it does not misdescribe a digest
that is in fact well-formed.

Verified with `cargo test -p eggpack-ci --all-targets --all-features
--locked` (79 passed, 0 failed) and `cargo clippy -p eggpack-ci
--all-targets --all-features --locked -- -D warnings` (clean). The new
regression test was confirmed to fail against the previous assertion.
A follow-up review of the 2026-10-23 post-implementation review chain found
defects in the chain's own newly written code. The chain is registered here as
a second corrective chain, and each milestone keeps its own plan and closure
record so that no closure history is rewritten.

Build/Qualification M007a closes a zero-length digest record the M007
consolidation could still produce: the canonical helper refused an empty file
before the read but not a read that produced zero bytes, so a file truncated in
between could produce one. The pre-change helper refused it after the read.

Build/Qualification M008a closes a fail-open in the M008 floor reader. It
abandoned its scan at the first `GLIBC_`-prefixed name that is not a plain
numeric version, and `GLIBC_PRIVATE` and `GLIBC_ABI_DT_RELR` are common, so
the abandonment discarded every other requirement the image carried —
including one that contradicted the declared floor. A binary requiring glibc
2.38 was therefore recorded as `Unverified` against a 2.17 floor, and
`Unverified` is admissible, so the target passed qualification with a false
declared floor. This contradicts the milestone's own rule that a contradicted
floor must fail closed. The reader now visits every requirement, and the
virtual-address translation no longer overflows.

Build/Qualification M009a closes ten defects in the M009 operator family. The
first is a data-destruction defect: `qualify` staged each candidate with a
hard link and, on failure, a plain copy, so when `--output-dir` equalled
`--artifacts-dir` the copy fallback truncated the shared inode and zeroed the
operator's own input candidate bytes. The rest close the operator family's
gaps against the CI path it stands in for: emulated qualification without a
sysroot, no identity-mode or consumer-validator surface, TOML-only input, and
a manifest that reported success for archive members it had not checked.

CI/Release M003o closes a reachable panic in the release-workflow renderer —
the generated-directory check was an assertion, and a legal 128-character
contract target produces a 153-character directory name — and two digest
diagnostics that named a formatting problem where ADR-0006 refuses the
well-formed all-zeros digest.

The registry, the Build/Qualification and CI/Release roadmaps, and the
`AGENTS.md` handoff are updated to carry both chains. No milestone is
registered ready or in progress.
`eggpack manifest` requires --build-bindings and --qualification-bindings;
the README invocation omitted both.
…r tree

The concurrent CLI/CI/core corrective commits (c17bdbe, d2fbd07, b205de6)
moved lines in the CLI, CI, and core crates, so the anchors this branch had
already re-based went stale again. Re-base them by symbol name and by
content-verified line match: 291 anchors moved by exact content match, and
the cases whose content genuinely changed were re-pointed by hand after
reading the new source (consumer_validator.rs, ci/policy.rs, mkdir_step,
digest.rs, the CI job emitters, and the release-plan input reader).

Also update the counts the moved code invalidates: the crate table, the core
and CI crate cards, the CLI crate card and its new file map, the CI and CLI
test-attribute counts, and the core file map. Document the operator family's
new surface (--qemu-sysroot, --identity-mode, --consumer-validators, TOML or
JSON input documents, the self-checking manifest, the qualify same-directory
refusal, and non-truncating staging) in architecture/overview.md and
README.md, pointing at cli.md rather than duplicating it.

The CI crate's mkdir_step is now fallible and the SHA-256 diagnostics name
the refusal reason; both claims are corrected rather than carried forward.
The record predates the CI module split, so its eggpack-ci/src/lib.rs
anchors no longer resolve. Re-point them by symbol name into policy.rs,
runner.rs, render_release.rs, and the core crate, and confirm each cited
line holds what the sentence claims.
Two further statements in the Planning Hygiene M003 closure record repeated
the over-strong 'no anchor was left indicative' claim; qualify them the same
way as the table and the section heading.
…ed counts

The 'Anchors checked: 2510 file:line citations' figure counted every numeric
line-reference token, bare ':N' references included, not distinct file:line
citations. State the measured counts (1144 file:line tokens across 21
documents in architecture/, 181 more in plans/) with the commands that produce
them, and restate the 'left indicative: 0' claim to match the 418 surviving
range-style anchors. Drop ci.md and ci-rendering.md from the 'confirmed
rather than re-pointed' list, since both carried uncorrected prose errors.

Apply the same correction to the two matching claims in the Planning Hygiene
M003 closure record.
Worker and others added 17 commits October 23, 2026 20:01
README.md: add a section for the six operator commands (check, plan, package,
qualify, collect, manifest), qualify the 'pure file-in/file-out' claim to the
ci family, and note that package performs a real Cargo build.

planning-and-governance.md: re-pin the code baseline. overview.md: record the
pending 0.1.1 patch release and make the pre-split CI citation explicitly
historical. core-build.md: cross-reference the floor verification status.
registry.md and AGENTS.md: include Bootstrap M003a in the closed-chain
enumeration and cite the two missing closure records. bootstrap roadmap:
disambiguate the two unrelated milestones that share the identifier M003a.
007/003l/003m/003n closure records: re-base every stale anchor by symbol
name into the CI module tree and the current core sources. Preserve the
verified substantive claims (CI-local runner deleted, no process spawning in
the CI production region, exactly two run_interpreter_bounded call sites).

ci-consumer-seam.md: correct the citation-state note, which contradicted its
own 'mod tests;' anchor.
core.md: pin the baseline to fa82486, re-measure the file map (8750 lines
across six files), add the missing src/floor.rs row, and re-base
run_git_bounded, host_matches_target, and the SHA-256 re-export by symbol
name. contract.md: update the crate size to 2449 lines and re-base the four
inline call-site anchors.
The citation-verification state in `architecture/overview.md` and the matching
claims in the planning-hygiene closure record carried counts that were correct
when they were measured, but the re-base itself moved them: the re-based
anchors are additional citations, so the tree now holds more of them than the
note says.

The counts are re-measured against the current tree and corrected:

- `architecture/` holds 1157 `file:line` citation tokens across 21 documents
  (1101 of them into `.rs` files), not 1144 (1086);
- `plans/` holds 186 more, so 1343 across `architecture/` and `plans/`, not
  181 and 1325;
- the directory carries 429 range-style anchors across 402 lines of 16
  documents, not 418 across 391;
- the per-document range-anchor line counts are corrected for
  `ci-rendering.md` (57), `cli.md` (40), `validation-model.md` (26), and
  `overview.md` (3, which the list omitted), and the list now sums to the
  stated 402.

The measurement commands are unchanged and are printed beside the numbers, so
the claim stays checkable rather than merely asserted.
…bility event

The architecture re-base left three areas with stale anchors. This closes them.

`architecture/contract.md` carried 198 anchor tokens pointing at the contract
source as it stood before `3ef806f` added 147 net lines, so the anchors drifted
progressively across the file. Every one is re-based by symbol name, reading
each target line to confirm it holds what its sentence claims. Three of the
re-based lines no longer held their claim, and three content corrections
follow from the re-base: only an unresolvable target or alias is a
`TargetMismatch` finding while every other expansion failure is an
`InvalidObservation`; the inline test count is 26; and the conformance test
count is 12.

`architecture/manifest.md` still described the manifest crate's layout as it
stood before ADR-0006 inserted the SHA-256 acceptance set. The function table
is re-based, three rows are added for the acceptance authority — `Sha256Error`,
`ALL_ZEROS_SHA256`, and `validate_sha256_hex` — and the inline test count is
corrected to 28. The publication section now records ADR-0006 as the
compatibility event it is: the all-zeros digest is refused everywhere,
`ReleaseManifest` stays at `schema_version: 1`, the published crate takes a
`0.1.1` patch release that is a separate human action and has not been
performed, and `eggup-eggpack` is named as the affected downstream consumer
with the acceptance change spelled out. That is what ADR-0006 §5.4 requires,
and it was missing.

`plans/adrs/ADR-0006-*.md` §2 described the divergence that motivated the
decision, with locations as of the ADR's date. The ADR had no dating language
and the section said "Today:", which is now false — the GitHub crate rejects
the all-zeros sentinel too. One dated note scopes the table, and the word
"Today" becomes "At this ADR's date".

`plans/implementation/**` are plans written before their implementation, and
their citations describe the tree they targeted; those were correct when
written and are part of the record. Four of them now carry one dated note
naming their baseline and pointing forward to each construct's current home,
so a reader is not left with a dead pointer. The anchors themselves are
unchanged.

Every citation introduced here was verified by reading the line it names.
ADR-0006 §5.2 and §9 obligate the published `eggpack-manifest` crate to
take a `0.1.1` patch release carrying the narrowed digest acceptance set,
and §5.4 requires that narrowing to be recorded as a compatibility event
in a release-manifest closure record. Neither obligation was tracked.

The crate has carried `0.1.1` in-tree since `9cf0bf8` and its sources have
not changed since, but crates.io exposes only `0.1.0`. No plan, closure
record, registry row, or roadmap entry tracked the publication, and the
release-manifest roadmap asserted that no further Release Manifest
implementation was implied. A milestone accepted by an ADR and never
planned survives indefinitely, because no code change would ever fail a
test.

M004 owns the publication and the compatibility record. Reviewing the
package surfaced a second gap: the `0.1.1` package carries two narrowings
of the published crate's public acceptance set, not one. The digest rule
is ADR-0006's. The second came from `3ef806f`, which made
`ReleaseManifest::validate` measure its canonical encoding, so a manifest
whose encoding exceeds `MAX_DOCUMENT_BYTES` is refused where `0.1.0`
accepted and serialized it — a document `0.1.0` could emit but not read
back. That narrowing was recorded only as an implementation note in
`architecture/manifest.md`, so it would have shipped unannounced. Both are
now recorded on both surfaces ADR-0006 §5.4 names.

Also corrects `architecture/manifest.md`: `ReleaseManifest::validate` was
cited as `:239-322`, which overshoots into `to_json`'s doc comment; the
function is `:239-305`. `ALL_ZEROS_SHA256` and `check_document_bound` are
marked private in the key-types table, and the private
`check_document_bound` is listed at all.

The registry carried the 2026-10-23 review-chain paragraph twice; the
duplicate is removed and the superset retained.
…the run

The first hosted CI run of the 2026-10-23 review chain (run 40207520563 on
d4d5e43) failed on macOS. The Linux and Windows lanes passed; two CI-crate
tests reported `Failed(InterpreterUnavailable)` where they expected
`Failed(OutputLimit)`. The local gate never saw it, because the same tests
pass on Linux.

The shared bounded runner terminates the supervised process group on its
cancellation, deadline, and output-bound paths, and treated a failed group
signal as a hard failure. A group's only member is the supervised child.
When that child has already exited it stays in the group as a zombie until
it is reaped, and the group holds no process at all once it is reaped.
Linux signals a zombie successfully; macOS reports `ESRCH` for it.

A validator that writes past its output bound and exits immediately
therefore terminated cleanly on Linux and failed on macOS, where `ESRCH`
was taken as a failed termination. `command-group` documents that a group
which has already exited produces an error from `kill`, so this was an
assumption the runner should not have made.

`ESRCH` is the kernel's own statement that the group holds no process, so
there is provably nothing left to terminate and the guarantee that no
descendant outlives the run still holds. The new helper treats it as
success and leaves every other errno a hard failure, so a group that
exists but cannot be signalled still fails the run closed. The check is
Unix-only: a Windows job object uses a different error space, where the
value 3 is `ERROR_PATH_NOT_FOUND` rather than `ESRCH`.

The same race exists on the deadline and cancellation paths — a child that
exits just as the deadline passes can be reaped before the kill — so all
three paths route through the one helper.

The CI crate's error-to-outcome mapping is unchanged. Its contract is "the
validator did not pass", which it reports faithfully; widening it to
distinguish launch failures from termination failures would change a
public surface to paper over a defect in its callee.

The regression test reaps a child and then signals its group. It fails
without the fix and passes with it, on Linux as well as macOS.

The architecture deep dives are re-based onto the corrected tree: 85
citations in `architecture/process-execution.md` and 38 more across the
other deep dives, re-based by content anchor rather than by arithmetic, and
every landing verified. The `eggpack-core/Cargo.toml` citations are
re-based the same way, because the new platform-specific dependency moved
that file's lines.
Surfaces the bounded runner's error message on the CI consumer-validator
path so the macOS lane's log names which runner path failed. Reverted once
the cause is identified.
The macOS lane of hosted CI run 40260732267 still failed after the first
ESRCH fix, with the same symptom: `Failed(InterpreterUnavailable)` where
the test expected `Failed(OutputLimit)`. A temporary diagnostic on the
consumer-validator path named the runner error, and a second one on the
group signal named the errno: `EPERM`, "Operation not permitted" — not
`ESRCH`.

So macOS refuses the whole group signal when the group still holds the
unreaped zombie of a child that has exited, and reports `EPERM` for it.
Linux signals the same zombie successfully, which is why the local gate
never saw this and the Linux lanes were always green.

Deciding on the errno alone was the wrong rule: `EPERM` cannot mean "the
group is empty" on its own. The rule is now "a failed group signal may be
ignored when there is nothing left to terminate", and it is decided by
observing the child rather than by reading the errno. `try_wait` reports
whether the supervised child has already exited, and reaps it while doing
so. A child that has exited is not a process that can outlive the run, so
the failure is benign — the same reason `ESRCH` is benign. A group that
holds a *live* process and still cannot be signalled remains a hard
failure, so the run fails closed.

A descendant that outlives the child is still caught: the drain budget
detects a reader parked at its limit, which means a descendant holds the
write end of a pipe, and the run fails closed with the output-limit
outcome.

The decision is extracted into `group_signal_failure_is_benign` so it can
be pinned directly: `ESRCH` is benign, `EPERM` is benign only when the
child has exited, and `EPERM` with a live child is not benign.

The architecture deep dives are re-based onto the corrected tree again, by
content anchor rather than by arithmetic, and every landing is verified.
The 2026-10-23 review chain had never run on hosted CI. Its first run
failed, and the failure was a real defect in the shared bounded runner
rather than an environment problem.

The runner terminated a supervised process group on its cancellation,
deadline, and output-bound paths, and treated a failed group signal as a
hard failure. macOS refuses to signal a group that still holds the
unreaped zombie of an exited child, and reports the whole signal as
`EPERM`; Linux signals the same zombie successfully. A validator that
wrote past its output bound and exited immediately therefore terminated
cleanly on Linux and failed on macOS, where the consumer-validator — which
maps every runner error onto `InterpreterUnavailable` — reported an
output-bound violation as "the interpreter could not be launched".

Both symptoms fail closed, so neither could let an invalid release
through. The second cost an operator the wrong first place to look.

The rule is now that a failed group signal may be ignored when there is
nothing left to terminate, decided by observing whether the supervised
child has exited rather than by reading the errno. A group holding a live
process that cannot be signalled still fails the run closed.

Hosted runs `40207520563`, `40260732267`, `40261344903`, and `40261826255`
failed on macOS; `40263176191` on `27cb16c` is green on all four lanes.
The two diagnostic commits are kept — they are the evidence for the
measured errno — rather than rewritten out of history.
ADR-0006 §5.2 and §9 obliged the published crate to take a `0.1.1` patch
release, and §5.4 required that narrowing to be recorded as a compatibility
event in a release-manifest closure record. Neither was tracked: the crate
had carried `0.1.1` in-tree since `9cf0bf8`, crates.io exposed only
`0.1.0`, and the release-manifest roadmap claimed no further Release
Manifest implementation was implied.

`eggpack-manifest 0.1.1` is published to crates.io from publication source
commit `4ce4fb850ffa0e141f1a807b60c150173507a92b`, checksum
`352c3e327159615b763298e911e239f1decc4a2c9e28c28be8ddd28e50515e37`, not
yanked, tagged `eggpack-manifest-v0.1.1`. Hosted run `40263953007` is green
on all four lanes; `0.1.0` remains published and resolvable with its
original checksum.

The closure record is the surface ADR-0006 §5.4 names, and it covers the
two narrowings the package actually carries. The digest rule is ADR-0006's.
The second came from `3ef806f`: `ReleaseManifest::validate` now measures its
canonical encoding, so a manifest whose encoding exceeds `MAX_DOCUMENT_BYTES`
is refused where `0.1.0` accepted and serialized it — a document `0.1.0`
could emit but not read back. That narrowing was recorded only as an
implementation note in `architecture/manifest.md`, so it would have shipped
unannounced. Both are now recorded, with `eggup-eggpack` named as the
affected consumer in each.

The consumer-side obligation is not discharged and is not claimed here:
`eggup-eggpack` pins `=0.1.0`, an exact requirement, so publishing `0.1.1`
does not move it, and its bump needs a plan registered in the Eggup
repository. Nothing in Eggup was changed. The narrowing breaks nothing in
the consumer today — its only all-zeros construct already asserts that the
digest must be refused.

ADR-0006 gains a dated note recording the discharge; its decision body is
not rewritten.
@dbowm91
dbowm91 merged commit a8edf52 into main Nov 17, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant