From bd5355d0a5c443c2d21fc59ed8f10f21e65f96ac Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Sun, 24 May 2026 11:24:00 +0200 Subject: [PATCH] docs(decisions): D-226 live-pause inspection harness (agent-navigable real-UI review) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A multi-layer debug/review harness that reuses the real client UI so a human and an automated agent can inspect deterministic server-computed state by attaching to the live (auto-pausing) server. Supersedes the offline file-dump idea from the D-225 discussion — the review tool is the production tool, no divergence, no stale dumps. Stack (bottom-up): live-pause substrate (TickRate::Paused + paused-allowlist, triggered by gameplay_occluded; freezes world phases, keeps the bridge/gen-drain alive) -> layer-stream proxy (D-225) -> human-visual viewer (#960, additive overlays; shape=attractor type, color=sub-biome) -> agent channel (AtlasAgentInterface: JSON observe + named-intent act, headless) -> interactive capture (reuses the existing tests/run-visual primitive; complements, does not supersede, the visual-golden regression role). Consumers: Layer-1 geography now; economics + save-state inspection adopt the pattern in their phases. Designed with Tyre (channel/pause/headless) + Araminta (overlay encoding + affordance UX). Rides existing seams — a naming-and-contract exercise, not a new subsystem. Tickets: #970 auto-pause, #969 proxy, #960 viewer, #971 agent channel, #972 capture (build order bottom-up). Co-Authored-By: Claude Opus 4.7 (1M context) --- decisions/architecture.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/decisions/architecture.md b/decisions/architecture.md index e1119f82d..d45a56115 100644 --- a/decisions/architecture.md +++ b/decisions/architecture.md @@ -1505,4 +1505,29 @@ Technical foundation decisions that constrain implementation: engine, client-ser --- -*85 decisions (D-001 through D-225, excluding gaps). Last updated: 2026-05-23 (D-225 — Atlas layer-stream proxy, resolves Q-098)* +### D-226: Live-pause inspection harness — agent-navigable, real-UI debug/review +- **Date:** 2026-05-24 +- **Decision:** A multi-layer harness that reuses the **real client UI** so both a human *and* an automated agent can review/debug deterministic server-computed state, by attaching to the live (auto-pausing) server. It supersedes the offline file-dump idea floated during D-225: the review tool *is* the production tool (zero divergence), inspecting live data through the real path rather than stale dumped artifacts. The stack, built bottom-up: + + **(1) Live-pause substrate.** The client attaches to the running server; entering a fullscreen implant app (the Atlas) **auto-pauses the sim**. Pause freezes the world-advancing tick phases (Movement / Simulation / Economy / Storyteller / Knowledge / TickAdvance) but **keeps PreInput (the gen-drain), Input (to receive resume), Snapshot and PostSnapshot (the bridge) alive** — so the UI keeps fetching data while the world is frozen. Built on the existing `TickRate::Paused` + the `input.rs` paused-allowlist seam, triggered by `HudGroups::gameplay_occluded` (D-170). For static Layer-1 geography pause is only a compute-saver; for *dynamic* state (economics) a stable frozen snapshot is essential. + + **(2) Data — layer-stream proxy (D-225).** Streams `Layer1Output` (later economics state, save state) from server to client on demand, mod-first, no bake. + + **(3) Human-visual viewer (#960).** The Atlas renders cascade layers as **additive, toggleable overlays** (relief base + rivers + drainage basins + attractors; *shape* encodes attractor type, *color* encodes sub-biome), extending the existing `OVERLAY_DEFS` / `AtlasOverlayBar` with a `generation` overlay group + a left-side legend panel. Buttons start `pending`/locked and unlock as each layer's data arrives ("grows as each layer lands", D-166). + + **(4) Agent-navigable channel.** A client-side `AtlasAgentInterface` exposing JSON `observe` (current data state + a walkable **UI affordance tree**) and `act` (named **semantic intents** — `select_body`, `open_regional`, `set_overlay`, `back`, … — backed by the same handlers a click calls, **not** pixel coordinates; the map uses `_gui_input`). Runs headless. Turns human-eyeball review into an agent-automatable QA sweep across the whole Reach (and later economics/saves). + + **(5) Capture — reuse, don't reinvent.** Interactive screenshots reuse the **existing `tests/run-visual` capture primitive** (frame-delayed `save_png`, proven by `character_creation.gd`'s standalone capture). The agent channel adds *interactive* explore-and-capture; the existing scenario/flow **visual-golden regression** role stays distinct and unchanged. Clear hover state before capture. + + **Consumers** (build geography now; the others adopt the pattern in their own phases — do **not** build them now): Layer-1 geography (Phase 4) → economics (dynamic; pause essential) → save-game inspection (load → pause → inspect; `save_state.rs` substrate). + +- **Rationale:** Reusing the real UI — rather than a parallel offline renderer or dumped files — means the debug/review surface never diverges from what ships, and a dropped artifact can't go stale. Agent-navigability converts qualitative "does the synthesis look natural?" review from a manual eyeball pass into an automatable sweep that flags the few outliers for a human. The harness rides seams that already exist (`TickRate::Paused`, the paused-allowlist, `gameplay_occluded`, the bridge framing, the `run-visual` capture primitive) — a naming-and-contract exercise, not a new subsystem. +- **New surface:** server pause-gating (run-conditions on the world phases keyed to a pause command); client `AtlasAgentInterface` (`observe`/`act`, Control-tree walker) + its local transport; the generation overlay rendering + selector + legend; interactive capture wired to `run-visual`. +- **Implementation:** Phase 4 (epic #750), built bottom-up — auto-pause substrate, #969 proxy (D-225), #960 viewer, agent channel, agent capture. Geography is the first consumer. +- **Raised by:** Jeroen + Claude (design), with Tyre (channel/pause/headless architecture) + Araminta (overlay encoding + affordance UX), 2026-05-24. +- **Cross-reference:** [D-225](#d-225) (layer-stream proxy — the data path), [D-166](#d-166) (per-layer Atlas progress viewer), [D-191](#d-191) (Atlas viewer), [D-169](#d-169) / [D-170](#d-170) (implant components / HUD occlusion — `gameplay_occluded` trigger), [D-200](#d-200) / [D-203](#d-203) (execution tiers / LRU cache), Q-099 (mod content catalog), `tests/run-visual` (capture primitive), `save_state.rs` (save-inspection consumer) +- **Dissent:** None + +--- + +*86 decisions (D-001 through D-226, excluding gaps). Last updated: 2026-05-24 (D-226 — live-pause inspection harness)*