feat: complete migration to 3D use of loc end-to-end

Author: tmcarmichael

README.md

@@ -4,7 +4,7 @@
 ![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero-brightgreen.svg)
 ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
 ![CI](https://github.com/tmcarmichael/compass-core/actions/workflows/ci.yml/badge.svg)
-![Coverage](<https://img.shields.io/badge/Coverage-78%25_(20.5K_measured)-blue.svg>)
+![Coverage](<https://img.shields.io/badge/Coverage-88%25_(20.5K_measured)-blue.svg>)
 
 A layered decision architecture for intelligent behavior in a real-time 3D world.
 
@@ -18,7 +18,7 @@ Decision-making is layered by design. Priority rules enforce the safety envelope
 
 A legacy 3D MMORPG emulator provided the demanding sandbox that forced this architecture to evolve: partial observability, noisy state, spatial hazard, resource pressure, and constant interruption. What began as reactive rules and state-machine routines grew into a layered system that preserves survival guarantees while adding learned adaptation and anticipatory planning. The result is an architecture shaped by the demands of the world it was built in.
 
-The system operates autonomously in multi-hour sessions. In [recorded sessions](docs/samples/learned-encounter-data.md), average fight duration for a given entity type dropped from 29.5s to 15.9s as encounter history accumulated, session grades improved from B to A, and operational parameters auto-tuned from defaults. See [docs/samples/](docs/samples/) for full session telemetry: [decision traces](docs/samples/decision-trace.md), [GOAP plans with cost tracking](docs/samples/goap-planner.md), [forensic ring buffer dumps](docs/samples/forensics-ring-buffer.md), and [4-tier log output](docs/samples/session-tiers.md) from live sessions.
+> **Scope.** This is a cleaned extraction from a private working repo, published as an architecture reference. Live runtime config, environment assets, and operational glue are intentionally omitted. See [docs/samples/](docs/samples/) for real session output.
 
 ---
 
@@ -219,7 +219,7 @@ GOAP                 Goal planner, spawn prediction, trajectory forecasting
 
 ---
 
-## Why a Legacy 3D MMORPG Emulator
+## Why an MMORPG Sandbox
 
 A legacy 3D MMORPG emulator concentrates most of the hard problems in autonomous agent design into a single domain:
 
@@ -236,7 +236,7 @@ A legacy 3D MMORPG emulator concentrates most of the hard problems in autonomous
 
 ## Reading the Code
 
-Start with [`perception/state.py`](src/perception/state.py): the frozen `GameState` and `SpawnData` dataclasses that every layer depends on. Then [`brain/decision.py`](src/brain/decision.py): the coordinator that evaluates rules and manages routine lifecycles. Pick any rule module in [`brain/rules/`](src/brain/rules/) to see how conditions and score functions are written. The GOAP planner lives in [`brain/goap/planner.py`](src/brain/goap/planner.py). Combat strategies are in [`routines/strategies/`](src/routines/strategies/).
+After the top-level overview, read by subsystem. Start with any rule module in [`brain/rules/`](src/brain/rules/) to see how conditions and score functions are written. Then inspect [`brain/goap/planner.py`](src/brain/goap/planner.py) for goal-directed sequencing, [`brain/world/model.py`](src/brain/world/model.py) for derived world intelligence, and [`brain/runner/loop.py`](src/brain/runner/loop.py) for the 10 Hz execution path. Combat strategies live in [`routines/strategies/`](src/routines/strategies/).
 
 For architecture details beyond the README, see [`docs/architecture.md`](docs/architecture.md). For design rationale, [`docs/design-decisions.md`](docs/design-decisions.md). For the full evolutionary arc, [`docs/evolution.md`](docs/evolution.md).
 
@@ -268,10 +268,6 @@ docs/                    Architecture, design decisions, evolution history, retr
 
 </details>
 
-> **Note:** This repository is an architecture and implementation reference. Running the full system requires the target environment and supporting assets described in the docs. This is a cleaned extraction from a private working repo; the evolution described in [docs/evolution.md](docs/evolution.md) reflects the actual development arc, published here as a single snapshot.
-
----
-
 Built with Python 3.14, zero runtime dependencies, and the standard library. See [docs/testing.md](docs/testing.md) for the test strategy and coverage philosophy.
 
 ---

docs/retrospective.md

@@ -97,8 +97,6 @@ The emulator was the concrete proof point, but this architecture applies to any
 
 - **Other game environments**: any application with readable process memory can be perceived the same way. The perception layer is the only part that changes.
 
-- **Robotics control loops**: perception -> decision -> action -> motor is the standard robotics architecture. The 10 Hz priority-rule engine, the non-blocking tick contract, and the hysteresis patterns apply directly. GOAP planning with learned cost functions is directly applicable to warehouse robots, delivery drones, and autonomous vehicles.
-
 - **Autonomous testing agents**: navigating complex UIs, handling error states, recovering from unexpected conditions. The routine state machine pattern handles multi-step UI flows cleanly.
 
 - **Any long-running autonomous system**: the 4-tier logging pipeline, the forensic buffer, and the scorecard system are useful wherever an agent operates unattended and needs post-hoc debugging.

docs/samples/learned-encounter-data.md

@@ -12,7 +12,7 @@
  "scorecard":{"pathing":0,"defeat_rate":100,"pull_success":100,"targeting":100,"survival":100,"mana_efficiency":83,"uptime":100,"overall":88,"grade":"B"},
  "mob_stats":{"a_tree_snake":{"avg_dur":29.5,"avg_mana":23,"pet_death_rate":0.07,"danger":0.04}}}
 
-{"session":"session_20260327_213213","version":"v1.37.2","duration_min":18.0,"defeats":24,"dph":77.8,
+{"session":"session_20260327_213213","version":"v1.33.2","duration_min":18.0,"defeats":24,"dph":77.8,
  "scorecard":{"pathing":100,"defeat_rate":100,"pull_success":95,"targeting":91,"survival":100,"mana_efficiency":100,"uptime":100,"overall":98,"grade":"A"},
  "mob_stats":{"a_tree_snake":{"avg_dur":15.9,"avg_mana":3,"pet_death_rate":0.0,"danger":0.0}}}
 
@@ -25,7 +25,7 @@
 
 ```json
 // data/memory/nektulos_tuning.json
-{"v":1,"roam_radius_mult":1.2999999999999998,"social_add_limit":5,"mana_conserve_level":0}
+{ "v": 1, "roam_radius_mult": 1.2999999999999998, "social_add_limit": 5, "mana_conserve_level": 0 }
 ```
 
 Defaults: `roam_radius_mult=1.0`, `social_add_limit=3`, `mana_conserve_level=0`.

docs/testing.md

@@ -1,3 +1,5 @@
+<!-- last_modified: 2026-03-30 -->
+
 # Testing
 
 How the test suite is structured, what it covers, and what it deliberately omits.
@@ -15,7 +17,7 @@ Hypothesis profiles: `dev` (50 examples, fast) and `ci` (200 examples, thorough)
 
 ## Coverage strategy
 
-Coverage is measured in CI with `pytest-cov` and enforced with a `fail_under` floor in `pyproject.toml`. The measured surface is ~17.7K of ~22K total source lines (80% of the codebase). Only 7 files are omitted; all require a live game client or game asset files.
+Coverage is measured in CI with `pytest-cov` and enforced with a `fail_under` floor in `pyproject.toml`. The measured surface is the full 20.5K source lines with zero omissions.
 
 ### What is covered
 
@@ -48,21 +50,17 @@ set_backend(recorder)
 
 This makes every routine testable without mocking, monkeypatching, or environment access. Tests assert on `recorder.actions` to verify motor commands.
 
-### What is omitted (and why)
+### Previously omitted modules
 
-The `[tool.coverage.run] omit` list in `pyproject.toml` excludes only modules that require external hardware or binary assets:
+Seven modules that were previously excluded from coverage measurement are now fully measured and tested via mock-based testing:
 
-| Omitted path | Reason |
-|---|---|
-| `src/perception/*` | Win32 `ReadProcessMemory`: requires a live game client process |
-| `src/eq/s3d.py`, `wld.py`, `zone_chr.py` | Binary asset parsers: require S3D/WLD game files |
-| `src/runtime/orchestrator.py` | Session lifecycle: thread coordination, logging wiring |
-| `src/runtime/server.py` | Web server: HTTP/WebSocket infrastructure |
-| `src/runtime/agent.py` | Process management: Win32 admin check, process spawning |
+- **Perception layer** (`src/perception/*`): Win32 `ReadProcessMemory` calls are tested through mock readers that return crafted SPAWNINFO buffers. `read_state()` assembly, profile chain resolution, struct validation, log parsing, and all sub-readers (char, spawn, inventory) are covered.
+- **Binary asset parsers** (`src/eq/s3d.py`, `wld.py`, `zone_chr.py`): tested with synthetic binary fixtures built via `struct.pack`.
+- **Runtime orchestration** (`src/runtime/orchestrator.py`, `agent.py`): config building, feature toggles, log buffer, session pruning tested with mock dependencies.
 
-These 7 files (~4K lines) are validated through runtime invariants, the forensics ring buffer, and session-level observability.
+### Compensating controls for deeply-coupled code
 
-### Compensating controls for omitted code
+The remaining uncovered lines are concentrated in multi-phase routine tick handlers (motor-coupled state machines) and the 10 Hz brain runner loop (threading, I/O). These are validated through:
 
 1. **Runtime invariants** (`src/util/invariants.py`): assertions that fire during operation and flush diagnostics on violation
 2. **Forensics buffer** (`src/util/forensics.py`): 300-tick ring buffer that dumps to disk on death or crash, providing post-hoc debugging for the perception/routine layers

pyproject.toml

@@ -27,6 +27,7 @@ dev = [
     "hypothesis>=6.100",
     "pre-commit>=4.0",
     "pytest-benchmark>=5.0",
+    "pytest-xdist>=3.5",
 ]
 
 # ── Tool configuration ───────────────────────────────────────────────
@@ -99,6 +100,6 @@ markers = [
 source = ["src"]
 
 [tool.coverage.report]
-fail_under = 78
+fail_under = 91
 show_missing = true
 skip_empty = true

src/brain/context.py

@@ -37,7 +37,7 @@
 from brain.state.threat import ThreatState
 from brain.state.zone import ZoneState
 from core.constants import XP_SCALE_MAX
-from nav.geometry import distance_2d
+from core.types import Point
 from perception.state import GameState
 from util.thread_guard import assert_brain_thread
 
@@ -283,16 +283,16 @@ def has_unlootable_corpse(self, state: GameState, max_dist: float = 120.0) -> bo
         for spawn in state.spawns:
             if not spawn.is_corpse:
                 continue
-            dist = distance_2d(state.x, state.y, spawn.x, spawn.y)
+            dist = state.pos.dist_to(spawn.pos)
             if dist > max_dist:
                 continue
-            defeat = self.find_unlootable_kill(spawn.name, spawn.x, spawn.y, corpse_spawn_id=spawn.spawn_id)
+            defeat = self.find_unlootable_kill(spawn.name, spawn.pos, corpse_spawn_id=spawn.spawn_id)
             if defeat:
                 return True
             # Log WHY matching failed
             for k in self.defeat_tracker.defeat_history:
                 if not k.looted and time.time() - k.time < 300:
-                    kdist = distance_2d(spawn.x, spawn.y, k.x, k.y)
+                    kdist = spawn.pos.dist_to(k.pos)
                     name_match = k.name in spawn.name or spawn.name.startswith(k.name)
                     log.debug(
                         "Loot match: corpse='%s'@(%.0f,%.0f) vs defeat='%s'@(%.0f,%.0f) "
@@ -318,25 +318,29 @@ def clear_recent_kills(self) -> None:
             (sid, t) for sid, t in self.defeat_tracker.recent_kills if now - t < 60
         ]
 
-    def record_kill(self, spawn_id: int, name: str = "", x: float = 0.0, y: float = 0.0) -> None:
+    _ORIGIN = Point(0.0, 0.0, 0.0)
+
+    def record_kill(self, spawn_id: int, name: str = "",
+                    pos: Point = _ORIGIN) -> None:
         """Delegate to defeat_tracker."""
         assert_brain_thread("record_kill")
-        self.defeat_tracker.record_kill(spawn_id, name=name, x=x, y=y)
+        self.defeat_tracker.record_kill(spawn_id, name=name, pos=pos)
 
-    def update_stationary_kills(self, player_x: float, player_y: float) -> None:
+    def update_stationary_kills(self, pos: Point) -> None:
         assert_brain_thread("update_stationary_kills")
         if self.metrics.last_kill_x == 0 and self.metrics.last_kill_y == 0:
-            self.metrics.last_kill_x = player_x
-            self.metrics.last_kill_y = player_y
+            self.metrics.last_kill_x = pos.x
+            self.metrics.last_kill_y = pos.y
             self.metrics.stationary_kills = 1
             return
-        dist = distance_2d(player_x, player_y, self.metrics.last_kill_x, self.metrics.last_kill_y)
+        last_kill_pos = Point(self.metrics.last_kill_x, self.metrics.last_kill_y, 0.0)
+        dist = pos.dist_to(last_kill_pos)
         if dist < 30:
             self.metrics.stationary_kills += 1
         else:
             self.metrics.stationary_kills = 1
-        self.metrics.last_kill_x = player_x
-        self.metrics.last_kill_y = player_y
+        self.metrics.last_kill_x = pos.x
+        self.metrics.last_kill_y = pos.y
 
     def should_reposition(self) -> bool:
         if self.metrics.stationary_kills < 2:
@@ -351,14 +355,13 @@ def should_reposition(self) -> bool:
     def find_unlootable_kill(
         self,
         corpse_name: str,
-        corpse_x: float,
-        corpse_y: float,
+        pos: Point,
         max_dist: float = 60.0,
         corpse_spawn_id: int = 0,
     ) -> DefeatInfo | None:
         """Delegate to defeat_tracker."""
         return self.defeat_tracker.find_unlootable_kill(
-            corpse_name, corpse_x, corpse_y, corpse_spawn_id=corpse_spawn_id, max_dist=max_dist
+            corpse_name, pos, corpse_spawn_id=corpse_spawn_id, max_dist=max_dist
         )
 
     def defeats_in_window(self, window_seconds: float) -> int:
@@ -424,7 +427,7 @@ def nearest_player_dist(self, state: GameState) -> float:
         best = 9999.0
         for spawn in state.spawns:
             if spawn.spawn_type == 0 and spawn.name != state.name:
-                dist = distance_2d(state.x, state.y, spawn.x, spawn.y)
+                dist = state.pos.dist_to(spawn.pos)
                 if dist < best:
                     best = dist
         return best
@@ -433,7 +436,7 @@ def nearby_player_count(self, state: GameState, radius: float = 200.0) -> int:
         count = 0
         for spawn in state.spawns:
             if spawn.spawn_type == 0 and spawn.name != state.name:
-                dist = distance_2d(state.x, state.y, spawn.x, spawn.y)
+                dist = state.pos.dist_to(spawn.pos)
                 if dist <= radius:
                     count += 1
         return count

src/brain/goap/spawn_predictor.py

@@ -38,6 +38,7 @@ def _cell_center(cx: int, cy: int) -> Point:
     return Point(
         x=(cx + 0.5) * CELL_SIZE,
         y=(cy + 0.5) * CELL_SIZE,
+        z=0.0,
     )
 
 

src/brain/goap/world_state.py

@@ -72,9 +72,9 @@ def build_world_state(state: GameState, ctx: AgentContext) -> PlanWorldState:
     # At camp
     at_camp = True
     if ctx.camp.roam_radius > 0:
-        from nav.geometry import distance_2d
+        from core.types import Point
 
-        d = distance_2d(state.x, state.y, ctx.camp.camp_x, ctx.camp.camp_y)
+        d = state.pos.dist_to(Point(ctx.camp.camp_x, ctx.camp.camp_y, 0.0))
         at_camp = d <= ctx.camp.roam_radius * 1.2  # slight buffer
 
     return PlanWorldState(