jpmschweitzer/settled-reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(decisions): D-226 live-pause inspection harness (agent-navigable real-UI review)

Browse Source 
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) <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-05-24 11:24:00 +02:00
co-authored by Claude Opus 4.7
parent 8cedf670f0
commit bd5355d0a5
1 changed files with 26 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
decisions/architecture.md
+26 -1
View File
@@ -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)*