Decision record · ADR
ADR-0033: Qualify reversible release surfaces before registry publication
Status: accepted | Date: 2026-08-05
References: ADR-0008, ADR-0009, ADR-0030, RFC-0006:C-INTEGRATIONS
Context
Section titled “Context”The halted InferLab 0.8.4 publication exposed a recoverability inversion. All six Cargo packages were published manually to crates.io before the filtered public snapshot completed ordinary public CI. That CI then found a real release-blocking defect. No product tag or GitHub Release existed, so those outward surfaces could still be withheld, but the registry versions could neither be deleted nor replaced. The published packages became permanent partial history before the more recoverable qualification surfaces had produced evidence.
ADR-0008 assigns the operator to initiate tags and manual registry publication, and ADR-0030 aggregates independently versioned workspace wheels under one product Release while retaining the package index as canonical transport. Neither decision orders those acts by recoverability. The existing implementation also resolves Release wheels from the package index, structurally placing a new wheel publication before aggregate Release qualification. The release design needs to preserve manual registry authority, identical artifact bytes across transports, independently versioned workspace packages, the filtered public mirror, and one aggregate product Release while ensuring that a failure on a retractable surface cannot first be discovered after an immutable registry publication.
Decision
Section titled “Decision”We will order coordinated product-publication acts by recoverability, leaving package registries as the final outward mutation.
A frozen candidate is packaged and qualified locally before its filtered snapshot is pushed without a product tag. The selected flow waits for public-main CI to complete on that exact snapshot before the operator creates the product tag. The tag workflow builds and qualifies product binaries, installer, plugin, and other repository-produced assets into a draft aggregate GitHub Release. The operator completes that draft with the locally prepared workspace-wheel inventory and checksum sidecars, verifies the downloaded aggregate inventory, and publishes the GitHub Release while it is still retractable.
Only after the complete GitHub Release is published and verified does the operator perform manual crates.io or Python package-index uploads. A workspace wheel that is new in the coordinated release is attached to the GitHub Release from the locally qualified candidate before the same bytes are uploaded to the package index; an unchanged wheel can continue to reuse its existing canonical index artifact. Cargo packages are likewise packaged and checked locally before the tag, then published in dependency order only after Release qualification. The package index remains the canonical workspace-package transport after publication, and registry writes remain manual under ADR-0008.
An independently versioned package-only publication still creates no package-scoped GitHub Release under ADR-0030. It nevertheless completes its local package checks and public-source CI before its manual registry upload. A coordinated product release no longer depends on a newly published registry artifact in order to qualify its retractable Release surface.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- A source, public-CI, binary, installer, plugin, wheel-inventory, or aggregate-Release failure can stop or retract the release before any new immutable registry version is created.
- The 0.8.4 partial-publication failure mode becomes structurally unavailable in the ordinary coordinated product flow.
- Manual registry authority, independent package versions, one aggregate product Release, and same-byte wheel identity across transports remain intact.
- Newly changed wheels can be qualified as part of the complete product inventory without using PyPI as their prequalification staging service.
Negative
Section titled “Negative”- The tag workflow now hands a draft Release to a manual wheel-inventory and final-publication step instead of completing the entire Release autonomously.
- A short intentional interval can exist after the GitHub Release is published but before the corresponding crates and new Python packages appear on their canonical registries.
- Multi-crate publication can still fail after an earlier crate succeeds; ordering all recoverable checks first reduces exposure but cannot make independent registry writes atomic.
Neutral
Section titled “Neutral”- Package registries remain canonical distribution surfaces after publication, while GitHub remains the aggregate product presentation and verified fallback.
- Registry uploads remain manual; this decision does not introduce GitHub trusted publishing or repository-held registry credentials.
- Existing partial 0.8.3 and 0.8.4 registry histories remain immutable facts and receive no retroactive product tags or Releases.
Alternatives Considered
Section titled “Alternatives Considered”Qualify and publish the complete aggregate GitHub Release before package-registry publication (accepted)
Section titled “Qualify and publish the complete aggregate GitHub Release before package-registry publication (accepted)”- Pros: Every retractable source, CI, binary, installer, plugin, wheel-inventory, and aggregate-Release check completes before a new immutable registry identity exists, The same locally prepared wheel bytes can be attached to the aggregate Release and only then uploaded manually to the package index
- Cons: The tag workflow and operator need a staged draft/finalization handoff instead of one fully autonomous Release job, A published GitHub Release can briefly precede availability of its corresponding Cargo and newly published Python packages on their canonical registries
Continue publishing package registries before public snapshot and product Release qualification (rejected)
Section titled “Continue publishing package registries before public snapshot and product Release qualification (rejected)”- Pros: The aggregate Release can download every workspace wheel from its canonical package index, The existing release workflow needs no staging handoff
- Cons: A public CI or Release qualification failure can strand package versions that cannot be deleted or replaced, Registry publication becomes an unsafe precondition for checks performed on more recoverable surfaces
- Rejected because: The 0.8.4 incident demonstrated the exact irreversible partial-publication failure this ordering permits.
Move package-registry publication into the tag-triggered GitHub workflow (rejected)
Section titled “Move package-registry publication into the tag-triggered GitHub workflow (rejected)”- Pros: One tag-triggered workflow could sequence asset qualification and registry upload without a manual handoff
- Cons: It expands GitHub workflow authority to irreversible registry writes and requires trusted-publishing policy that the operator has not selected, Automation does not remove partial multi-package registry failure after the first successful upload
- Rejected because: The ordering defect can be corrected while retaining the confirmed manual registry-publication boundary; expanding publication authority is unnecessary.