feat(simulation): step-canvas serving — tagged envelope (D-255, T-1181)

The D-225-discharging wire migration per D-255(c): a new
server/src/atlas/step_canvas.rs subsystem (six-rung StepCanvasRung
ladder — Global variable-extent rung 0 through Chunk 64m — the
StepCanvasRequest/StepCanvasResponse tagged envelope extending the
proven ShapeProbe discriminated-shape pattern, PNG-per-field dense +
MessagePack-native sparse encoding per the T-1179 measured table, and
both server cache tiers: the structurally keep-always GlobalTierCache
and the dual-axis StepCanvasCache with storage TTLs per rung and
SIM_STATE_TTL clock-bucket staleness per the D-227 amendment (1)
formula). Wired through bridge/{mod,tcp,local}.rs (sixth demux shape,
send_step_canvas_response mirroring the five existing senders),
gen_queue.rs (DeriveStepCanvas work item with per-connection-per-rung
coalescing, reusing the shared TerrainAnalysisCache), and plugin.rs
(serve/complete systems, lazy D-206 rung-0 population).

Acceptance gate (mandatory per D-227 amendment (3)):
tests/step_canvas_acceptance_gate.rs — cache-hit == cache-miss
byte-identical for every rung, lossless encode round-trips, cache
round-trips vs fresh derive, distinct-center sanity. 5/5 pass.

Station-spacing cap ADOPTED: course stations floored to District
spacing (2,048 m) at finer rungs — the S2-measured +38-87% chunk/block
course cost had zero display benefit at the same station density
(COURSE_STATION_SPACING_FLOOR_M).

Documented honest gaps, not shortcuts: settlement_id is a proximity
approximation (no footprint polygons exist yet); glaciation/flooded_q
sim-state planes are wire-shape-ready D-253 stubs; rung-0 uses signed
equator-anchored rows (the canonical D-256 core convention — T-1186's
wrong-latitude behavior applies unchanged and unfixed here, by
instruction).

Legacy district_window carrier byte-unchanged: window_derivation_golden
6/6 byte-identical, all district_window suites pass unmodified. Full
suite at implementation time: 2127 passed across 45 binaries.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

server/src/atlas/gen_queue.rs

@@ -258,6 +258,48 @@ pub enum GenWorkItem {
         /// special-cased away.
         min_wl_m: u32,
     },
+    /// Derive a D-255(a) step canvas (T-1181, the tagged-envelope migration).
+    ///
+    /// **Binding serving model — same as `DeriveWindow`:** step canvases ride
+    /// this SAME Rayon queue, never inline on the `PreInput` drain (D-255(d):
+    /// "never inline here"). Reuses the SAME `TerrainAnalysisCache` LRU
+    /// `DeriveWindow` already populates — a step-canvas request and a legacy
+    /// `district_window` request for the same body share one
+    /// `run_layer1`-derived `(Layer1Output, TerrainAnalysis)` cache entry
+    /// (keyed on `body_id` alone), so a player already panning the legacy
+    /// window viewer and then opening the new stepped map (or vice versa)
+    /// pays the ~45 ms `run_layer1` cost at most once per body, not once per
+    /// carrier.
+    DeriveStepCanvas {
+        body_id: String,
+        /// Coalescing/routing key — NOT used by `run_work_item` itself (the
+        /// derive is connection-agnostic), only by
+        /// `GenerationQueue::submit_step_canvas` to decide which still-pending
+        /// item a new one for the same connection+body+rung supersedes.
+        conn_id: ConnectionId,
+        heightmap_path: PathBuf,
+        sea_level: f32,
+        body_seed: SeedChain,
+        body_params: Box<BodyParams>,
+        /// The body's placed settlements, pre-resolved at dispatch time from
+        /// `BodyWorldState.placements` if already cached (empty otherwise —
+        /// `settlement_id` coverage is simply all-zero until the body's own
+        /// `AnalyzeBody` cascade has placed settlements; see
+        /// `step_canvas::serve_step_canvas_request`'s doc).
+        placements: Vec<crate::atlas::attractor_matching::CityPlacement>,
+        /// The D-255(a) rung this canvas targets.
+        rung: crate::atlas::step_canvas::StepCanvasRung,
+        /// World-metre centre (ignored for `StepCanvasRung::Global`, whose
+        /// canvas is whole-body/origin-anchored).
+        center: (i64, i64),
+        /// Canvas pixel budget for every FIXED rung (ignored for `Global`,
+        /// whose extent is the body's own region grid).
+        extent: (u32, u32),
+        /// Octave cutoff in whole metres, already quantized by the caller
+        /// (`step_canvas::quantize_min_wl_m_for_rung`) — never a raw wire
+        /// value.
+        min_wl_m: u32,
+    },
 }
 
 impl GenWorkItem {
@@ -293,6 +335,29 @@ impl GenWorkItem {
             None
         }
     }
