docs(prd-0070): correct the firecracker-split difficulty framing
test / integration-docker (pull_request) Successful in 15s
tracker-policy-pr / check-pr (pull_request) Successful in 15s
test / unit (pull_request) Failing after 36s
test / integration-firecracker (pull_request) Successful in 3m23s
test / coverage (pull_request) Has been skipped
test / publish-infra (pull_request) Has been skipped

Reevaluated against the actual nft ruleset: the firecracker split's isolation
is nearly free, not "the real work." Agent VMs are already dropped except the
DNAT'd gateway ports, so re-pointing that single DNAT rule at the gateway VM
(dnat to $(gw_guest)) isolates agents from a separate orchestrator VM with zero
new agent rules; the only added nft is a mirrored gateway link + one
gateway->orchestrator forward rule. The effort is the mechanical second-VM
lifecycle, and it's validatable on a Firecracker host.

Sharpened the Access bullet accordingly and added a note to Sequencing
decoupling the original consolidation's "real work" (the broker shim) from the
split, whose difficulty actually runs the other way (docker/macOS do the real
work — new control network, dual-homed gateway, the token-only->L3 upgrade;
firecracker is nearly free).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-07-25 03:17:24 -04:00
parent b676ce3156
commit a74894c6f6
+24 -7
View File
@@ -413,13 +413,21 @@ blocks it at L3. **The split is the moment to fix that, not a risk to it:**
the control net. macOS mirrors this with a second container network and the
orchestrator's pinned control-net IP (no Apple DNS — reuse the
`gateway_hosts` `/etc/hosts` mechanism).
- **Firecracker — nearly free.** The nft forward chain already drops
everything a VM sends except the DNAT'd gateway ports, so a *separate*
orchestrator VM is unreachable by agent VMs with **no new agent rules**. The
new piece is a gateway-VM ↔ orchestrator-VM link — the same shape as today's
orch `/31` link, but between the two infra VMs instead of loopback within
one — with a forward-accept rule for that link alone. Agent egress DNATs to
the **gateway** VM's data ports; nothing DNATs to the orchestrator VM.
- **Firecracker — the isolation is nearly free; the work is a second VM.** The
nft forward chain already drops everything an agent VM sends except the
DNAT'd gateway ports, so re-pointing that **single DNAT rule** at the gateway
VM (`dnat to $(gw_guest)` instead of `$(orch_guest)` in
`scripts/firecracker-netpool.sh`) isolates agents from a *separate*
orchestrator VM with **zero new agent rules** — the existing `drop` handles
the rest. The only *added* nft is a second infra link that mirrors today's
orch `/31` block (a `masquerade` for its upstream egress) plus one
`iifname "$GW_IFACE" oifname "$ORCH_IFACE" accept` so the gateway VM reaches
`orch_guest:8099`. The actual effort is the **lifecycle** — a second infra VM
in the pool (boot / adopt / health / teardown, split init scripts) —
mechanical because it mirrors the existing single-VM code. All of it is
validatable on a Firecracker host (inspect the nft table; confirm an agent VM
cannot reach `orch_guest:8099`), so despite the PRD's earlier framing this is
**not** the hard or risky part of the split.
Role-scoped JWT auth (#469) stays as defense-in-depth on all three,
unchanged. A *compromised gateway* can already reach the orchestrator today
@@ -496,6 +504,15 @@ Backend order (cheapest proof → hardest → last):
the dev-harness so the app logic is already proven.
3. **macOS (Apple container)** — last (container-to-container networking).
That ordering — and "the real work" — is about the original **consolidation**:
the launch-broker shim and wiring the orchestrator into a VM. The later
orchestrator/gateway **split** (§"Separating the planes") is a smaller, separate
change, and its per-backend difficulty runs the *other* way: docker/macOS carry
the real work (a new control network, a dual-homed gateway, the token-only→L3
isolation upgrade), while on Firecracker the isolation is nearly free (re-point
one DNAT rule) and the only effort is a mechanical second infra VM. Firecracker
is not the hard part of the split.
Keep the gateway **service one shared thing** throughout.
## Non-goals