Semiotic Codebase Visualization, Aqueduct LLM Flow & Gamified Developer Control Research (Nov 2026)

Synthesizes November 2026 state-of-the-art research across 3D software city codebase visualizers (CodeCharta, CodeCity, M3triCity), multi-agent LLM orchestrator & token-stream telemetry graphs (LangGraph Studio, AutoGen Studio, Rivet, Arize Phoenix), and classical hydraulic city-builder UX semiotics (Caesar III, Timberborn, Anno 117: Pax Romana). Establishes the normative Milestone v6.2 semiotic architecture for Vox Axis (LudusSandbox and HarnessRiverPanel), mapping crate layers (L0–L5), LoC, churn, and diagnostics to classical Roman architecture while translating LLM token throughput, prompt-cache reservoirs, verification gates, and developer commands into interactive Roman aqueduct hydraulics.

1. Executive Summary & Problem Statement

As autonomous coding harnesses and multi-agent orchestrators scale to 130+ crate workspaces (vox), developers face a dual observability crisis:

Spatial Codebase Blindness: Flat file trees and tabular static-analysis dashboards hide architectural layering (layers.toml), blast-radius coupling (fan-in / fan-out), and concurrent multi-agent write-set collisions.
Opaque Orchestrator & LLM Activity: Text-only streaming logs obscure which model tier (MENS Local QLoRA vs. Balanced Hybrid vs. Frontier Cloud) is active, how fast tokens are streaming (tok/s), how full the prompt-cache and context window reservoirs are, and where generated patches are held or rejected by deterministic verification gates (vox check, TOESTUB, cargo test).

Milestone v6.2 resolves both challenges by uniting two rich visual traditions—Software City Semiotics and Classical Roman Hydraulic Engineering (Aquaeductus, Castellum Divisorium, Clausurae Sluice Gates)—paired with zero-hop gamified developer controls (Check, Test, Audit, Stage/Revert Diff, Flush Sluice, Quarantine District, Claim Quest Yield).

2. Comparative Survey of External Systems (Current to November 2026)

2.1 Spatial Codebase & Software City Visualizers

System	Spatial Metaphor	Metric-to-Geometry Mapping	Strengths	Limitations Addressed by Vox `Urbs`
CodeCity (Wettel & Lanza)	3D Urban Grid	Districts = Packages; Building Height = Methods/LoC; Base Footprint = Attributes; Color = Churn / Age	Pioneered spatial anomaly detection (“God Class” skyscrapers vs. flat boilerplate neighborhoods)	Read-only static post-mortem; no live agent presence, no dependency hydraulics, and no direct developer action execution.
CodeCharta (MaibornWolff, 2024–2026)	3D Treemap City + Dependency Arcs	Area = LoC / RLOC; Height = Cyclomatic / Cognitive Complexity; Color = SonarQube Coverage / Debt	Bridges engineering and product leadership; supports multi-metric overlays and edge bundling	Generic rectangular boxes lack domain semiotics; every package looks identical regardless of architectural layer (`L0` vs. `L5`).
M3triCity / Gource / GitKraken Spatial	Evolutionary & Activity Graphs	Tree/Radial Nodes = Directories; Moving Sprites/Beams = Committer / Agent edits over time	Intuitive visualization of who is touching what in real time	Lacks persistent architectural topology and compiler/test gate enforcement.

Key Semiotic Takeaway for Vox Urbs: A software city becomes dramatically more legible when architectural role and layer (L0–L5) are encoded into the silhouette of the building itself (semiotic typology), rather than relying solely on box height:

L0 Foundation (vox-crypto, vox-secrets): Bedrock Vaults & Fortified Springheads (Fons & Aerarium).
L1 Core & Compiler (vox-compiler, vox-ast, vox-hir, vox-typeck): Stepped White Carrara Marble Parthenon / Acropolis Temples (Templum Linguarum).
L2 Runtime & Storage (vox-db, vox-search, vox-actor-runtime): Domed Rotundas & Library of Celsus Facades (Tabularium & Athenaeum).
L3 Orchestrator & Mesh (vox-orchestrator, vox-populi, vox-skills): Peristyle Praetorium Basilicas & Colonaded Forums (Praetorium).
L4 ML & Evaluation (vox-mens, vox-corpus, vox-eval): Vaulted Imperial Thermae & Training Palaestrae (Thermae Mens).
L5 Surfaces (vox-gui, vox-cli, vox-lsp): Multi-Tiered Oval Colosseums & Civic Rostra (Amphitheatrum).