+
+    /// Coalescing key for `DeriveStepCanvas` items only — `(connection, body,
+    /// rung)` (T-1181, mirroring `window_supersede_key`'s exact reasoning):
+    /// a pan-burst that queues several step-canvas requests for the same
+    /// connection+body+rung before the first is dispatched collapses to one
+    /// derive. A different rung for the same connection+body does NOT
+    /// coalesce — every rung is a separate in-flight derive, not a competing
+    /// update to the same one. `None` for every other variant.
+    pub fn step_canvas_supersede_key(
+        &self,
+    ) -> Option<(ConnectionId, &str, crate::atlas::step_canvas::StepCanvasRung)> {
+        if let GenWorkItem::DeriveStepCanvas {
+            body_id,
+            conn_id,
+            rung,
+            ..
+        } = self
+        {
+            Some((*conn_id, body_id, *rung))
+        } else {
+            None
+        }
+    }
 }
 
 // ---------------------------------------------------------------------------
@@ -352,6 +417,22 @@ pub enum GenCompletion {
         /// boxing rationale).
         layer: Box<DistrictWindowLayer>,
     },
+    /// A D-255(a) step canvas finished deriving (T-1181). The main thread
+    /// inserts `canvas` into `GlobalTierCache` (rung `Global`) or
+    /// `StepCanvasCache` (every other rung), keyed as
+    /// `serve_step_canvas_request` documents — NOT pushed into any in-flight
+    /// response, same re-poll-and-hit-cache model as `WindowDerived`.
+    StepCanvasDerived {
+        body_id: String,
+        rung: crate::atlas::step_canvas::StepCanvasRung,
+        center: (i64, i64),
+        extent: (u32, u32),
+        min_wl_m: u32,
+        /// Boxed to keep `GenCompletion` variant sizes balanced — an
+        /// `EncodedStepCanvas` carries eight PNG/msgpack-encoded fields,
+        /// comparable to `WindowDerived`'s own boxing rationale.
+        canvas: Box<crate::atlas::step_canvas::EncodedStepCanvas>,
+    },
     /// Work item failed — body_id or city_id for logging.
     Failed { item: GenWorkItem, reason: String },
 }
@@ -523,6 +604,36 @@ impl GenerationQueue {
         }
     }
 
+    /// Submit a `DeriveStepCanvas` item with per-connection-per-rung
+    /// coalescing (T-1181, mirroring `submit_window`'s exact discipline): if
+    /// an item for the SAME `(connection, body, rung)` is still pending
+    /// (not yet dispatched), it is replaced in place — a step-cross burst
+    /// that queues several requests for the same connection+body+rung before
+    /// the first is dispatched collapses to one derive. `item` MUST be a
+    /// `DeriveStepCanvas` variant; any other variant falls through to plain
+    /// `submit` with no coalescing.
+    pub fn submit_step_canvas(&self, item: GenWorkItem, priority: GenPriority) {
+        if let Some(key) = item.step_canvas_supersede_key() {
+            let key = (key.0, key.1.to_string(), key.2);
+            let mut pending = self.pending.lock().unwrap();
+            pending.retain(|q| {
+                q.item
+                    .step_canvas_supersede_key()
+                    .map(|k| (k.0, k.1.to_string(), k.2) != key)
+                    .unwrap_or(true)
+            });
+            let pos = pending
+                .iter()
+                .position(|q| q.priority > priority)
+                .unwrap_or(pending.len());
+            pending.insert(pos, QueuedWork { priority, item });
+            drop(pending);
+            self.dispatch_next();
+        } else {
+            self.submit(item, priority);
+        }
+    }
+
     /// Drain all completed items from the channel and dispatch pending work.
     ///
     /// Call once per tick from the main thread. Returns all completions
