GloriousFlywheel Clean Derivation Promotion Workflow 2026-04-15

GloriousFlywheel Clean Derivation Promotion Workflow 2026-04-15

Snapshot date: 2026-04-15

Purpose

Define the recommended promotion workflow from mutable builder outputs to durably published clean derivations.

This note is intentionally explicit about what is implemented today versus what is only recommended future behavior.

Companion notes:

Current Repo Facts

Direct inspection on 2026-04-15 shows:

  • Attic is implemented as the mutable Nix binary-cache surface
  • Bazel remote cache is implemented as the mutable action/CAS acceleration surface
  • GHCR is already a concrete OCI publication surface in primary repo code and docs
  • FlakeHub is not implemented in primary repo surfaces
  • no first-class clean-derivation promotion rule exists in code or docs
  • downstream lab evidence on 2026-04-16 shows that self-hosted Nix lanes cannot assume the toolchain is already present on tinyland-nix

Output Classes

1. Mutable Builder Outputs

These are ordinary CI and builder outputs that may populate:

  • Attic
  • Bazel remote cache
  • ephemeral OCI build outputs before publication

They are useful for acceleration and reuse, but they are not automatically promoted artifacts.

2. Published OCI Artifacts

Current basis:

  • implemented through GHCR-facing image surfaces

These are container images intentionally pushed to a registry.

3. Clean Derivations

Current basis:

  • recommended concept only

Definition for this repo:

  • the subset of builder outputs that are eligible for durable publication and discovery beyond mutable CI caches

Phase 0: Bootstrap The Builder Toolchain

Before any self-hosted Nix workflow claims a clean-derivation or FlakeHub story, it must first guarantee its own toolchain.

Current evidence:

  • lab#71 surfaced tinyland-nix failures that hit determinate-nixd: command not found and nix: command not found before any repo build logic ran
  • merged lab#73 corrected that by always running DeterminateSystems/determinate-nix-action@v3 on the affected tinyland-nix jobs

Current recommendation:

  • treat Nix installation and verification as workflow-owned bootstrap on self-hosted Nix lanes
  • treat FlakeHub login and cache steps as post-bootstrap acceleration, not as a substitute for Nix installation
  • treat runner memory-envelope selection as a separate builder-lane decision, not as something FlakeHub or ARC autoscaling solves implicitly

Phase 1: Build

Run the workload on the appropriate builder class:

  • tinyland-nix for reproducible Nix builds and nix2container
  • tinyland-docker for ordinary Linux CI and non-privileged Bazel-backed work
  • tinyland-dind for daemon-backed or heavy containerized Linux work

Phase 2: Fill Mutable Acceleration Layers

Allow the build to populate mutable acceleration surfaces:

  • Attic for Nix outputs
  • Bazel remote cache for action/CAS outputs

This phase is already implemented.

Phase 3: Validate

Only consider promotion after the output has cleared the relevant validation surface for that build class.

Current repo gap:

  • the repo does not yet expose a formal clean-derivation gate or promotion job

Phase 4: Classify

Decide whether the output is promotable.

Recommended promotable criteria:

  • reproducible enough to be re-identified from source and inputs
  • intentionally user-facing or cross-org reusable
  • not installation-local or transient debug output
  • not relying on mutable cache semantics as its only distribution model

Phase 5: Publish To The Right Surface

Recommended target matrix:

Output type Mutable acceleration surface Durable publication surface
Nix derivation used only for CI acceleration Attic none
Bazel action/CAS output used only for CI acceleration Bazel remote cache none
OCI image intended for use mutable build layers as needed GHCR
promoted clean derivation Attic may still carry it FlakeHub when implemented

Phase 6: Document Ownership

Once an output is promoted, the repo should document:

  • who owns the builder path
  • who owns the publication path
  • what makes the output clean enough to stay published

What This Means Today

Implemented today:

  • mutable Attic-backed Nix acceleration
  • mutable Bazel remote-cache acceleration
  • GHCR-oriented OCI publication surfaces

Not implemented today:

  • FlakeHub publication
  • a clean-derivation promotion job
  • a documented automation path from builder success to FlakeHub release

Current Guidance

Until the repo gains a real promotion workflow:

  • treat Attic as a mutable builder cache, not a public catalog
  • treat Bazel remote cache as acceleration only
  • treat GHCR as the concrete publication path for OCI images
  • make self-hosted Nix workflows prove their own toolchain bootstrap before claiming any clean-derivation or FlakeHub path
  • for runner-dashboard specifically, keep durable public publication on the GHCR image path unless release authority changes intentionally
  • that intentional release-authority change should clear gloriousflywheel-runner-dashboard-release-authority-change-gate-2026-04-16.md
  • do not describe Nix or Bazel outputs as FlakeHub-published unless the repo actually implements that flow

Relationship To Builder Promotion

Builder-surface promotion and output promotion are related but separate:

  • a builder can remain additive even if it produces promotable artifacts later
  • a builder should not become first-class while its publication boundary is still ambiguous
  • that is why linux-xr-docker should stay additive until the clean-derivation boundary is explicit enough to support a reusable product claim

Recommendation

Recommended next implementation order:

  1. keep writing the promotion rule in repo-facing docs and planning notes
  2. define the self-hosted Nix bootstrap boundary explicitly
  3. define the clean-derivation gate for Nix outputs explicitly
  4. start from the candidate set in gloriousflywheel-nix-output-candidates-2026-04-15.md
  5. start with the explicit gate in gloriousflywheel-runner-dashboard-promotion-gate-2026-04-15.md
  6. only then add FlakeHub to primary docs or active workflows

Exit Condition

  • the repo has a written answer for how outputs move from mutable caches to durable publication
  • builder docs stop implying that cache fill is the same thing as publication
  • FlakeHub can be added later without rewriting the builder contract from scratch

GloriousFlywheel