docs(simulation): correct stale cascade docs and pin layer order (#955)

Address the doc/test-correctness items from PR #149 review:

- cascade.rs: Layer 3 is RNG-free (pure fn of attractors+cities); it does
  not consume the carried SeedChain. Corrected the "first RNG-using layer"
  claims on the module doc and the Settlement variant (Hoshe H3).
- cascade.rs: layers_are_ordered now also asserts Topography < Settlement,
  pinning the invariant the up_to >= Settlement guards rely on (Tyre T2).
- features.rs: strength is an integer 0-100 (quantized at extraction), not
  f32, and consumers that rank by it use the integer value (Hoshe H2).
- layer_proxy.rs: AtlasLayerRequest.up_to is not yet honored — run_work_item
  runs through Settlement unconditionally; per-request depth deferred to
  #1021 (Tyre T1).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-03 17:33:36 +02:00
co-authored by Claude Opus 4.8
parent 9d8ff8b341
commit 2d8367d3bc
3 changed files with 26 additions and 10 deletions
+12 -4
View File
@@ -11,9 +11,10 @@
//! path-loading [`run_cascade`] is a thin wrapper around it.
//!
//! **Determinism (D-010 #4):** for a fixed heightmap + [`SeedChain`], the
//! snapshot is reproducible. Layers 0–1 are RNG-free (pure functions of the
//! heightmap); the carried `SeedChain` feeds the RNG-using layers (Layer 3+,
//! D-224).
//! snapshot is reproducible. Layers 0–3 are RNG-free — Layers 0–1 are pure
//! functions of the heightmap, and Layer 3 is a pure function of
//! (attractors, cities). The carried `SeedChain` is reserved for the future
//! RNG-using layers (Layer 4+, D-224).
use std::path::Path;
@@ -36,7 +37,9 @@ pub enum CascadeLayer {
/// Layer 1 — empty-world topography: drainage, feature tags, sub-biome (#953).
Topography,
/// Layer 3 — settlement placement: attractor-matched city positions (#955, D-211).
/// First RNG-using layer (uses the carried `SeedChain`).
/// Deterministic and RNG-free: a pure function of (attractors, cities) via
/// `match_cities`. The carried `SeedChain` is unused here; later stochastic
/// layers (Layer 4+) will consume it.
Settlement,
}
@@ -258,7 +261,12 @@ mod tests {
#[test]
fn layers_are_ordered() {
// The `up_to >= CascadeLayer::Settlement` guards in the cascade rely on
// this declaration order — pin it explicitly so reordering the enum (or
// inserting a layer out of sequence) fails here instead of silently
// breaking which layers run.
assert!(CascadeLayer::Heightmap < CascadeLayer::Topography);
assert!(CascadeLayer::Topography < CascadeLayer::Settlement);
}
#[test]