Glorious Flywheel

Pooled, cache-first build and runner substrate for local development and CI.

GloriousFlywheel is a working alpha implementation of:

• capability-class runner lanes
• Attic-backed Nix acceleration
• Bazel remote-cache acceleration
• narrow explicit Bazel REAPI proof lanes for selected target classes
• shared developer and CI contract surfaces
• operator and control-plane tooling

The source repo is public, but docs/ still contains operator-facing truth, historical planning, and internal topology notes. The safer consumer-facing package remains the green fresh-history mirror seed generated by just public-alpha-export; treating the full repo as polished public API still requires an explicit exposure review.

Repo Surfaces

• docs/: internal product, operator, architecture, and status docs
• public-docs/: conservative future public package projected from internal truth
• examples/: consumer-facing cache and runner attachment examples for the public alpha export
• docs/research/: internal planning and evidence notes

docs/ is not a polished public API. The public-alpha package is the smaller public-docs/ tree and its export/scrub tooling.

Current Operating Truth

• the Honey on-prem cluster is the current physical target; honey carries the baseline runner lanes, sting is the source-gated compute-expansion surface, and bumble is not a default runner target
• GitHub is the primary forge surface
• GitLab remains a compatibility path
• capability classes such as tinyland-nix, tinyland-docker, tinyland-dind, and bounded additive lanes such as tinyland-nix-heavy are the normal runner taxonomy
• repo identity is not runner taxonomy
• owner-specific GitHub App installs, tfvars, and private auth media belong in implementation overlays, not the core product stack
• local development and CI are meant to use the same shared substrate
• first-party validation, security scans, Bzlmod/Bazel canaries, RBE chaos probes, and status renderers must dogfood shared tinyland-* runner lanes; GitHub-hosted runners are not an acceptable fallback for this repo
• current main proves shared cache acceleration plus narrow target-scoped REAPI proofs for //app:build, //app:unit_tests, //:deployment_bundle, //docs-site:build, and the WAS-110 public-input handoff; it does not prove universal full remote offload for every developer workload
• operator access is private and tailnet-first
• environment-owned S3-compatible state is the live authority for the main stacks
• Attic and Bazel are acceleration layers, not publication surfaces
• FlakeHub is publication and discovery work, not runtime/bootstrap

GloriousFlywheel is not a repo-specific runner enrollment catalog. Repo-shaped runner labels are architectural debt, not the product direction.

First-Party Dogfood Contract

GloriousFlywheel is the runner product, so its own CI is product evidence. Required first-party checks must run on shared capability-class runners such as tinyland-nix, tinyland-nix-heavy, tinyland-docker, or tinyland-dind.

That includes:

• repository validation and docs checks
• secret scanning and security canaries
• Bzlmod, Bazel cache, external-input, and vendor-mode proofs
• RBE proof and chaos workflows
• runner topology and status reporting

GitHub-hosted runners are not an acceptable first-party path for this repo. Publication and control-plane jobs such as FlakeHub, GitHub Pages, image mirrors, and release metadata must still dogfood shared tinyland-* lanes. Any future proposal to use hosted runners must fail just dogfood-contract-audit until it is explicitly reviewed and removed from first-party product evidence. Public fork PR code is not trusted to execute inside the cluster-backed runner pool; first-party self-hosted validation is for trusted branches and same-repo PRs.

Start Here

• Internal Docs Index
• Future Public Docs Package
• Current State
• Public Alpha Reopen Readiness
• Infrastructure Quick Start
• Pilot Repo Guide
• Browser RBE Candidate Guide
• Justfile Commands

Pilot Repos

Repos that want to pilot GloriousFlywheel today should start with the cache-backed path, not the executor-backed proof lane:

• use shared capability-class runner labels such as tinyland-nix, tinyland-docker, or tinyland-dind
• bootstrap Nix through the shared composite actions or an equivalent repo-local wrapper
• require a real BAZEL_REMOTE_CACHE before claiming Bazel cache-backed execution
• pass --remote_cache="$BAZEL_REMOTE_CACHE" from a wrapper after cache preflight succeeds
• keep pull-request cache behavior read-only unless a trusted write policy is explicitly selected
• treat RBE as target-class scoped: use executor-backed mode only for targets in config/rbe-target-eligibility.json or for an explicit proof run that will update that manifest
• for browser-backed RBE candidates, use the declared browser runtime authority and disable Playwright/Puppeteer lifecycle browser downloads before asking for a forced executor proof

The public-export-safe starting point is the Pilot Repo Guide and the Pilot Workflow Template. Internal operators should pair them with Cache Integration, Bazel Remote Execution, and Bazel External Fetch Authority. For Vite/SvelteKit Playwright or Puppeteer proof work, also read Browser Runtime Authority.

Developer Contract

Enter the repo through direnv allow or nix develop first. That devshell is the normal entrypoint for the shared dev+CI substrate contract, but it only attaches Bazel dogfood to the shared cache-backed path once the shell has a real BAZEL_REMOTE_CACHE value.

Normal developer usage is:

• enter the devshell with direnv allow or nix develop
• run just info and confirm whether Bazel is in shared-cache-backed or compatibility-local-only mode; the shell does not invent a shared cache endpoint on its own
• run just cache-contract when you need a non-networked explanation of the current cache attachment state
• use just bazel-build-cached for Bazel dogfood once just cache-contract-strict passes against a real shared cache endpoint
• use the executor-backed RBE path only for explicit proof or eligible target classes; target eligibility is tracked in config/rbe-target-eligibility.json
• use just check, just nix-build, and just app-test for routine repo validation
• treat raw local bazel build, raw local bazel test, bazelisk, and --config=ci as compatibility or debug paths only

Current main proves cache-backed local execution with shared cache acceleration and target-scoped executor-backed REAPI proofs. It does not prove universal full remote execution or remote-builder offload for every developer workload, so that boundary stays explicit.

Build And Validation

just check
just nix-build
just app-test

The repo also validates the Nix dashboard derivation in CI with nix build .#runner-dashboard. Use just nix-check or just check-full when you explicitly need the heavier full-flake validation path.

Current Boundaries

• the full source repo is public but still contains operator-facing internal docs and historical material; public-consumer posture is tracked separately
• public-docs/ is the conservative public-alpha entrypoint
• the generated public-docs references are enforced by just check-public-docs
• the scrubbed public-alpha mirror seed is enforced by just public-alpha-export-check and materialized by just public-alpha-export
• dogfood contract drift is enforced by just dogfood-contract-audit
• direct full-repo visibility is checked separately with just public-alpha-visibility-report; it is not the same as source dogfood health
• broad repo-level GitHub issues stay quiet by default; new repo work should be reopened intentionally when it needs issue tracking

License

Zlib