feat: full migration to 3d points

Author: tmcarmichael

README.md

@@ -4,21 +4,51 @@
 ![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.
 
+> Compass is a cleaned public case study of a real autonomous agent architecture originally developed against a legacy 3D MMORPG emulator.
+>
+> This repository is intentionally published as an architecture reference and proof of work, not as a turnkey botting tool, live client integration package, or runnable game-automation release. The focus here is the system design: perception, decision-making, routines, navigation, learning, observability, and real session telemetry.
+
+## What This Repo Is
+
+- A modern Python implementation of a layered real-time agent architecture
+- A systems case study built against a noisy, high-pressure 3D sandbox
+- A reference for control-loop design, rule systems, utility scoring, GOAP planning, navigation, and learned adaptation
+- A record of real decision traces, forensics, plans, and session outputs from the underlying private system
+
+## What This Repo Is Not
+
+- A ready-to-run bot
+- A packaged live integration for the target game client
+- A dump of private configs, assets, or operational glue
+- A turnkey automation release intended for direct operational use
+
+Compass treats a legacy MMORPG as a demanding autonomy sandbox rather than as the point of the project. The interesting problem is not the game itself; it is the combination of partial observability, noisy state, real-time interruption, 3D navigation, competing goals, social threat, and long-horizon autonomy.
+
+The public release preserves the architecture, model code, test strategy, and representative telemetry from that system. It is meant to be read, inspected, and evaluated as a systems architecture project.
+
 <p align="center">
   <img src="docs/compass-hero.png" alt="Compass" width="720">
 </p>
 
+## How To Evaluate This Repo
+
+- Read [docs/architecture.md](docs/architecture.md) for the execution model and subsystem boundaries
+- Read [docs/design-decisions.md](docs/design-decisions.md) for the rationale behind the main architectural choices
+- Browse [docs/samples/](docs/samples/) for real decision traces, GOAP plans, forensics dumps, and session telemetry
+- Run `just check` to verify the public codebase, tests, typing, and linting
+- Start with [`src/perception/state.py`](src/perception/state.py), [`src/brain/decision.py`](src/brain/decision.py), and [`src/brain/runner/loop.py`](src/brain/runner/loop.py) to understand the core loop
+
 Compass defines a control architecture for agents that must perceive, decide, and navigate a 3D open world in real time. Live world state flows through a forward-only pipeline that separates perception, decision-making, routines, and movement, while a typed world model gives each layer a shared view of the world.
 
 Decision-making is layered by design. Priority rules enforce the safety envelope, utility scoring ranks immediate choices, and goal-oriented planning coordinates multi-step behavior across time. Routines execute those decisions without blocking and remain interruptible under threat. Encounter history, spatial memory, and navigation over parsed world geometry help the agent adapt and plan in an unpredictable environment.
 
 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.
+In the underlying private system, this architecture operated 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.
 
 ---
 
@@ -219,7 +249,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 +266,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 +298,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/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/combat_eval.py

@@ -11,9 +11,8 @@
 from enum import StrEnum, unique
 from typing import Any
 
-from core.types import Disposition
+from core.types import Disposition, Point
 from eq.strings import normalize_mob_name
-from nav.geometry import distance_2d
 from perception.queries import (
     is_pet,
 )
@@ -274,7 +273,7 @@ def find_targets(
 
         if not is_resource and not is_valid_target(spawn, player_level):
             continue
-        dist = distance_2d(player_x, player_y, spawn.x, spawn.y)
+        dist = Point(player_x, player_y, 0.0).dist_to(spawn.pos)
         if dist > max_distance:
             continue
         con = con_color(player_level, spawn.level)

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(Point(k.x, k.y, 0.0))
                     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(