GloriousFlywheel Cache And Publication Contract 2026-04-15

GloriousFlywheel Cache And Publication Contract 2026-04-15

Snapshot date: 2026-04-15

Purpose

Separate what the repo already implements from what still exists only as reset intent.

This document is primarily about four surfaces:

  • Attic
  • Bazel remote cache
  • FlakeHub
  • RustFS

It also touches state authority, because the current repo still collapses state, storage, cache, and publication into one blurry story.

Repo-Grounded Current State

Attic

Implemented now:

  • Attic is the repo’s real Nix binary-cache distribution path.
  • ARC and GitLab runner surfaces both inject ATTIC_SERVER and ATTIC_CACHE into workloads. See tofu/modules/arc-runner/locals.tf:43-60 and tofu/modules/gitlab-runner/locals.tf:109-169.
  • GitHub composite actions already consume this model in .github/actions/setup-flywheel/action.yml:21-40 and .github/actions/nix-job/action.yml:38-49.
  • The repo already documents token generation and cache initialization in scripts/generate-attic-token.sh:1-142 and scripts/init-cache.sh:1-514.
  • The Nix watch-store publication flow is explicitly documented in docs/build-system/watch-store.md:8-129.

What Attic currently is:

  • a binary substitution and CI push surface for Nix store paths
  • an internal or semi-public artifact distribution layer for trusted builders and consumers

What Attic is not yet in this repo:

  • a public product catalog
  • a documented clean-derivation authority
  • a substitute for state backend design

Bazel Remote Cache

Implemented now:

  • Bazel remote cache is a real deployed component inside the Attic stack. tofu/stacks/attic/main.tf:1293-1350 instantiates the module.
  • The module exposes gRPC and HTTP endpoints plus bazelrc config. tofu/stacks/attic/main.tf:1031-1043 and docs/reference/tofu-modules.md:108 confirm that contract.
  • ARC runners inject BAZEL_REMOTE_CACHE for docker and nix workloads via tofu/modules/arc-runner/locals.tf:52-54.
  • Consumer docs exist, but they still use stale endpoint examples. docs/runners/cache-integration.md:9-35 and docs/runners/github-actions.md:80-93.

What Bazel cache currently is:

  • a performance cache for action results and CAS blobs
  • a mutable acceleration layer for CI and repeated builds

What Bazel cache is not:

  • a release artifact channel
  • a public package feed
  • a human-facing trust root

FlakeHub

Implemented now:

  • nothing in primary repo surfaces

Repo fact:

  • there are 0 non-research references to FlakeHub, flakehub, clean-derivation, or clean derivation

Inference from the reset direction:

  • FlakeHub should become the first-class discovery and publication surface for GloriousFlywheel flakes and clean derivations, rather than being treated as another mutable CI cache

That is an inference, not current implementation.

RustFS

Implemented now:

  • the repo contains a real tofu/modules/rustfs module with an explicit interface-compatible replacement story for minio-tenant
  • see tofu/modules/rustfs/main.tf:1-360, tofu/modules/rustfs/variables.tf:1-175, and tofu/modules/rustfs/outputs.tf:1-48

Not implemented now:

  • no stack currently instantiates the RustFS module
  • no non-research primary docs describe RustFS as an active storage or state backend

What RustFS currently is:

  • a candidate S3-compatible backend module

What RustFS currently is not:

  • an active part of the GloriousFlywheel deployment path
  • an end-user artifact interface

State Authority Today

Current repo truth:

  • GitLab HTTP state is still the only implemented state authority in the stack backends
  • see tofu/stacks/arc-runners/backend.tf:1-8, tofu/stacks/attic/backend.tf:1-42, tofu/stacks/gitlab-runners/backend.tf:1-8, and tofu/stacks/runner-dashboard/backend.tf:1-8
  • local operator entrypoints still assume the same GitLab HTTP backend through Justfile:228-260 and docs/infrastructure/quick-start.md:86-97
  • deploy workflow assumptions match that design in .github/workflows/deploy-arc-runners.yml:66-76 and .github/workflows/deploy-arc-runners.yml:157-167

Implication:

  • any RustFS-backed or local-first state story is still future intent
  • the repo must not pretend the migration has already happened

M2 P0 Execution Snapshot

Applied during the first executable M2 pass on 2026-04-15:

  • normalized self-hosted ARC defaults in .github/actions/setup-flywheel/action.yml to the stack-backed coordinates: http://attic.nix-cache.svc.cluster.local and grpc://bazel-cache.nix-cache.svc.cluster.local:9092
  • normalized public Attic defaults in flake.nix to https://nix-cache.tinyland.dev and https://nix-cache.tinyland.dev/main
  • aligned the primary cache-consumer docs with those same coordinates: docs/runners/github-actions.md, docs/runners/cache-integration.md, docs/runners/nix-builds.md, docs/reference/environment-variables.md, docs/architecture/cache-architecture.md, and docs/runners/project-onboarding.md

