| 1 | # Review brief: fleet-internal engines (#335) |
| 2 | |
| 3 | You are an independent second reader of a design spec for the CARLOS |
| 4 | platform (this repository). Read it cold and adversarially. |
| 5 | |
| 6 | **Spec:** `docs/superpowers/specs/2026-10-21-fleet-internal-engines-design.md`, |
| 7 | at the commit named in the prompt. |
| 8 | |
| 9 | ## What it claims |
| 10 | |
| 11 | A registered doc engine's hostname is refused to every public request on |
| 12 | every box, and granted apps reach it through a per-instance unix socket (or |
| 13 | the edge-local door), relayed over the existing backhaul hop, which now |
| 14 | signs the caller. Read §2's anti-goals first: the spec fails if an engine |
| 15 | can become public again by accident, if a tenant can forge a caller, or if |
| 16 | an isolated instance's fence opens. |
| 17 | |
| 18 | ## What to check |
| 19 | |
| 20 | Check against the code on `main`, not the spec's description of it. Cite |
| 21 | `file:line` for every claim about existing code. |
| 22 | |
| 23 | - **The edge:** `internal/edge/edge.go` (`ServeHTTP`, `backhaul`, |
| 24 | `backhaulTo`, `httpFallbackHandler`, `Allowed`, `unknownHost`, the |
| 25 | cache path), `homemap.go` (`acceptHop`, `dialAddress`, `Owner`, |
| 26 | `ExactHome`), `mesh.go` (hop MAC), `door.go`, `doorkeys.go`, |
| 27 | `purge.go` / `purge_listen_unix.go` (`ListenControl`). |
| 28 | - **Instances:** `internal/activator/backend_exec.go` (launch env, |
| 29 | `CARLOS_CONTROL_SOCKET`), `provision.go`, `prepare.go`, |
| 30 | `generations.go`, `cmdunit.go`, `internal/host/units/carlos-instance*@.service`, |
| 31 | `internal/instancectl/gen.go`, `internal/layout/preflight.go`. |
| 32 | - **Grants and records:** `internal/doorkey`, `internal/caps`, |
| 33 | `internal/console/apistore.go` (store grant), `apisystemupdate.go` |
| 34 | (`systemOperator`). |
| 35 | |
| 36 | ## Questions to answer |
| 37 | |
| 38 | 1. Can a public request reach a registered engine by any path: a spelling |
| 39 | of the host, a wildcard route, the :80 handler, a door caller, a |
| 40 | backhaul from an old box, the login re-resolution, an upgrade, the |
| 41 | cache, a hibernating wake? |
| 42 | 2. Can a tenant forge or borrow a caller identity: through headers, through |
| 43 | another instance's socket, across generations, in the flat layout, via |
| 44 | the door? |
| 45 | 3. Does §6.3's "never reopens" hold across restarts, stale mirrors, revision |
| 46 | rollback by a bucket writer, and `engines remove`? |
| 47 | 4. Can the per-instance socket be built as described for every unit kind, |
| 48 | within the 107-byte socket path limit, and is the "one socket per |
| 49 | instance" claim true of the binds? |
| 50 | 5. Does the hop extension stay compatible with boxes on the old build in |
| 51 | both directions? |
| 52 | 6. Anything §5.5's limits break (streaming, upgrades, long conversions). |
| 53 | |
| 54 | ## Output |
| 55 | |
| 56 | Findings ranked P1 (spec fails a goal or anti-goal, or cannot be built), P2 |
| 57 | (a real gap a builder would hit), P3 (worth fixing). For each: the section, |
| 58 | the failure scenario as concrete steps, the code citation, and a suggested |
| 59 | fix. End with an overall verdict: accept, accept with fixes, or reject. |
| 60 | Do not report wording or style. |
| 61 | |
| 62 | ## Round 2 and later |
| 63 | |
| 64 | Read your previous findings (`CODEX-FINDINGS-ENGINES-R<n-1>.md`) and the |
| 65 | spec's §12 disposition table first. Start your answer with a table: each |
| 66 | previous finding, and whether the new revision actually fixes it (cite the |
| 67 | section). Then report only NEW findings. |
| 68 | |
| 69 | §2.1's rulings are fixed: do not argue for registration-based internal |
| 70 | marking or for unit-backed callers. Report only a mechanism that fails to |
| 71 | honour a ruling, fails a goal or anti-goal, breaks something else in the |
| 72 | platform, or cannot be built against `main`. A mechanism the spec names, |
| 73 | bounds and assigns is complete at spec level; do not ask for plan-level |
| 74 | detail. |
| 75 | |
amadan