amadan
spec: fleet architecture — say what ships
The spec is the binding document and lives in this branch; shipping code that silently contradicts it is how a spec stops being trusted. - §7: the third missing-inventory state is "unreadable", not "stale". The implementation is the improvement — an age is already on the page, so staleness is a number the operator reads, not a fourth state, and a snapshot that will not parse is the failure worth naming. - §6.4: describes the layer order that actually ships, which satellites are drawn (bucket, alarm) and which are table-only (identity, and likewise firewall/network/disk/certificate), and what "anchored to its owner" means in a layered layout. - §6.4: anchor-linking nodes to their detail cards is NOT delivered. Recorded as a follow-up rather than left as a false promise, and noted in §10 as deferred.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 file changed,
+30
−8
docs/superpowers/specs/2026-08-19-fleet-architecture-diagram-design.md+30 −8
CI passed — run details
diff --git a/docs/superpowers/specs/2026-08-19-fleet-architecture-diagram-design.md b/docs/superpowers/specs/2026-08-19-fleet-architecture-diagram-design.md| index eabe177ae..0598d14c5 100644 |
| --- a/docs/superpowers/specs/2026-08-19-fleet-architecture-diagram-design.md |
| +++ b/docs/superpowers/specs/2026-08-19-fleet-architecture-diagram-design.md |
| @@ -258,9 +258,19 @@ This is the rule that makes the page worth building: |
| A deterministic layered pass in Go, no JavaScript library, no CDN |
| (the vendored-icons rule): |
| -1. **Layer by kind** — `zone`/`record` at layer 0, `router` at 1, `box` |
| - at 2, `app`/`instances` at 3, with `bucket`, `alarm` and `identity` |
| - as satellites anchored to their owner. |
| +1. **Layer by kind** — left to right: `zone`, `record`, `ip`, |
| + `router`/`external`/`alarm`, `box`/`machine`, `apps`, `bucket`. Of the |
| + satellites, `bucket` and `alarm` are DRAWN and `identity` is not: |
| + `alarm` sits in the column immediately left of the box or machine it |
| + watches — few enough per fleet (one auto-recover alarm per box) that an |
| + armed alarm beside its box is worth the ink, and left of it so the |
| + `watches` edge reads in the same direction as every other edge. |
| + `identity`, and likewise `firewall`, `network`, `disk` and |
| + `certificate`, are listed in the resource tables below the diagram |
| + instead: a graph that draws every IAM role is a hairball. "Anchored to |
| + its owner" in a layered layout means ordered by the row of the thing it |
| + watches, which is what the barycentre sweep in (2) does — not pinned to |
| + the same Y. |
| 2. **Order within a layer** to reduce crossings: one barycentre sweep |
| down and one up, then a stable sort by name so the same fleet always |
| produces the same picture. A diagram that reshuffles between refreshes |
| @@ -269,9 +279,13 @@ A deterministic layered pass in Go, no JavaScript library, no CDN |
| `viewBox` so it scales without script. |
| Legibility as the fleet grows: instances are drawn as one `instances` |
| -node per box carrying a count, never one node per instance. Nodes link |
| -by anchor to detail cards below the SVG, so the page needs no JS to be |
| -useful and no click handler to be complete. |
| +node per box carrying a count, never one node per instance. |
| + |
| +**Not delivered (follow-up, 2026-08-19):** nodes were to link by anchor to |
| +their detail cards below the SVG. They do not; the page needs no JS |
| +regardless, because everything on it is server-rendered, but clicking a |
| +node does nothing and the reader scrolls to find the card. Recorded here |
| +rather than left as a promise the page does not keep — see §10. |
| ## 7. The page |
| @@ -299,8 +313,13 @@ Body, in order: |
| **Every section soft-fails independently.** A missing inventory renders |
| the CARLOS half of the page with an "inventory not available" panel, |
| naming which of the three states applies: never taken, not granted |
| -(latched), or stale. A failed registry read costs the overlay, not the |
| -page. Nothing renders a confident "none" for a read that did not happen. |
| +(latched), or unreadable — the snapshot object exists but could not be |
| +fetched or parsed. ("Unreadable" rather than "stale", which an earlier |
| +draft of this section said: the snapshot's age is already on the page |
| +beside the account id, so staleness is a number the operator reads, not a |
| +fourth state, and a snapshot that will not parse is the failure actually |
| +worth naming.) A failed registry read costs the overlay, not the page. |
| +Nothing renders a confident "none" for a read that did not happen. |
| ## 8. The IAM grant (precondition) |
| @@ -362,3 +381,6 @@ as ungranted, which is the designed state and not a fault. |
| that a CLI door is a small follow-up, but it is not this spec. |
| - Cost Explorer actuals on this page. `/fleet/economics` owns money; |
| this page owns shape, and shows the modelled per-box figure only. |
| +- **Deferred, not dropped:** anchor-linking each diagram node to its detail |
| + card below the SVG (§6.4). The page ships without it; every fact the |
| + anchors would have jumped to is on the page already. |