@@ -988,6 +1099,66 @@ fn run_work_item(
                 reason: format!("heightmap load failed: {e}"),
             },
         },
+        GenWorkItem::DeriveStepCanvas {
+            body_id,
+            conn_id: _, // routing-only (queue-level coalescing); the derive itself is connection-agnostic
+            heightmap_path,
+            sea_level,
+            body_seed,
+            body_params,
+            placements,
+            rung,
+            center,
+            extent,
+            min_wl_m,
+        } => match load_heightmap_png(heightmap_path, body_id, *sea_level) {
+            Ok(hm) => {
+                // Same GRID_W×GRID_H downsample AnalyzeBody/DeriveWindow apply
+                // (D-202) — the true DistrictPos<->world-metres mapping must
+                // stay consistent across every derive path.
+                let working = if hm.width > GRID_W || hm.height > GRID_H {
+                    hm.downsample(GRID_W, GRID_H)
+                } else {
+                    hm
+                };
+                // Same per-body TerrainAnalysisCache LRU DeriveWindow already
+                // populates (T-1137 binding decision, extended here) — keyed
+                // on body_id alone, so a step-canvas request and a legacy
+                // district_window request for the same body share one
+                // ~45 ms run_layer1 re-derive, never pay it twice.
+                let (l1, ta) = terrain_cache
+                    .lock()
+                    .unwrap()
+                    .get_or_derive(body_id, &working);
+                let climate = ClimateConstants::default();
+                let raw = crate::atlas::step_canvas::build_step_canvas(
+                    *body_seed,
+                    body_id,
+                    body_params,
+                    &ta,
+                    &l1.river_network,
+                    placements,
+                    *rung,
+                    *center,
+                    *extent,
+                    &climate,
+                    *min_wl_m,
+                );
+                let canvas = crate::atlas::step_canvas::encode_step_canvas(&raw);
+                GenCompletion::StepCanvasDerived {
+                    body_id: body_id.clone(),
+                    rung: *rung,
+                    center: *center,
+                    extent: *extent,
+                    min_wl_m: *min_wl_m,
+                    canvas: Box::new(canvas),
+                }
+            }
+            Err(e) => GenCompletion::Failed {
+                item: item.clone(),
+                reason: format!("heightmap load failed: {e}"),
+            },
+        },
     }
 }
 

server/src/atlas/layer_proxy.rs

