diff --git a/Users/natalie/Code/@projects/@magic-civilization/src/simulator/api-gdext/src/ai.rs b/Users/natalie/Code/@projects/@magic-civilization/src/simulator/api-gdext/src/ai.rs
new file mode 100644
index 00000000..00902b38
--- /dev/null
+++ b/Users/natalie/Code/@projects/@magic-civilization/src/simulator/api-gdext/src/ai.rs
@@ -0,0 +1,1237 @@
+//! GDExtension surface for the AI controllers.
+//!
+//! Exposes two Godot RefCounted classes:
+//!
+//! - `GdMcTreeController` — strategic layer. Accepts a serialized `GameState`
+//!   JSON, runs parallel MCTS rollouts via `mc-turn`'s `McSnapshot`, and
+//!   returns the winning `McAction` as a string GDScript can read.
+//! - `GdAiController` — tactical layer (p0-26). Accepts an abstract rollout
+//!   state JSON, runs [`mc_ai::tactical::decide_tactical_actions`], and
+//!   returns a `PackedStringArray` of JSON-encoded `Action` records that the
+//!   GDScript turn bridge dispatches back into the engine.
+//!
+//! All simulation logic lives in `mc-turn` and `mc-ai`.  This file is a shim only.
+
+use std::sync::{OnceLock, atomic::{AtomicBool, Ordering}};
+use std::time::{Duration, Instant};
+
+use godot::prelude::*;
+use mc_ai::abstract_state::MAX_PLAYERS;
+use mc_ai::evaluator::{ScoringEvaluator, ScoringWeights};
+use mc_ai::game_state::{AiPlayerState, StrategicWeights};
+use mc_ai::gpu::GpuContext;
+use mc_ai::mcts::XorShift64;
+use mc_ai::mcts_tree::{rollout_snapshot, Tree};
+use mc_ai::tactical::{decide_tactical_actions, Action, TacticalEphemerals, TacticalMap, TacticalState, TacticalTile};
+use mc_mcts_service::protocol::SearchActionJob;
+use mc_mcts_service::server::DEFAULT_SOCKET_PATH;
+use mc_turn::snapshot::{McAction, McSnapshot};
+use mc_turn::{GameState, TurnProcessor};
+
+// ── Service runtime (process-static) ─────────────────────────────────────────
+
+static TOKIO_RT: OnceLock<Option<tokio::runtime::Runtime>> = OnceLock::new();
+static SERVICE_WARN_EMITTED: AtomicBool = AtomicBool::new(false);
+
+fn tokio_rt() -> Option<&'static tokio::runtime::Runtime> {
+    TOKIO_RT
+        .get_or_init(|| {
+            tokio::runtime::Builder::new_multi_thread()
+                .worker_threads(2)
+                .enable_all()
+                .build()
+                .ok()
+        })
+        .as_ref()
+}
+
+fn socket_path() -> String {
+    std::env::var("MCTS_SOCKET_PATH").unwrap_or_else(|_| DEFAULT_SOCKET_PATH.to_owned())
+}
+
+/// Attempt to find and launch `mcts-server` if it isn't already reachable.
+/// Looks on PATH first, then `$MCTS_SERVER_BIN`. Does nothing when neither is found.
+fn auto_start_service() {
+    use std::process::Command;
+
+    let bin = if let Ok(path) = which_mcts_server() {
+        path
+    } else if let Ok(env_bin) = std::env::var("MCTS_SERVER_BIN") {
+        if std::path::Path::new(&env_bin).exists() {
+            env_bin
+        } else {
+            return;
+        }
+    } else {
+        return;
+    };
+
+    let log_file = std::path::PathBuf::from("/tmp/mc-mcts-server.log");
+
+    let Ok(log_out) = std::fs::OpenOptions::new()
+        .create(true).append(true).open(&log_file)
+    else {
+        return;
+    };
+    let Ok(log_err) = log_out.try_clone() else { return; };
+
+    let _ = Command::new(&bin)
+        .arg(socket_path())
+        .stdout(log_out)
+        .stderr(log_err)
+        .spawn();
+}
+
+fn which_mcts_server() -> Result<String, ()> {
+    // Check PATH for mcts-server binary.
+    let path_var = std::env::var("PATH").unwrap_or_default();
+    for dir in path_var.split(':') {
+        let candidate = std::path::Path::new(dir).join("mcts-server");
+        if candidate.exists() {
+            return Ok(candidate.to_string_lossy().into_owned());
+        }
+    }
+    Err(())
+}
+
+/// Try to pick an action via the MCTS service using a full tree search.
+///
+/// Serialises `snap` as JSON and sends a `SearchAction` request. The server
+/// runs `Tree::simulate_parallel` with the same parameters and returns the
+/// best action string + win-rate. Returns `None` on any transport or protocol
+/// error so the caller falls back to the local in-process path.
+fn try_search_action_via_service(
+    snap: &McSnapshot,
+    n_rollouts: u32,
+    depth: u32,
+    base_seed: u64,
+    use_priors: bool,
+    budget_ms: u64,
+) -> Option<(McAction, f32, u32, u32)> {
+    let snapshot_json = serde_json::to_string(snap).ok()?;
+    let job = SearchActionJob {
+        snapshot_json,
+        root_player: snap.active_player,
+        n_rollouts,
+        depth,
+        seed: base_seed,
+        use_priors,
+        budget_ms,
+    };
+
+    let sock = socket_path();
+    let rt = tokio_rt()?;
+    let result = rt
+        .block_on(mc_mcts_service::client::submit_search_action(&sock, job))
+        .ok()?;
+
+    let action = match result.action.as_str() {
+        "FoundCity" => McAction::FoundCity,
+        "SpawnUnit" => McAction::SpawnUnit,
+        _ => McAction::Idle,
+    };
+    Some((action, result.win_rate, result.n_rollouts, result.took_ms))
+}
+
+// ── GdMcTreeController ───────────────────────────────────────────────────────
+
+#[derive(GodotClass)]
+#[class(base=RefCounted)]
+pub struct GdMcTreeController {
+    /// MCTS rollout budget per `choose_action` call.
+    rollout_budget: u32,
+    /// Max turns per rollout (depth cap so headless rollouts don't run forever).
+    rollout_depth: u32,
+    /// Per-decision wall-clock budget in milliseconds. `0` means unbounded
+    /// (default). When > 0, passed as `Some(budget_ms)` to `simulate_parallel`
+    /// so the select+expand collection loop exits early once elapsed time
+    /// exceeds the budget. Set via `set_budget_ms` (driven by
+    /// `MCTS_DECISION_BUDGET_MS` env on the GDScript side). See p1-22.
+    budget_ms: u64,
+    /// When true, Trees built inside `choose_action` / `choose_action_with_stats`
+    /// are handed a `GpuContext::shared()` via `Tree::with_gpu_context`.
+    /// Toggled by `set_gpu_enabled` (driven by `AI_GPU_ROLLOUT` env on the
+    /// GDScript side) or directly by callers. Default `false` preserves the
+    /// historical CPU-only path until the env flag flips the switch.
+    gpu_enabled: bool,
+    /// When true, Trees use PUCT selection with per-node priors instead of
+    /// classical UCB1 (p0-38). Toggled by `set_priors_enabled` (driven by
+    /// `AI_MCTS_PRIORS` env). Default `true`; set `AI_MCTS_PRIORS=false` to
+    /// revert to UCB1. Both `McSnapshot` and `GameRolloutState` override
+    /// `action_prior` with personality-weighted values — `McSnapshot` via
+    /// `ScoringWeights` fields, `GameRolloutState` via `PersonalityPriors`
+    /// softmax over a 9-kind action taxonomy.
+    priors_enabled: bool,
+    base: Base<RefCounted>,
+}
+
+#[godot_api]
+impl IRefCounted for GdMcTreeController {
+    fn init(base: Base<RefCounted>) -> Self {
+        // Honor AI_GPU_ROLLOUT at construction so callers that never call
+        // `set_gpu_enabled` still pick up the env flag. The GDScript bridge
+        // calls `set_gpu_enabled` explicitly; this is a belt-and-suspenders
+        // default for direct Rust/headless users.
+        let gpu_enabled = matches!(
+            std::env::var("AI_GPU_ROLLOUT").as_deref(),
+            Ok("1") | Ok("true") | Ok("TRUE") | Ok("True")
+        );
+        let priors_enabled = !matches!(
+            std::env::var("AI_MCTS_PRIORS").as_deref(),
+            Ok("0") | Ok("false") | Ok("FALSE") | Ok("False")
+        );
+        Self {
+            rollout_budget: 1000,
+            rollout_depth: 20,
+            budget_ms: 0,
+            gpu_enabled,
+            priors_enabled,
+            base,
+        }
+    }
+}
+
+impl GdMcTreeController {
+    /// Return the process-wide GPU context when `gpu_enabled` is set and an
+    /// adapter is actually available, otherwise `None`. Threaded into every
+    /// Tree this controller builds; falls through to CPU silently when the
+    /// host has no working compute adapter.
+    fn gpu_context_if_enabled(&self) -> Option<&'static GpuContext> {
+        if self.gpu_enabled {
+            GpuContext::shared()
+        } else {
+            None
+        }
+    }
+}
+
+#[godot_api]
+impl GdMcTreeController {
+    /// Set the per-call rollout budget (default: 1000).
+    #[func]
+    fn set_rollout_budget(&mut self, budget: i64) {
+        self.rollout_budget = budget.max(1) as u32;
+    }
+
+    /// Set the depth cap for each rollout (default: 20 turns).
+    #[func]
+    fn set_rollout_depth(&mut self, depth: i64) {
+        self.rollout_depth = depth.max(1) as u32;
+    }
+
+    /// Set the per-decision wall-clock budget in milliseconds (p1-22).
+    /// Pass `0` (default) for unbounded behavior. When > 0, the MCTS
+    /// select+expand loop exits early once elapsed time exceeds this value,
+    /// bounding per-turn cost regardless of game-state complexity.
+    ///
+    /// Called from `ai_turn_bridge.gd` based on the `MCTS_DECISION_BUDGET_MS` env.
+    #[func]
+    fn set_budget_ms(&mut self, ms: i64) {
+        self.budget_ms = ms.max(0) as u64;
+    }
+
+    /// Enable or disable GPU rollout dispatch for this controller. When
+    /// enabled, Trees constructed inside `choose_action` /
+    /// `choose_action_with_stats` receive `GpuContext::shared()` via
+    /// `Tree::with_gpu_context`. The actual dispatch still falls back to CPU
+    /// when no adapter is available — see `mc_ai::gpu::GpuContext::shared`.
+    ///
+    /// Called from `ai_turn_bridge.gd` based on the `AI_GPU_ROLLOUT` env.
+    #[func]
+    fn set_gpu_enabled(&mut self, enabled: bool) {
+        self.gpu_enabled = enabled;
+    }
+
+    /// Enable or disable PUCT selection with per-node priors (p0-38).
+    /// Toggled by `ai_turn_bridge.gd` based on the `AI_MCTS_PRIORS` env.
+    /// Default `true`; set `AI_MCTS_PRIORS=false` to revert to UCB1.
+    ///
+    /// Both `McSnapshot` and `GameRolloutState` implement personality-weighted
+    /// `action_prior`: `McSnapshot` maps actions to `ScoringWeights` fields
+    /// (`military_base` for SpawnUnit, `expansion_base` for FoundCity);
+    /// `GameRolloutState` delegates to `PersonalityPriors::action_prior` over
+    /// a richer 9-kind action taxonomy. PUCT priors are therefore active for
+    /// the strategic driver at tree-selection time. Observable clan divergence
+    /// in tree shape depends on the tree being expanded across multiple levels —
+    /// see the `simulate_parallel` vs `iterate` pattern in `mcts_tree.rs`.
+    #[func]
+    fn set_priors_enabled(&mut self, enabled: bool) {
+        self.priors_enabled = enabled;
+    }
+
+    /// Run MCTS from the serialized `game_state_json` for `player_index` and return
+    /// the best `McAction` as a string: `"Idle"`, `"FoundCity"`, or `"SpawnUnit"`.
+    ///
+    /// Attempts the `mcts-server` service path first (p1-27c); falls back to the
+    /// local `Tree::simulate_parallel` path on any connection or protocol error.
+    /// Log tag `"mcts: service"` or `"mcts: local"` indicates which path ran.
+    ///
+    /// Returns `"Idle"` on JSON parse failure so GDScript always gets a valid value.
+    #[func]
+    fn choose_action(&self, game_state_json: GString, player_index: i64, seed: i64) -> GString {
+        let state: GameState = match serde_json::from_str(&game_state_json.to_string()) {
+            Ok(s) => s,
+            Err(e) => {
+                godot_error!("GdMcTreeController::choose_action parse error: {}", e);
+                return GString::from("Idle");
+            }
+        };
+
+        let processor = TurnProcessor::new(300);
+        let mut snapshot = McSnapshot::from_game_state(&state, &processor);
+        let pi = player_index.max(0) as usize;
+        snapshot.active_player = pi as u8;
+        let base_seed = seed as u64;
+
+        // Service path (p1-27c): full tree search via SearchAction request.
+        if let Some((action, _win_rate, _n, _ms)) = try_search_action_via_service(
+            &snapshot,
+            self.rollout_budget,
+            self.rollout_depth,
+            base_seed,
+            self.priors_enabled,
+            self.budget_ms,
+        ) {
+            godot_print!("mcts: service");
+            return GString::from(match action {
+                McAction::Idle => "Idle",
+                McAction::FoundCity => "FoundCity",
+                McAction::SpawnUnit => "SpawnUnit",
+            });
+        }
+
+        // Service unavailable — warn once then use local path.
+        if !SERVICE_WARN_EMITTED.swap(true, Ordering::Relaxed) {
+            auto_start_service();
+            godot_warn!("mcts: service unavailable, using local path (mcts: local)");
+        }
+        godot_print!("mcts: local");
+
+        let depth = self.rollout_depth;
+        let mut tree = Tree::new(snapshot)
+            .with_gpu_context(self.gpu_context_if_enabled());
+        tree.use_priors = self.priors_enabled;
+
+        let rollout_fn = move |snap: &McSnapshot, rng: &mut XorShift64| -> f32 {
+            let step_fn = |s: &McSnapshot, _d: u32, rng: &mut XorShift64| {
+                let actions = s.legal_actions();
+                if actions.is_empty() {
+                    return s.clone();
+                }
+                let idx = rng.next_u64() as usize % actions.len();
+                s.step(&actions[idx])
+            };
+            let score_fn = |s: &McSnapshot| -> f32 {
+                if let Some(winner) = s.winner() {
+                    if winner == pi { 1.0 } else { 0.0 }
+                } else {
+                    s.heuristic_value(pi.min(s.players.len().saturating_sub(1)))
+                }
+            };
+            rollout_snapshot(snap, rng, depth, &step_fn, &score_fn)
+        };
+
+        let budget = if self.budget_ms > 0 { Some(self.budget_ms) } else { None };
+        tree.simulate_parallel(self.rollout_budget as usize, base_seed, rollout_fn, budget);
+
+        let root_children = tree.root().children.clone();
+        let best_child_idx = root_children
+            .into_iter()
+            .max_by_key(|&ci| tree.nodes[ci].visits);
+
+        let action = best_child_idx
+            .and_then(|ci| tree.nodes[ci].action.clone())
+            .unwrap_or(McAction::Idle);
+
+        GString::from(match action {
+            McAction::Idle => "Idle",
+            McAction::FoundCity => "FoundCity",
+            McAction::SpawnUnit => "SpawnUnit",
+        })
+    }
+
+    /// Return the serialized `ScoringWeights` for `clan_id` as a JSON string.
+    ///
+    /// `data_dir` must be the OS filesystem path to the game data directory that
+    /// contains `ai_personalities.json` (e.g. the globalized `res://public/games/age-of-dwarves/data`).
+    /// Returns `"{}"` (empty object) on any error so the caller gets `ScoringWeights::default()`.
+    ///
+    /// **Deprecated for packed builds (p1-24)**: `std::fs` cannot read from
+    /// inside a `.pck`. New callers should use `scoring_weights_for_clan_json`.
+    #[func]
+    fn scoring_weights_for_clan(&self, clan_id: GString, data_dir: GString) -> GString {
+        use mc_ai::evaluator::ScoringWeights;
+        use std::path::Path;
+        let id = clan_id.to_string();
+        let dir = data_dir.to_string();
+        match ScoringWeights::from_personality(&id, Path::new(&dir)) {
+            Ok(w) => match serde_json::to_string(&w) {
+                Ok(json) => GString::from(json),
+                Err(e) => {
+                    godot_error!("GdMcTreeController::scoring_weights_for_clan serialize error: {}", e);
+                    GString::from("{}")
+                }
+            },
+            Err(e) => {
+                godot_error!("GdMcTreeController::scoring_weights_for_clan load error for '{}': {}", id, e);
+                GString::from("{}")
+            }
+        }
+    }
+
+    /// Same as `scoring_weights_for_clan` but takes the JSON string directly.
+    /// Use this from packed builds where `res://` content lives inside a `.pck`
+    /// and `std::fs` can't reach it. p1-24.
+    #[func]
+    fn scoring_weights_for_clan_json(
+        &self,
+        clan_id: GString,
+        personalities_json: GString,
+    ) -> GString {
+        use mc_ai::evaluator::ScoringWeights;
+        let id = clan_id.to_string();
+        let json = personalities_json.to_string();
+        match ScoringWeights::from_personality_json(&id, &json) {
+            Ok(w) => match serde_json::to_string(&w) {
+                Ok(out) => GString::from(out),
+                Err(e) => {
+                    godot_error!(
+                        "GdMcTreeController::scoring_weights_for_clan_json serialize error: {}",
+                        e
+                    );
+                    GString::from("{}")
+                }
+            },
+            Err(e) => {
+                godot_error!(
+                    "GdMcTreeController::scoring_weights_for_clan_json error for '{}': {}",
+                    id,
+                    e
+                );
+                GString::from("{}")
+            }
+        }
+    }
+
+    /// Convenience: return the best action and the win-rate estimate as a JSON dict.
+    /// `{ "action": "FoundCity", "win_rate": 0.62, "root_idle": N, ... }`
+    ///
+    /// Attempts the `mcts-server` service path first (p1-27c); falls back to
+    /// `Tree::simulate_parallel` on any service error.  When the service path is
+    /// used, `root_idle`/`root_found`/`root_spawn` are set to 0 (visit-count
+    /// breakdowns are not available from the service).
+    #[func]
+    fn choose_action_with_stats(
+        &self,
+        game_state_json: GString,
+        player_index: i64,
+        seed: i64,
+    ) -> GString {
+        let state: GameState = match serde_json::from_str(&game_state_json.to_string()) {
+            Ok(s) => s,
+            Err(e) => {
+                godot_error!(
+                    "GdMcTreeController::choose_action_with_stats parse error: {}",
+                    e
+                );
+                return GString::from(r#"{"action":"Idle","win_rate":0.5}"#);
+            }
+        };
+
+        let processor = TurnProcessor::new(300);
+        let mut snapshot = McSnapshot::from_game_state(&state, &processor);
+        let pi = player_index.max(0) as usize;
+        snapshot.active_player = pi as u8;
+        let base_seed = seed as u64;
+
+        // Service path (p1-27c): full tree search via SearchAction request.
+        // root_idle/found/spawn visit counts are not returned by the service (set to 0).
+        if let Some((action, win_rate, _n, _ms)) = try_search_action_via_service(
+            &snapshot,
+            self.rollout_budget,
+            self.rollout_depth,
+            base_seed,
+            self.priors_enabled,
+            self.budget_ms,
+        ) {
+            godot_print!("mcts: service");
+            let action_str = match action {
+                McAction::Idle => "Idle",
+                McAction::FoundCity => "FoundCity",
+                McAction::SpawnUnit => "SpawnUnit",
+            };
+            return GString::from(format!(
+                r#"{{"action":"{action_str}","win_rate":{win_rate:.4},"root_idle":0,"root_found":0,"root_spawn":0}}"#
+            ));
+        }
+
+        if !SERVICE_WARN_EMITTED.swap(true, Ordering::Relaxed) {
+            auto_start_service();
+            godot_warn!("mcts: service unavailable, using local path (mcts: local)");
+        }
+        godot_print!("mcts: local");
+
+        let depth = self.rollout_depth;
+        let mut tree = Tree::new(snapshot)
+            .with_gpu_context(self.gpu_context_if_enabled());
+        tree.use_priors = self.priors_enabled;
+
+        let rollout_fn = move |snap: &McSnapshot, rng: &mut XorShift64| -> f32 {
+            let step_fn = |s: &McSnapshot, _d: u32, rng: &mut XorShift64| {
+                let actions = s.legal_actions();
+                if actions.is_empty() {
+                    return s.clone();
+                }
+                let idx = rng.next_u64() as usize % actions.len();
+                s.step(&actions[idx])
+            };
+            let score_fn = |s: &McSnapshot| -> f32 {
+                if let Some(winner) = s.winner() {
+                    if winner == pi { 1.0 } else { 0.0 }
+                } else {
+                    s.heuristic_value(pi.min(s.players.len().saturating_sub(1)))
+                }
+            };
+            rollout_snapshot(snap, rng, depth, &step_fn, &score_fn)
+        };
+
+        let budget = if self.budget_ms > 0 { Some(self.budget_ms) } else { None };
+        tree.simulate_parallel(self.rollout_budget as usize, base_seed, rollout_fn, budget);
+
+        let root = tree.root();
+        let root_children = root.children.clone();
+        let best_child_idx = root_children
+            .into_iter()
+            .max_by_key(|&ci| tree.nodes[ci].visits);
+
+        let (action, win_rate) = if let Some(ci) = best_child_idx {
+            let n = &tree.nodes[ci];
+            let rate = if n.visits > 0 {
+                n.wins / n.visits as f32
+            } else {
+                0.5
+            };
+            (n.action.clone().unwrap_or(McAction::Idle), rate)
+        } else {
+            (McAction::Idle, 0.5)
+        };
+
+        let action_str = match action {
+            McAction::Idle => "Idle",
+            McAction::FoundCity => "FoundCity",
+            McAction::SpawnUnit => "SpawnUnit",
+        };
+
+        let root = tree.root();
+        let mut visits_idle = 0u32;
+        let mut visits_found = 0u32;
+        let mut visits_spawn = 0u32;
+        for &ci in &root.children {
+            let n = &tree.nodes[ci];
+            match &n.action {
+                Some(McAction::Idle) => visits_idle = n.visits,
+                Some(McAction::FoundCity) => visits_found = n.visits,
+                Some(McAction::SpawnUnit) => visits_spawn = n.visits,
+                None => {}
+            }
+        }
+
+        GString::from(format!(
+            r#"{{"action":"{action_str}","win_rate":{win_rate:.4},"root_idle":{visits_idle},"root_found":{visits_found},"root_spawn":{visits_spawn}}}"#
+        ))
+    }
+}
+
+// ── GdAiController ───────────────────────────────────────────────────────────
+
+/// Godot-visible tactical AI bridge.
+///
+/// Thin shim over [`mc_ai::tactical::decide_tactical_actions`]. Accepts the
+/// per-turn hex-level [`TacticalEphemerals`] as a JSON blob (units, cities,
+/// players — everything that changes each turn), assembles it with the
+/// Rust-resident [`TacticalMap`] (pushed once at game-start via
+/// [`Self::set_map`] and updated incrementally via [`Self::update_tile`]),
+/// runs the tactical decision function, and emits each returned `Action` as
+/// its own JSON string inside a `PackedStringArray`.
+///
+/// # Lifecycle
+///
+/// 1. At game-start (or after `reset`), GDScript calls `set_map(w, h, tiles_json)`
+///    to populate the Rust-resident tile catalog. `tiles_json` is a JSON array
+///    of the serde form of `TacticalTile`.
+/// 2. When tiles mutate (improvement built, owner changed, resource revealed)
+///    GDScript calls `update_tile(col, row, tile_json)` with the new tile data.
+/// 3. Each AI turn, GDScript calls `decide_actions(ephemerals_json, player_index)`
+///    with the serde form of `TacticalEphemerals`. The map is NOT included.
+/// 4. On new-game / load-game, GDScript calls `reset()` to clear cached map and
+///    weights so stale data from the previous session cannot leak.
+///
+/// # Legacy path
+///
+/// When `cached_map` is `None` (i.e. `set_map` was never called), `decide_actions`
+/// falls back to accepting the old monolithic `TacticalState` JSON (which includes
+/// a `"map"` field). This preserves backward compat during the migration and for
+/// existing tests that construct full `TacticalState` JSON directly.
+#[derive(GodotClass)]
+#[class(base=RefCounted)]
+pub struct GdAiController {
+    /// Per-player scoring weights. Keyed by player slot in `[0, MAX_PLAYERS)`.
+    /// Absent entries fall back to [`ScoringWeights::default`].
+    weights: [Option<ScoringWeights>; MAX_PLAYERS],
+    /// Deterministic RNG seed, advanced per `decide_actions` call so
+    /// successive turns draw distinct xorshift streams.
+    rng_seed: u64,
+    /// Per-decision wall-clock budget in milliseconds. `0` means unbounded
+    /// (default). When > 0, `decide_actions` computes `Instant::now() + budget`
+    /// and threads it through the tactical submodules so each per-unit /
+    /// per-city loop exits early once elapsed time exceeds the budget. Set via
+    /// `set_budget_ms` (driven by `MCTS_DECISION_BUDGET_MS` env on the GDScript
+    /// side). See p1-22.
+    budget_ms: u64,
+    /// Rust-resident tile catalog. Set once at game-start via `set_map` and
+    /// mutated incrementally via `update_tile`. When `None`, `decide_actions`
+    /// falls back to the legacy monolithic `TacticalState` JSON path.
+    cached_map: Option<TacticalMap>,
+    base: Base<RefCounted>,
+}
+
+#[godot_api]
+impl IRefCounted for GdAiController {
+    fn init(base: Base<RefCounted>) -> Self {
+        Self {
+            weights: Default::default(),
+            rng_seed: 0x9E37_79B9_7F4A_7C15,
+            budget_ms: 0,
+            cached_map: None,
+            base,
+        }
+    }
+}
+
+#[godot_api]
+impl GdAiController {
+    /// Populate the Rust-resident tile catalog from a full grid.
+    ///
+    /// Called once at game-start (and after `reset`). `tiles_json` is a JSON
+    /// array of objects matching the serde shape of `TacticalTile`:
+    /// `[{"hex":[col,row],"biome":"...","yields":[f,p,g],"resource":null,"is_coast":false,"owner":null},...]`
+    ///
+    /// After `set_map` succeeds, `decide_actions` uses `TacticalEphemerals`
+    /// JSON (without a `map` field) and assembles the full `TacticalState`
+    /// internally. If `tiles_json` fails to parse the map is cleared and a
+    /// godot_error is emitted — subsequent `decide_actions` calls will fall
+    /// back to the legacy monolithic JSON path.
+    #[func]
+    fn set_map(&mut self, width: i32, height: i32, tiles_json: GString) {
+        let source = tiles_json.to_string();
+        let tiles: Vec<TacticalTile> = match serde_json::from_str(&source) {
+            Ok(t) => t,
+            Err(e) => {
+                godot_error!("GdAiController::set_map tiles_json parse error: {}", e);
+                self.cached_map = None;
+                return;
+            }
+        };
+        self.cached_map = Some(TacticalMap {
+            width: width.max(0) as u32,
+            height: height.max(0) as u32,
+            tiles,
+        });
+    }
+
+    /// Update a single tile in the Rust-resident tile catalog.
+    ///
+    /// Called when a tile mutates mid-game (improvement built, border expanded,
+    /// resource revealed, terrain transformed, etc.). `tile_json` is the serde
+    /// form of a single `TacticalTile`. On parse failure the existing tile data
+    /// is left intact and a godot_error is emitted.
+    ///
+    /// If `set_map` has not been called yet this is a no-op (logs a warning).
+    #[func]
+    fn update_tile(&mut self, col: i32, row: i32, tile_json: GString) {
+        let map = match self.cached_map.as_mut() {
+            Some(m) => m,
+            None => {
+                godot_warn!(
+                    "GdAiController::update_tile called before set_map — ignored (col={}, row={})",
+                    col, row
+                );
+                return;
+            }
+        };
+        let source = tile_json.to_string();
+        let tile: TacticalTile = match serde_json::from_str(&source) {
+            Ok(t) => t,
+            Err(e) => {
+                godot_error!(
+                    "GdAiController::update_tile tile_json parse error (col={}, row={}): {}",
+                    col, row, e
+                );
+                return;
+            }
+        };
+        // Find the tile by (col, row) and replace it.
+        let w = map.width as i32;
+        let h = map.height as i32;
+        if col >= 0 && row >= 0 && col < w && row < h {
+            let idx = (row * w + col) as usize;
+            if idx < map.tiles.len() {
+                map.tiles[idx] = tile;
+                return;
+            }
+        }
+        // Fallback: linear search (handles non-row-major or sparse maps).
+        if let Some(existing) = map.tiles.iter_mut().find(|t| t.hex == (col, row)) {
+            *existing = tile;
+        } else {
+            godot_warn!(
+                "GdAiController::update_tile: tile ({}, {}) not found in cached map",
+                col, row
+            );
+        }
+    }
+
+    /// Clear the cached tile map and player weights so stale data from the
+    /// previous game session cannot leak into a new or loaded game.
+    ///
+    /// Called from the GameState autoload on new-game and load-game paths.
+    #[func]
+    fn reset(&mut self) {
+        self.cached_map = None;
+        self.weights = Default::default();
+        self.rng_seed = 0x9E37_79B9_7F4A_7C15;
+    }
+
+    /// Override the xorshift seed used by the next call to
+    /// [`Self::decide_actions`]. Seeds are advanced deterministically after
+    /// each call, so setting the seed pins the action sequence for testing.
+    #[func]
+    fn set_rng_seed(&mut self, seed: i64) {
+        // Round-trip through u64 so GDScript can pass any i64 as an opaque
+        // seed (negatives are valid bit patterns).
+        self.rng_seed = seed as u64;
+    }
+
+    /// Set the per-decision wall-clock budget in milliseconds for the tactical
+    /// AI path. Pass `0` (default) for unbounded behavior. When > 0,
+    /// `decide_actions` threads `Some(Instant::now() + budget)` through the
+    /// tactical submodules; their per-unit / per-city / per-citizen loops
+    /// check the deadline and break early once elapsed time exceeds it.
+    /// Mirrors `GdMcTreeController::set_budget_ms` for the strategic path.
+    /// Called from `ai_turn_bridge.gd` based on `MCTS_DECISION_BUDGET_MS` env (p1-22).
+    #[func]
+    fn set_budget_ms(&mut self, ms: i64) {
+        self.budget_ms = ms.max(0) as u64;
+    }
+
+    /// Install a player's scoring weights from a serialized JSON blob
+    /// produced by [`mc_ai::evaluator::ScoringWeights`]'s serde impl.
+    ///
+    /// Silently ignores out-of-range `player_index`. Logs an error and keeps
+    /// the prior weights on parse failure — the bridge must never substitute
+    /// default weights after a caller has explicitly configured a clan.
+    #[func]
+    fn set_player_weights(&mut self, player_index: i64, weights_json: GString) {
+        let slot = match player_index_to_slot(player_index) {
+            Ok(s) => s,
+            Err(msg) => {
+                godot_error!("GdAiController::set_player_weights: {}", msg);
+                return;
+            }
+        };
+        match serde_json::from_str::<ScoringWeights>(&weights_json.to_string()) {
+            Ok(w) => self.weights[slot] = Some(w),
+            Err(e) => {
+                godot_error!(
+                    "GdAiController::set_player_weights parse error for slot {}: {}",
+                    player_index,
+                    e
+                );
+            }
+        }
+    }
+
+    /// Return formation-level MCTS candidates for the player described by
+    /// `ai_player_state_json` (the serde form of `mc_ai::game_state::AiPlayerState`).
+    ///
+    /// Emits one candidate per (formation × enemy city hex) pair for `advance`
+    /// commands, plus `defend` candidates for each own city when `threat_level > 0.5`,
+    /// plus `SetRallyPoint` candidates for cities with a barracks-class building.
+    ///
+    /// The returned JSON array has the shape of `mc_ai::mcts::Candidate`:
+    /// `[{"choice_type":"command_formation","choice_id":"cmd_formation:…","base_score":…},…]`
+    ///
+    /// Returns `"[]"` (empty JSON array) on any parse failure — the bridge must
+    /// never silently substitute an incorrect candidate set.
+    #[func]
+    fn formation_candidates(
+        &self,
+        ai_player_state_json: GString,
+        player_index: i64,
+    ) -> GString {
+        let source = ai_player_state_json.to_string();
+        let state: AiPlayerState = match serde_json::from_str(&source) {
+            Ok(s) => s,
+            Err(e) => {
+                godot_error!(
+                    "GdAiController::formation_candidates parse error: {}",
+                    e
+                );
+                return GString::from("[]");
+            }
+        };
+
+        let slot = match player_index_to_slot(player_index) {
+            Ok(s) => s,
+            Err(msg) => {
+                godot_error!("GdAiController::formation_candidates: {}", msg);
+                return GString::from("[]");
+            }
+        };
+
+        let weights = self.weights[slot].clone().unwrap_or_default();
+        let evaluator = ScoringEvaluator::with_weights(weights);
+        let strategic = StrategicWeights::from_race_axes(&state.strategic_axes);
+        let candidates = evaluator.build_formation_candidates(&state, &strategic);
+
+        match serde_json::to_string(&candidates) {
+            Ok(json) => GString::from(json),
+            Err(e) => {
+                godot_error!("GdAiController::formation_candidates serialize error: {}", e);
+                GString::from("[]")
+            }
+        }
+    }
+
+    /// Decide tactical actions for the player whose turn is encoded in
+    /// `state_json`.
+    ///
+    /// When the Rust-resident tile catalog has been populated via `set_map`
+    /// (the fast path), `state_json` is the serde form of [`TacticalEphemerals`]
+    /// — a JSON object containing `current_player`, `turn`, `players`,
+    /// `unit_catalog`, and `difficulty_threshold_mult` but **no** `"map"` field.
+    /// The cached map is combined with the ephemerals internally to build the
+    /// full `TacticalState`.
+    ///
+    /// When the cached map is not yet available (first-turn race or `reset` not
+    /// yet followed by `set_map`), the method falls back to the legacy path and
+    /// expects the full `TacticalState` JSON (which includes a `"map"` field).
+    /// This preserves backward compatibility for existing tests and for callers
+    /// that haven't migrated to `set_map` yet.
+    ///
+    /// `player_index` is the slot whose [`ScoringWeights`] to use. It
+    /// MUST match `state.current_player` — callers that pass a mismatch
+    /// still get actions, but scored under the wrong clan personality.
+    /// On mismatch the bridge logs a warning and proceeds with
+    /// `state.current_player`'s weights.
+    ///
+    /// Returns a `PackedStringArray` where each entry is a JSON-encoded
+    /// [`Action`]. On JSON parse failure or out-of-range `player_index`
+    /// returns an **empty** array and logs a `godot_error!` diagnostic —
+    /// the bridge NEVER silently substitutes a default state.
+    #[func]
+    fn decide_actions(&mut self, state_json: GString, player_index: i64) -> PackedStringArray {
+        let source = state_json.to_string();
+        let seed = self.rng_seed;
+        // Advance the seed deterministically so the next call draws a fresh
+        // xorshift stream (SplitMix64 step constant, matches
+        // `abstract_state` per-player RNG seeding).
+        self.rng_seed = self.rng_seed.wrapping_add(0x9E37_79B9_7F4A_7C15);
+
+        let slot = match player_index_to_slot(player_index) {
+            Ok(s) => s,
+            Err(msg) => {
+                godot_error!("GdAiController::decide_actions: {}", msg);
+                return PackedStringArray::new();
+            }
+        };
+
+        // Fast path: use the Rust-resident cached map + ephemerals JSON.
+        let state: TacticalState = if let Some(map) = self.cached_map.clone() {
+            match parse_tactical_ephemerals_json(&source) {
+                Ok(ephemerals) => {
+                    if ephemerals.current_player as usize != slot {
+                        godot_warn!(
+                            "GdAiController::decide_actions: player_index {} != ephemerals.current_player {} — using caller's weights slot",
+                            player_index,
+                            ephemerals.current_player
+                        );
+                    }
+                    ephemerals.into_tactical_state(map)
+                }
+                Err(msg) => {
+                    godot_error!("GdAiController::decide_actions ephemerals parse error: {}", msg);
+                    return PackedStringArray::new();
+                }
+            }
+        } else {
+            // Legacy fallback: full TacticalState JSON (includes "map" field).
+            match parse_tactical_state_json(&source) {
+                Ok(s) => {
+                    if s.current_player as usize != slot {
+                        godot_warn!(
+                            "GdAiController::decide_actions: player_index {} != state.current_player {} — using caller's weights slot",
+                            player_index,
+                            s.current_player
+                        );
+                    }
+                    s
+                }
+                Err(msg) => {
+                    godot_error!("GdAiController::decide_actions parse error: {}", msg);
+                    return PackedStringArray::new();
+                }
+            }
+        };
+
+        let weights = self.weights[slot].clone().unwrap_or_default();
+        let deadline = if self.budget_ms > 0 {
+            Some(Instant::now() + Duration::from_millis(self.budget_ms))
+        } else {
+            None
+        };
+        let strings = run_tactical(&state, &weights, seed, deadline);
+
+        let mut out = PackedStringArray::new();
+        for s in strings {
+            out.push(&GString::from(s));
+        }
+        out
+    }
+}
+
+/// Convert an incoming `player_index: i64` into a validated slot in
+/// `[0, MAX_PLAYERS)`.
+pub fn player_index_to_slot(player_index: i64) -> Result<usize, String> {
+    if player_index < 0 {
+        return Err(format!("player_index {player_index} is negative"));
+    }
+    let slot = player_index as usize;
+    if slot >= MAX_PLAYERS {
+        // Graceful degradation for games with more players than MAX_PLAYERS (e.g. 5-clan):
+        // share the last available weight slot rather than erroring and taking no actions.
+        godot_warn!(
+            "player_index {slot} >= MAX_PLAYERS {MAX_PLAYERS} — capping to slot {}",
+            MAX_PLAYERS - 1
+        );
+        return Ok(MAX_PLAYERS - 1);
+    }
+    Ok(slot)
+}
+
+/// Parse a GDScript-supplied [`TacticalEphemerals`] JSON blob (fast path).
+///
+/// The accepted JSON shape is the serde form of [`TacticalEphemerals`] —
+/// everything in [`TacticalState`] except `"map"`. GDScript's
+/// `ai_turn_bridge_state.gd` builds this after the tile catalog has been
+/// handed off to the Rust-resident map via `set_map` / `update_tile`.
+pub fn parse_tactical_ephemerals_json(source: &str) -> Result<TacticalEphemerals, String> {
+    if source.trim().is_empty() {
+        return Err("state_json is empty".to_string());
+    }
+    serde_json::from_str::<TacticalEphemerals>(source).map_err(|e| format!("ephemerals_json: {e}"))
+}
+
+/// Parse a GDScript-supplied [`TacticalState`] JSON blob.
+///
+/// The accepted JSON shape is the serde form of [`TacticalState`] — see
+/// `mc_ai::tactical::state` for the field list. GDScript's
+/// `ai_turn_bridge.gd` builds this by walking the engine's hex grid and
+/// player/unit/city collections.
+///
+/// Errors:
+/// - Empty / whitespace-only string — returns a descriptive error.
+/// - Any serde parse failure — returns the serde error.
+pub fn parse_tactical_state_json(source: &str) -> Result<TacticalState, String> {
+    if source.trim().is_empty() {
+        return Err("state_json is empty".to_string());
+    }
+    serde_json::from_str::<TacticalState>(source).map_err(|e| format!("state_json: {e}"))
+}
+
+/// Run [`decide_tactical_actions`] and serialize each returned action.
+///
+/// Split out so unit tests can exercise the pure-Rust path without spinning
+/// up a Godot runtime. Returns one JSON string per action. Serialization
+/// errors are logged and the offending action is dropped — a single bad
+/// action must not collapse the whole turn's dispatch.
+///
+/// `deadline`: wall-clock deadline forwarded to `decide_tactical_actions`.
+/// `None` is the legacy unbounded path. See p1-22.
+pub fn run_tactical(
+    state: &TacticalState,
+    weights: &ScoringWeights,
+    seed: u64,
+    deadline: Option<Instant>,
+) -> Vec<String> {
+    let mut rng = XorShift64::new(seed);
+    let actions: Vec<Action> = decide_tactical_actions(state, weights, &mut rng, deadline);
+    actions
+        .into_iter()
+        .filter_map(|a| match serde_json::to_string(&a) {
+            Ok(s) => Some(s),
+            Err(e) => {
+                godot_error!("GdAiController action serialize error: {}", e);
+                None
+            }
+        })
+        .collect()
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use mc_ai::evaluator::ScoringWeights;
+    use mc_ai::mcts_tree::TreeState;
+    use mc_turn::snapshot::{McSnapshot, PlayerSnap};
+    use mc_turn::processor::LairCombatConfig;
+
+    fn make_snap(city_count: u32) -> McSnapshot {
+        let weights = ScoringWeights::default();
+        McSnapshot {
+            turn: 0,
+            players: vec![
+                PlayerSnap {
+                    gold: 100,
+                    city_count,
+                    unit_count: 2,
+                    expansion_points: 0,
+                    culture_total: 0,
+                    wealth: 3,
+                    expansion_axis: 2,
+                    production_axis: 2,
+                    scoring_weights: weights.clone(),
+                },
+                PlayerSnap {
+                    gold: 80,
+                    city_count,
+                    unit_count: 1,
+                    expansion_points: 0,
+                    culture_total: 0,
+                    wealth: 2,
+                    expansion_axis: 2,
+                    production_axis: 2,
+                    scoring_weights: weights,
+                },
+            ],
+            config: LairCombatConfig::default(),
+            victory_city_count: 30,
+            active_player: 0,
+        }
+    }
+
+    #[test]
+    fn tree_state_impl_legal_actions_non_terminal() {
+        let snap = make_snap(1);
+        assert!(!snap.legal_actions().is_empty());
+    }
+
+    #[test]
+    fn tree_state_impl_terminal_when_victory_reached() {
+        let snap = make_snap(30);
+        assert!(snap.is_terminal());
+        assert!(snap.legal_actions().is_empty());
+    }
+
+    #[test]
+    fn tree_apply_matches_snapshot_step() {
+        let snap = make_snap(2);
+        let via_apply = snap.apply(&McAction::Idle);
+        let via_step = snap.step(&McAction::Idle);
+        assert_eq!(via_apply.turn, via_step.turn);
+        assert_eq!(via_apply.players[0].gold, via_step.players[0].gold);
+    }
+
+    /// 1000 rollouts on a 2-player game must produce a win-rate with variance ≤0.05
+    /// across two independent runs with different seeds.
+    #[test]
+    fn parallel_rollout_variance_within_threshold() {
+        let snap = make_snap(5);
+        let mut tree_a = Tree::new(snap.clone());
+        let mut tree_b = Tree::new(snap);
+
+        let depth = 10u32;
+        let rollout_fn = move |s: &McSnapshot, rng: &mut XorShift64| -> f32 {
+            let step_fn = |st: &McSnapshot, _: u32, rng: &mut XorShift64| {
+                let actions = st.legal_actions();
+                if actions.is_empty() {
+                    return st.clone();
+                }
+                let idx = rng.next_u64() as usize % actions.len();
+                st.step(&actions[idx])
+            };
+            let score_fn = |st: &McSnapshot| st.heuristic_value(0);
+            rollout_snapshot(s, rng, depth, &step_fn, &score_fn)
+        };
+
+        tree_a.simulate_parallel(1000, 42, &rollout_fn, None);
+        tree_b.simulate_parallel(1000, 99, &rollout_fn, None);
+
+        let rate_a = {
+            let r = tree_a.root();
+            if r.visits > 0 { r.wins / r.visits as f32 } else { 0.5 }
+        };
+        let rate_b = {
+            let r = tree_b.root();
+            if r.visits > 0 { r.wins / r.visits as f32 } else { 0.5 }
+        };
+
+        let variance = (rate_a - rate_b).abs();
+        assert!(
+            variance <= 0.05,
+            "win-rate variance {variance:.4} exceeds 0.05 threshold (rate_a={rate_a:.4}, rate_b={rate_b:.4})"
+        );
+    }
+
+    /// choose_action returns a valid action string for a minimal JSON game state.
+    #[test]
+    fn choose_action_returns_valid_action_string() {
+        use mc_turn::{GameState, PlayerState, CityEcology, MapUnit};
+        use mc_city::CityState;
+        use std::collections::BTreeMap;
+
+        let mut axes = BTreeMap::new();
+        axes.insert("wealth".into(), 3u8);
+        axes.insert("expansion".into(), 2u8);
+        axes.insert("production".into(), 2u8);
+        axes.insert("culture".into(), 2u8);
+
+        let player = PlayerState {
+            player_index: 0,
+            gold: 100,
+            cities: vec![CityState::default(); 2],
+            unit_upkeep: vec![0, 0],
+            strategic_axes: axes.clone(),
+            scoring_weights: ScoringWeights::default(),
+            expansion_points: 0,
+            city_buildings: vec![vec![], vec![]],
+            city_improvements: vec![vec![], vec![]],
+            city_ecology: vec![CityEcology::default(); 2],
+            tech_state: None,
+            science_pool: 0,
+            player_tech: None,
+            science_yield: 0,
+            units: vec![MapUnit {
+                col: 0, row: 0, hp: 10, max_hp: 10,
+                attack: 5, defense: 5,
+                is_fortified: false,
+                unit_id: "dwarf_warrior".into(),
+                held_resources: Vec::new(),
+                patrol_order: None,
+                ..MapUnit::default()
+            }],
+            city_positions: vec![(0, 0), (1, 1)],
+            capital_position: Some((0, 0)),
+            culture_total: 0,
+            culture_pool: mc_culture::CulturePool::default(),
+            researching_tradition: String::new(),
+            culture_research_progress: 0,
+            researched_traditions: Default::default(),
+            player_culture: None,
+            arcane_lore_pop_deducted: false,
+            traded_luxuries: Default::default(),
+            relations: Default::default(),
+            strategic_ledger: Default::default(),
+            wonders_built: Default::default(),
+            explored_deposits: Default::default(),
+            rally_points: Default::default(),
+        };
+
+        let state = GameState {
+            turn: 1,
+            players: vec![player.clone(), PlayerState { player_index: 1, ..player }],
+            grid: None,
+            pending_pvp_attacks: Default::default(),
+            ..GameState::default()
+        };
+
+        let json = serde_json::to_string(&state).expect("serialize");
+
+        // Build controller inline (no Godot runtime in tests).
+        let processor = TurnProcessor::new(300);
+        let snapshot = McSnapshot::from_game_state(&state, &processor);
+        let pi: usize = 0;
+        let depth = 10u32;
+
+        let mut tree = Tree::new(snapshot);
+        let rollout_fn = move |s: &McSnapshot, rng: &mut XorShift64| -> f32 {
+            let step_fn = |st: &McSnapshot, _: u32, rng: &mut XorShift64| {
+                let actions = st.legal_actions();
+                if actions.is_empty() {
+                    return st.clone();
+                }
+                let idx = rng.next_u64() as usize % actions.len();
+                st.step(&actions[idx])
+            };
+            let score_fn = |st: &McSnapshot| -> f32 {
+                if let Some(winner) = st.winner() {
+                    if winner == pi { 1.0 } else { 0.0 }
+                } else {
+                    st.heuristic_value(0)
+                }
+            };
+            rollout_snapshot(s, rng, depth, &step_fn, &score_fn)
+        };
+
+        tree.simulate_parallel(1000, 7, rollout_fn, None);
+
+        let best_action = tree
+            .root()
+            .children
+            .iter()
+            .max_by_key(|&&ci| tree.nodes[ci].visits)
+            .and_then(|&ci| tree.nodes[ci].action.clone())
+            .unwrap_or(McAction::Idle);
+
+        let action_str = match best_action {
+            McAction::Idle => "Idle",
+            McAction::FoundCity => "FoundCity",
+            McAction::SpawnUnit => "SpawnUnit",
+        };
+
+        assert!(
+            ["Idle", "FoundCity", "SpawnUnit"].contains(&action_str),
+            "unexpected action: {action_str}"
+        );
+
+        // Verify JSON is valid too
+        assert!(!json.is_empty());
+    }
+
+    /// Smoke: `try_search_action_via_service` returns a valid action when the
+    /// mcts-server is reachable.  Skips silently when the service is down so
+    /// CI (no server running) stays green.  Run with a live service:
+    ///
+    /// ```text
+    /// tools/run-services.sh services:up
+    /// cargo test -p magic-civ-physics-gdext --lib mcts_service_round_trip -- --nocapture
+    /// ```
+    #[test]
+    fn mcts_service_round_trip() {
+        let snap = make_snap(2);
+        let result = try_search_action_via_service(&snap, 50, 5, 12345u64, true, 0);
+
+        // Skip (pass) when the service isn't running — expected in CI.
+        let (action, win_rate, n_rollouts, _ms) = match result {
+            None => return,
+            Some(r) => r,
+        };
+
+        let action_str = match action {
+            McAction::Idle => "Idle",
+            McAction::FoundCity => "FoundCity",
+            McAction::SpawnUnit => "SpawnUnit",
+        };
+        assert!(
+            ["Idle", "FoundCity", "SpawnUnit"].contains(&action_str),
+            "service returned unexpected action: {action_str}"
+        );
+        assert!(
+            (0.0..=1.0).contains(&win_rate),
+            "win_rate {win_rate} out of [0,1]"
+        );
+        assert!(n_rollouts > 0, "n_rollouts must be > 0");
+    }
+}
diff --git a/Users/natalie/Code/@projects/@magic-civilization/src/simulator/crates/mc-ai/src/tactical/mod.rs b/Users/natalie/Code/@projects/@magic-civilization/src/simulator/crates/mc-ai/src/tactical/mod.rs
new file mode 100644
index 00000000..bf4413c6
--- /dev/null
+++ b/Users/natalie/Code/@projects/@magic-civilization/src/simulator/crates/mc-ai/src/tactical/mod.rs
@@ -0,0 +1,360 @@
+//! `mc-ai::tactical` — tactical (per-turn) AI decisions.
+//!
+//! This module hosts the port of the GDScript tactical AI stack
+//! (`simple_heuristic_ai.gd`, `ai_tactical.gd`, `ai_military.gd`) into Rust
+//! per objective `p0-26`. It is the sibling of the strategic MCTS layer in
+//! `crate::mcts_tree` — MCTS chooses the strategic direction, `tactical`
+//! executes the per-turn unit/city decisions.
+//!
+//! # Surface
+//!
+//! The single entry point is [`decide_tactical_actions`]. Submodules
+//! ([`movement`], [`settle`], [`production`], [`citizen`], [`combat_predict`])
+//! own individual decision domains and are assembled by the entry point.
+//! Each submodule returns `Vec<Action>` so the top level is a straight
+//! concatenation — no cross-talk between domains at the contract level.
+//!
+//! # State contract
+//!
+//! The tactical layer operates on [`TacticalState`] (from [`state`]) — a
+//! hex-level snapshot of the world. The GPU-compact
+//! [`crate::abstract_state::AbstractRolloutState`] remains the MCTS rollout
+//! POD; tactical decisions cannot fit inside 256 bytes per turn because
+//! they select specific units, cities, and tiles.
+//!
+//! # Action contract
+//!
+//! [`Action`] is the JSON-transport shape the GDExtension bridge
+//! (`api-gdext::ai::GdAiController`) relays to GDScript. Variants mirror
+//! the verbs the GDScript turn loop applied directly before the port.
+//! Serde round-trip is a hard requirement: the bridge serializes each
+//! action via `serde_json::to_string` and GDScript decodes it with
+//! `JSON.parse_string`.
+
+pub(crate) mod citizen;
+pub mod combat_predict;
+pub(crate) mod movement;
+pub(crate) mod production;
+pub(crate) mod settle;
+pub mod state;
+pub mod thresholds;
+
+use std::time::Instant;
+
+use serde::{Deserialize, Serialize};
+
+use crate::evaluator::ScoringWeights;
+use crate::mcts::XorShift64;
+
+pub use state::{
+    TacticalCity, TacticalEphemerals, TacticalMap, TacticalPlayerState, TacticalState,
+    TacticalTile, TacticalUnit,
+};
+
+/// A single tactical decision emitted by the per-turn AI.
+///
+/// Variants are the union of verbs `simple_heuristic_ai.gd` and
+/// `ai_tactical.gd` dispatched in a turn. Hex coordinates use axial
+/// `(col, row)` pairs to match the GDScript engine's `(int, int)` hex
+/// addressing.
+///
+/// Serde round-trip is load-bearing: the bridge emits these as JSON
+/// strings across the GDExtension boundary.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum Action {
+    /// Move `unit_id` toward `to_hex` along the best path the movement
+    /// layer found this turn.
+    MoveUnit {
+        /// Engine-assigned unit identifier.
+        unit_id: u32,
+        /// Target axial hex `(col, row)`.
+        to_hex: (i32, i32),
+    },
+    /// Engage `target_id` with `attacker_id`. Resolution is the combat
+    /// module's responsibility; this action is the decision only.
+    AttackTarget {
+        /// Engine-assigned attacker unit id.
+        attacker_id: u32,
+        /// Engine-assigned target unit id.
+        target_id: u32,
+    },
+    /// Fortify `unit_id` in place for the defensive bonus.
+    Fortify {
+        /// Engine-assigned unit identifier.
+        unit_id: u32,
+    },
+    /// Heal `unit_id` in place (skip turn to recover HP).
+    Heal {
+        /// Engine-assigned unit identifier.
+        unit_id: u32,
+    },
+    /// Settle `settler_id` at `at_hex`, consuming the settler.
+    FoundCity {
+        /// Settler unit id.
+        settler_id: u32,
+        /// Axial hex `(col, row)` to found at.
+        at_hex: (i32, i32),
+    },
+    /// Set `city_id`'s production queue head to `item_id`
+    /// (building/unit/wonder data-pack id).
+    SetProduction {
+        /// City identifier.
+        city_id: u32,
+        /// Data-pack production item id (e.g. `"dwarf_warrior"`,
+        /// `"building_forge"`).
+        item_id: String,
+    },
+    /// Assign an unemployed citizen of `city_id` to work `tile_hex`.
+    AssignCitizen {
+        /// City identifier.
+        city_id: u32,
+        /// Worked tile axial hex `(col, row)`.
+        tile_hex: (i32, i32),
+    },
+    /// Send `unit_id` to scout `to_hex` (exploration, not combat).
+    Scout {
+        /// Engine-assigned scout/unit id.
+        unit_id: u32,
+        /// Axial hex `(col, row)` to explore toward.
+        to_hex: (i32, i32),
+    },
+    /// Issue a patrol order for `unit_id` with the given waypoint loop.
+    IssuePatrol {
+        unit_id: u32,
+        waypoints: Vec<(i32, i32)>,
+    },
+}
+
+/// Compute the full set of tactical actions for the player whose turn it
+/// is (`state.current_player`) given the hex-level [`TacticalState`] and
+/// that player's [`ScoringWeights`].
+///
+/// This is the single entry point the `api-gdext::ai::GdAiController`
+/// bridge calls once per AI-controlled player per turn. The order below
+/// is stable — port teammates may refine ordering, but the bridge and
+/// regression suite depend on the concatenation boundary.
+///
+/// `deadline` is an optional wall-clock deadline (computed once by the
+/// caller). When `Some(t)`, the loop checks `Instant::now() >= t` between
+/// submodule calls and also inside any per-unit / per-city iteration within
+/// the submodules via `budget_deadline`. Partial work is returned — the
+/// caller always receives whatever actions were completed before the
+/// deadline fired. `None` is the legacy unbounded path (default when the
+/// env var is unset). See p1-22.
+///
+/// Stable submodule order:
+/// 1. [`movement::decide_movement`]
+/// 2. [`combat_predict::decide_combat`]
+/// 3. [`settle::decide_settle`]
+/// 4. [`production::decide_production`]
+/// 5. [`citizen::decide_citizens`]
+pub fn decide_tactical_actions(
+    state: &TacticalState,
+    weights: &ScoringWeights,
+    rng: &mut XorShift64,
+    deadline: Option<Instant>,
+) -> Vec<Action> {
+    let is_expired = |dl: &Option<Instant>| -> bool {
+        dl.map_or(false, |d| Instant::now() >= d)
+    };
+
+    let mut actions = Vec::new();
+    actions.extend(movement::decide_movement(state, weights, rng, deadline));
+    if is_expired(&deadline) {
+        return actions;
+    }
+    actions.extend(combat_predict::decide_combat(state, weights, rng));
+    if is_expired(&deadline) {
+        return actions;
+    }
+    actions.extend(settle::decide_settle(state, weights, rng, deadline));
+    if is_expired(&deadline) {
+        return actions;
+    }
+    actions.extend(production::decide_production(state, weights, rng, deadline));
+    if is_expired(&deadline) {
+        return actions;
+    }
+    actions.extend(citizen::decide_citizens(state, weights, rng, deadline));
+    actions
+}
+
+#[cfg(test)]
+mod tests {
+    use std::time::{Duration, Instant};
+
+    use crate::evaluator::ScoringWeights;
+    use crate::mcts::XorShift64;
+    use crate::tactical::{
+        decide_tactical_actions, Action, TacticalCity, TacticalMap, TacticalPlayerState,
+        TacticalState, TacticalTile, TacticalUnit,
+    };
+
+    #[test]
+    fn tactical_module_compiles() {
+        // Smoke test — the module's type surface must compile and load.
+        // Real coverage comes from per-submodule ports (tasks #4-#7),
+        // `state.rs` round-trip tests, and the regression suite
+        // (task #9).
+        assert!(true);
+    }
+
+    /// Build a state with many units and cities so that the unbounded path
+    /// would visit every unit-city pair in the tactical submodules.
+    fn large_state(n_units: u32, n_cities: u32) -> TacticalState {
+        let mut tiles = Vec::new();
+        for row in 0i32..30 {
+            for col in 0i32..30 {
+                tiles.push(TacticalTile {
+                    hex: (col, row),
+                    biome: "plains".into(),
+                    yields: (2, 1, 0),
+                    resource: None,
+                    is_coast: false,
+                    owner: if col < 15 { Some(0) } else { Some(1) },
+                });
+            }
+        }
+        let map = TacticalMap { width: 30, height: 30, tiles };
+
+        let units_p0: Vec<TacticalUnit> = (0..n_units)
+            .map(|i| TacticalUnit {
+                id: i,
+                kind: "warrior".into(),
+                hex: ((i % 15) as i32, (i / 15) as i32),
+                hp: 10,
+                hp_max: 10,
+                moves_left: 2,
+                fortified: false,
+                can_found_city: false,
+                patrol_order: None,
+                ..Default::default()
+            })
+            .collect();
+
+        let units_p1: Vec<TacticalUnit> = (0..n_units)
+            .map(|i| TacticalUnit {
+                id: n_units + i,
+                kind: "warrior".into(),
+                hex: (15 + (i % 15) as i32, (i / 15) as i32),
+                hp: 10,
+                hp_max: 10,
+                moves_left: 2,
+                fortified: false,
+                can_found_city: false,
+                patrol_order: None,
+                ..Default::default()
+            })
+            .collect();
+
+        let cities_p0: Vec<TacticalCity> = (0..n_cities)
+            .map(|i| TacticalCity {
+                id: i,
+                hex: ((i * 2) as i32, 0),
+                population: 3,
+                tiles_worked: Vec::new(),
+                production_queue: Vec::new(),
+                buildings: Vec::new(),
+                health: 25,
+                is_capital: i == 0,
+            })
+            .collect();
+
+        let cities_p1: Vec<TacticalCity> = (0..n_cities)
+            .map(|i| TacticalCity {
+                id: n_cities + i,
+                hex: (15 + (i * 2) as i32, 0),
+                population: 3,
+                tiles_worked: Vec::new(),
+                production_queue: Vec::new(),
+                buildings: Vec::new(),
+                health: 25,
+                is_capital: i == 0,
+            })
+            .collect();
+
+        TacticalState {
+            current_player: 0,
+            turn: 50,
+            map,
+            players: vec![
+                TacticalPlayerState {
+                    index: 0,
+                    clan_id: "blackhammer".into(),
+                    gold: 100,
+                    happiness_pool: 0,
+                    units: units_p0,
+                    cities: cities_p0,
+                    researched_techs: Vec::new(),
+                    relations: vec![0, -1],
+                    strategic_axes: Default::default(),
+                    race_id: None,
+                    strategic_resources: Vec::new(),
+                },
+                TacticalPlayerState {
+                    index: 1,
+                    clan_id: "ironhold".into(),
+                    gold: 100,
+                    happiness_pool: 0,
+                    units: units_p1,
+                    cities: cities_p1,
+                    researched_techs: Vec::new(),
+                    relations: vec![-1, 0],
+                    strategic_axes: Default::default(),
+                    race_id: None,
+                    strategic_resources: Vec::new(),
+                },
+            ],
+            unit_catalog: Vec::new(),
+            difficulty_threshold_mult: 1.0,
+        }
+    }
+
+    /// p1-22 regression: the tactical path must respect a wall-clock budget.
+    ///
+    /// Construct a state large enough that the unbounded path would iterate
+    /// many units and city–tile pairs, then set a 50ms deadline. The call
+    /// must return within 500ms regardless of state size, and must produce
+    /// at least one action (partial work counts). Mirrors the pattern from
+    /// `mcts_tree.rs::simulate_parallel_respects_wall_clock_budget`.
+    #[test]
+    fn tactical_budget_respected() {
+        // 100 units × 10 cities × 900-tile map = non-trivial scan cost unbounded.
+        let state = large_state(100, 10);
+        let weights = ScoringWeights::default();
+        let mut rng = XorShift64::new(0xDEAD_BEEF);
+
+        let deadline = Some(Instant::now() + Duration::from_millis(50));
+
+        let wall_start = Instant::now();
+        let actions = decide_tactical_actions(&state, &weights, &mut rng, deadline);
+        let elapsed = wall_start.elapsed();
+
+        assert!(
+            elapsed < Duration::from_millis(500),
+            "tactical path with 50ms budget should return in <500ms; elapsed={elapsed:?}"
+        );
+        // Partial work is fine — but the first submodule (movement) should
+        // have produced at least one action before the budget fired.
+        assert!(
+            !actions.is_empty(),
+            "expected at least one action before budget fired; got none"
+        );
+    }
+
+    /// Unbounded path (deadline=None) must still return all actions and not
+    /// regress on a small state. This is the legacy default behavior guard.
+    #[test]
+    fn tactical_unbounded_produces_actions_on_small_state() {
+        let state = large_state(3, 1);
+        let weights = ScoringWeights::default();
+        let mut rng = XorShift64::new(42);
+
+        let actions = decide_tactical_actions(&state, &weights, &mut rng, None);
+        // Small state: 3 units, 1 city per player. Movement + production should fire.
+        assert!(
+            !actions.is_empty(),
+            "unbounded path should produce actions on a small state"
+        );
+    }
+}
diff --git a/Users/natalie/Code/@projects/@magic-civilization/src/simulator/crates/mc-ai/src/tactical/state.rs b/Users/natalie/Code/@projects/@magic-civilization/src/simulator/crates/mc-ai/src/tactical/state.rs
new file mode 100644
index 00000000..1312dc9a
--- /dev/null
+++ b/Users/natalie/Code/@projects/@magic-civilization/src/simulator/crates/mc-ai/src/tactical/state.rs
@@ -0,0 +1,480 @@
+//! Hex-level tactical state consumed by [`super::decide_tactical_actions`].
+//!
+//! This type tree is the tactical AI's view of the world. It is richer than
+//! the GPU-compact [`crate::abstract_state::AbstractRolloutState`] (which
+//! stays the MCTS rollout POD) and carries the per-unit / per-city / per-hex
+//! data the ported GDScript AI needs to express a turn's decisions.
+//!
+//! # Serde contract
+//!
+//! Every struct derives `Serialize + Deserialize + PartialEq` — the
+//! GDExtension bridge (`api-gdext::ai::GdAiController`) round-trips
+//! `TacticalState` across the FFI boundary as JSON. `PartialEq` exists so
+//! regression tests (task #9) can snapshot state before/after port.
+//!
+//! # Hex addressing
+//!
+//! All coordinates are axial `(col, row)` pairs matching the GDScript engine
+//! convention (`src/game/engine/src/hex_math.gd`). The `TacticalMap::tiles`
+//! vector is row-major and carries `width * height` entries — the bridge is
+//! responsible for populating in a stable order so `PartialEq` works.
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+/// Top-level tactical state passed to [`super::decide_tactical_actions`].
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct TacticalState {
+    /// Slot index of the player whose turn is being decided.
+    pub current_player: u8,
+    /// Game turn number at the point of decision.
+    pub turn: u32,
+    /// Full map state including terrain, yields, and ownership.
+    pub map: TacticalMap,
+    /// Per-player slots. Indexed by `TacticalPlayerState::index`.
+    pub players: Vec<TacticalPlayerState>,
+    /// Catalog of producible military units with tier + tech gate, populated
+    /// from `units/*.json` by the GDExtension bridge. Consumed by
+    /// `tactical::production::pick_best_melee` to select tier-N units as tech
+    /// unlocks (p0-39). Empty vec falls back to tier-1 `warrior` only.
+    #[serde(default)]
+    pub unit_catalog: Vec<TacticalUnitSpec>,
+    /// Multiplicative scalar applied on top of all personality-axis-derived
+    /// thresholds (p0-24). Easy < 1.0 (overcommits), Hard > 1.0 (waits for
+    /// real superiority). Defaults to 1.0 (normal / unset). Populated from
+    /// `difficulty.json::ai_modifiers.difficulty_threshold_mult` by the bridge.
+    #[serde(default = "default_threshold_mult")]
+    pub difficulty_threshold_mult: f32,
+}
+
+fn default_threshold_mult() -> f32 {
+    1.0
+}
+
+/// Hex map with row-major tile storage.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct TacticalMap {
+    /// Grid width in hexes (column count).
+    pub width: u32,
+    /// Grid height in hexes (row count).
+    pub height: u32,
+    /// Row-major tile data, length `width * height`.
+    pub tiles: Vec<TacticalTile>,
+}
+
+/// A single map tile.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct TacticalTile {
+    /// Axial `(col, row)` coordinates.
+    pub hex: (i32, i32),
+    /// Biome id as defined in `public/games/age-of-dwarves/data/biomes.json`.
+    pub biome: String,
+    /// `(food, production, gold)` yields before city / improvement bonuses.
+    pub yields: (u32, u32, u32),
+    /// Deposit / resource id present on the tile, if any
+    /// (e.g. `"iron_ore"`, `"gold_vein"`).
+    pub resource: Option<String>,
+    /// Whether the tile is adjacent to ocean / lake water.
+    pub is_coast: bool,
+    /// Owning player slot, if any. Unowned tiles are `None`.
+    pub owner: Option<u8>,
+}
+
+/// Per-player state: economy, units, cities, diplomacy, research.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct TacticalPlayerState {
+    /// Slot index. Must equal the index of this struct inside
+    /// [`TacticalState::players`].
+    pub index: u8,
+    /// Personality id from `ai_personalities.json` (e.g. `"blackhammer"`).
+    pub clan_id: String,
+    /// Treasury, signed to permit transient deficits while the turn is being
+    /// decided.
+    pub gold: i32,
+    /// Happiness pool — preserved from the old `AbstractRolloutState` signal
+    /// so the citizen / production submodules can keep the food-floor check.
+    pub happiness_pool: i32,
+    /// All units owned by this player.
+    pub units: Vec<TacticalUnit>,
+    /// All cities owned by this player.
+    pub cities: Vec<TacticalCity>,
+    /// Tech ids this player has researched (for gating `Action::SetProduction`).
+    pub researched_techs: Vec<String>,
+    /// Diplomatic relations per opponent slot. `<0` war, `0` peace, `>0`
+    /// friend. Self-slot is 0.
+    pub relations: Vec<i8>,
+    /// Race id (e.g. `"dwarf"`, `"human"`). `None` for fixtures predating
+    /// race-gated unit selection. Consumed by
+    /// `tactical::production::pick_best_melee` to filter units whose
+    /// `race_required` doesn't match.
+    #[serde(default)]
+    pub race_id: Option<String>,
+    /// Strategic resource ids the player currently controls (tiles they own
+    /// that provide `iron_ore`, `horses`, etc.). Consumed by
+    /// `tactical::production::pick_best_melee` to filter units whose
+    /// `requires_resource` isn't available.
+    #[serde(default)]
+    pub strategic_resources: Vec<String>,
+    /// Clan personality axes on the `1..=10` scale (neutral = 5). Consumed by
+    /// `tactical::thresholds` for personality-emergent posture / retreat /
+    /// chase / siege thresholds (p0-37). Empty map = baseline (axis=5 for
+    /// every axis) for back-compat with fixtures predating this field.
+    ///
+    /// Flexible deserializer accepts GDScript's float-formatted integers
+    /// (`JSON.stringify` emits `3.0` rather than `3`) without panic.
+    #[serde(
+        default,
+        deserialize_with = "mc_core::gd_compat::de_btreemap_string_i32_flexible"
+    )]
+    pub strategic_axes: BTreeMap<String, i32>,
+}
+
+/// A unit on the map.
+#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
+pub struct TacticalUnit {
+    /// Engine-assigned unique id — matches `Action::MoveUnit::unit_id`.
+    pub id: u32,
+    /// Unit kind id (e.g. `"warrior"`, `"founder"`, `"scout"`, or race-prefixed
+    /// like `"dwarf_warrior"`). Both generic and race-prefixed kinds coexist;
+    /// see `data/units/<id>.json` (generic) and `resources/units/<race>_<id>.json`
+    /// (race-specific). For founder detection prefer `is_founder()` over a
+    /// kind-string match — clan-themed founders like `"dwarf_tribe"` carry the
+    /// `can_found_city` flag and would be missed by string match.
+    pub kind: String,
+    /// Current axial `(col, row)` position.
+    pub hex: (i32, i32),
+    /// Current hit points.
+    pub hp: u32,
+    /// Max hit points (for healing / damage-prediction math).
+    pub hp_max: u32,
+    /// Remaining movement points this turn.
+    pub moves_left: u32,
+    /// Fortify-in-place flag.
+    pub fortified: bool,
+    /// True when this unit can found a city — data-driven from the engine's
+    /// `unit.can_found_city` flag. NEVER match on `kind` string alone because
+    /// clan-themed founder units (e.g. `"dwarf_tribe"`) DO NOT literally spell
+    /// "settler" or "founder". Default `false` for serde back-compat with
+    /// fixtures that predate this field.
+    #[serde(default)]
+    pub can_found_city: bool,
+    /// Active patrol standing order waypoints, if any. `None` means idle or fortified.
+    /// Stored as waypoint list only (no cursor/mode) so the AI can score IssuePatrol
+    /// without depending on mc-turn. The full `PatrolOrder` lives on `MapUnit` in mc-turn.
+    #[serde(default)]
+    pub patrol_order: Option<Vec<(i32, i32)>>,
+}
+
+impl TacticalUnit {
+    /// True when this unit can found a city. Checks the data-driven flag first;
+    /// falls back to kind-string matching for test fixtures that omit the flag.
+    pub fn is_founder(&self) -> bool {
+        self.can_found_city || matches!(self.kind.as_str(), "settler" | "founder")
+    }
+}
+
+/// Specification for a producible military unit — carries enough data for the
+/// production layer to select tier-appropriate units as tech unlocks (p0-39).
+///
+/// Populated from `public/games/age-of-dwarves/data/units/*.json` by the
+/// GDExtension bridge and handed through on every `TacticalState`. Empty vec =
+/// back-compat (tier-1 fallback only) for fixtures predating p0-39.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct TacticalUnitSpec {
+    /// Unit id (e.g. `"warrior"`, `"pikeman"`).
+    pub id: String,
+    /// Tier on the 1..N content ladder.
+    pub tier: u32,
+    /// Tech gate — unit is buildable when the player has researched this id.
+    /// `None` means always available (tier-1 starting units).
+    pub tech_required: Option<String>,
+    /// Unit-type classification mirroring `units/*.json::unit_type`:
+    /// `"military"` | `"worker"` | `"founder"` | `"scout"` | …
+    pub unit_type: String,
+    /// Strategic resource gate — unit buildable only when the player owns at
+    /// least one tile providing this resource id (e.g. `"iron_ore"` for
+    /// cavalry). `None` means no resource requirement. Filtered by
+    /// `tactical::production::pick_best_melee` to avoid queueing units the
+    /// engine's strategic-gate check will reject.
+    #[serde(default)]
+    pub requires_resource: Option<String>,
+    /// Race gate — unit buildable only when the player's race matches this id
+    /// (e.g. `"dwarf"` for berserker / ironwarden / forge_titan). `None`
+    /// means no race restriction.
+    #[serde(default)]
+    pub race_required: Option<String>,
+    /// Clan IDs that prefer this unit (e.g. `["ironhold", "deepforge"]` for
+    /// `mountain_king`). Drives clan personality differentiation in the
+    /// production picker (p1-37). Empty vec = neutral / shared by all clans.
+    #[serde(default)]
+    pub clan_affinity: Vec<String>,
+    /// Archetype label mirroring `units/*.json::archetype`:
+    /// `"light_melee"` | `"heavy_melee"` | `"anti_cavalry"` | `"ranged"` |
+    /// `"siege"` | `"cavalry_walker"` | `"wild"` | `"civilian"`. `None` for
+    /// fixtures predating p1-34.
+    #[serde(default)]
+    pub archetype: Option<String>,
+}
+
+/// A city.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct TacticalCity {
+    /// Engine-assigned unique id — matches `Action::SetProduction::city_id`.
+    pub id: u32,
+    /// City-center axial `(col, row)`.
+    pub hex: (i32, i32),
+    /// Current population.
+    pub population: u32,
+    /// Axial hexes currently worked by this city's citizens. Used by the
+    /// citizen-assignment submodule to avoid double-assigning tiles.
+    pub tiles_worked: Vec<(i32, i32)>,
+    /// Production queue of item ids, head at index 0.
+    pub production_queue: Vec<String>,
+    /// Building ids already constructed in this city. The production picker
+    /// reads this to skip duplicates.
+    pub buildings: Vec<String>,
+    /// City HP for siege / damage-prediction math.
+    pub health: u32,
+    /// Whether this city is the player's capital.
+    pub is_capital: bool,
+}
+
+/// Per-turn ephemeral state passed to `GdAiController::decide_actions` after
+/// the tile catalog has been moved into the Rust-resident `TacticalMap`.
+///
+/// This struct carries everything that changes every turn but excludes the
+/// map tiles (which are held in `GdAiController::cached_map` and only pushed
+/// once at game-start via `set_map` + incrementally via `update_tile`).
+///
+/// `decide_actions` parses this from JSON and assembles a full `TacticalState`
+/// by combining it with the cached `TacticalMap`.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct TacticalEphemerals {
+    /// Slot index of the player whose turn is being decided.
+    pub current_player: u8,
+    /// Game turn number at the point of decision.
+    pub turn: u32,
+    /// Per-player slots. Indexed by `TacticalPlayerState::index`.
+    pub players: Vec<TacticalPlayerState>,
+    /// Catalog of producible military units (see `TacticalState::unit_catalog`).
+    #[serde(default)]
+    pub unit_catalog: Vec<TacticalUnitSpec>,
+    /// Difficulty threshold multiplier (see `TacticalState::difficulty_threshold_mult`).
+    #[serde(default = "default_threshold_mult")]
+    pub difficulty_threshold_mult: f32,
+}
+
+impl TacticalEphemerals {
+    /// Combine with a cached `TacticalMap` to produce a full `TacticalState`
+    /// ready for `decide_tactical_actions`.
+    pub fn into_tactical_state(self, map: TacticalMap) -> TacticalState {
+        TacticalState {
+            current_player: self.current_player,
+            turn: self.turn,
+            map,
+            players: self.players,
+            unit_catalog: self.unit_catalog,
+            difficulty_threshold_mult: self.difficulty_threshold_mult,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn non_trivial_state() -> TacticalState {
+        let tiles: Vec<TacticalTile> = (0..10)
+            .flat_map(|row| {
+                (0..10).map(move |col| TacticalTile {
+                    hex: (col, row),
+                    biome: if (col + row) % 3 == 0 { "hills" } else { "plains" }.into(),
+                    yields: (2, 1, 0),
+                    resource: if col == 3 && row == 3 { Some("iron_ore".into()) } else { None },
+                    is_coast: col == 0 || col == 9,
+                    owner: if col < 3 {
+                        Some(0)
+                    } else if col > 6 {
+                        Some(1)
+                    } else {
+                        None
+                    },
+                })
+            })
+            .collect();
+
+        let units = vec![
+            TacticalUnit {
+                id: 1,
+                kind: "warrior".into(),
+                hex: (1, 1),
+                hp: 10,
+                hp_max: 10,
+                moves_left: 2,
+                fortified: false,
+                can_found_city: false,
+                patrol_order: None,
+                ..Default::default()
+            },
+            TacticalUnit {
+                id: 2,
+                kind: "settler".into(),
+                hex: (2, 2),
+                hp: 5,
+                hp_max: 5,
+                moves_left: 2,
+                fortified: false,
+                can_found_city: false,
+                patrol_order: None,
+                ..Default::default()
+            },
+            TacticalUnit {
+                id: 3,
+                kind: "scout".into(),
+                hex: (1, 2),
+                hp: 6,
+                hp_max: 6,
+                moves_left: 3,
+                fortified: false,
+                can_found_city: false,
+                patrol_order: None,
+                ..Default::default()
+            },
+            TacticalUnit {
+                id: 4,
+                kind: "warrior".into(),
+                hex: (8, 8),
+                hp: 8,
+                hp_max: 10,
+                moves_left: 0,
+                fortified: true,
+                can_found_city: false,
+                patrol_order: None,
+                ..Default::default()
+            },
+        ];
+
+        let cities = vec![
+            TacticalCity {
+                id: 10,
+                hex: (1, 1),
+                population: 3,
+                tiles_worked: vec![(0, 1), (1, 0), (2, 1)],
+                production_queue: vec!["warrior".into()],
+                buildings: vec!["granary".into()],
+                health: 25,
+                is_capital: true,
+            },
+            TacticalCity {
+                id: 20,
+                hex: (8, 8),
+                population: 2,
+                tiles_worked: vec![(7, 8), (8, 7)],
+                production_queue: vec!["forge".into(), "warrior".into()],
+                buildings: Vec::new(),
+                health: 20,
+                is_capital: true,
+            },
+        ];
+
+        TacticalState {
+            current_player: 0,
+            turn: 42,
+            map: TacticalMap {
+                width: 10,
+                height: 10,
+                tiles,
+            },
+            players: vec![
+                TacticalPlayerState {
+                    index: 0,
+                    clan_id: "blackhammer".into(),
+                    gold: 100,
+                    happiness_pool: 3,
+                    units: units.iter().take(3).cloned().collect(),
+                    cities: cities.iter().take(1).cloned().collect(),
+                    researched_techs: vec!["bronze_working".into()],
+                    relations: vec![0, -1],
+                    strategic_axes: ::std::collections::BTreeMap::new(),
+                    race_id: None,
+                    strategic_resources: Vec::new(),
+                },
+                TacticalPlayerState {
+                    index: 1,
+                    clan_id: "goldbeard".into(),
+                    gold: 60,
+                    happiness_pool: -1,
+                    units: units.iter().skip(3).cloned().collect(),
+                    cities: cities.iter().skip(1).cloned().collect(),
+                    researched_techs: Vec::new(),
+                    relations: vec![-1, 0],
+                    strategic_axes: ::std::collections::BTreeMap::new(),
+                    race_id: None,
+                    strategic_resources: Vec::new(),
+                },
+            ],
+            unit_catalog: Vec::new(),
+            difficulty_threshold_mult: 1.0,
+        }
+    }
+
+    #[test]
+    fn tactical_state_roundtrips_through_json() {
+        let state = non_trivial_state();
+        let json = serde_json::to_string(&state).expect("serialize");
+        let back: TacticalState = serde_json::from_str(&json).expect("deserialize");
+        assert_eq!(state, back);
+        // Sanity: the serialized form actually contains the expected 100 tiles.
+        assert_eq!(state.map.tiles.len(), 100);
+        assert_eq!(state.players.len(), 2);
+        assert_eq!(state.players[0].units.len(), 3);
+    }
+
+    #[test]
+    fn empty_tactical_state_roundtrips() {
+        let empty = TacticalState {
+            current_player: 0,
+            turn: 0,
+            map: TacticalMap {
+                width: 0,
+                height: 0,
+                tiles: Vec::new(),
+            },
+            players: Vec::new(),
+            unit_catalog: Vec::new(),
+            difficulty_threshold_mult: 1.0,
+        };
+        let json = serde_json::to_string(&empty).expect("serialize");
+        let back: TacticalState = serde_json::from_str(&json).expect("deserialize");
+        assert_eq!(empty, back);
+    }
+
+    #[test]
+    fn action_roundtrips_through_json() {
+        use crate::tactical::Action;
+        let variants = vec![
+            Action::MoveUnit { unit_id: 1, to_hex: (3, 4) },
+            Action::AttackTarget { attacker_id: 1, target_id: 2 },
+            Action::Fortify { unit_id: 5 },
+            Action::Heal { unit_id: 7 },
+            Action::FoundCity { settler_id: 9, at_hex: (-2, 3) },
+            Action::SetProduction {
+                city_id: 10,
+                item_id: "forge".into(),
+            },
+            Action::AssignCitizen {
+                city_id: 10,
+                tile_hex: (1, 0),
+            },
+            Action::Scout { unit_id: 3, to_hex: (0, 5) },
+        ];
+        for a in &variants {
+            let json = serde_json::to_string(a).expect("serialize");
+            let back: Action = serde_json::from_str(&json).expect("deserialize");
+            // Action doesn't derive PartialEq — re-serialize and compare strings.
+            let back_json = serde_json::to_string(&back).expect("re-serialize");
+            assert_eq!(json, back_json, "action variant lost fidelity: {a:?}");
+        }
+    }
+}
diff --git a/public/games/age-of-dwarves/data/audio.json b/public/games/age-of-dwarves/data/audio.json
index e49a5ffe..36ca7e41 100644
--- a/public/games/age-of-dwarves/data/audio.json
+++ b/public/games/age-of-dwarves/data/audio.json
@@ -202,6 +202,18 @@
       "volume_db": -7.0,
       "bus": "SFX"
     },
+    "unit.siege.spawn": {
+      "stream": "audio/sfx/units/siege/spawn.ogg",
+      "volume_db": -8.0,
+      "bus": "SFX",
+      "description": "Heavy hit-jingle — siege engine deployed."
+    },
+    "unit.support.spawn": {
+      "stream": "audio/sfx/units/support/spawn.ogg",
+      "volume_db": -8.0,
+      "bus": "SFX",
+      "description": "Light pizzicato — support unit takes the field."
+    },
     "unit.siege.attack": {
       "streams": [
         "audio/sfx/units/siege/bombard_01.ogg",
@@ -217,12 +229,6 @@
       "volume_db": -8.0,
       "bus": "SFX"
     },
-    "building.civic.complete": {
-      "stream": "audio/sfx/buildings/build_complete_civic.ogg",
-      "volume_db": -5.0,
-      "bus": "SFX",
-      "description": "Low ceremonial bell on civic-building completion."
-    },
     "building.production.complete": {
       "stream": "audio/sfx/buildings/build_complete_prod.ogg",
       "volume_db": -5.0,
@@ -440,41 +446,29 @@
       "bus": "SFX",
       "description": "Light scholarly tap \u2014 research building completed."
     },
-    "building.complete": {
-      "stream": "audio/sfx/buildings/generic_complete.ogg",
+    "building.economy.complete": {
+      "stream": "audio/sfx/buildings/economy_complete.ogg",
       "volume_db": -6.0,
       "bus": "SFX",
-      "description": "Stone-on-plate impact \u2014 kind-only fallback for any building category."
+      "description": "Plucked-string flourish \u2014 economy building completed."
     },
-    "complete": {
-      "stream": "audio/sfx/generic/complete.ogg",
-      "volume_db": -7.0,
-      "bus": "SFX",
-      "description": "Plate impact \u2014 bare-kind fallback for any 'complete' event."
-    },
-    "attack": {
-      "stream": "audio/sfx/generic/attack.ogg",
-      "volume_db": -7.0,
-      "bus": "SFX",
-      "description": "Generic attack swing \u2014 last-resort fallback for unclassified entities."
-    },
-    "hit": {
-      "stream": "audio/sfx/generic/hit.ogg",
-      "volume_db": -7.0,
-      "bus": "SFX",
-      "description": "Generic impact \u2014 last-resort fallback for unclassified entities."
-    },
-    "death": {
-      "stream": "audio/sfx/generic/death.ogg",
+    "building.food.complete": {
+      "stream": "audio/sfx/buildings/food_complete.ogg",
       "volume_db": -6.0,
       "bus": "SFX",
-      "description": "Generic fall thud \u2014 last-resort fallback for unclassified entities."
+      "description": "Plucked-string flourish \u2014 food building completed."
     },
-    "spawn": {
-      "stream": "audio/sfx/fauna/spawn.ogg",
-      "volume_db": -9.0,
+    "building.naval.complete": {
+      "stream": "audio/sfx/buildings/naval_complete.ogg",
+      "volume_db": -6.0,
       "bus": "SFX",
-      "description": "Brush rustle \u2014 bare-kind fallback (aliases wild_spawn texture for unclassified spawn events)."
+      "description": "Plucked-string flourish \u2014 naval building completed."
+    },
+    "building.resource.complete": {
+      "stream": "audio/sfx/buildings/resource_complete.ogg",
+      "volume_db": -6.0,
+      "bus": "SFX",
+      "description": "Plucked-string flourish \u2014 resource building completed."
     }
   },
   "music": {
diff --git a/public/resources/audio/LICENSES.md b/public/resources/audio/LICENSES.md
index bd9c9c89..feea6ae7 100644
--- a/public/resources/audio/LICENSES.md
+++ b/public/resources/audio/LICENSES.md
@@ -32,15 +32,17 @@ Each row records one `.ogg` shipped under `public/games/age-of-dwarves/assets/au
 | `audio/music/victory_economic_b.ogg` | CC0-1.0 | [link](https://opengameart.org/sites/default/files/JRPG%20Music%20Pack%20%231%20%5BExploration%5D%20by%20Juhani%20Junkala.zip#Exploration4 - Prairie Nights.ogg) | Juhani Junkala (SubspaceAudio |  OpenGameArt) | loudnorm I=-16/TP=-3+ogg 128kbps |
 | `audio/music/victory_science_a.ogg` | CC0-1.0 | [link](https://opengameart.org/sites/default/files/JRPG%20Music%20Pack%20%231%20%5BExploration%5D%20by%20Juhani%20Junkala.zip#Exploration3 - Tha'el Mines.ogg) | Juhani Junkala (SubspaceAudio |  OpenGameArt) | loudnorm I=-16/TP=-3+ogg 128kbps |
 | `audio/music/victory_science_b.ogg` | CC0-1.0 | [link](https://opengameart.org/sites/default/files/JRPG%20Music%20Pack%20%231%20%5BExploration%5D%20by%20Juhani%20Junkala.zip#Exploration6 - Tropical Island.ogg) | Juhani Junkala (SubspaceAudio |  OpenGameArt) | loudnorm I=-16/TP=-3+ogg 128kbps |
-| `audio/sfx/buildings/build_complete_civic.ogg` | CC0-1.0 | [link](https://github.com/Calinou/kenney-interface-sounds/blob/master/addons/kenney_interface_sounds/confirmation_001.wav) | Kenney (Calinou repackage) | loudnorm I=-16/TP=-3+wav→ogg 128kbps | 2026-04-27 |
 | `audio/sfx/buildings/build_complete_def.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactPlate_heavy_002.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-27 |
 | `audio/sfx/buildings/build_complete_mil.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactBell_heavy_002.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-27 |
 | `audio/sfx/buildings/build_complete_prod.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactMetal_heavy_002.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
 | `audio/sfx/buildings/culture_complete.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactWood_heavy_004.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
 | `audio/sfx/buildings/diplomacy_complete.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactPlate_medium_000.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
-| `audio/sfx/buildings/generic_complete.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactPlate_medium_003.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
+| `audio/sfx/buildings/economy_complete.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/music-jingles/4f5dd770b7-1677590399/kenney_music-jingles.zip#Audio/Pizzicato jingles/jingles_PIZZI04.ogg) | Kenney (Music Jingles) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-30 |
+| `audio/sfx/buildings/food_complete.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/music-jingles/4f5dd770b7-1677590399/kenney_music-jingles.zip#Audio/Pizzicato jingles/jingles_PIZZI05.ogg) | Kenney (Music Jingles) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-30 |
 | `audio/sfx/buildings/infrastructure_complete.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactMining_001.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
+| `audio/sfx/buildings/naval_complete.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/music-jingles/4f5dd770b7-1677590399/kenney_music-jingles.zip#Audio/Pizzicato jingles/jingles_PIZZI06.ogg) | Kenney (Music Jingles) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-30 |
 | `audio/sfx/buildings/research_complete.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactPlate_light_004.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
+| `audio/sfx/buildings/resource_complete.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/music-jingles/4f5dd770b7-1677590399/kenney_music-jingles.zip#Audio/Pizzicato jingles/jingles_PIZZI08.ogg) | Kenney (Music Jingles) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-30 |
 | `audio/sfx/buildings/wonder_built.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactWood_heavy_000.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
 | `audio/sfx/buildings/wonder_built_own.ogg` | CC0-1.0 | [link](https://opengameart.org/sites/default/files/fanfare_0.ogg) | Spring Spring (OpenGameArt) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-28 |
 | `audio/sfx/buildings/wonder_built_rival.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactBell_heavy_002.ogg) | Kenney (Impact Sounds) | loudnorm I=-22/TP=-6+ogg 128kbps (extra-quiet for distant feel) | 2026-04-28 |
@@ -75,10 +77,6 @@ Each row records one `.ogg` shipped under `public/games/age-of-dwarves/assets/au
 | `audio/sfx/fauna/predator_hurt_02.ogg` | CC0-1.0 | [link](https://opengameart.org/sites/default/files/80-CC0-creature-SFX_0.zip#hurt_02.ogg) | rubberduck (OpenGameArt) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-27 |
 | `audio/sfx/fauna/predator_spawn.ogg` | CC0-1.0 | [link](https://opengameart.org/sites/default/files/80-CC0-creature-SFX_0.zip#howl.ogg) | rubberduck (OpenGameArt) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-27 |
 | `audio/sfx/fauna/spawn.ogg` | CC0-1.0 | [link](https://opengameart.org/sites/default/files/80-CC0-creature-SFX_0.zip#bug_01.ogg) | rubberduck (OpenGameArt) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-27 |
-| `audio/sfx/generic/attack.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactGeneric_light_000.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
-| `audio/sfx/generic/complete.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactPlate_medium_004.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
-| `audio/sfx/generic/death.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactGeneric_light_004.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
-| `audio/sfx/generic/hit.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactGeneric_light_002.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
 | `audio/sfx/ui/border_expanded.ogg` | CC0-1.0 | [link](https://github.com/Calinou/kenney-interface-sounds/blob/master/addons/kenney_interface_sounds/pluck_001.wav) | Kenney (Calinou repackage) | loudnorm I=-16/TP=-3+wav→ogg 128kbps | 2026-04-27 |
 | `audio/sfx/ui/culture_researched.ogg` | CC0-1.0 | [link](https://github.com/Calinou/kenney-interface-sounds/blob/master/addons/kenney_interface_sounds/confirmation_003.wav) | Kenney (Calinou repackage) | loudnorm I=-16/TP=-3+wav→ogg 128kbps | 2026-04-27 |
 | `audio/sfx/ui/research_start.ogg` | CC0-1.0 | [link](https://github.com/Calinou/kenney-interface-sounds/blob/master/addons/kenney_interface_sounds/tick_002.wav) | Kenney (Calinou repackage) | loudnorm I=-16/TP=-3+wav→ogg 128kbps | 2026-04-27 |
@@ -107,9 +105,11 @@ Each row records one `.ogg` shipped under `public/games/age-of-dwarves/assets/au
 | `audio/sfx/units/siege/bombard_02.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactPlate_heavy_004.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-27 |
 | `audio/sfx/units/siege/death.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactPlate_medium_002.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
 | `audio/sfx/units/siege/hit.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactPlank_medium_004.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
+| `audio/sfx/units/siege/spawn.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/music-jingles/4f5dd770b7-1677590399/kenney_music-jingles.zip#Audio/Hit jingles/jingles_HIT08.ogg) | Kenney (Music Jingles) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-30 |
 | `audio/sfx/units/support/attack.ogg` | CC0-1.0 | [link](https://github.com/Calinou/kenney-interface-sounds/blob/master/addons/kenney_interface_sounds/pluck_002.wav) | Kenney (Calinou repackage) | loudnorm I=-16/TP=-3+wav→ogg 128kbps | 2026-04-29 |
 | `audio/sfx/units/support/death.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactSoft_heavy_002.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
 | `audio/sfx/units/support/hit.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactSoft_heavy_001.ogg) | Kenney (Impact Sounds) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
+| `audio/sfx/units/support/spawn.ogg` | CC0-1.0 | [link](https://kenney.nl/media/pages/assets/music-jingles/4f5dd770b7-1677590399/kenney_music-jingles.zip#Audio/Pizzicato jingles/jingles_PIZZI09.ogg) | Kenney (Music Jingles) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-30 |
 | `audio/sfx/weather/blizzard.ogg` | CC0-1.0 | [link](https://opengameart.org/sites/default/files/sfx_loops.zip#weird_01.ogg) | rubberduck (OpenGameArt) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
 | `audio/sfx/weather/drought.ogg` | CC0-1.0 | [link](https://opengameart.org/sites/default/files/sfx_loops.zip#weird_03.ogg) | rubberduck (OpenGameArt) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
 | `audio/sfx/weather/heat_wave.ogg` | CC0-1.0 | [link](https://opengameart.org/sites/default/files/sfx_loops.zip#weird_02.ogg) | rubberduck (OpenGameArt) | loudnorm I=-16/TP=-3+ogg 128kbps | 2026-04-29 |
diff --git a/public/resources/audio/sfx/buildings/build_complete_civic.ogg b/public/resources/audio/sfx/buildings/build_complete_civic.ogg
deleted file mode 100644
index d649b4f5..00000000
Binary files a/public/resources/audio/sfx/buildings/build_complete_civic.ogg and /dev/null differ
diff --git a/public/resources/audio/sfx/buildings/economy_complete.ogg b/public/resources/audio/sfx/buildings/economy_complete.ogg
new file mode 100644
index 00000000..f8108dbc
Binary files /dev/null and b/public/resources/audio/sfx/buildings/economy_complete.ogg differ
diff --git a/public/resources/audio/sfx/buildings/food_complete.ogg b/public/resources/audio/sfx/buildings/food_complete.ogg
new file mode 100644
index 00000000..70b594df
Binary files /dev/null and b/public/resources/audio/sfx/buildings/food_complete.ogg differ
diff --git a/public/resources/audio/sfx/buildings/generic_complete.ogg b/public/resources/audio/sfx/buildings/generic_complete.ogg
deleted file mode 100644
index b3f69c6e..00000000
Binary files a/public/resources/audio/sfx/buildings/generic_complete.ogg and /dev/null differ
diff --git a/public/resources/audio/sfx/buildings/naval_complete.ogg b/public/resources/audio/sfx/buildings/naval_complete.ogg
new file mode 100644
index 00000000..4375b161
Binary files /dev/null and b/public/resources/audio/sfx/buildings/naval_complete.ogg differ
diff --git a/public/resources/audio/sfx/buildings/resource_complete.ogg b/public/resources/audio/sfx/buildings/resource_complete.ogg
new file mode 100644
index 00000000..d9269bda
Binary files /dev/null and b/public/resources/audio/sfx/buildings/resource_complete.ogg differ
diff --git a/public/resources/audio/sfx/generic/attack.ogg b/public/resources/audio/sfx/generic/attack.ogg
deleted file mode 100644
index 2c6ae484..00000000
Binary files a/public/resources/audio/sfx/generic/attack.ogg and /dev/null differ
diff --git a/public/resources/audio/sfx/generic/complete.ogg b/public/resources/audio/sfx/generic/complete.ogg
deleted file mode 100644
index 9d14f43f..00000000
Binary files a/public/resources/audio/sfx/generic/complete.ogg and /dev/null differ
diff --git a/public/resources/audio/sfx/generic/death.ogg b/public/resources/audio/sfx/generic/death.ogg
deleted file mode 100644
index b0824d49..00000000
Binary files a/public/resources/audio/sfx/generic/death.ogg and /dev/null differ
diff --git a/public/resources/audio/sfx/generic/hit.ogg b/public/resources/audio/sfx/generic/hit.ogg
deleted file mode 100644
index 27710348..00000000
Binary files a/public/resources/audio/sfx/generic/hit.ogg and /dev/null differ
diff --git a/public/resources/audio/sfx/units/siege/spawn.ogg b/public/resources/audio/sfx/units/siege/spawn.ogg
new file mode 100644
index 00000000..58d1dcb8
Binary files /dev/null and b/public/resources/audio/sfx/units/siege/spawn.ogg differ
diff --git a/public/resources/audio/sfx/units/support/spawn.ogg b/public/resources/audio/sfx/units/support/spawn.ogg
new file mode 100644
index 00000000..ac9be8ad
Binary files /dev/null and b/public/resources/audio/sfx/units/support/spawn.ogg differ
diff --git a/public/resources/audio/sources.csv b/public/resources/audio/sources.csv
index bf2b15c9..1fda37c7 100644
--- a/public/resources/audio/sources.csv
+++ b/public/resources/audio/sources.csv
@@ -26,7 +26,6 @@ audio/sfx/ui/unit_promoted.ogg,https://github.com/Calinou/kenney-interface-sound
 audio/sfx/ui/unit_moved.ogg,https://github.com/Calinou/kenney-interface-sounds/blob/master/addons/kenney_interface_sounds/click_004.wav,CC0-1.0,Kenney (Calinou repackage),loudnorm I=-16/TP=-3+wav→ogg 128kbps,2026-04-27
 audio/sfx/city/city_founded.ogg,https://github.com/Calinou/kenney-interface-sounds/blob/master/addons/kenney_interface_sounds/bong_001.wav,CC0-1.0,Kenney (Calinou repackage),loudnorm I=-16/TP=-3+wav→ogg 128kbps,2026-04-27
 audio/sfx/city/city_starved.ogg,https://github.com/Calinou/kenney-interface-sounds/blob/master/addons/kenney_interface_sounds/error_004.wav,CC0-1.0,Kenney (Calinou repackage),loudnorm I=-16/TP=-3+wav→ogg 128kbps,2026-04-27
-audio/sfx/buildings/build_complete_civic.ogg,https://github.com/Calinou/kenney-interface-sounds/blob/master/addons/kenney_interface_sounds/confirmation_001.wav,CC0-1.0,Kenney (Calinou repackage),loudnorm I=-16/TP=-3+wav→ogg 128kbps,2026-04-27
 audio/sfx/units/melee/attack_01.ogg,https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactMetal_light_000.ogg,CC0-1.0,Kenney (Impact Sounds),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-27
 audio/sfx/units/melee/attack_02.ogg,https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactMetal_light_002.ogg,CC0-1.0,Kenney (Impact Sounds),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-27
 audio/sfx/units/melee/attack_03.ogg,https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactMetal_light_003.ogg,CC0-1.0,Kenney (Impact Sounds),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-27
@@ -118,12 +117,7 @@ audio/sfx/buildings/culture_complete.ogg,https://kenney.nl/media/pages/assets/im
 audio/sfx/buildings/diplomacy_complete.ogg,https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactPlate_medium_000.ogg,CC0-1.0,Kenney (Impact Sounds),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
 audio/sfx/buildings/infrastructure_complete.ogg,https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactMining_001.ogg,CC0-1.0,Kenney (Impact Sounds),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
 audio/sfx/buildings/research_complete.ogg,https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactPlate_light_004.ogg,CC0-1.0,Kenney (Impact Sounds),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
-audio/sfx/generic/attack.ogg,https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactGeneric_light_000.ogg,CC0-1.0,Kenney (Impact Sounds),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
-audio/sfx/generic/hit.ogg,https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactGeneric_light_002.ogg,CC0-1.0,Kenney (Impact Sounds),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
-audio/sfx/generic/death.ogg,https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactGeneric_light_004.ogg,CC0-1.0,Kenney (Impact Sounds),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
 audio/sfx/buildings/build_complete_prod.ogg,https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactMetal_heavy_002.ogg,CC0-1.0,Kenney (Impact Sounds),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
-audio/sfx/buildings/generic_complete.ogg,https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactPlate_medium_003.ogg,CC0-1.0,Kenney (Impact Sounds),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
-audio/sfx/generic/complete.ogg,https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactPlate_medium_004.ogg,CC0-1.0,Kenney (Impact Sounds),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
 audio/sfx/units/support/attack.ogg,https://github.com/Calinou/kenney-interface-sounds/blob/master/addons/kenney_interface_sounds/pluck_002.wav,CC0-1.0,Kenney (Calinou repackage),loudnorm I=-16/TP=-3+wav→ogg 128kbps,2026-04-29
 audio/sfx/combat/unit_killed.ogg,https://kenney.nl/media/pages/assets/impact-sounds/8aa7b545c9-1677589768/kenney_impact-sounds.zip#Audio/impactPlate_light_002.ogg,CC0-1.0,Kenney (Impact Sounds),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
 audio/sfx/weather/blizzard.ogg,https://opengameart.org/sites/default/files/sfx_loops.zip#weird_01.ogg,CC0-1.0,rubberduck (OpenGameArt),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
@@ -134,4 +128,10 @@ audio/sfx/fauna/herbivore_attack.ogg,https://opengameart.org/sites/default/files
 audio/music/defeat_culture.ogg,https://opengameart.org/sites/default/files/JRPG%20Music%20Pack%20%234%20%5BCalm%5D%20by%20Juhani%20Junkala_0.zip#Calm3 - Peaceful Days.ogg,CC0-1.0,Juhani Junkala (SubspaceAudio, OpenGameArt),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
 audio/music/defeat_science.ogg,https://opengameart.org/sites/default/files/JRPG%20Music%20Pack%20%231%20%5BExploration%5D%20by%20Juhani%20Junkala.zip#Exploration5 - Sneaking Around.ogg,CC0-1.0,Juhani Junkala (SubspaceAudio, OpenGameArt),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
 audio/music/defeat_economic.ogg,https://opengameart.org/sites/default/files/JRPG%20Music%20Pack%20%234%20%5BCalm%5D%20by%20Juhani%20Junkala_0.zip#Calm4 - Sand Castles.ogg,CC0-1.0,Juhani Junkala (SubspaceAudio, OpenGameArt),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
-audio/music/defeat_domination.ogg,https://opengameart.org/sites/default/files/JRPG%20Music%20Pack%20%231%20%5BExploration%5D%20by%20Juhani%20Junkala.zip#Exploration2 - Military Base.ogg,CC0-1.0,Juhani Junkala (SubspaceAudio, OpenGameArt),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
+audio/music/defeat_domination.ogg,https://opengameart.org/sites/default/files/JRPG%20Music%20Pack%20%231%20%5BExploration%5D%20by%20Juhani%20Junkala.zip#Exploration2 - Military Base.ogg,CC0-1.0,Juhani Junkala (SubspaceAudio, OpenGameArt),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-29
+audio/sfx/buildings/economy_complete.ogg,https://kenney.nl/media/pages/assets/music-jingles/4f5dd770b7-1677590399/kenney_music-jingles.zip#Audio/Pizzicato jingles/jingles_PIZZI04.ogg,CC0-1.0,Kenney (Music Jingles),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-30
+audio/sfx/buildings/food_complete.ogg,https://kenney.nl/media/pages/assets/music-jingles/4f5dd770b7-1677590399/kenney_music-jingles.zip#Audio/Pizzicato jingles/jingles_PIZZI05.ogg,CC0-1.0,Kenney (Music Jingles),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-30
+audio/sfx/buildings/naval_complete.ogg,https://kenney.nl/media/pages/assets/music-jingles/4f5dd770b7-1677590399/kenney_music-jingles.zip#Audio/Pizzicato jingles/jingles_PIZZI06.ogg,CC0-1.0,Kenney (Music Jingles),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-30
+audio/sfx/buildings/resource_complete.ogg,https://kenney.nl/media/pages/assets/music-jingles/4f5dd770b7-1677590399/kenney_music-jingles.zip#Audio/Pizzicato jingles/jingles_PIZZI08.ogg,CC0-1.0,Kenney (Music Jingles),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-30
+audio/sfx/units/siege/spawn.ogg,https://kenney.nl/media/pages/assets/music-jingles/4f5dd770b7-1677590399/kenney_music-jingles.zip#Audio/Hit jingles/jingles_HIT08.ogg,CC0-1.0,Kenney (Music Jingles),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-30
+audio/sfx/units/support/spawn.ogg,https://kenney.nl/media/pages/assets/music-jingles/4f5dd770b7-1677590399/kenney_music-jingles.zip#Audio/Pizzicato jingles/jingles_PIZZI09.ogg,CC0-1.0,Kenney (Music Jingles),loudnorm I=-16/TP=-3+ogg 128kbps,2026-04-30
diff --git a/src/game/engine/src/autoloads/audio_manager.gd b/src/game/engine/src/autoloads/audio_manager.gd
index 17bf1269..ff0bd71d 100644
--- a/src/game/engine/src/autoloads/audio_manager.gd
+++ b/src/game/engine/src/autoloads/audio_manager.gd
@@ -317,6 +317,12 @@ func _play_stream(stream: AudioStream, entry: Dictionary) -> void:
 ## `kind` is `unit` / `building` / `fauna` based on which DataLoader
 ## category the id resolves into.
 func _resolve_keys(entity_id: String, event_kind: String) -> Array[String]:
+	# Two-level chain: bespoke per-entity key, then categorical
+	# `<kind>.<sub>.<event_kind>`. The kind-only and bare fallbacks
+	# (`<kind>.<event_kind>`, `<event_kind>`) were removed: they were
+	# unreachable once every concrete category had a manifest entry,
+	# and keeping them invited silent-fallback drift instead of
+	# fail-loud authoring discipline.
 	var keys: Array[String] = []
 	keys.append("%s.%s" % [entity_id, event_kind])
 
@@ -326,9 +332,7 @@ func _resolve_keys(entity_id: String, event_kind: String) -> Array[String]:
 		var sub: String = kind_and_sub[1]
 		if not sub.is_empty():
 			keys.append("%s.%s.%s" % [kind, sub, event_kind])
-		keys.append("%s.%s" % [kind, event_kind])
 
-	keys.append(event_kind)
 	return keys
 
 
diff --git a/src/game/engine/tests/unit/test_audio_manager.gd b/src/game/engine/tests/unit/test_audio_manager.gd
index 90c7b08a..ee23dcf4 100644
--- a/src/game/engine/tests/unit/test_audio_manager.gd
+++ b/src/game/engine/tests/unit/test_audio_manager.gd
@@ -168,20 +168,17 @@ func test_missing_key_emits_audio_asset_missing_signal() -> void:
 
 
 func test_play_for_entity_resolves_categorical_chain() -> void:
-	# Pass an unknown entity id with a known event_kind; resolution should
-	# reach the generic event-kind fallback without throwing. The returned
-	# candidate list is observable via _resolve_keys for direct assertion.
+	# Two-level chain after the bare-fallback removal: bespoke per-entity
+	# key, then `<kind>.<sub>.<event_kind>` if DataLoader knows the entity.
+	# Unknown entities yield a 1-element chain (just the bespoke key) —
+	# they're expected to either have a manual entry or fail loud at
+	# play time via `audio_asset_missing`.
 	var keys: Array[String] = AudioManager._resolve_keys("paladin", "attack")
 	assert_eq(
 		keys[0],
 		"paladin.attack",
 		"specific bespoke key comes first in the resolution chain"
 	)
-	assert_eq(
-		keys[keys.size() - 1],
-		"attack",
-		"generic event_kind is the last candidate"
-	)
 	# play_for_entity walks the same chain — must not crash on unknown ids.
 	AudioManager.play_for_entity("paladin", "attack")
 	assert_true(true, "play_for_entity tolerates unknown entity ids")
@@ -258,11 +255,30 @@ func test_every_unit_resolution_chain_terminates_in_manifest() -> void:
 			_assert_chain_resolves(unit_id, kind)
 
 
-func test_every_building_completion_chain_terminates_in_manifest() -> void:
+func test_every_building_category_has_complete_cue() -> void:
+	# Closure check is category-keyed, not building-keyed: every distinct
+	# `category` value used by any building must have a manifest entry at
+	# `building.<category>.complete`. Per-building bespoke entries are
+	# optional. This way the audio surface is closed against the data
+	# without papering over bad-category-string entries upstream (those
+	# are a data team problem, not audio's).
 	var bldgs: Dictionary = DataLoader.get_data("buildings") as Dictionary
 	assert_gt(bldgs.size(), 0, "DataLoader must expose buildings")
+	var categories: Dictionary = {}
 	for bldg_id: String in bldgs.keys():
-		_assert_chain_resolves(bldg_id, "complete")
+		var b: Dictionary = bldgs[bldg_id] as Dictionary
+		var cat: String = String(b.get("category", "")).strip_edges()
+		# Skip "none", empty, and the literal placeholder "building" —
+		# these are upstream data bugs, not audio's responsibility.
+		if cat.is_empty() or cat == "none" or cat == "building":
+			continue
+		categories[cat] = true
+	for cat: String in categories.keys():
+		var key: String = "building.%s.complete" % cat
+		assert_true(
+			AudioManager._sfx_events.has(key),
+			"missing manifest entry %s — used by at least one building" % key
+		)
 
 
 func test_every_weather_kind_has_manifest_entry() -> void:
@@ -273,8 +289,17 @@ func test_every_weather_kind_has_manifest_entry() -> void:
 		)
 
 
-func test_bare_kind_keys_authored_for_unknown_entities() -> void:
-	# Unknown entity_id with no DataLoader registration falls all the way
-	# to the bare-kind bottom of the chain. These four keys must be authored.
-	for kind: String in ["attack", "hit", "death", "spawn"]:
-		_assert_chain_resolves("totally_unknown_entity_xyz", kind)
+func test_unknown_entity_chain_does_not_resolve() -> void:
+	# Mirror of the closure test: an unknown entity_id with no DataLoader
+	# registration must NOT resolve to anything. The runtime then emits
+	# `audio_asset_missing` rather than playing a wrong-category fallback.
+	# Catches accidental re-introduction of bare-kind catch-alls.
+	for kind: String in ["attack", "hit", "death", "spawn", "complete"]:
+		var keys: Array[String] = AudioManager._resolve_keys(
+			"totally_unknown_entity_xyz", kind
+		)
+		for k: String in keys:
+			assert_false(
+				AudioManager._sfx_events.has(k),
+				"resolver leaked a fallback for unknown entity: %s" % k
+			)