Repository navigation
Description
Problem Statement
HashKey release evidence is currently split across a Python validator, a Bash source orchestrator, an artifact smoke script, Make, and two GitHub workflows. The public all command is trusted as the complete source gate, but it does not invoke the already-defined full workspace suite. Its run_x || failed=1 aggregation also places Bash functions in a conditional context, allowing an earlier command failure inside a function to be masked by a later success.
The release workflow separately smokes pre-archive OUT_DIR binaries rather than the tar/zip users download. Workflow code chooses basic versus execution, provided upstream checkouts need not be clean, cross-target identity is not closed over the release matrix, and a GitHub draft plus Docker publication can enter the publication lifecycle before archive evidence succeeds.
These are not independent script defects. They are consequences of release-evidence membership, failure semantics, artifact policy, source identity, and publication ordering having no single owner.
Solution
Deepen .github/scripts/hashkey_release_gate.py into the sole HashKey release evidence-plan module. It owns one authoritative release plan with two lifecycle projections:
source: the non-optional source evidence plan, including no-default runtime regression and full all-features workspace tests;artifact: final-archive validation for one closed release target, with native binary surfaces on every supported target and standalone HashKey execution on the designated Linux target.
The shell becomes a zero-policy launcher. Make, CI, and release are driving callers, not adapters. The real internal ports are managed/provided upstream checkout and tar.gz/zip artifact bundles. The workflow passes archive, target, and release tag; the module owns target policy, tag/commit identity, archive safety, and evidence aggregation.
The release lifecycle moves GitHub draft creation and asset upload into a gated finalize job. prepare only computes release inputs, matrix jobs produce complete workflow asset bundles after artifact evidence, Docker waits for the matrix, and finalize rejects any pre-existing release before creating the draft. Stable publication remains manual and nightly publication remains automatic, but neither can begin before required source/archive evidence succeeds.
The complete architecture contract is docs/prototypes/hashkey-release-evidence-plan-module-v1.7.1.md.
Implementation Decisions
- Public operations are
source,artifact --archive --target --release-tag, and the existing HSK-onlymetadataprojection. all, individual public source stages, skip/only lists, pin-print flags, and workflow-ownedbasic|executionmodes are hard-cut without silent aliases.- Source membership is fixed in Python and includes gate/repository contracts, four upstream goldens, Foundry plus four CLI conformance slices, standard and no-default builds, static checks, no-default runtime regression, and the full locked all-features workspace suite.
- Independent source evidence continues after failures. Any failed or required blocked result is sticky; only a real missing prerequisite may block dependent evidence.
- Provided upstream checkout must be the approved clean checkout root, with no staged, unstaged, untracked, ignored, or submodule drift. It is never reset, cleaned, or deleted.
- Artifact evidence runs after tar/zip creation, before checksum/SBOM/attestation/signing/upload. Adapters preflight the complete archive, accept exactly four root regular binaries, reject unsafe or ambiguous entries, and never fall back to
OUT_DIR. - The supported target map is closed over the seven release triples. Unknown targets are usage errors. Every target runs native version/help surfaces on a matching-architecture host; only
x86_64-unknown-linux-gnuadds standalone execution smoke. - HashKey stable, ordinary stable, and nightly tags have separate module-owned identity projections. The tag, checkout HEAD, and all four binary-reported build commit identities must agree.
preparecannot create or populate a GitHub release. Docker depends on the archive matrix. Finalize depends on prepare, every matrix job, and Docker, rejects any existing draft/published release, then creates and fills the draft.- The module does not become a generic DAG engine, plugin framework, retry scheduler, or public command-runner abstraction.
Acceptance Criteria
- One Python module is the only source/artifact evidence membership authority.
- Full workspace and no-default runtime suites are required and deterministic; no undocumented filter, network dependency, or allow-failure remains.
- Earlier failures cannot be masked by later successes, including within a former Bash group.
- Make and workflows do not know source stage membership or artifact smoke modes.
- Managed and provided upstream inputs satisfy the same approved immutable-source contract.
- Final tar.gz/zip archives, not build directories, are the artifact evidence subjects.
- Workflow/module target sets and host-architecture policy match exactly and fail closed on drift.
- All four binaries prove the same release tag class and build commit as checkout HEAD.
- No GitHub draft, archive asset upload, or Docker publication can begin before required source/archive evidence passes.
- Legacy interfaces and direct artifact-helper calls are deleted in the same migration series.
- Linux tar, ARM64, Windows ZIP, ordinary stable, HashKey stable, and nightly paths have end-to-end regression coverage.
Out of Scope
- Changing HashKey/B20 runtime semantics, approved upstream revision, release metadata schema, Rust/package pins, or the canonical smoke assertions.
- Introducing a generic workflow engine, external plan file, evidence receipt schema, plugin registry, or arbitrary stage composition.
- Making Docker and GitHub release publication transactional across external systems.
- Reworking checksum, SBOM, attestation, signing, changelog, or immutable-release policy beyond the ordering needed to enforce the gate.
Implementation Tickets
- Make workspace gate tests deterministic #71 Make workspace gate tests deterministic
- Establish the release evidence plan core #72 Establish the release evidence plan core
- Harden upstream checkout evidence #73 Harden upstream checkout evidence
- Validate final release archives #74 Validate final release archives
- Enforce artifact runtime evidence #75 Enforce artifact runtime evidence
- Gate release publication after evidence #76 Gate release publication after evidence
- Contract legacy release gate interfaces #77 Contract legacy release gate interfaces
Native dependency order:
- Harden upstream checkout evidence #73 is blocked by Establish the release evidence plan core #72.
- Validate final release archives #74 is blocked by Establish the release evidence plan core #72.
- Enforce artifact runtime evidence #75 is blocked by Establish the release evidence plan core #72 and Validate final release archives #74.
- Gate release publication after evidence #76 is blocked by Make workspace gate tests deterministic #71, Establish the release evidence plan core #72, Harden upstream checkout evidence #73, and Enforce artifact runtime evidence #75.
- Contract legacy release gate interfaces #77 is blocked by Gate release publication after evidence #76.
Activity
mowind commentedon Aug 5, 2026
Implementation complete. Child issues #71–#77 are all closed. The release evidence-plan module now owns source/artifact/metadata contracts, deterministic workspace evidence, upstream checkout validation, archive and native identity checks, gated finalize publication, and hard-cut legacy interfaces. Pushed commits include 0ff5d83, 76ddb6c, 803c965, bb28214, f0cea37, 18f157c, 67c5fd3, 96a4ff8, 09b21f9, and 52ee153. Local HashKey gate tests pass (31 tests), release-file validation passes, metadata generate/validate lifecycle passes, and the no-default workspace suite completed 2078/2078. CI HashKey runs for the latest commit are queued.
mowind commentedon Aug 5, 2026
Closing after completion of implementation tickets #71–#77.