@@ -31,7 +31,7 @@ use crate::simulation::generator::{AttractorType, DistrictType, MaintenanceAutho
 
 /// Fallback sea level when the heightmap PNG carries no `sea_level` tEXt chunk
 /// (the loader prefers the chunk; this is only the floor).
-const DEFAULT_SEA_LEVEL: f32 = 0.3;
+pub(crate) const DEFAULT_SEA_LEVEL: f32 = 0.3;
 
 /// Hard server-side clamp on [`AtlasLayerRequest::window_n`] (D-226 T-1124
 /// amendment §4, binding numbers). 64×64 districts ≈ 131 km per side — the
@@ -484,7 +484,7 @@ const _: () =
 /// to the coarser/lower band, i.e. `<=` on the running best distance) keeps
 /// the mapping total and deterministic for any `u32` input, including values
 /// far outside the octave range (e.g. `u32::MAX` snaps to the coarsest band).
-fn quantize_min_wl_m(raw: u32) -> u32 {
+pub(crate) fn quantize_min_wl_m(raw: u32) -> u32 {
     let raw_f = raw as f64;
     let mut best = MIN_WL_BANDS_M[0];
     let mut best_dist = (raw_f - best).abs();

server/src/atlas/mod.rs

@@ -35,6 +35,7 @@ pub mod scale;
 pub mod shell;
 pub mod skeleton_gen;
 pub mod source_resolver;
+pub mod step_canvas;
 pub mod subbiome;
 pub mod tile_condition;
 pub mod trait_catalog_reader;

server/src/atlas/plugin.rs

@@ -36,6 +36,10 @@ use crate::atlas::road_graph::{RoadGraph, RoadNode};
 use crate::atlas::scale;
 use crate::atlas::skeleton_gen::derive_complexity;
 use crate::atlas::source_resolver::BodySourceResolverResource;
+use crate::atlas::step_canvas::{
+    serve_step_canvas_request, GlobalTierCache, StepCanvasCache, StepCanvasResponse,
+    StepCanvasStatus, STEP_CANVAS_CACHE_CAPACITY,
+};
 use crate::atlas::trait_catalog_reader::{
     ExteriorCatalog, TraitBias, TraitCatalogReaderResource, TraitTemplate,
 };
@@ -49,6 +53,7 @@ use crate::atlas::trait_swerve::{
 use crate::bridge::{
     AtlasRequestBuffer, AtlasResponseBuffer, BrowseRequestBuffer, BrowseResponseBuffer,
     CityNamesRequestBuffer, CityNamesResponseBuffer, StarMapRequestBuffer, StarMapResponseBuffer,
+    StepCanvasRequestBuffer, StepCanvasResponseBuffer,
 };
 use crate::seed::{SeedChain, SeedDomain};
 use crate::simulation::generator::{
@@ -66,6 +71,8 @@ impl Plugin for GenerationPlugin {
         app.insert_resource(GenerationQueue::new())
             .insert_resource(BodyWorldStateCache::new(CACHE_CAPACITY))
             .insert_resource(DistrictWindowCache::new(DISTRICT_WINDOW_CACHE_CAPACITY))
+            .insert_resource(GlobalTierCache::new())
+            .insert_resource(StepCanvasCache::new(STEP_CANVAS_CACHE_CAPACITY))
             .add_systems(
                 Update,
                 drain_generation_completions.in_set(TickPhase::PreInput),
@@ -76,7 +83,11 @@ impl Plugin for GenerationPlugin {
                 Update,
                 serve_city_names_requests.in_set(TickPhase::PreInput),
             )
-            .add_systems(Update, serve_browse_requests.in_set(TickPhase::PreInput));
+            .add_systems(Update, serve_browse_requests.in_set(TickPhase::PreInput))
+            .add_systems(
+                Update,
+                serve_step_canvas_requests.in_set(TickPhase::PreInput),
+            );
     }
 }
 
@@ -218,6 +229,68 @@ pub fn serve_browse_requests(
     }
 }
 
+/// Drain inbound step-canvas requests and serve each through the proxy
+/// (T-1181, D-255(c)/(d)): Global rung → the always-keep `GlobalTierCache`;
+/// every fixed rung → the dual-axis-evicted `StepCanvasCache`. Cache hit →
+/// Ready, miss → resolve + enqueue (`GenWorkItem::DeriveStepCanvas`) +
+/// Pending — same D-225 poll/cache/enqueue model `serve_atlas_requests`
+/// already uses for `district_window`.
+fn serve_step_canvas_requests(
+    mut requests: ResMut<StepCanvasRequestBuffer>,
+    mut responses: ResMut<StepCanvasResponseBuffer>,
+    mut global_cache: ResMut<GlobalTierCache>,
+    mut canvas_cache: ResMut<StepCanvasCache>,
+    body_state_cache: Res<BodyWorldStateCache>,
+    queue: Res<GenerationQueue>,
+    resolver: Option<Res<BodySourceResolverResource>>,
+    body_params_reader: Option<Res<BodyParamsReaderResource>>,
+    rng: Option<Res<SimRng>>,
+    time: Option<Res<SimulationTime>>,
+) {
+    if requests.0.is_empty() {
+        return;
+    }
+    let world_seed = rng.as_ref().map(|r| r.seed()).unwrap_or(0);
+    let tick = time.as_ref().map(|t| t.tick).unwrap_or(0);
+    let params_reader = body_params_reader.as_ref().map(|r| &r.0);
+    let pending: Vec<_> = requests.0.drain(..).collect();
+    for (conn_id, req) in pending {
+        // Read-only lookup (peek, no LRU bump — this proxy is not the
+        // canonical "this body was visited" signal, serve_atlas_requests'
+        // own cache.get already owns that) for settlement_id coverage
+        // (step_canvas::serve_step_canvas_request's doc). Empty when the
+        // body isn't cached yet or has no placements — settlement_id then
+        // reads all-zero on the derived canvas, not an error.
+        let placements: &[crate::atlas::attractor_matching::CityPlacement] = body_state_cache
+            .peek(&req.body_id)
+            .map(|s| s.placements.as_slice())
+            .unwrap_or(&[]);
+        let resp = match resolver.as_ref() {
+            Some(r) => serve_step_canvas_request(
+                &req,
+                &mut global_cache.as_mut(),
+                &mut canvas_cache.as_mut(),
+                &queue,
+                &r.0,
+                params_reader,
+                placements,
+                world_seed,
+                tick,
+                conn_id,
+            ),
+            None => StepCanvasResponse {
+                body_id: req.body_id.clone(),
+                rung: req.rung,
+                center: req.center,
+                min_wl_m: req.min_wl_m,
+                status: StepCanvasStatus::Error("no body source resolver".to_string()),
+                canvas: None,
+            },
+        };
+        responses.0.push((conn_id, resp));
+    }
+}
+
 /// Drain finished background work each tick and apply it to the cache (D-206).
 ///
 /// Runs in `PreInput` (off the Rayon workers, on the main thread): a cheap
@@ -226,10 +299,13 @@ fn drain_generation_completions(
     queue: Res<GenerationQueue>,
     mut cache: ResMut<BodyWorldStateCache>,
     mut window_cache: ResMut<DistrictWindowCache>,
+    mut global_tier_cache: ResMut<GlobalTierCache>,
+    mut step_canvas_cache: ResMut<StepCanvasCache>,
     city_reader: Option<Res<CityContextReaderResource>>,
     trait_catalog: Option<Res<TraitCatalogReaderResource>>,
     body_params_reader: Option<Res<BodyParamsReaderResource>>,
     rng: Option<Res<SimRng>>,
+    time: Option<Res<SimulationTime>>,
 ) {
     for completion in queue.drain_completions() {
         match completion {
@@ -470,6 +546,28 @@ fn drain_generation_completions(
                     *layer,
                 );
             }
+            GenCompletion::StepCanvasDerived {
+                body_id,
+                rung,
+                center,
+                extent,
+                min_wl_m,
+                canvas,
+            } => {
+                // T-1181, D-255(d): cache the completed canvas — NOT pushed
+                // into any in-flight response (same re-poll-and-hit-cache
+                // model WindowDerived above uses). Global (rung 0) goes to
+                // the always-keep GlobalTierCache; every fixed rung goes to
+                // the dual-axis-evicted StepCanvasCache.
+                if rung.is_global() {
+                    global_tier_cache.as_mut().insert(body_id, *canvas);
+                } else {
+                    let tick = time.as_ref().map(|t| t.tick).unwrap_or(0);
+                    step_canvas_cache
+                        .as_mut()
+                        .insert((body_id, rung, center, extent, min_wl_m), *canvas, tick);
+                }
+            }
         }
     }
 }
@@ -926,6 +1024,8 @@ mod tests {
         world.insert_resource(GenerationQueue::new());
         world.insert_resource(BodyWorldStateCache::new(CACHE_CAPACITY));
         world.insert_resource(DistrictWindowCache::new(DISTRICT_WINDOW_CACHE_CAPACITY));
+        world.insert_resource(GlobalTierCache::new());
+        world.insert_resource(StepCanvasCache::new(STEP_CANVAS_CACHE_CAPACITY));
 
         world.resource::<GenerationQueue>().submit(
             GenWorkItem::AnalyzeBody {