10.1 Ephemeral Tart Cleanroom VMs & Declarative Nix

chinwag runner start --ephemeral && chinwag env lock

PRD Metadata (PRD-0035 / CHWG-0202):

• Status: RATIFIED — SCHEDULED ON BOARD (02 · 📐 SCOPED & BENCHMARKED)
• Live Board Ticket: CHWG-0202 on GitHub Projects v2 (github.com/orgs/emunlabs/projects/1)
• Invariants Enforced: INV-NIX-VIRTIOFS-01 · INV-NIX-RO-STORE-01 · INV-NIX-ZERO-SYNTAX-01 · INV-CLEANROOM-TRUST-SPLIT-01
• Author & Assignee: Brian Spector (Emun Labs, Inc., 1401 Lavaca St STE 81335, Austin, TX 78701) · @ARCHITECT · @RUST · @QA

1. Problem Statement & Strategic Wedge

Cloud-hosted Apple Silicon macOS CI runners charge $0.08–$0.16/minute ($480–$960/month for an active engineering team) and suffer from two structural bottlenecks:

1. Cold Toolchain & Dependency Drift (45s–180s Tax): Even when an Apple Virtualization.framework VM clones in <2s, traditional CI pipelines spend 45s–180s running brew install, downloading Rust/Node/Python toolchains, or compiling uncached crates—and subtle drift between developer laptops (brew upgrade roulette) causes non-deterministic CI failures.
2. Self-Hosted Runner Contamination & Secret Exposure: Standard persistent self-hosted runners execute untrusted pull requests directly on the host filesystem, exposing ~/.ssh, macOS Keychain, and production .env secrets while polluting global build caches across jobs.

The Chinwag Solution (chinwag runner + chinwag env lock): Turn existing Apple Silicon Macs (Mac Studio, Mac mini, and idle MacBook Pro laptops over iroh QUIC) into a zero-trust, bit-for-bit reproducible cleanroom CI swarm that boots an isolated APFS Copy-on-Write macOS VM in 1.8 seconds, mounts the host's /nix/store and sccache read-only over VirtioFS in <200ms, compiles incremental Rust/TypeScript workspaces in 18 seconds (down from 9 minutes cold), and destroys the VM in 100ms after every job at $0/minute cloud compute cost.

2. Three-Layer Declarative Cleanroom Stack

flowchart TD
  A["Repository Manifests\n(Cargo.toml / package.json / .chinwag/env.ts)"] --> B["chinwag env lock\n(Zero-Nix-Syntax Lockfile Compiler)"]
  B --> C["Deterministic .chinwag/flake.lock\n(SHA-256 Content-Addressed Store Paths)"]
  C --> D["Ephemeral Tart Cleanroom VM (1.8s APFS CoW Clone)\n+ nix-darwin Immutable System Spine"]
  H["Mac Host NVMe Cache\n(/nix/store + sccache)"] -->|"VirtioFS Read-Only Mount (:ro)\n(<200ms Zero-Network Bind @ >5 GB/s)"| D
  D --> E["XNU Kernel Seatbelt (INV-NIX-RO-STORE-01)\n(Hard SIGKILL on /nix/store Writes & nix-daemon Sockets)"]

Layer 1: Ephemeral APFS Copy-on-Write Tart VMs (1.8s Boot, 100ms Teardown)

• Every CI job executes tart clone chinwag-cleanroom-base job-<uuid> --ephemeral on Apple's native Virtualization.framework.
• APFS Copy-on-Write clones the golden nix-darwin base image in 1.8 seconds without duplicating disk blocks on NVMe.
• Upon job completion (or timeout/crash), the supervisor captures a zstd-compressed + Hybrid Post-Quantum HPKE (X25519MLKEM768) failure bundle (Hook H4) and runs tart delete job-<uuid> in 100ms, guaranteeing zero state persistence between builds.

Layer 2: Host-Shared Read-Only /nix/store & sccache via VirtioFS (INV-NIX-VIRTIOFS-01 & INV-NIX-RO-STORE-01)

