GloriousFlywheel Internal Live Contract 2026-04-23

Snapshot date: 2026-04-23

Purpose

Define the smallest authoritative internal contract for GloriousFlywheel as it exists now.

This note is the contract input for TIN-458.

It settles the current internal truth for:

• state authority
• endpoint authority by audience
• auth and mutation authority
• runner-class boundaries
• onboarding and bootstrap expectations

This is not the future public docs surface.

Audience Model

Platform Scope

The current internal live platform is:

• one physical cluster: honey
• one primary forge surface: GitHub
• one compatibility forge surface: GitLab
• one shared Nix binary cache family: Attic backed by RustFS
• one optional shared Bazel remote-cache family
• one internal operator dashboard and OpenTofu operator path

It is not yet:

• a forge-neutral mutation platform
• a stable public product surface
• a fully generated contract from config/organization.yaml

State Authority

Active stacks

The four active infrastructure stacks on current main are:

The active stack contract is now backend "s3" for all four stacks.

GitLab-managed HTTP state is not part of the current live contract for those stacks.

Authority order

Use this order when reasoning about truth:

1. repo code plus stack inputs define desired state
2. S3-compatible OpenTofu state defines managed-resource authority
3. live cluster state is observed state and may drift

Manual cluster edits are drift unless they are an explicit bounded operator action such as a temporary runner control action that is expected to reconcile later.

Compatibility-only state path

TF_HTTP_* and GitLab-managed HTTP state remain compatibility-only for:

• archived or external repair paths
• old documentation and old workflows not yet rewritten
• historical compatibility consumers

Do not treat GitLab HTTP state as the current internal authority for the four active stacks.

Endpoint Contract By Audience

Shared cache endpoints

Bazel external endpoint rule

There is not yet a stable supported general-consumer Bazel endpoint contract for dev machines or external repos.

Current truth:

• shared self-hosted runners use cluster-internal Bazel cache DNS
• operator or private-access Bazel hostnames may exist, but they are internal implementation detail, not the onboarding contract
• no public or semi-public Bazel hostname should be treated as the canonical downstream default

Dashboard and operator access rule

Dashboard access and cluster access are tailnet-first and private.

This note intentionally does not promote one public dashboard hostname or one public Kubernetes API hostname into the contract. Those remain internal access details owned by the operator surface and environment config.

Cache Roles

Attic

Attic is the internal shared Nix cache.

Current contract:

• shared runner default cache name is main
• runner-side configuration is injected automatically on supported self-hosted paths
• internal consumers may override ATTIC_CACHE for dedicated project caches when that is intentional
• read access may be exposed through https://nix-cache.tinyland.dev
• write authority remains internal and credentialed

Attic is an acceleration layer, not the public product’s primary discovery surface.

Bazel remote cache

Bazel remote cache is an optional acceleration layer.

Current contract:

• primary supported path is the cluster-internal runner path
• cache miss means rebuild, not product failure
• it is not yet a stable general public/dev-machine endpoint contract
• it is not a publication surface

FlakeHub

FlakeHub is publication and discovery only.

It is not part of the active runtime or bootstrap authority path for the internal platform.

Auth And Mutation Authority

Read-side auth

Current read-side operator access is mixed-mode:

• trusted proxy-header auth through Tailscale or mTLS is the preferred internal operator direction
• GitLab OAuth remains the interactive compatibility login path
• WebAuthn remains a supported interactive auth mechanism

When trusted proxy headers are enabled, proxy identity outranks stored interactive sessions.

Role model

Current dashboard role model is:

• viewer
• operator
• admin

Role assignment currently resolves through the auth-policy environment variables and trusted identity mapping.

Mutation authority

Current mutation truth is intentionally narrow:

• OpenTofu remains the authoritative path for managed infrastructure changes
• GitHub App auth is authoritative for ARC runner registration and runner job routing
• dashboard mutation remains compatibility-shaped today:
  • runner pause or resume
  • submitted config changes
  • GitLab-backed compatibility mutation and submission surfaces

There is still no settled forge-neutral or cluster-native replacement mutation authority.

Do not describe the current platform as already having a neutral control plane.

Runner-Class Contract

Shared GitHub runner labels

Compatibility GitLab runner classes

These still exist, but they are compatibility surfaces:

• gl-nix
• gl-docker
• gl-dind

Do not describe them as the primary product surface.

Proof-only or repo-scoped surfaces

These are not shared-platform promises:

• repo-scoped KVM harness labels such as nix-vm-test-kvm
• repo-scoped Darwin proof in tinyland-inc/lab
• any repo-scoped experimental hardware or proof lane not explicitly promoted into the shared label contract

Bootstrap And Onboarding Expectations

GitHub-first onboarding

The primary internal adoption path is:

1. install the Tinyland GitHub App
2. use shared runs-on labels
3. use the GloriousFlywheel composite actions where appropriate

Nix rule

The runner image carrying Determinate Nix is an optimization, not the whole contract.

Current expectation:

• use tinyland-inc/GloriousFlywheel/.github/actions/nix-job@main, or
• bootstrap or verify Nix explicitly before raw nix commands

Bazel rule

Current expectation:

• self-hosted Bazel consumers use BAZEL_REMOTE_CACHE or a repo-local --config=runner-pool style wrapper
• cluster-internal shared-runner cache addressing is the only stable current default

Dev-machine rule

Current expectation for internal human-operated machines:

• Attic reads may use https://nix-cache.tinyland.dev
• Attic writes require internal credentials and explicit intent
• Bazel remote-cache use from dev machines is not yet a stable platform promise
• direnv, flakes, and local shell bootstrap remain internal workflow expectations, not yet a polished external onboarding contract

Compatibility-Only And Out-Of-Contract Values

The following should be treated as stale, compatibility-only, or out of contract for current internal guidance:

• GitLab HTTP backend as the current authority for the four active stacks
• attic-cache-dev as the live cache namespace
• grpc://bazel-cache.attic-cache-dev.svc.cluster.local:9092
• https://attic.dev-cluster.example.com
• https://attic.tinyland.dev
• old fuzzy-dev cache hostnames
• any ad hoc public-facing Bazel cache hostname presented as the default downstream onboarding path

Not Yet Promised

This contract does not currently promise:

• a forge-neutral mutation authority
• a stable public docs surface
• a stable general-consumer external Bazel endpoint
• full contract generation from config/organization.yaml
• a shared platform-owned macOS lane
• broader GPU productization beyond the bounded shared tinyland-nix-gpu proof floor
• multi-cluster federation as part of the active platform contract

Consequence For Follow-On Rewrites

The next doc rewrites should align to this note before they try to improve style or onboarding.

The first rewrite bundle should target the highest-drift files already named in the owner/disposition matrix, especially:

1. docs/architecture/cache-and-state-roles.md
2. docs/architecture/deployment-contract.md
3. docs/runners/cache-integration.md
4. docs/runners/self-service-enrollment.md
5. docs/architecture/builder-contract.md
6. docs/ci-cd/pipeline-overview.md

Related

• GloriousFlywheel Internal Platform Brief And Boundary Rules 2026-04-23
• GloriousFlywheel Topology And Config Authority Strategy 2026-04-23
• GloriousFlywheel Square One Owner And Disposition Matrix 2026-04-23