GloriousFlywheel Linux Builder Contract 2026-04-15

GloriousFlywheel Linux Builder Contract 2026-04-15

Snapshot date: 2026-04-15

Retired runner-label correction (2026-04-24): Any linux-xr-docker or linux-xr-specific runner-label guidance in this note is historical only. Active runner labels must be shared capability classes, not repo or project identity.

Purpose

Define the current Linux builder contract for GloriousFlywheel from repo truth.

This note is the first concrete input for TIN-127 and GitHub issue #171. It is intentionally scoped to builder classes, canary workloads, and publication boundaries.

Companion notes:

Current Repo Facts

Direct inspection on 2026-04-15 shows:

  • the ARC stack defines three baseline runner classes:
    • Nix: tinyland-nix / gh-nix
    • Docker: tinyland-docker / gh-docker
    • DinD: tinyland-dind / gh-dind
  • the stack also supports additive runner classes through extra_runner_sets
  • the repo-owned additive policy currently defines one named builder canary: linux-xr-docker
  • the self-hosted GitHub actions surface currently injects:
    • Attic on Nix-oriented paths
    • Bazel remote cache on self-hosted paths
  • downstream lab evidence from 2026-04-16 shows that tinyland-nix cannot be modeled as “Nix is already installed”:
    • failing Build x86_64-linux and DevShell Cache jobs surfaced during lab#71 with determinate-nixd: command not found and then nix: command not found before repo build logic ran
    • merged lab#73 corrected that by always running DeterminateSystems/determinate-nix-action@v3 on the affected tinyland-nix jobs
  • docs/build-system/containers.md already documents three build methods: nix2container, Dockerfile, and rules_img
  • non-research primary surfaces still do not implement:
    • FlakeHub publication
    • a clean-derivation promotion workflow
    • a dedicated first-class Linux-builder label separate from runner classes

Builder Classes

1. Nix Builder Class

Current label:

  • tinyland-nix

Intended use:

  • Nix flake builds
  • reproducible package builds
  • daemon-free OCI assembly via nix2container
  • cache-aware jobs that benefit from Attic as the primary binary-cache surface

Current cache contract:

  • Attic is the primary mutable cache
  • Bazel remote cache is also available for mixed Nix/Bazel jobs

Bootstrap contract:

  • tinyland-nix is the Nix-oriented runner lane, not a guarantee that the Nix toolchain is preinstalled on every self-hosted runner
  • self-hosted Nix workflows should install or verify Nix explicitly before repo build logic runs
  • the current proven bootstrap pattern is DeterminateSystems/determinate-nix-action@v3
  • FlakeHub login/cache steps come after bootstrap and are not a substitute for Nix installation

2. Docker Builder Class

Current label:

  • tinyland-docker

Intended use:

  • default Linux CI for lint, test, and ordinary build jobs
  • non-privileged Linux workloads
  • Bazel-backed or general shell-based build steps that do not require Docker daemon access

Current cache contract:

  • Bazel remote cache is the primary mutable cache
  • Attic is not the default primary surface for this class

3. DinD Builder Class

Current label:

  • tinyland-dind

Intended use:

  • Docker image builds
  • privileged Linux CI
  • jobs that require a Docker daemon or container: semantics
  • heavier containerized Linux workloads that do not fit the plain Docker class

Current cache contract:

  • Bazel remote cache remains available
  • Attic is not the primary cache contract for this class

Named Canary Builder

linux-xr-docker

Current basis:

  • implemented as a repo-owned additive ARC runner set

Classification:

  • Linux builder canary

Why it matters:

  • it is the clearest current proof that GloriousFlywheel needs a documented Linux-heavy builder path beyond the generic baseline labels
  • it exercises the privileged, containerized Linux build path that current downstream consumers already need
  • it is already named in reset planning instead of being a local-only custom scale set

Current contract:

  • treat linux-xr-docker as the canary for the DinD-backed Linux builder path
  • do not present it as a generic example or tenant-specific leftover
  • do not promote it into a first-class builder surface until the criteria in gloriousflywheel-builder-surface-promotion-criteria-2026-04-15.md are met

Build-Method Mapping

Current recommended mapping:

Build method Preferred builder class Why
nix build Nix reproducible Nix path with Attic-backed cache reuse
nix2container Nix daemon-free OCI assembly from Nix outputs
Bazel build without privileged container needs Docker default Linux CI path with Bazel cache
Dockerfile build needing daemon access DinD privileged container runtime required
heavy containerized Linux canary workload DinD via linux-xr-docker current named proof point

Publication Boundary

Builder-facing summary:

  • Attic is the mutable Nix binary-cache surface for trusted CI and builders
  • Bazel remote cache is the mutable action/CAS acceleration surface
  • GHCR is the concrete current OCI publication surface
  • FlakeHub is a planned future publication and discovery surface for promoted flakes and clean derivations, not a current implemented builder output path
  • RustFS is an internal storage candidate, not a builder-facing publication surface
  • current scaling ambiguity for memory-heavy tinyland-nix jobs is now split into a separate decision note: gloriousflywheel-nix-builder-bootstrap-and-scaling-options-2026-04-16.md

Clean-Derivation Boundary

Current repo state:

  • no first-class clean-derivation promotion rule is implemented

Builder implication:

  • builders may populate mutable caches without implying that outputs are promoted or public
  • no builder class should be described as publishing to FlakeHub today
  • the recommended promotion flow now lives in gloriousflywheel-clean-derivation-promotion-workflow-2026-04-15.md

Contract Recommendation

Recommended current contract for downstream users:

  1. Use tinyland-docker as the default Linux CI builder.
  2. Use tinyland-dind when the workload requires Docker daemon or privileged container semantics.
  3. Use tinyland-nix when reproducible Nix outputs or nix2container are the natural build path.
  4. Make self-hosted tinyland-nix workflows self-provision or verify the Nix toolchain instead of depending on mutable runner image state.
  5. Treat linux-xr-docker as the current named Linux-builder canary, not as the final general-purpose Linux-builder product surface.
  6. Treat Attic and Bazel as mutable acceleration layers, not publication or release channels.
  7. Do not promise FlakeHub publication until clean-derivation promotion is real in primary repo surfaces.

Exit Condition

  • primary runner docs explain builder classes rather than only raw labels
  • the repo has a named current answer for Linux-heavy CI instead of leaving linux-xr-docker implicit
  • the builder docs stop blurring cache acceleration with artifact publication

GloriousFlywheel