Skip to content

Deepen HashKey release evidence plan #70

Closed

Description

@mowind

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-only metadata projection.
  • all, individual public source stages, skip/only lists, pin-print flags, and workflow-owned basic|execution modes 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-gnu adds 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.
  • prepare cannot 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

Native dependency order:

Activity

  1. mowind commented on Aug 5, 2026

    @mowind
    OwnerAuthor

    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.

  2. mowind commented on Aug 5, 2026

    @mowind
    OwnerAuthor

    Closing after completion of implementation tickets #71–#77.

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

    ready-for-agentFully specified and ready for an AFK agent

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions