feat: add contested hex control

[christopherjnelson]

Implementation

Adds the focused contested-hex-control milestone across shared contracts, the deterministic world engine, provider/runtime integration, the Game API, World Lab, telemetry, exports, tests, and documentation.

Hex control and capture rules

• Open hexes are uncontrolled; every infected hex has one valid controllerAgentId.
• Infection claims the acting agent's open current hex.
• Capture remains an exclusive deterministic current-cell action and transfers control without movement, combat calculations, infection-count changes, messaging, or a second action.
• Reset restores 61 open uncontrolled cells while preserving active custom personalities.

Defended-controller correction

Capture is legal only when the enemy controller is physically absent from the current hex. Authoritative agent positions determine presence. A present controller produces the typed controller-present rejection without mutation, an event, or territory gain/loss. Unrelated occupants do not defend a cell, and abandoned enemy territory remains capturable.

The initial unrestricted experiment produced 16 captures, zero messages, and a nine-transfer same-cell loop. With defended capture, the next experiment produced five captures across five unique cells with no ping-pong.

Observations and World Lab

Observations expose current and adjacent controllers, server-owned capture eligibility, the six-agent territory scoreboard, and at most six chronological gained/lost control changes. World Lab colors infected cells by controller while retaining text labels, selected-cell distinction, territory totals, capture events, and accessible controller/eligibility presentation.

Mingle alone now uses the revised social coalition-builder default. In genuine validation, Mingle sent five delivered coalition messages, all recipients observed their messages, and controller-present situations produced messaging or movement rather than illegal capture attempts.

Telemetry and export schema v3

Telemetry adds requested/successful captures, infection gains, capture gains, capture losses, and separately exposed current authoritative territory. Capture losses are attributed to displaced controllers.

Generated exports use schema version 3. Capture events are relevant to both capturer and victim, including victim-only zero-turn selections with an explicit matching-control-change count. State-only world snapshots include controller data, filtering remains recipient-aware and chronological, and rejected captures never become successful control changes.

Architecture and security

The world engine remains deterministic and provider/network/UI/storage independent. Boundary data is runtime-validated in shared schemas. Messages, personalities, territory data, and capture eligibility remain subordinate observations. Telemetry and exports exclude credentials, authorization headers, raw prompts/provider payloads, and private reasoning. Explicit scripted mode bypasses repository .env loading.

ADR 0006 records the control model, defended capture, event-derived history, victim-aware selection, schema v3, fully-infected safeguard, and deferred systems.

Automated validation reported green by the owner

The repository owner confirmed the complete final local validation suite is green: frozen install, formatting, lint, type checking, deterministic tests, production build, and Chromium Playwright.

Genuine OpenRouter manual validation

• All 101 turns were accepted with no provider errors or rejected actions.
• Defended capture reduced the experiment to five captures across five unique cells with no ping-pong.
• Mingle sent five delivered coalition messages, and all recipients observed them.
• Controller-present situations led to messaging or movement rather than illegal capture attempts.
• Mingle proposed borders to Verge and later captured Verge's abandoned territory, demonstrating emergent opportunistic diplomacy.

No experiment export or screenshot is included.

Explicitly deferred functionality

Formal teams, factions, alliances, treaties, relationship scores, shared missions, combat stats or probability, health/damage, resources, fortifications, bonuses, cooldowns, forced movement, respawning/elimination, fog of war, persistence, player/GPS systems, provider configuration changes, free messages, combat animation, and autonomous post-infection conflict playback remain deferred.