eggpack-core 0.1.2

Producer-side planning, qualification, local finalization, and manifest aggregation for Eggpack
Documentation
# eggpack-core

Producer-side planning, bounded Cargo building and qualification, local finalization, and manifest aggregation. PackConfig/ReleasePlan planning is pure. The first-party builder accepts strict `BuildBindingsV1` package/bin mappings for contract logical slots, checks the declared Rust/cargo-zigbuild tool intent, executes direct Cargo process groups with time/output bounds, and returns exact non-empty candidate paths. Each `BuildAttempt` carries the release id and source revision from its `ReleasePlan`. `QualificationBindingsV1` selects one exact candidate smoke check per executable target; fixed argv is passed directly to that candidate, with no shell, executable field, environment map, or repository script. `qualify_target` reconciles the plan, build bindings, attempt, candidate inventory, and qualification bindings; validates ELF, PE/COFF, or thin Mach-O format and architecture; hashes exact candidate bytes before and after execution; and returns deterministic identity-bound evidence. Native and deferred-native matching-host runs plus finite Linux QEMU user-mode runs use bounded process groups. Evidence contains host/classification/support, the compatibility-floor verification status, per-candidate size/hash/format/architecture, and bounded process outcomes, never local paths, output contents, or environment values.

`finalize_release` accepts identity-matched build and qualification evidence for the exact planned target set, enforces required-target qualification gates, copies direct and bundle candidates under contract names, and creates SHA-256 sidecars from final bytes. Archive output currently accepts only an explicit `ArchiveEncoding::TarGzip`; the contract archive asset filename must end in `.tar.gz`. Archive member names come from contract member paths, while tar/gzip timestamps and ownership metadata are normalized for deterministic output. Manifest v1 is constructed only after all artifacts and sidecars are complete, so its artifact digests cover final release bytes and its member digests cover the bytes written into the archive. The finalizer writes only into a new output root beneath a caller-secured parent (mode 0700 on Unix; Windows inherits the parent ACL) and returns no successful aggregate on failure. This remains producer-side file construction: no extraction, installation, publication, or authenticity claim is performed.

`eggpack-core` owns the single producer-side file-digest authority: `file_digest` (`src/digest.rs`) is the only way a file becomes a byte count and a lowercase hex SHA-256. It refuses symlinks, empty files, and non-regular files, streams the bytes through a fixed 64 KiB buffer, accumulates the size with overflow checking, and re-inspects the path after the read so a file that changed while it was read is refused instead of recorded. Manifest aggregation, finalization, and candidate qualification all route through it, and `eggpack-ci` and `eggpack-github` consume the same public helper. A refused digest is a hard failure of the enclosing operation: never a warning, never a retry against the same path, never an empty or placeholder digest. The helper changes no hash semantics — identical bytes still produce an identical digest and size.

`BuildStrategy` and `Qualification` are independent producer axes. `Qualification::Native` is admissible for a `NativeCargo` **or** `CargoZigbuild` target, and requires the effective qualification host (`qualification_host`, else the build host) to match the target OS/architecture. This is what lets a cross-built candidate for a compatibility floor be proven by execution on a matching native host, including a separate qualification host for a cross-built candidate; a cross-tool-built candidate never earns native qualification merely by compiling, and a non-matching host records a failed `HostMismatch` outcome rather than a pass or a skip. A declared `CompatibilityFloor` remains a build-policy input carried into the cross-tool build command: native execution on a matching host proves the candidate runs there, and is not by itself independent proof that the produced binary honours the declared minimum glibc/macOS runtime.

A declared compatibility floor is now *recorded*, not merely implied. `FloorVerificationStatus` (`src/floor.rs`) is a finite, closed status — never a free-form string, never an `Option<bool>` — and it is carried both on the plan (`PlannedTarget::floor_status`) and on the qualification evidence (`QualificationEvidence::floor`). `NotDeclared` means the target declares no floor; `ToolchainBound` means the floor was bound into the build toolchain by the cargo-zigbuild triple rewrite and the toolchain is trusted to honour it; `Verified` means the produced bytes were independently inspected and satisfy the declared floor; `Unverified(reason)` means a floor was declared and the bytes did not confirm it, for a bounded reason; `NotSatisfied` means the bytes require a newer runtime than the declared floor. The status is computed from the inspected bytes — never from a smoke run — through a bounded ELF reader that reads the program headers, the dynamic table, and the `GLIBC_x.y` version requirements, and compares them in the direction that matters: a binary requiring a newer glibc than declared does not satisfy the floor. A contradicted floor is false, so it fails the qualification for that target rather than being reported as merely unverified; an unverifiable floor is a recorded status, not a failed release. A macOS deployment floor is not independently verified yet and is recorded as `Unverified(FloorKindNotVerifiable)`.

`eggpack-core` owns the one bounded process runner. `run_bounded_cancellable`
(build), `run_qualification_process` and `run_qemu_process` (qualification),
`run_git_bounded` (revision verification), and `run_interpreter_bounded` (an
external consumer validator's Python interpreter) all reach the same private
runner. It clears the environment except for a documented per-allowance
allowlist, bounds the wall time and the retained output, terminates the whole
process group or job object on every failure path so no descendant outlives the
run, and joins the reader threads under a budget derived from the run's own
remaining deadline — a reader still parked at its budget is detached and the run
fails closed. An over-limit stream is detected at the moment of excess and the
group is terminated then, not at the deadline; the observable outcome is
unchanged. Captured output never crosses the boundary: callers learn the
outcome and the retained byte counts only. `run_interpreter_bounded` takes an
`InterpreterCommandSpec` whose argument vector is OS-native, so a validated
absolute path reaches the interpreter byte-exact.

`cargo_command` exposes typed shell-free Cargo/CargoZigbuild intent for provider renderers. `execute_target` uses a caller-owned absolute repository root and a pre-existing private work root; each invocation/target gets a new Cargo target directory. The local process runner only launches Cargo, rustc, or Zig, clears inherited environment state except a small toolchain/path allowlist, and never returns captured output contents. Process-tree timeout cleanup uses `command-group` process groups/jobs.

Windows Cargo builds require an initialized Visual Studio developer environment. The Windows CI lane runs `ilammy/msvc-dev-cmd` before builder qualification and verifies that `link.exe` resolves beneath `VCToolsInstallDir`; this supplies the MSVC linker, SDK, and library environment used by Cargo and build scripts.

Example logical binding document:

```toml
schema_version = 1

[targets]
"x86_64-unknown-linux-gnu" = [
  { selector = { kind = "direct" }, package = "eggsact", binary = "eggsact" },
]
```