2.2 Multi-Agent Orchestrator & LLM Token-Stream Visualizers

Platform (2025–2026)	Visual Paradigm	LLM & Token Stream Representation	Interactive Developer Controls
LangGraph Studio (LangChain)	State-Machine Directed Graph	Live node pulsing on `stream_mode` (`values`, `updates`, `messages`); step-by-step tool call assembly	Time-Travel Checkpoints: pause graph at any node, edit state JSON, and fork/replay execution.
AutoGen Studio / AG2 (Microsoft)	Multi-Agent Team Control-Transition Graph	Live message trajectories between conversational agents + inline tool/code execution blocks	Team Builder & Handoff Override: interrupt agent loop, inject human guidance, or swap model backend.
Rivet (Ironclad)	Reactive Dataflow Node Canvas	Per-node live token streaming inspector showing prompt inputs, completion stream, and branch taken	Live Node Breakpoints & A/B Split: toggle branch gates and re-run subgraphs in place.
Arize Phoenix (AX)	OpenTelemetry / OpenInference Trace & Agent Path Graph	Span waterfall + aggregated token gauges (`prompt_tokens`, `cache_read_tokens`, `ttft_ms`, `tpot_ms`)	Judge & Gate Attribution: isolate which verification step or prompt-cache miss caused latency/cost spikes.

Key Semiotic Takeaway for Vox Aqueduct Pipeline Cascade: Abstract node-and-wire boxes fail to convey throughput pressure, caching volume, and gate backpressure at a glance. By mapping the LLM pipeline onto a 3-tier Roman Aqueduct (Castellum Divisorium), developers read systemic health pre-attentively:

Laminar Flow Velocity & Particle Density $\leftrightarrow$ Token generation speed (tok/s) and active agent concurrency.
Fluid Chromatics & Particle Geometry $\leftrightarrow$ Semantic state:
- Crystalline Cyan Wave-Crests (❯❯): AQUA PURA — MCP tool & context retrieval supply (vox-search, @kb).
- Molten Gold Rhombus Ingots (◆◆): IGNIS OPERIS — Active LLM token streaming & AST patch synthesis.
- Verdigris Emerald Laurel Seals (◉): VIA VICTORIAE — Verified patches passing compiler, TOESTUB, and test gates.
- Crimson Warning Triangles & Backpressure Eddies (▲◎): CLOACA FAULT — Intercepted compiler errors, policy violations, or multi-agent collisions.

2.3 Classical Hydraulic & City-Builder UX Semiotics (Caesar III, Timberborn, Anno 117: Pax Romana)

Elevation & Gravity as Architectural Layering (Anno 117: Pax Romana, 2025–2026):
- In Anno 117, aqueducts carry water from high-elevation springheads down stepped stone arches to urban cisterns (Castella) and baths; “water cannot flow uphill” serves as an intuitive topological rule.
- Vox Translation: Dependency viaducts flow along architectural elevation terraces (L0 → L5). An upward dependency inversion (layers.toml violation) renders as a cracked crimson keystone arch (⚠ LAYER VIOLATION) with turbulent backpressure eddies.
Physical Sluice Gates & Settling Basins (Timberborn):
- In Timberborn, mechanical sluice gates (Clausurae) have immediate diegetic state signifiers: raised/lowered bronze gates, depth gauges on retaining walls, and visible backup/overflow when a gate is closed.
- Vox Translation: The 4 verification stages (Generated → Compiled → Tested → Gated & Verified) render as stepped travertine settling basins separated by interactive brass sluice gates. Developers can click any sluice gate to arm/bypass strict interception, flush stalled tasks, or inspect rejected diffs.
Walkers, Vexillum Standards & Civic Desirability (Caesar III):
- In Caesar III, patrician villas evolve visually as infrastructure coverage rises, while named walkers patrol streets with clear speech/task banners.
- Vox Translation: Active agents (LEGIO-XX, AEDILIS, QUAESTOR) march along isometric stone streets carrying draggable Roman Vexillum standards labeled with their live model (Qwen3-8B MENS / Claude Opus 4.6) and current tool call (⚙ vox_apply_structured_edit · +14/-3). Dragging a Vexillum banner onto another building or crate reassigns the agent on the spot.

