Skip to content

fix(release): prove independent distribution rebuild reproducibility before publication #1763

Description

@seonghobae

Release acceptance gap

Protected main@493326f2de49ea1704da0ded19868ed05d2fe00f requires more than artifact existence and provenance. docs/PRD.md PRD-FR-081 requires release evidence for packaging, provenance/SBOM and reproducibility; docs/TRD.md likewise lists release artifact digests/SBOM/provenance and reproducibility evidence as separate acceptance inputs.

The current protected release-evidence index computes SHA-256 over the one set of wheel/sdist files it receives. That proves the identity of those files, not that a clean independent rebuild of the exact same source/toolchain reproduces them. Active supply-chain writer #1692 correctly owns SBOM/provenance and immutable draft→asset/PyPI→publish transaction safety, but its current scope and issue #1691 do not claim independent rebuild reproducibility.

This is therefore a successor release-reproducibility lane, not an expansion of #1692.

Single-writer and sequencing boundary

Scientific/engineering claim boundary

Distinguish these claims explicitly:

  1. Artifact identity — SHA-256 identifies one produced file. Existing release-evidence indexing already does this.
  2. Same-environment clean rebuild repeatability — two clean builds under the same locked target/toolchain produce byte-identical output.
  3. Independent-runner reproducibility — independent clean runners for the same target/toolchain produce byte-identical output.
  4. Cross-target scientific/runtime parity — different OS/architecture wheels need not have identical bytes; their numerical/API parity is a separate fast-mlsirm contract.

Do not describe (1) as evidence for (2) or (3), and do not require byte identity across different wheel target triples.

RED → GREEN contract

  1. Add focused fail-first release-contract tests showing publication cannot finalize when the required reproducibility manifest is absent, incomplete, source-mismatched, target-mismatched, or reports unequal digests for a same-target rebuild pair.
  2. Derive the build time input from the exact release source commit and export a documented SOURCE_DATE_EPOCH rather than wall-clock time. The Reproducible Builds specification defines SOURCE_DATE_EPOCH as the standardized build-time input for reproducible output; use the exact commit timestamp and record it in evidence.
  3. For the sdist and for every published wheel matrix target, perform two clean builds from the same exact release_commit, immutable dependency/toolchain inputs, target triple/interpreter contract, and build options. Do not reuse target/, dist/, wheel caches, or a predecessor artifact as the second build input.
  4. Prefer independent jobs/runners for the two members of each comparison. If a target cannot yet provide independent-runner equality, fail closed for the stronger claim and record the narrower verified level rather than silently downgrading acceptance.
  5. Compare complete artifact bytes by SHA-256 after canonical filename/target matching. Fail on missing, duplicate, extra, renamed, or many-to-one matches; do not normalize or rewrite the generated artifact to manufacture equality.
  6. Emit one machine-readable reproducibility manifest bound to release_commit, version, commit timestamp / SOURCE_DATE_EPOCH, Cargo.lock hash, Rust toolchain, maturin version/action SHA, runner image identity, target/interpreter tag, build arguments, both artifact digests, and comparison result.
  7. Feed that manifest into the existing release-evidence index and release acceptance. The index must distinguish artifact_digest from rebuild_reproducibility; a single original artifact digest cannot satisfy the new requirement.
  8. Attach/attest the accepted reproducibility manifest through the canonical release transaction after fix(release): publish SBOM and build provenance #1692 lands. Preserve builder-local provenance; the comparison/aggregation job must not masquerade as the builder of either distribution.
  9. Keep publication fail closed: GitHub Release finalization and PyPI publication must not proceed when the required same-target reproducibility evidence is absent or failed.
  10. Preserve token-based PyPI semantics and all branch/review gates. No force push, gate weakening, source rewriting, skipped/xfail acceptance, cache-only second builds, or denominator tricks.

Required evidence

For each artifact target record:

  • exact source SHA and source commit timestamp;
  • clean-build A and B runner/toolchain identities;
  • dependency-lock and build-action identities;
  • wheel/sdist filename and target tag;
  • SHA-256(A), SHA-256(B), and exact equality verdict;
  • failure class when equality is not achieved;
  • retained artifacts/logs sufficient to diagnose timestamp, archive-order, generated metadata, linker, toolchain, or platform-image nondeterminism.

Release documentation must state exactly which reproducibility level is proven. A same-runner or same-image double build must not be advertised as universal cross-platform bit reproducibility.

Acceptance

  • Focused RED demonstrates that current protected main can produce/hash one artifact set without proving a clean rebuild.
  • GREEN demonstrates byte-identical same-target rebuild evidence at the declared level for the complete release matrix, including sdist, without shrinking the matrix.
  • Exact-current CI/security/coverage/review gates pass and an independent current-head approval exists.
  • docs/release_acceptance.md, TRD/TEST_STRATEGY/OPERABILITY/recovery/release evidence docs and the governed changelog describe the claim, failure semantics, rollback, and diagnostic path without overstating cross-platform guarantees.
  • docs/product-technical-gap-baseline.md is updated only through its canonical single-writer lane.

Basis

  • fast-mlsirm PRD-FR-081: exact integrated protected-head release requires packaging, provenance/SBOM, reproducibility, compatibility, review, rollback/migration, and release-acceptance evidence.
  • fast-mlsirm TRD release acceptance separately requires artifact digests/SBOM/provenance and reproducibility evidence.
  • Reproducible Builds, SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/

This issue remains open until the reproducibility evidence is integrated on protected main and exercised by an actual release transaction; a single successful local or synthetic test is not release completion.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions