From 0146450951e1e49b38af19afb2a4ad0b88029563 Mon Sep 17 00:00:00 2001 From: codex Date: Mon, 27 Jul 2026 03:31:34 +0000 Subject: [PATCH] docs(prd): extend authoritative cleanup boundaries --- .../0082-authoritative-failure-boundaries.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/prds/0082-authoritative-failure-boundaries.md b/docs/prds/0082-authoritative-failure-boundaries.md index 596441c9..d615668b 100644 --- a/docs/prds/0082-authoritative-failure-boundaries.md +++ b/docs/prds/0082-authoritative-failure-boundaries.md @@ -36,6 +36,15 @@ misleading behavior: destructive plan. 5. Gateway log-pump threads race stream closure during shutdown and emit uncaught exceptions even when shutdown otherwise succeeds. +6. Firecracker discovers VMs through whitespace-split `pgrep -a` output. + A configured cache path containing spaces can hide a live VM from the + snapshot and make its run directory appear orphaned. +7. Docker cleanup asks compose for its project snapshot in best-effort mode. + A transient query failure can therefore become an empty stopped-project + set and authorize deletion of associated state directories. +8. Firecracker artifact downloads and registry publication have no network + deadline, so an unresponsive registry can hold setup or release work + indefinitely. These are one design problem: state used to authorize deletion, replacement, or resource allocation must be authoritative at the point of use. @@ -46,6 +55,8 @@ or resource allocation must be authoritative at the point of use. appeared in a pre-confirmation snapshot. - Firecracker cleanup proves immediately before action that a PID is still the same Firecracker process and that a run directory is still orphaned. +- Firecracker process discovery reads NUL-delimited argv from `/proc`; paths + are never reconstructed from whitespace-delimited process listings. - All backend cleanup discovery primitives raise a typed enumeration error on operational failure. No backend may independently continue from a partial snapshot. @@ -60,6 +71,8 @@ or resource allocation must be authoritative at the point of use. callers because bottles themselves are untrusted. - Gateway child-output pumping treats expected stream closure during shutdown as completion while preserving diagnostics for unexpected failures. +- Artifact pull, existence-check, and publication requests use explicit + network deadlines. - Unit tests cover PID/path reuse, partial backend enumeration, transient policy resolution failure, slow bodies, concurrency saturation, and stream closure races. @@ -94,6 +107,13 @@ Backend-specific primitives define how to identify a resource. Firecracker uses process start identity plus canonical config/run paths; container backends use authoritative CLI queries and stable resource names/labels. +Container engines expose destructive name-based commands without a portable +compare-and-delete operation. Cleanup therefore refreshes after confirmation +and requires every discovery query to succeed, minimizing but not claiming to +eliminate the final name-reuse race. A future engine-specific stable-ID +primitive may close that residual window without moving control flow back +into each backend. + ### Enforcement state versus introspection state Egress enforcement retains its deny-all fallback because uncertainty must not @@ -124,6 +144,8 @@ reported through the supervisor's normal diagnostic channel. 5. Shared cleanup refresh/revalidation plus authoritative macOS discovery. 6. Strict supervisor introspection and bounded supervisor/Git HTTP work. 7. Gateway shutdown log-pump closure handling. +8. Lossless Firecracker process identities, authoritative Docker cleanup + queries, and bounded Firecracker artifact transfers. ## Open questions