• Instead of downloading gigabytes of compilers and crates inside each ephemeral VM:
  1. The Mac host maintains a central /nix/store and content-addressed sccache directory on local NVMe (synchronized peer-to-peer across the org's iroh QUIC mesh).
  2. chinwag runner mounts /nix/store and the read-only build cache into the guest VM via VirtioFS (--dir=nix-store:/nix/store:ro,cache:/var/cache/chinwag:ro) at >5 GB/s memory-bus throughput.
  3. Hypervisor + XNU Kernel Seatbelt Immutability (INV-NIX-RO-STORE-01):
     • The host VMM enforces the :ro tag at the hypervisor boundary, rejecting FUSE_WRITE, FUSE_CREATE, FUSE_UNLINK, FUSE_RENAME, and FUSE_SETXATTR opcodes before they reach host APFS.
     • Inside the guest VM and on host workers, chinwag-contain-trampoline compiles non-negotiable XNU Seatbelt (sandbox_init) rules that terminate any process attempting to mutate /nix/store or connect to nix-daemon:

;; INV-NIX-RO-STORE-01: Read-only /nix/store; hard SIGKILL on all store writes & nix-daemon sockets
(allow file-read* (subpath "/nix/store"))
(deny file-write* (subpath "/nix/store") (with send-signal SIGKILL))
(deny file-write-xattr file-write-mode file-write-owner (subpath "/nix/store") (with send-signal SIGKILL))
(deny file-read* file-write* (subpath "/nix/var/nix/daemon-socket") (with send-signal SIGKILL))
(deny network-outbound (remote unix-socket (path-literal "/nix/var/nix/daemon-socket/socket")))

Layer 3: Zero-Nix-Syntax Lockfile Synthesis (INV-NIX-ZERO-SYNTAX-01)

• Developers never write a single line of .nix expression syntax:
  • Mode A — Zero-Config Auto-Lock (Default): Running chinwag env lock inspects Cargo.toml, rust-toolchain.toml, package.json, pyproject.toml, and go.mod, resolves the exact nixpkgs derivation hashes, and writes .chinwag/flake.lock with Ed25519-signed narHash Merkle verification receipts in .chinwag/state.crdb.
  • Mode B — Typed TypeScript Environment Spec (.chinwag/env.ts): For custom system libraries or service daemons (Postgres, Redis, MinIO), developers declare dependencies in typed TypeScript (@chinwag/jinx-nixpkgs) with full IDE autocomplete.

3. Two-Tier Trust Split (INV-CLEANROOM-TRUST-SPLIT-01)

To prevent untrusted fork PRs or experimental agent branches from touching release signing credentials, chinwag runner enforces two distinct runner profiles:

4. Multi-Mac 4-VM Cleanroom Swarm Over iroh QUIC

Apple's macOS EULA and Virtualization.framework cap each physical Mac at 2 concurrent macOS VMs. Chinwag turns that hardware limit into a federated multi-Mac advantage:

• Primary Workstation / Build Server (2 Always-On Cleanroom VMs): Runs two dedicated ephemeral Tart slots (slot-1, slot-2) continuously.
• Opportunistic Laptop Swarm (+2 Idle VMs per MacBook Pro): Developer laptops running chinwag runner join --opportunistic automatically contribute up to 2 ephemeral VM slots only when three hardware telemetry predicates hold:
  1. Connected to AC Wall Power (IOPMPowerSource == AC Power)
  2. Thermal State Nominal (NSProcessInfoThermalStateNominal)
  3. Host CPU Idle Headroom > 70%
• Instant Wakeup on User Input: The moment a developer touches the trackpad/keyboard or unplugs AC power, the laptop finishes or checkpoints the active step and drains its opportunistic runner slots in <500ms.

5. Mechanized Delivery Slices on the Project Board (CHWG-0202)

1. Slice 1A (CHWG-0202-A — Golden Tart Image & VirtioFS :ro Seatbelt): Build chinwag-cleanroom-base (nix-darwin + Determinate Nix), wire tart run --dir=nix-store:/nix/store:ro, and verify INV-NIX-RO-STORE-01 Seatbelt SIGKILL tests + <200ms mount latency.
2. Slice 1B (CHWG-0202-B — chinwag env lock Zero-Nix Compiler): Implement automatic lockfile synthesis from Cargo.toml / package.json -> .chinwag/flake.lock with pre-mount narHash verification receipts in .chinwag/state.crdb.
3. Slice 1C (CHWG-0202-C — chinwag runner 2-Tier Trust Gate & iroh Pool): Implement JIT GitHub Actions / GitLab runner registration (chinwag-ephemeral-public vs. chinwag-ephemeral-release), Hook H4 HPKE failure bundle sealing, and AC/thermal-gated multi-Mac pooling.

• Ready to ship verified code at autonomous speed? Reserve Your Organization Credit Pack →