diff --git a/client/scripts/protocol/protocol.gd b/client/scripts/protocol/protocol.gd index e0fddaebe..2e3a2ee6c 100644 --- a/client/scripts/protocol/protocol.gd +++ b/client/scripts/protocol/protocol.gd @@ -774,11 +774,12 @@ static func decode_atlas_layer_response(bytes: PackedByteArray) -> Variant: ## road_graph/settlements (T-960): passthrough fields for the L2 road/rail ## graph and L3 settlement placements, mirroring the district_grid precedent ## (T-1046) — raw decoded maps/arrays, no further client-side reshaping. -## Key names "road_graph"/"settlements" are the CONFIRMED wire contract — -## identical to server/src/atlas/layer_proxy.rs AtlasLayerResponse's field -## names (pinned 2026-07-14; round-tripped by test_atlas_overlays.gd and the -## server's msgpack round-trip tests). This remains the one client-side spot -## to touch if the contract ever changes. +## region_grid (T-1113): the region climate grid, same passthrough pattern. +## Key names "road_graph"/"settlements"/"region_grid" are the CONFIRMED wire +## contract — identical to server/src/atlas/layer_proxy.rs AtlasLayerResponse's +## field names (pinned 2026-07-14; round-tripped by test_atlas_overlays.gd and +## the server's msgpack round-trip tests). This remains the one client-side +## spot to touch if the contract ever changes. static func atlas_response_from_raw(raw: Variant) -> Variant: if not raw is Dictionary or not raw.has("status"): return null @@ -798,6 +799,7 @@ static func atlas_response_from_raw(raw: Variant) -> Variant: "district_grid": raw.get("district_grid"), "road_graph": raw.get("road_graph"), "settlements": raw.get("settlements"), + "region_grid": raw.get("region_grid"), } diff --git a/client/tests/fixtures/msgpack/atlas_response_not_found.msgpack b/client/tests/fixtures/msgpack/atlas_response_not_found.msgpack index ac84932a1..b45ad1b02 100644 --- a/client/tests/fixtures/msgpack/atlas_response_not_found.msgpack +++ b/client/tests/fixtures/msgpack/atlas_response_not_found.msgpack @@ -1 +1 @@ -†§body_id¥ghost¦status¨NotFound¦layer1À­district_gridÀªroad_graphÀ«settlementsÀ \ No newline at end of file +‡§body_id¥ghost¦status¨NotFound¦layer1À­district_gridÀªroad_graphÀ«settlementsÀ«region_gridÀ \ No newline at end of file diff --git a/client/tests/fixtures/msgpack/atlas_response_pending.msgpack b/client/tests/fixtures/msgpack/atlas_response_pending.msgpack index 97399184a..2ad9d65e5 100644 --- a/client/tests/fixtures/msgpack/atlas_response_pending.msgpack +++ b/client/tests/fixtures/msgpack/atlas_response_pending.msgpack @@ -1 +1 @@ -†§body_id¤GJ1c¦status§Pending¦layer1À­district_gridÀªroad_graphÀ«settlementsÀ \ No newline at end of file +‡§body_id¤GJ1c¦status§Pending¦layer1À­district_gridÀªroad_graphÀ«settlementsÀ«region_gridÀ \ No newline at end of file diff --git a/client/tests/fixtures/msgpack/atlas_response_ready.msgpack b/client/tests/fixtures/msgpack/atlas_response_ready.msgpack index ec4101d91..14c10caed 100644 Binary files a/client/tests/fixtures/msgpack/atlas_response_ready.msgpack and b/client/tests/fixtures/msgpack/atlas_response_ready.msgpack differ diff --git a/client/tests/test_input_roundtrip.gd b/client/tests/test_input_roundtrip.gd index 71c8136cd..3354a910d 100644 --- a/client/tests/test_input_roundtrip.gd +++ b/client/tests/test_input_roundtrip.gd @@ -26,17 +26,13 @@ static func _random_test_port() -> int: func _spawn_server(server_path: String) -> bool: - for attempt in range(MAX_PORT_ATTEMPTS): - _test_port = _random_test_port() - var addr := "127.0.0.1:%d" % _test_port - _server_pid = OS.create_process(server_path, [addr]) - if _server_pid <= 0: - continue - await get_tree().create_timer(0.15).timeout - if OS.is_process_running(_server_pid): - return true + _test_port = _random_test_port() + var addr := "127.0.0.1:%d" % _test_port + _server_pid = OS.create_process(server_path, [addr]) + if _server_pid <= 0: _server_pid = -1 - return false + return false + return true func after_test() -> void: @@ -51,37 +47,48 @@ func after_test() -> void: ## Spawn the server, connect, and complete the protocol handshake. ## Binary absence is handled by per-test `_do_skip` — by the time this runs the ## binary exists, so any failure here is a real failure (asserted loudly). +## The server binds its port AFTER plugin/simulation init (~250ms), so a +## random-port collision surfaces as a mid-connect process death, not an +## instant spawn failure — a death during the connect window therefore +## retries on a fresh port instead of failing the test (the push gate hit +## exactly that race: "Failed to bind ... Address already in use"). func _connect_to_server() -> bool: var server_path := _server_binary_path() - var spawned := await _spawn_server(server_path) - assert_bool(spawned).override_failure_message( - "server spawn failed after %d port attempts" % MAX_PORT_ATTEMPTS - ).is_true() - if not spawned: - return false - - _bridge = LocalBridge.new() var connected := false - var elapsed := 0.0 - while elapsed < CONNECT_TIMEOUT: - if _server_pid > 0 and not OS.is_process_running(_server_pid): - push_warning("Server process died during connection") + for _attempt in range(MAX_PORT_ATTEMPTS): + if not _spawn_server(server_path): + continue + _bridge = LocalBridge.new() + var elapsed := 0.0 + while elapsed < CONNECT_TIMEOUT: + if not OS.is_process_running(_server_pid): + push_warning( + "Server died pre-connect (port %d likely in use) — retrying" % _test_port + ) + break + if _bridge.get_status() == StreamPeerTCP.STATUS_NONE: + _bridge.connect_to_server("127.0.0.1", _test_port) + _bridge.poll() + if _bridge.get_status() == StreamPeerTCP.STATUS_CONNECTED: + connected = true + break + if _bridge.get_status() == StreamPeerTCP.STATUS_ERROR: + _bridge.disconnect_from_server() + _bridge.reset() + await get_tree().create_timer(0.1).timeout + elapsed += 0.1 + if connected: break - if _bridge.get_status() == StreamPeerTCP.STATUS_NONE: - _bridge.connect_to_server("127.0.0.1", _test_port) - _bridge.poll() - if _bridge.get_status() == StreamPeerTCP.STATUS_CONNECTED: - connected = true - break - if _bridge.get_status() == StreamPeerTCP.STATUS_ERROR: - _bridge.disconnect_from_server() - _bridge.reset() - await get_tree().create_timer(0.1).timeout - elapsed += 0.1 + _bridge.disconnect_from_server() + _bridge = null + if _server_pid > 0 and OS.is_process_running(_server_pid): + OS.kill(_server_pid) + _server_pid = -1 assert_bool(connected).override_failure_message( - "TCP connect to spawned server failed within %.1fs" % CONNECT_TIMEOUT + "TCP connect to spawned server failed within %.1fs across %d port attempts" + % [CONNECT_TIMEOUT, MAX_PORT_ATTEMPTS] ).is_true() if not connected: return false diff --git a/governance/decisions/architecture.md b/governance/decisions/architecture.md index 8447b546e..6af6617a0 100644 --- a/governance/decisions/architecture.md +++ b/governance/decisions/architecture.md @@ -1560,11 +1560,48 @@ Technical foundation decisions that constrain implementation: engine, client-ser - **(c) Legend panel stands.** The left-side legend (shape/color key for attractor types and sub-biomes) remains an unshipped, in-scope deliverable of item (3)/T-960. - **(d) No tile-level Atlas map.** The planetary Atlas maps generation layers down to settlement/quarter-skeleton granularity only; chunk/tile/voxel fill (L5) is verified by the believability/derivation harnesses and inspected **in-world in Phase 5** — never as a planetary map layer (at most aggregate stats). Ratifies T-1046's implementation precedent; matching D-191 amendment + CLAUDE.md Phase-4 wording updated the same day. + **Amended 2026-07-16 (T-1112 — coarse quarter-footprint Atlas layer, the L4 skeleton on the planetary map):** the fourth generation-cascade layer to land on the Atlas, sitting between T-1046's `district_grid` (D-239 coarse morphology) and item (d)'s hard ceiling. Design only — implementation is a follow-up ticket (touch points named in §4 below, none built here). + + - **(1) `QuarterFootprintLayer` data shape.** Source of truth is `BodyWorldState.quarters: BTreeMap` (`QuarterWorldState { skeleton: QuarterSkeleton, block_tags }`), where `QuarterSkeleton.blocks: [[BlockSkeleton; 4]; 4]` carries `zoning: ZoningType`, `district_type: DistrictType`, `density_pct: u8`, `landmark: Option` per block, plus `corridors: Vec` at the quarter level. Critically, **`QuarterWorldState` carries no independent spatial position** — `QuarterId` is a content-addressable hash (`SeedChain::for_body(world_seed, body_id).derive(SeedDomain::Layer4Quarter, city_id).seed()`, `plugin.rs::build_skeleton_work_item`), not a coordinate. The only spatial anchor a quarter has is the `city_id` it was generated for — which `SettlementLayer`/`CityPlacement` (T-960 §2, D-211) already carries as `(city_id, position)`. So the layer is **keyed by `city_id`, joined to a quarter by recomputing the same deterministic `quarter_id` derivation** the dispatch path already uses (a pure function of already-public inputs — no new field needed anywhere) and looking it up in `state.quarters`. This also means **no city-outline geometry is derived or served** — at planetary-map projection a 512 m quarter is roughly 1/80th of a heightmap pixel (a district ≈ 2048 m is already sub-pixel at ~40–78 km/px, D-243), so there is no real silhouette to trace; the layer is aggregate stats anchored at the existing L3 settlement position, mirroring `RoadGraphLayer`/`SettlementLayer`'s established "trim the internal struct to what an overlay needs" pattern rather than inventing outline geometry with no data behind it. + + Per settlement-with-quarters, the served aggregate is: + ```rust + pub struct QuarterFootprintEntry { + pub city_id: u64, + pub density_avg_pct: u8, // basis-point mean of BlockSkeleton.density_pct, 16 blocks + pub dominant_district_type: DistrictType, // mode across 16 blocks; ties → lowest declaration-order variant + pub dominant_zoning: ZoningType, // mode across 16 blocks; same tie rule + pub landmark_count: u8, // count of Some(LandmarkSlot) across 16 blocks (max 16) + pub corridor_count: u8, // QuarterSkeleton.corridors.len(), clamped to u8 + } + pub struct QuarterFootprintLayer { + pub entries: BTreeMap, // keyed by city_id, D-010 determinism + } + ``` + Five fields earn their place: `density_avg_pct` and the two dominant-mode fields are Araminta's color/shape encoding inputs (§3); `landmark_count`/`corridor_count` are inspection-only (the D-226(d) ceiling forbids them as a map-visible channel — they surface in the existing city-click sidebar instead, an `ImplantDataRow` addition, not a new draw call). Rejected from the set: per-block detail (violates the ceiling outright), `reservations`/`social_sites` counts (no consumer identified — Araminta's encoding doesn't need them and nothing else asked), and a float density (D-010 integer discipline — `density_pct` is already `u8` basis-point-flavored on the source struct, so the mean stays `u8`, no `f32` anywhere on the wire). `dominant_district_type`/`dominant_zoning` serialize as their named enum variant (serde default), following the `RoadGraphLayer`/`SettlementLayer` precedent (`RoadNodeKind`, `MaintenanceAuthority` — neither `repr(u8)`-pinned, serialized as names) rather than `district_grid`'s `as u8` byte-packing, which was specific to a dense `cols×rows` array where `MorphologyZone` is deliberately `repr(u8)`-pinned for that purpose; a handful of per-settlement aggregate fields have no such packing need. `BTreeMap` throughout for D-010 determinism, matching `block_tags`' own `BTreeMap<(u8,u8), _>` precedent on the source struct. + + - **(2) Hard ceiling (binding).** This layer is the concrete instance of item (d)'s "at most aggregate stats" clause: five scalar fields per settlement, quantized `u8`, no per-block zoning/street/tag detail ever reaches the wire, and no chunk/tile/voxel data is touched (this layer reads only `QuarterSkeleton`/`BlockSkeleton`, never `FillChunk` output — a different generation phase entirely, D-230). If a future ticket wants finer planetary-scale detail than this, the answer is "no" per item (d), not "extend this struct" — the settlement/quarter-skeleton granularity ceiling applies to this layer by construction, not by restraint that could erode. + + - **(3) Overlay encoding (Araminta).** New overlay id `gen_l4_quarters` (label `QTR`, `group: "toggle"`, matching the `gen_*` convention in `OVERLAY_DEFS`). **No outline is drawn** (per §1) — the layer is a **density-scaled glyph anchored at the existing L3 settlement position**, drawn in the same pass immediately after `_draw_gen_settlements` so it reads as "on top of" the city dot it annotates. Square side scales off `density_avg_pct` (e.g. `4.0 + density_avg * 6.0` px at 1.0 zoom, clamped `[4.0, 12.0]`) — dense build reads as a bigger block, sparse as smaller, without pretending to show real shape. **Shape carries identity, color carries intensity** (the same convention as `_sub_biome_color`/`MORPHOLOGY_COLORS`): shape = `dominant_district_type`, a small corner-notch glyph family on the filled square (plain = mixed/no clear dominant, corner tab top-right = commercial, corner tab bottom-right = industrial, small diamond cutout center = civic/landmark — capped at 3–4 variants, a coarse skeleton read, not a legend of every `DistrictType`); color = `density_avg_pct` on a single-hue intensity ramp within the existing settlement-gold family (`COLOR_SETTLEMENT` → `COLOR_SETTLEMENT_CAPITAL`-adjacent bright gold at high density), so the new layer reads as *part of* the settlement-marker family rather than a competing hue, since it always co-renders beside `gen_l3_settlements`. `landmark_count`/`corridor_count` are **not** a visual channel (§2's ceiling) — they surface as `ImplantDataRow`s in the existing city-click sidebar panel. Zoom gating reuses `SETTLEMENT_LABEL_MIN_ZOOM = 2.0` (no new threshold): below it, glyph draws at minimum size with color only (the notch is illegible at a few px anyway); at/above it, full size with the dominant-type notch visible. Legend entry (`GENERATION_LEGEND`): + ```gdscript + { + "overlay_id": "gen_l4_quarters", + "title": "QUARTER FOOTPRINT — L4 (color = density, shape = dominant type)", + "rows": [ + {"glyph": "â–ª", "color": Color(0.55, 0.48, 0.30, 0.6), "label": "low density"}, + {"glyph": "â–ª", "color": Color(0.94, 0.82, 0.38, 1.0), "label": "high density"}, + {"glyph": "â—ª", "color": Color.TRANSPARENT, "label": "dominant type (corner tab)"}, + ], + } + ``` + + - **(4) Six wiring touch points (follow-up ticket, not built here).** `AtlasLayerResponse` gains `quarter_footprints: Option` + a `build_quarter_footprint_layer(state, placements)` function mirroring `build_district_grid`'s "empty source → `None`" contract (`server/src/atlas/layer_proxy.rs`); `ZoningType` gains `PartialOrd, Ord` derives mirroring `DistrictType`'s T-994 precedent (`server/src/simulation/generator.rs` — declaration order is not a stability-pinned wire format on either enum, so the additive derive is safe), which is what makes §1's lowest-declaration-order tie-break computable for `dominant_zoning` (PR #179 review: `DistrictType` already carries the derives, `ZoningType` does not — the tie rule itself is unchanged); `protocol.gd` passthrough for the new field (mirrors the existing `district_grid`/`road_graph`/`settlements` fields); a `gen_l4_quarters` entry in `OVERLAY_DEFS` (`client/ui/implant/apps/atlas/atlas_viewer.gd`); a `_draw_gen_l4_quarters()` function imitating `_draw_gen_district`'s "read `viewer.get_generation_quarter_footprints()`, guard on `Dictionary`, draw" shape (`atlas_marker_overlay.gd`); and the `GENERATION_LEGEND` entry above (`atlas_legend_panel.gd`). `layer_proxy.rs` was mid-concurrent-edit for T-1113's `region_grid` addition at design time — read-only pass, no conflict expected (both land as new sibling `Option` fields on `AtlasLayerResponse`, following the same one-field-per-layer pattern the growth-ceiling note on that struct already anticipates naming T-1112 and T-1113 as the last two candidates). + - **Rationale:** Reusing the real UI — rather than a parallel offline renderer or dumped files — means the debug/review surface never diverges from what ships, and a dropped artifact can't go stale. Agent-navigability converts qualitative "does the synthesis look natural?" review from a manual eyeball pass into an automatable sweep that flags the few outliers for a human. The harness rides seams that already exist (`TickRate::Paused`, the paused-allowlist, `gameplay_occluded`, the bridge framing, the `run-visual` capture primitive) — a naming-and-contract exercise, not a new subsystem. - **New surface:** server pause-gating (run-conditions on the world phases keyed to a pause command); client `AtlasAgentInterface` (`observe`/`act`, Control-tree walker) + its local transport; the generation overlay rendering + selector + legend; interactive capture wired to `run-visual`. - **Implementation:** Phase 4 (epic T-750), built bottom-up — auto-pause substrate, T-969 proxy (D-225), T-960 viewer, agent channel, agent capture. Geography is the first consumer. - **Raised by:** Jeroen + Claude (design), with Tyre (channel/pause/headless architecture) + Araminta (overlay encoding + affordance UX), 2026-05-24. -- **Cross-reference:** [D-225](#d-225) (layer-stream proxy — the data path), [D-166](#d-166) (per-layer Atlas progress viewer), [D-191](#d-191) (Atlas viewer), [D-169](#d-169) / [D-170](#d-170) (implant components / HUD occlusion — `gameplay_occluded` trigger), [D-200](#d-200) / [D-203](#d-203) (execution tiers / LRU cache), Q-099 (mod content catalog), `tests/run-visual` (capture primitive), `save_state.rs` (save-inspection consumer) +- **Cross-reference:** [D-225](#d-225) (layer-stream proxy — the data path), [D-166](#d-166) (per-layer Atlas progress viewer), [D-191](#d-191) (Atlas viewer), [D-169](#d-169) / [D-170](#d-170) (implant components / HUD occlusion — `gameplay_occluded` trigger), [D-200](#d-200) / [D-203](#d-203) (execution tiers / LRU cache), Q-099 (mod content catalog), `tests/run-visual` (capture primitive), `save_state.rs` (save-inspection consumer). **T-1112 amendment additionally:** [D-222](#d-222) (Quarter terminology — the 512m unit this layer surfaces), [D-234](#d-234) (footprint geometry — the block-subdivision source the aggregates summarize), [D-243](#d-243) (quarter = 512m rung, and the containment ladder that makes a quarter sub-pixel at planetary projection — Araminta's no-outline rationale), [D-010](#d-010) (determinism — integer-only aggregates, `BTreeMap` keying). - **Dissent:** None --- diff --git a/server/src/atlas/believability.rs b/server/src/atlas/believability.rs index 866192318..2dbce82f9 100644 --- a/server/src/atlas/believability.rs +++ b/server/src/atlas/believability.rs @@ -497,7 +497,14 @@ pub fn seed_to_u64(seed: &str) -> u64 { } /// Resolve the committed inputs for `body_id` and run the real deterministic cascade -/// (through the road graph), returning the per-body world state to [`analyze`]. +/// (through the full production depth, `CascadeLayer::Region`), returning the +/// per-body world state to [`analyze`]. +/// +/// The terminal layer here MIRRORS production (`gen_queue.rs::run_work_item`) by +/// ruling (PR #179 F3): a shallower harness run would silently hand future +/// believability conditions (D-245's climate-appropriateness is the natural +/// consumer of `state.regions`) an empty layer that production populates. +/// When production's terminal advances, advance this one with it. /// /// `Err` if `systems.db` or the body's `heightmap.png` cannot be found, or the body /// has no params — callers (the regression harness) may *skip* on that rather than @@ -529,7 +536,7 @@ pub fn cascade_for_body(world_seed: u64, body_id: &str) -> Result, + /// Per-region (~205 km) climate context — season/weather/temperature + /// baseline cells (D-243 §3, T-1113). + /// + /// Populated by the background cascade's Region layer; the covering grid + /// only (no blend-padding ring — see `cascade::LayerRegionOutput`). + /// `BTreeMap` keyed by `RegionPos` for D-010 determinism. Empty until the + /// Region layer has run. Footprint is trivial (~195×98 cells at the D-243 + /// true-scale ceiling; a handful on today's working grids). + pub regions: BTreeMap, /// Last sim tick this entry was read. Used for LRU eviction. pub last_accessed: SimTick, } @@ -224,6 +235,7 @@ mod tests { road_graph: RoadGraph::default(), quarters: BTreeMap::new(), districts: BTreeMap::new(), + regions: BTreeMap::new(), last_accessed: tick, } } diff --git a/server/src/atlas/cascade.rs b/server/src/atlas/cascade.rs index 33aedccca..6ff67192f 100644 --- a/server/src/atlas/cascade.rs +++ b/server/src/atlas/cascade.rs @@ -28,8 +28,9 @@ use crate::atlas::district_profile::{self, BodyParams, DistrictPos, DistrictProf use crate::atlas::features::TerrainAnalysis; use crate::atlas::heightmap::{self, BodyHeightmap, HeightmapLoadError}; use crate::atlas::layer1::{self, Layer1Output}; +use crate::atlas::region_profile::{self, RegionProfile}; use crate::atlas::road_graph::{self, RoadGraph}; -use crate::atlas::scale; +use crate::atlas::scale::{self, RegionPos}; use crate::seed::SeedChain; use crate::simulation::generator::{CompatibilityMatrix, GeographicAttractor, TerritorialStatus}; @@ -57,6 +58,16 @@ pub enum CascadeLayer { /// last** to honour the append-only `Ord` rule (it neither needs nor blocks /// the DistrictProfile layer; requesting it runs DistrictProfile first, harmlessly). RoadGraph, + /// Region climate layer (~205 km cells, D-243 §3, T-1113). Pure function of + /// `(seed, body_params, heightmap dims)` — the region baselines the district + /// layer already derives internally (and discards) are RETAINED here as + /// their own layer output for the Atlas. Semantically the climate context + /// *above* districts, but **appended last** per the append-only `Ord` rule + /// (the RoadGraph precedent): it depends on no other layer, so requesting + /// it runs the earlier layers first, harmlessly. The cheap double-derive + /// (district blend cache + this layer) is deliberate — one layer, one + /// concern, no cache plumbing between layers. + Region, } /// Output of the cascade for one body, up to the requested layer (#952). @@ -81,6 +92,9 @@ pub struct CascadeSnapshot { /// Layer 2 — inter-settlement road/rail graph. `Some` once /// [`CascadeLayer::RoadGraph`] has run (D-211, T-1038). pub road_graph: Option, + /// Region climate layer — ~205 km climate-context cells. `Some` once + /// [`CascadeLayer::Region`] has run (D-243 §3, T-1113). + pub layer_region: Option, /// **Transient** — the `TerrainAnalysis` produced by the Layer-1 drainage /// pass (T-1044). Populated when Layer 1 runs; consumed (and freed) once /// both `DistrictProfile` and `RoadGraph` have consumed it. @@ -98,6 +112,19 @@ pub struct LayerDistrictOutput { pub districts: std::collections::BTreeMap, } +/// Region climate layer output (T-1113, D-243 §3): per-region (~205 km) climate +/// context covering the body's district grid. Stored in `BodyWorldState.regions`. +/// +/// The set is the **covering grid only** — the regions whose districts tile the +/// body, with no ±1 neighbour padding. (The district layer's internal region +/// cache pads a neighbour ring because its edge-fuzz blend samples across +/// boundaries; that padding is a blend implementation detail, not part of the +/// body's own region grid, and a dense Atlas wire encoding wants exact dims.) +#[derive(Debug, Clone, Default)] +pub struct LayerRegionOutput { + pub regions: std::collections::BTreeMap, +} + /// Layer 3 output (#955, D-211): attractor-matched settlement placements for the /// body. Re-derivable from (Layer-1 attractors + settlement records + seed). #[derive(Debug, Clone, Default)] @@ -123,6 +150,7 @@ impl CascadeSnapshot { .layer_district .map(|lr| lr.districts) .unwrap_or_default(); + let regions = self.layer_region.map(|lr| lr.regions).unwrap_or_default(); let road_graph = self.road_graph.unwrap_or_default(); // terrain_analysis (transient) is intentionally dropped here. let _ = self.terrain_analysis; @@ -138,6 +166,7 @@ impl CascadeSnapshot { road_graph, quarters: std::collections::BTreeMap::new(), districts, + regions, last_accessed: 0, } } @@ -203,6 +232,7 @@ pub fn run_cascade_from_heightmap( layer3: None, layer_district: None, road_graph: None, + layer_region: None, terrain_analysis: None, }; @@ -330,6 +360,42 @@ pub fn run_cascade_from_heightmap( snapshot.terrain_analysis = None; } + // Region climate layer (D-243 §3, T-1113) — the ~205 km climate-context + // cells the district blend already derives internally, retained as their + // own layer output. Pure function of (seed, body_params, heightmap dims): + // no TerrainAnalysis needed, so it runs outside the transient-borrow block + // above. Gates on body_params like the DistrictProfile layer (no params → + // no climate inputs → the layer skips, `regions` stays empty). + if up_to >= CascadeLayer::Region { + if let Some(params) = body_params { + // The covering region grid: the same district dims the district + // layer computes (heightmap dims ÷ cells-per-district), mapped up + // to region cells — WITHOUT the ±1 neighbour padding the district + // blend cache adds (see LayerRegionOutput's doc). + let gcpr = scale::HEIGHTMAP_CELLS_PER_DISTRICT.max(1); + let district_cols = (snapshot.heightmap.width as usize).div_ceil(gcpr) as i32; + let district_rows = (snapshot.heightmap.height as usize).div_ceil(gcpr) as i32; + let max_region = scale::district_to_region(( + district_cols.saturating_sub(1), + district_rows.saturating_sub(1), + )); + let mut region_positions: Vec = Vec::new(); + for ry in 0..=max_region.1 { + for rx in 0..=max_region.0 { + region_positions.push((rx, ry)); + } + } + let climate = district_profile::ClimateConstants::default(); + let regions = region_profile::derive_regions_for_body( + body_seed, + params, + &climate, + region_positions, + ); + snapshot.layer_region = Some(LayerRegionOutput { regions }); + } + } + snapshot } @@ -461,6 +527,7 @@ mod tests { assert!(CascadeLayer::Topography < CascadeLayer::Settlement); assert!(CascadeLayer::Settlement < CascadeLayer::DistrictProfile); assert!(CascadeLayer::DistrictProfile < CascadeLayer::RoadGraph); + assert!(CascadeLayer::RoadGraph < CascadeLayer::Region); } #[test] @@ -794,4 +861,83 @@ mod tests { // Silence unused-import warning when the filter above changes. let _ = RoadNodeKind::Settlement; } + + /// Region climate layer (T-1113, D-243 §3): runs as the cascade terminal, + /// populates `BodyWorldState.regions` with the covering region grid, gates + /// on body_params like the DistrictProfile layer, and is deterministic. + #[test] + fn region_layer_populates_regions_deterministically() { + use crate::atlas::district_profile::BodyParams; + + let params = BodyParams { + hydrosphere: Some("ocean".into()), + atmosphere: Some("breathable".into()), + planet_class: Some("temperate".into()), + ..Default::default() + }; + let run = || { + run_cascade_from_heightmap( + body_seed(), + test_heightmap(), + &[], + None, + Some(¶ms), + CascadeLayer::Region, + ) + }; + let snap = run(); + let lr = snap.layer_region.as_ref().expect("Region layer ran"); + // 64×32 working grid → 8×4 districts → a single covering region at + // (0,0) (100 districts per region side — the working grid is far + // inside one region cell today; the D-243 elastic seam grows this). + assert_eq!(lr.regions.len(), 1, "one covering region on the test grid"); + let profile = lr.regions.get(&(0, 0)).expect("region (0,0) present"); + assert!( + profile.clock.mean_temp_c.is_some(), + "breathable temperate body derives a temperature baseline" + ); + assert!((0..=100).contains(&profile.moisture_q)); + + // Determinism: identical inputs → bit-identical region output. + let key = |s: &CascadeSnapshot| { + s.layer_region + .as_ref() + .unwrap() + .regions + .iter() + .map(|(pos, p)| { + ( + *pos, + p.clock.season as u8, + p.clock.weather as u8, + p.clock.mean_temp_c.map(f32::to_bits), + p.moisture_q, + ) + }) + .collect::>() + }; + assert_eq!( + key(&snap), + key(&run()), + "region layer must be deterministic" + ); + + // The regions propagate into the hot-cache BodyWorldState. + let state = snap.into_body_world_state(); + assert_eq!(state.regions.len(), 1); + assert!(state.regions.contains_key(&(0, 0))); + + // No body params → the layer skips and regions stays empty (mirrors + // the DistrictProfile gate). + let no_params = run_cascade_from_heightmap( + body_seed(), + test_heightmap(), + &[], + None, + None, + CascadeLayer::Region, + ); + assert!(no_params.layer_region.is_none()); + assert!(no_params.into_body_world_state().regions.is_empty()); + } } diff --git a/server/src/atlas/gen_queue.rs b/server/src/atlas/gen_queue.rs index 15fda3c69..614a28b6f 100644 --- a/server/src/atlas/gen_queue.rs +++ b/server/src/atlas/gen_queue.rs @@ -407,13 +407,14 @@ fn run_work_item(item: &GenWorkItem) -> GenCompletion { } else { hm }; - // Run the full cascade through RoadGraph (Layer 2, T-1038), the - // terminal layer. It subsumes Settlement, DistrictProfile (T-1023), - // and all prior layers. DistrictProfile derivation still gates on - // body_params internally (skipped when absent — e.g. a body with no - // params row), but the road graph needs no body params, so it runs - // for every analyzed body. - let up_to = CascadeLayer::RoadGraph; + // Run the full cascade through Region (T-1113), the terminal + // layer. It subsumes RoadGraph (T-1038), Settlement, + // DistrictProfile (T-1023), and all prior layers. + // DistrictProfile and Region derivation both gate on + // body_params internally (skipped when absent — e.g. a body + // with no params row), but the road graph needs no body + // params, so it runs for every analyzed body. + let up_to = CascadeLayer::Region; let snapshot = run_cascade_from_heightmap( *body_seed, working, diff --git a/server/src/atlas/layer_proxy.rs b/server/src/atlas/layer_proxy.rs index 253221afd..011e89f2f 100644 --- a/server/src/atlas/layer_proxy.rs +++ b/server/src/atlas/layer_proxy.rs @@ -31,8 +31,8 @@ const DEFAULT_SEA_LEVEL: f32 = 0.3; /// A client request for a body's generation layers (D-225). /// /// `up_to` is a forward-compat seam that is **not yet honored**: `run_work_item` -/// (`gen_queue.rs`) currently runs the cascade through `CascadeLayer::RoadGraph` -/// (the terminal layer, T-1038) unconditionally on every request, ignoring this +/// (`gen_queue.rs`) currently runs the cascade through `CascadeLayer::Region` +/// (the terminal layer, T-1113) unconditionally on every request, ignoring this /// field. Wiring per-request depth (and the partial caching it implies) is /// deferred to #1021. #[derive(Debug, Clone, Serialize, Deserialize)] @@ -70,13 +70,13 @@ pub struct DistrictGridLayer { } /// A layer response: the computed `Layer1Output` + the coarse district grid -/// (D-225, T-1046) + the road-graph and settlement overlays (T-960 §1/§2), or -/// a non-ready status. +/// (D-225, T-1046) + the road-graph and settlement overlays (T-960 §1/§2) + +/// the region climate grid (T-1113), or a non-ready status. /// /// Growth ceiling (governance-bounded): the one-`Option`-field-per-layer /// pattern tops out around six fields — D-226's 2026-07-13 amendment (d) /// rules out any L5/tile Atlas layer ever, leaving T-1112 (quarter -/// footprints) and T-1113 (region climate) as the only remaining candidates. +/// footprints) as the only remaining candidate. #[derive(Debug, Clone, Serialize, Deserialize)] pub struct AtlasLayerResponse { pub body_id: String, @@ -94,6 +94,9 @@ pub struct AtlasLayerResponse { /// The settlement-placement overlay (T-960 §2, #955). `Some` on a cache hit /// once the Settlement layer has placed at least one city; `None` otherwise. pub settlements: Option, + /// The region climate grid for the Atlas overlay (D-243 §3, T-1113). + /// `Some` on a cache hit once the Region layer has run; `None` otherwise. + pub region_grid: Option, } /// Build the coarse [`DistrictGridLayer`] from a body's cached state (T-1046). @@ -129,6 +132,83 @@ pub fn build_district_grid( }) } +// --------------------------------------------------------------------------- +// RegionGridLayer (T-1113, D-243 §3) +// --------------------------------------------------------------------------- + +/// The ~205 km region climate grid for the Atlas overlay (T-1113), dense +/// row-major like [`DistrictGridLayer`] (the T-1046 encoding precedent). +/// Serves the **mean-state** `RegionClock` fields only — the Q-105 tick-phase +/// callbacks are deferred, so what ships is the static climate context. +/// +/// Wire encoding is all-integer (D-010 wire discipline): +/// - `season[i]` / `weather[i]` — the `repr(u8)` discriminants of +/// `SeasonPhase` / `WeatherState` (pinned, append-only). +/// - `mean_temp_dc[i]` — mean-annual temperature baseline in **deci-°C** +/// (×10, `round`ed; 0.1 °C is ample for a map overlay). `i16::MIN` is the +/// sentinel for "no atmosphere → no temperature" (airless bodies carry +/// `mean_temp_c: None`); real values are class-band-clamped far inside +/// i16 range. +/// - `moisture_q[i]` — the 0–100 region moisture primitive. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct RegionGridLayer { + pub cols: u32, + pub rows: u32, + pub season: Vec, + pub weather: Vec, + pub mean_temp_dc: Vec, + pub moisture_q: Vec, +} + +/// Sentinel for "airless body — no temperature baseline" in +/// [`RegionGridLayer::mean_temp_dc`]. +pub const REGION_TEMP_NONE_DC: i16 = i16::MIN; + +/// Build the [`RegionGridLayer`] from a body's cached state (T-1113). +/// Returns `None` when the Region layer has not run (empty `regions`). +/// The stored region set is the dense covering grid `[0, cols) × [0, rows)` +/// (see `cascade::LayerRegionOutput` — no blend-padding ring), so the extent +/// comes from the maximum `RegionPos`, mirroring [`build_district_grid`]. +pub fn build_region_grid( + state: &crate::atlas::body_world_state::BodyWorldState, +) -> Option { + if state.regions.is_empty() { + return None; + } + let cols = state.regions.keys().map(|(x, _)| *x).max().unwrap_or(0) as u32 + 1; + let rows = state.regions.keys().map(|(_, y)| *y).max().unwrap_or(0) as u32 + 1; + let n = (cols * rows) as usize; + let mut season = vec![0u8; n]; + let mut weather = vec![0u8; n]; + let mut mean_temp_dc = vec![REGION_TEMP_NONE_DC; n]; + let mut moisture_q = vec![0u8; n]; + for (&(x, y), profile) in &state.regions { + if x < 0 || y < 0 { + continue; + } + let i = (y as u32 * cols + x as u32) as usize; + if i < n { + season[i] = profile.clock.season as u8; + weather[i] = profile.clock.weather as u8; + mean_temp_dc[i] = match profile.clock.mean_temp_c { + Some(t) => { + ((t * 10.0).round() as i32).clamp(i16::MIN as i32 + 1, i16::MAX as i32) as i16 + } + None => REGION_TEMP_NONE_DC, + }; + moisture_q[i] = profile.moisture_q.clamp(0, 100) as u8; + } + } + Some(RegionGridLayer { + cols, + rows, + season, + weather, + mean_temp_dc, + moisture_q, + }) +} + // --------------------------------------------------------------------------- // RoadGraphLayer (T-960 §1, T-1038) // --------------------------------------------------------------------------- @@ -341,6 +421,7 @@ pub fn handle_atlas_request( let district_grid = build_district_grid(state); let road_graph = build_road_graph_layer(state); let settlements = build_settlement_layer(state); + let region_grid = build_region_grid(state); return AtlasLayerResponse { body_id: req.body_id.clone(), status: AtlasLayerStatus::Ready, @@ -348,6 +429,7 @@ pub fn handle_atlas_request( district_grid, road_graph, settlements, + region_grid, }; } @@ -420,6 +502,7 @@ pub fn handle_atlas_request( district_grid: None, road_graph: None, settlements: None, + region_grid: None, } } // Unknown / no terrain → re-requesting won't help. @@ -431,6 +514,7 @@ pub fn handle_atlas_request( district_grid: None, road_graph: None, settlements: None, + region_grid: None, }, Err(e) => AtlasLayerResponse { body_id: req.body_id.clone(), @@ -439,6 +523,7 @@ pub fn handle_atlas_request( district_grid: None, road_graph: None, settlements: None, + region_grid: None, }, } } @@ -487,6 +572,7 @@ mod tests { road_graph: crate::atlas::road_graph::RoadGraph::default(), quarters: std::collections::BTreeMap::new(), districts: std::collections::BTreeMap::new(), + regions: std::collections::BTreeMap::new(), last_accessed: 0, }; // 3×2 grid with two distinct zones at the corners. @@ -512,6 +598,64 @@ mod tests { assert!(build_district_grid(&state).is_none()); } + /// T-1113: the region climate grid mirrors the district-grid encoding — + /// `None` when the Region layer hasn't run; dense row-major with the + /// integer wire quantization (deci-°C temp, `i16::MIN` airless sentinel) + /// when it has. + #[test] + fn build_region_grid_encodes_dense_quantized_climate() { + use crate::atlas::region_profile::{RegionClock, RegionProfile, SeasonPhase, WeatherState}; + + let mut state = blank_state("GJ1c"); + // Empty regions → None (the Region layer hasn't run). + assert!(build_region_grid(&state).is_none()); + + // A 2×1 covering grid: one temperate region, one airless-style region + // (mean_temp_c = None → the sentinel). + state.regions.insert( + (0, 0), + RegionProfile { + pos: (0, 0), + clock: RegionClock { + season: SeasonPhase::Summer, + weather: WeatherState::Clear, + mean_temp_c: Some(12.34), + }, + latitude_deg: 45.0, + moisture_q: 80, + }, + ); + state.regions.insert( + (1, 0), + RegionProfile { + pos: (1, 0), + clock: RegionClock { + season: SeasonPhase::Winter, + weather: WeatherState::Snow, + mean_temp_c: None, + }, + latitude_deg: -10.0, + moisture_q: 5, + }, + ); + + let grid = build_region_grid(&state).expect("regions present → Some grid"); + assert_eq!((grid.cols, grid.rows), (2, 1)); + assert_eq!(grid.season.len(), 2); + assert_eq!(grid.season[0], SeasonPhase::Summer as u8); + assert_eq!(grid.weather[0], WeatherState::Clear as u8); + // 12.34 °C → 123 deci-°C (rounded). + assert_eq!(grid.mean_temp_dc[0], 123); + assert_eq!(grid.moisture_q[0], 80); + assert_eq!(grid.season[1], SeasonPhase::Winter as u8); + assert_eq!(grid.weather[1], WeatherState::Snow as u8); + assert_eq!( + grid.mean_temp_dc[1], REGION_TEMP_NONE_DC, + "airless None maps to the sentinel" + ); + assert_eq!(grid.moisture_q[1], 5); + } + /// A blank `BodyWorldState` for tests that only care about one field — /// callers overwrite `placements`/`road_graph`/etc. as needed. fn blank_state(body_id: &str) -> BodyWorldState { @@ -527,6 +671,7 @@ mod tests { road_graph: crate::atlas::road_graph::RoadGraph::default(), quarters: std::collections::BTreeMap::new(), districts: std::collections::BTreeMap::new(), + regions: std::collections::BTreeMap::new(), last_accessed: 0, } } @@ -728,6 +873,7 @@ mod tests { district_grid: None, road_graph: build_road_graph_layer(&state), settlements: build_settlement_layer(&state), + region_grid: build_region_grid(&state), }; let bytes = rmp_serde::to_vec_named(&resp).expect("encode"); @@ -829,6 +975,7 @@ mod tests { road_graph: crate::atlas::road_graph::RoadGraph::default(), quarters: std::collections::BTreeMap::new(), districts: std::collections::BTreeMap::new(), + regions: std::collections::BTreeMap::new(), last_accessed: 0, }); let (_db, resolver) = empty_resolver(); @@ -957,7 +1104,11 @@ mod tests { } /// With body_params_reader wired, a cache miss enqueues an AnalyzeBody that - /// completes with populated `districts` (DistrictProfile layer ran). + /// completes with populated `districts` (DistrictProfile layer ran) AND + /// populated `regions` (Region layer ran — the production terminal, + /// T-1113). Then the completed state served back through + /// `handle_atlas_request` carries a `region_grid` — closing the full + /// dispatch → Ready → region_grid loop (PR #179 F4). #[test] fn body_params_reader_wired_produces_populated_regions() { let mut cache = BodyWorldStateCache::new(CACHE_CAPACITY); @@ -995,6 +1146,29 @@ mod tests { !body_state.districts.is_empty(), "districts must be populated when body_params_reader is wired (T-1032 dispatch path)" ); + assert!( + !body_state.regions.is_empty(), + "regions must be populated when body_params_reader is wired (T-1113 dispatch path)" + ); + + // Serve the completed state back through the proxy: the cache-hit + // branch must build and include the region grid. + cache.insert(body_state); + let ready = handle_atlas_request( + &req("GJ1c"), + &mut cache, + &queue, + &resolver, + None, + Some(¶ms_reader), + 42, + 2, + ); + assert_eq!(ready.status, AtlasLayerStatus::Ready); + assert!( + ready.region_grid.is_some(), + "a Ready response for a Region-populated body must carry region_grid" + ); } /// Without body_params_reader (None), districts is empty — pre-T-1032 behaviour. @@ -1034,5 +1208,10 @@ mod tests { body_state.districts.is_empty(), "districts must remain empty when no body_params_reader is wired" ); + assert!( + body_state.regions.is_empty(), + "regions must remain empty when no body_params_reader is wired \ + (the Region layer gates on body_params, T-1113)" + ); } } diff --git a/server/src/atlas/plugin.rs b/server/src/atlas/plugin.rs index 69551e4a0..2124d8f1c 100644 --- a/server/src/atlas/plugin.rs +++ b/server/src/atlas/plugin.rs @@ -113,6 +113,7 @@ fn serve_atlas_requests( district_grid: None, road_graph: None, settlements: None, + region_grid: None, }, }; responses.0.push(resp); diff --git a/server/tests/gen_fixtures.rs b/server/tests/gen_fixtures.rs index bc88579d3..9a60a9808 100644 --- a/server/tests/gen_fixtures.rs +++ b/server/tests/gen_fixtures.rs @@ -624,6 +624,7 @@ fn generate_atlas_layer_response_fixtures() { district_grid: None, road_graph: Some(road_graph), settlements: Some(settlements), + region_grid: None, }; write_fixture( "atlas_response_ready", @@ -637,6 +638,7 @@ fn generate_atlas_layer_response_fixtures() { district_grid: None, road_graph: None, settlements: None, + region_grid: None, }; write_fixture( "atlas_response_pending", @@ -650,6 +652,7 @@ fn generate_atlas_layer_response_fixtures() { district_grid: None, road_graph: None, settlements: None, + region_grid: None, }; write_fixture( "atlas_response_not_found",