ADR: Disposable JuiceFS rig and non-mutating Development acceptance

Date: 2026-08-28 Status: Accepted for Development validation

Context

Shared JuiceFS volumes need filesystem-level evidence across more than one client, without allowing local tests to share metadata, credentials, object storage, or teardown scope with the control plane, CAS, or object-FUSE. macOS developers normally cannot prove KVM/virtiofs guest behavior. A Development acceptance command also risks turning a test harness into a live mutator.

Decision

Provide a fixed-name local Compose rig under infra/test/juicefs-rig with:

• PostgreSQL 16 over TLS, separately owned juicefs_dev (JuiceFS metadata) and platinum_rig (local CP) databases, and roles that cannot create roles/databases or bypass row security;
• a dedicated MinIO bucket/prefix with loopback-only service ports;
• JuiceFS CE 1.4.1 binaries verified against architecture-specific SHA-256;
• two independent privileged Linux RW clients and a distinct RO client; and
• a canonical bare repository inside the disposable CE namespace at /system/git/rig-project.git, plus per-client host-only gitdirs whose exported worktrees never expose .git, a remote, or a system subtree; and
• marker-, path-, and label-guarded teardown that removes only this project and its named volumes/network, never Docker-pruned resources.

On macOS/no-KVM, the rig explicitly reports a Linux-container substitution and does not claim guest or virtiofs proof. The local verifier fails required filesystem checks instead of recording skipped checks as passing.

Provide verify/juicefs-development-e2e.sh as a Development-only dry-run, local preflight, and explicitly authorized execution runner. It rejects every other API base; its execution path requires an exact Development SHA, two named host identities/fingerprints, dedicated org/bucket inputs, separate 0600 tokens, and a restore trap before it mutates gates or fixtures.

Consequences

The local rig gives reproducible, disposable coverage for FUSE, PostgreSQL, MinIO, cloning, quotas, and recovery. It cannot establish real control-plane route behavior, host enrollment, KVM guests, or virtiofs. Those remain explicit Development acceptance requirements rather than implied by Compose success.

The loopback-only app-rig self-starts a fixed isolated CP/dashboard fixture, the separate platinum_rig logical database, and two simulated command workers. Its result is explicitly limited to CP/web and simulated host-command behavior; it never upgrades to a guest or virtiofs claim.

The app-rig simulators advertise Git v1 only after JuiceFS enrollment and exercise bounded CP lifecycle/replay/conflict/project-usage receipts. They are not Git filesystem evidence. The FUSE rig separately exercises a real hidden bare repository inside the CE namespace, exported plain worktrees, checkpoint/push, restore and conflict without a network Git coordinator. Development acceptance requires advertised public Git v1 routes and fails closed when they are absent. It also authorizes the canonical /v1/admin/hosts/:id/roll workflow dispatch separately and machine-verifies the fresh heartbeat's exact agent SHA/fingerprint after that health-gated workflow returns.