Rewrite ADR-0129 for MicroVM boundary

Task 5808 · Done · Coder · created · updated

Epic 5777 — MicroVM nodes. This child is the architecture's **C11: ADR and docs single home**. It runs after every build child (phase 2) so every pointer it writes resolves to a real file (check_context's dangling-path rule). Upstream: PRD task 5778 `prd`, Architecture task 5779 `architecture`. ## Original requirement (verbatim) Epic Goal 11: "ADR-0129 is amended to say the boundary is the VM, with the attack that defeats it stated in one sentence." PRD R15: "ADR-0129 is rewritten in place. The boundary is the VM. One sentence names the attack that defeats it (a VMM/KVM escape, e.g. a Cloud Hypervisor or host-kernel KVM bug). The per-OS-user, per-project `dynamic` content goes, and ADR-0118 G1/G3 closures and docs are restated for the VM. `docs/policies/worktree-pool-policy.md` §slot_mode is replaced by a pointer to the MicroVM node mode's single home." R16 (docs half): "... and every test, doc and UI string of theirs." ## Approach (settled) - Rewrite ADR-0129 in `docs/adrs/README.md` in place: the VM boundary; exactly one sentence naming the attack: *a Cloud Hypervisor/KVM escape that also bypasses its seccomp and landlock confinement reaches the node daemon's user*. Delete the per-OS-user/per-project `dynamic` content. Restate ADR-0118 G1/G3 for the VM; update ADR-0130's risk row. Kernel + patterns/anti-patterns + home pointer format; no "superseded by" trails (ADR rule 10). - New single home `docs/policies/microvm-nodes.md`: the mode (node mark, plan feature + org override, shared-node rule, blockers), the sizing chain (system → org → project → node, node wins), egress (default list single-homed in `apps/api/app/microvm_egress.py` — point, never copy; fake-IP DNS + relay in `apps/jaahd/microvm_egress.py`), lifecycle (destroy at done/reset/delete, retain on system_failed for `microvm_retention_hours`), the node runtime (`jaah-microvmd`, tap pool, pins file) — each a pointer to its code home, not restated detail. - Hub `CLAUDE.md`: the worktree router row drops `projects.slot_mode` and a MicroVM row routes to the new policy (keep the hub small). `docs/policies/worktree-pool-policy.md` §slot_mode becomes a pointer. - Sweep `docs/` for any remaining per-task OS-user, `slot_mode=dynamic`, hermetic-quarantine, `envhelper`, `env_registry`, `jaah-envd@`, `jaah-env@` prose and rewrite/delete it. - Write any path that does not exist as plain prose, never in backticks. ## Acceptance criteria (verbatim) - AC-17 ADR. Oracle: ADR-0129 in `docs/adrs/README.md` states the VM boundary and contains exactly one sentence naming the attack that defeats it. No living doc still describes per-task OS users, `slot_mode=dynamic` or hermetic quarantine (`python3 tools/check_context.py` green). - AC-12 (docs half): `grep -rn "slot_mode\|HERMETIC_ENVIRONMENTS_ACTIVE\|envhelper\|env_registry\|jaah-envd@\|jaah-env@" apps packaging docs` returns only migration history (`apps/api/migrations/`). Credentials & reach: AC-17 (`check_context.py`) — none beyond the worktree — **verified**. AC-16 — forge via `jaah-forge` — **verified**. Out of scope: no code changes. Do not restate code-home detail in prose (single-home). Do not touch static-worktree, port-grid or co-located-node policy beyond the §slot_mode pointer (N1). No perf claims (N9). Epic: "retiring static worktrees, co-located nodes (Multi-Node Hosts), the port grid or user slots; Mac/Windows hosts; GPU passthrough; any change to pricing beyond moving products to KVM-capable instance families." Done means: - ADR-0129 states the VM boundary and contains exactly one attack sentence — quote it in the report. - `grep -rn "slot_mode\|HERMETIC_ENVIRONMENTS_ACTIVE\|envhelper\|env_registry\|jaah-envd@\|jaah-env@" apps packaging docs` returns only `apps/api/migrations/` — cite output. - `docs/policies/microvm-nodes.md` exists, routed from `CLAUDE.md`; worktree-pool-policy §slot_mode is a pointer. - `python3 tools/check_context.py` green (and `--audit` shows no new orphan). - `./dc check full` green on the PR; PR auto-merged and the Jaah Deploy for dev succeeds (AC-16).

Outcome

ADR-0129 rewritten for the VM boundary (one attack sentence); G1/G3 + cross-refs restated; new microvm-nodes.md routed from hub. check_context green, AC-12 grep clean. PR #5113 merged; dev Jaah Deploy success. Deferred: stale code strings, offboard VM disks.

Pull request

Artifacts

Activity

  • Draft
  • Ready
  • Runner started
  • Runner ended (done)