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:

schema_version = 1

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