GloriousFlywheel Builder Surface Promotion Criteria 2026-04-15

Snapshot date: 2026-04-15

Purpose

Define when a builder workload should stay installation-specific, stay repo-owned additive, or be promoted into a first-class GloriousFlywheel builder surface.

This note is the narrow follow-through after the additive ARC policy governance and Linux builder contract notes. It is for TIN-127 and issue #171.

Companion notes:

• gloriousflywheel-arc-additive-policy-governance-2026-04-15.md
• gloriousflywheel-linux-builder-contract-2026-04-15.md
• gloriousflywheel-cache-publication-contract-2026-04-15.md

Current Repo Facts

Direct inspection on 2026-04-15 shows:

• baseline ARC builder classes already exist as public runner labels:
  • tinyland-docker
  • tinyland-dind
  • tinyland-nix
• repo-owned additive runner policy already exists through tofu/stacks/arc-runners/dev-extra-runner-sets.tfvars
• linux-xr-docker is currently the only named repo-owned additive builder canary
• no first-class dedicated Linux-builder label exists beyond the baseline classes above
• no formal promotion criteria were written down before this note

Surface Levels

Level 0: Installation-Owned Builder

Where it lives:

• local {env}.tfvars
• TOFU_EXTRA_POLICY_TFVARS

What it means:

• the workload matters to one installation, org, or operator flow
• GloriousFlywheel does not claim it as part of the shared product surface

Level 1: Repo-Owned Additive Builder Canary

Where it lives:

• tofu/stacks/arc-runners/dev-extra-runner-sets.tfvars

What it means:

• the workload is important enough to keep visible in the repo
• it is a canary or proof point for a builder path that GloriousFlywheel needs to understand better
• it is not yet stable enough or broad enough to become a first-class builder surface

Level 2: First-Class Builder Surface

Where it lives:

• baseline builder docs
• primary runner-selection docs
• lifecycle and capacity docs
• public labels or otherwise stable product-facing contract surfaces

What it means:

• GloriousFlywheel now treats the builder path as part of the product, not just as a canary
• downstream repos should be able to adopt it without reading research notes or tribal history

Promotion Criteria

Promote a builder from Level 1 to Level 2 only when most of these are true:

• it serves more than one named downstream consumer, or one consumer whose needs clearly generalize into a reusable builder class
• its workload shape is stable enough that label, privilege mode, cache contract, and resource envelope can be documented without hand-waving
• its lifecycle ownership is explicit: scaling, failure mode, and upgrade responsibility are understood
• its cache and publication boundaries are explicit: what goes to Attic, what goes to Bazel, what is only mutable acceleration, and what is promotable
• it no longer depends on installation-specific naming, secrets, or local-only assumptions
• it has at least one durable validation or canary path that GloriousFlywheel can point to as evidence
• removing the builder from primary docs would materially weaken the product’s stated platform contract

Do not promote a builder when most of these are true:

• it exists primarily for one repo, one org, or one operator setup
• it is still being used to discover the right resource shape or privilege profile
• its cache or publication story is still ambiguous
• it needs research-note caveats to avoid misleading downstream users
• its failure mode or lifecycle ownership is still an active design question

Required Promotion Artifacts

Before a Level 1 canary becomes Level 2, GloriousFlywheel should have:

1. a stable contract note
2. primary runner docs updated
3. runner-selection guidance updated
4. lifecycle ownership captured in the milestone or issue surface
5. publication boundary captured in the cache/builder contract notes
6. a decision on whether the builder keeps a dedicated label or stays mapped to an existing baseline class

Current Classification

linux-xr-docker

Current level:

• Level 1: repo-owned additive builder canary

Why it stays additive for now:

• it is a strong proof point for the heavy containerized Linux path
• it is already important enough to keep repo-owned and reviewable
• it still derives much of its meaning from one named downstream canary
• the repo has not yet defined whether that path should become a dedicated first-class builder surface or remain a documented specialization of the DinD class
• the clean-derivation and FlakeHub promotion policy is still not implemented

Promotion trigger for linux-xr-docker:

• promote only if the repo decides that heavy containerized Linux builds are a reusable product surface with stable lifecycle, cache, and publication rules, not just a canary specialization of tinyland-dind

Recommendation

Recommended current stance:

• keep linux-xr-docker repo-owned and additive
• do not invent a new first-class label yet
• use the current canary to drive the publication-boundary and lifecycle work in #171
• revisit promotion after the clean-derivation and FlakeHub workflow is explicit

Exit Condition

• the repo has explicit written criteria for additive-versus-first-class builder decisions
• linux-xr-docker has a defensible current classification
• future builder promotions can be argued from criteria instead of intuition