Still unresolved after that pass:

  • .github/workflows/deploy-arc-runners.yml still hard-codes both civo kubeconfig generation and GitLab HTTP backend coordinates for state
  • all four active stacks still expose backend "http" and GitLab-managed state comments, with no alternative backend implemented in-stack
  • Justfile and docs/infrastructure/quick-start.md still instruct operators to initialize stacks through TF_HTTP_PASSWORD and GitLab-managed state

Meaning now:

  • primary cache-coordinate drift is no longer the main blocker in active code and primary docs
  • state-backend authority and deploy-workflow authority are now the sharpest unresolved M2 P0 surfaces

Ownership Split After The First M2 Pass

The repo now has a cleaner issue boundary than it did at the start of M2.

#167 / TIN-125

Should own:

  • cache defaults in active code
  • cache-consumer documentation
  • Attic versus Bazel versus FlakeHub versus RustFS contract language
  • clean-derivation publication policy inputs for #171

Should not keep owning:

  • OpenTofu backend migration
  • deploy workflow authority
  • local operator initialization mechanics

Reason:

  • the first executable M2 pass already removed the highest-signal cache default drift from active code and primary docs
  • the remaining unresolved work is mostly not about cache endpoints anymore; it is about who owns state, kubeconfig generation, and operator entrypoints

#169 / TIN-128

Should own:

  • tofu/stacks/*/backend.tf
  • .github/workflows/deploy-arc-runners.yml
  • Justfile OpenTofu init path
  • docs/infrastructure/quick-start.md deployment and initialization guidance
  • the cluster-contract decision for local-first blahaj deployment targets

Reason:

  • those files and flows still encode GitLab HTTP state and Civo kubeconfig generation as the active operator path
  • changing them requires a deployment-authority decision, not more cache copy cleanup

Contract Recommendation

The contract below is partly repo-grounded and partly forward-looking. The forward-looking parts are labeled as recommendation.

1. Attic Contract

Current basis:

  • implemented

Recommended authority:

  • Attic is the mutable Nix binary-cache distribution surface for trusted CI, trusted builders, and known consumer machines

Recommended non-goals:

  • not the primary public catalog for releases
  • not the definition of which outputs are clean or promoted
  • not the state backend

2. Bazel Remote Cache Contract

Current basis:

  • implemented

Recommended authority:

  • Bazel remote cache is the mutable build-acceleration layer for action and CAS artifacts

Recommended non-goals:

  • not a release channel
  • not a public consumption endpoint
  • not a substitute for artifact publication policy

3. FlakeHub Contract

Current basis:

  • not implemented in primary surfaces

Recommended authority:

  • FlakeHub should become the public or cross-org publication and discovery layer for GloriousFlywheel flakes and clean derivations

Recommended non-goals:

  • not a general-purpose mutable CI cache
  • not the backend store for Bazel action results
  • not the place to hide local-only or unpromoted build outputs

4. RustFS Contract

Current basis:

  • candidate backend module only

Recommended authority:

  • RustFS should be treated as an internal S3-compatible storage substrate if the stack chooses to replace or supplement MinIO

Recommended non-goals:

  • not an end-user-facing publication surface
  • not a substitute for FlakeHub
  • not evidence that state migration is already complete

Clean-Derivation Boundary

Current repo state:

  • no first-class clean-derivation concept is written into the code or docs

Recommendation:

  • define clean derivations as the promoted subset of outputs eligible for durable publication beyond mutable CI caches
  • Attic and Bazel can hold non-promoted and transient outputs
  • FlakeHub should receive only outputs that meet the clean-derivation contract

That publication boundary is not implemented yet.

Consumer Contract

Current repo already supports:

  • ARC consumers using tinyland-nix, tinyland-docker, or tinyland-dind
  • automatic ATTIC_SERVER, ATTIC_CACHE, and BAZEL_REMOTE_CACHE injection
  • cache-aware Nix and Bazel builds

Current repo does not yet support as a first-class documented contract:

  • a stable FlakeHub publication path
  • a clean-derivation promotion workflow
  • a trustworthy explanation of which artifacts are local-only versus public

Work Required To Make This True

Immediate

  • correct stale cache coordinates in primary code and docs
  • decide and document the state-backend authority honestly
  • stop presenting GitLab HTTP state as incidental detail

Next

  • add FlakeHub to primary docs and, when ready, active workflows
  • define the clean-derivation promotion rule
  • decide whether RustFS is a real near-term storage migration path or just a retained alternative module

After That

  • update downstream guidance so repos know:
    • when to rely on Attic
    • when to rely on Bazel remote cache
    • when to publish via FlakeHub
    • which outputs are promotable

Backlog Mapping

  • TIN-125 / #167: state and cache truth
  • TIN-127 / #171: builder, FlakeHub, and clean-derivation contract
  • TIN-128 / #169: local-first deployment authority once state ownership is explicit

Companion execution notes for #171 now include:

Notes

  • The strongest implemented contract in the repo today is Attic plus Bazel remote cache for CI acceleration.
  • The weakest but most strategically important missing contract is FlakeHub plus clean-derivation publication.
  • RustFS should be discussed as internal storage substrate, not as a publication-facing feature, unless the repo gains real integration work.

GloriousFlywheel