3. Normative Semiotic Mapping & Developer Action Matrix (`v6.2`)

3.1 Semiotic Codebase City (`LudusSandbox.tsx` & `worldRenderer.ts`)

Visual Signifier in `Urbs`	Codebase / Orchestrator Meaning	Direct Developer Action (1-Click)
Terrace Elevation & Badge (`L0`–`L5`)	Crate layer in `docs/src/architecture/layers.toml`	Click `[L0..L5]` filter pill in the Semiotic Layer & Action Bar to isolate or pan to that architectural tier.
Monumental Temple / Basilica Silhouette	Crate archetype (`Acropolis Compiler`, `Praetorium Orchestrator`, `Colosseum GUI`, `Rotunda DB/MENS`, `Harbor Mesh`)	Click temple or top medallion to open the crate’s dedicated Vox Axis surface (`Explorer`, `Flow`, `Dashboard`, `Memory`, `MENS`, `Mesh`).
White Carrara Marble Plinth & Fluted Colonnade	High-fan-in / landmark crate with clean compilation & passing tests	Click to inspect upstream providers (`⬆`) and downstream blast radius (`⚡`) in the `ImperiumInspector` DAG.
Timber Scaffolding + Mason Chisel Sparks	Uncommitted Git diff (`+added / -deleted` lines) or active agent edit in progress	Click building or `[🔍 Diff Loupe]` to open `SpeculumLoupePopover` and Stage (`✓`) or Revert (`↺`) the file.
Rising Brazier Flames + Dark Smoke Plume	Compiler or TOESTUB diagnostic error (`errors > 0`) on crate/file	Click `[⚒ Fix Error]` or `[⚙ vox check]` in the Quick-Action Dock to dispatch an immediate repair turn.
Wrought-Iron Perimeter Portcullis (`🔒`)	`Clausura Ferrea` read-only agent quarantine active on crate	Click `[🔒 Quarantine]` to toggle write-protection so autonomous agents cannot mutate the crate.
Crossed-Swords Standard & Red Cone (`⚔`)	Multi-agent write-set or blast-radius collision	Click `[⇄ Serialize]` or `[🌿 Split Worktree]` to isolate colliding agents onto dedicated Git worktrees.

3.2 Aqueduct LLM & Orchestrator Cascade (`HarnessRiverPanel.tsx` & `riverCanvasRenderer.ts`)

Aqueduct Element	Orchestrator / LLM Telemetry	Direct Developer Action (1-Click)
Aquae Caput (Hub & 8-Spoke Source Arcade)	Shows the active Hub Coordinator + 8 MENS Spoke arches (`Lang`, `Compiler`, `Runtime`, `Orch`, `DB`, `GUI`, `CLI`, `Test`)	Click any Spoke Arch or Tier Card to inspect routing weights or pin the active model tier.
3 Parallel Marble Channels (`Cursus I / II / III`)	`Tier 1 Fast Local MENS` (Gold), `Tier 2 Balanced Hybrid` (Amber-Bronze), `Tier 3 Deep Architecture` (Verdigris Emerald)	Click `[Reroute Tier ▾]` or tier sluice card to shift posture between Local Thrift, Balanced, and Deep Reasoning.
Brass Sluice Gates (`Clausurae I–IV`)	Deterministic verification gates: `AST Parse`, `Typecheck`, `TOESTUB Audit`, `Test Suite`	Click any sluice gate pill to toggle Armed / Bypass, run `vox check` / `vox audit`, or flush stalled tasks.
Castellum Reservoir Dial Gauges	Live `Throughput (tok/s)`, `BLAKE3 Prompt Cache Hit %`, and `Context Reservoir Fill %`	Click `[Compact Context]` or `[Flush Cache]` to trigger session compaction (`vox_chat_compact_up_to`).
Aerarium Yield Basin (`+XP · +Denarii ◆`)	Gamified thrift yield earned when local MENS + BLAKE3 cache save cloud tokens	Click `[Claim Quest Yield]` to record XP/Denarii toward the `Collegium & Ludus Arena` leaderboard.