settled-reach/docs/workshops/planet-down-cascade/consultant-review-planet-down-cascade.md

Consultant Review — Planet-Down Cascade Workshop Brief

Reviewer: External strategic consultant Date: 2026-04-30 Status: Lead-reviewed directives for incorporation into workshop brief before Round 1 Scope: Architectural amendments, unlocked decisions, new workshop requirements

---

Summary

The brief as written is thorough, well-structured, and asks the right questions. The cascade vision is correct. The following amendments reflect lead decisions made during review that change the brief's foundational assumptions in three areas: the execution model, the placement architecture, and the spatial hierarchy. These are lead directives, not open questions — the workshop designs algorithms within them.

---

Amendment 1: Three-Tier Execution Model

The brief's two-tier Phase 3/Phase 5 split is replaced.

The brief states:

• Phase 3 = Python tooling + systems.db (offline, Layers 1-2)
• Phase 5 = Rust runtime + seed-derived (Layers 3-4)

The actual architecture is three tiers:

Tier	When	Language	What	Storage
Build-time	make regen-db	Python	Atlas generation, system-level economics, star map, aggregate specs. Everything the economic simulation needs to run.	systems.db (permanent)
Runtime background	Game session, background threads	Rust	Layer 1-2 cascade: heightmap drainage, settlement placement, road graphs, regional cell tagging. Runs per-body. Seed-deterministic.	Session DB (reproducible from seed)
Runtime on-demand	Player proximity trigger	Rust	Layer 3-4 cascade: city district grids, block skeletons, street tiles. Generated as player approaches.	Never stored (regenerated from seed + Layer 1-2 output)

Why: The economic simulation runs on system-level aggregate specs (economic_role, population, corp_presence, trade capacity) that already exist in systems.db from build-time generation. It does not need Layer 1-2 spatial detail — it does not need to know where mining camps sit on a planetary surface to calculate inter-system commodity flows. Layer 1-2 regional data (drainage, settlement positions, road graphs, TerritorialStatus) is consumed only by Layer 3 city planning and Layer 4 street rendering, both of which are proximity-triggered. Therefore Layer 1-2 generation does not need to be precomputed for all ~400-500 bodies at build time.

What this means for generate_regional.py: The Python implementation becomes a reference and validation tool. The runtime Layer 1-2 cascade is implemented in Rust. The algorithms must be identical — same seed, same heightmap, same output. The Python version can be used for offline testing, visualization, and regression validation.

Implication for the workshop: Algorithm designs for Layers 1-2 must be specified in a form that is implementable in Rust on a background thread. No Python-only dependencies. No assumptions about offline batch processing.

---

Amendment 2: Background Generation and Precaching

Layer 1-2 generation runs on background threads, spidering outward from the player.

The priority queue is event-driven, not purely proximity-driven:

Priority	Trigger	Rationale
Immediate	Player's current body	Must complete before the player sees anything
High	Any system referenced in player-facing content: news ticker, dialogue, mission text, corporate records, Meridian broadcasts	The moment a system name is rendered to the player, that system's cascade is queued — by the time the player reads the sentence and thinks "where is that?", the cascade should be done
Medium	Gate-adjacent systems, spidering outward from current position	Speculative pre-generation for likely travel destinations
Low	Everything else, breadth-first along the gate graph	Background fill

Performance envelope: Layer 1-2 for a single body should complete in low single-digit seconds. The cascade is: read a heightmap, run drainage, find attractors, place settlements, connect roads, tag cells. This is geometry and constraint solving on a coarse grid, not heavy simulation. The workshop should design algorithms with this performance target in mind.

Planetary map dependency: The planetary map UI requires Layer 1-2 output to render (cities, rivers, roads are all generated data). This means a body's cascade must complete before the player opens that body's map. For the player's current body this is trivially satisfied (immediate priority). For remote bodies, the event-driven queue handles the common case (player clicks a system the game just mentioned). Edge case: player browses to a system that hasn't been generated yet. The UI either shows a brief loading state or a diegetic "survey data unavailable" placeholder until the cascade completes.

---

Amendment 3: Fully Generative Placement

markers.json is stripped to topographic features only. All settlement and river placement is fully generative.

What markers.json retains: Mountain ranges, seas, major coastline features — topographic features that are defined by the heightmap and do not depend on civilization.

What markers.json loses: City positions, city coordinates, river polylines, road paths. All of these become generator output.

How cities are placed: The generator reads the heightmap, finds geographic attractors (confluences, harbors, arable plains, mountain passes), and places settlements at attractors based on the body's economic profile and population data from systems.db. The placement algorithm is a constraint satisfaction problem: N settlements with known economic roles and populations, M geographic attractors with known characteristics, find the assignment that maximizes plausibility.

How rivers are placed: The generator runs drainage simulation from the heightmap. Water flows downhill. Rivers emerge from the drainage network. No authored river positions.

How names work: The authored layer controls identity, not placement. systems.db knows that a body has N named cities with specific roles and populations. It knows river names and mountain range names. The generator assigns these names to generated features based on matching criteria. Cities that must exist by name (because corporate records reference them as headquarters locations) are name-locked. Everything else gets generated names from the culture's naming pool.

The constraint set is minimal: The only hard requirement on city placement is that corporate cross-references in systems.db must resolve — if a corporation is headquartered in a named city, that city must exist and be the kind of place where that corporation would plausibly sit. All other placement is the generator's decision.

What this eliminates from the workshop's open questions:

• L1-Q1 (authored rivers vs. drainage network) — eliminated. No authored rivers to reconcile.
• L2-Q1 (city positions anchored vs. re-derived) — eliminated. All city positions are derived.
• CL-Q4 (authored rivers vs. drainage network, elevated) — eliminated. Same resolution as L1-Q1.

What this adds to the workshop's open questions:

• New: Attractor-matching algorithm. How does the generator match N named cities with known economic roles to M geographic attractors? What are the matching heuristics? What happens when the best attractor for a logistics hub is also the best attractor for a fishing port?
• New: Name reservation fulfillment. What data structure represents the name reservations from systems.db, and at what point in the cascade does the generator fulfill them?

---

Amendment 4: Spatial Hierarchy Definition

The workshop must lock down a coherent spatial hierarchy with defined dimensions at every tier.

The following eight-tier hierarchy is the lead's naming directive:

Tier	Name	Scale	Defined by
7	System	Star system	Gate graph
6	Body	Planet / moon / station	systems.db
5	Area	Major topographic division	Heightmap feature boundaries (coastlines, mountain ranges)
4	Province	Road-map travel region	Natural boundaries from Layer 1 (drainage basins, ridgelines)
3	Region	City footprint + surroundings	Decomposition formula
2	District	512×512 sim tiles	DistrictSkeleton
1	Block	4×4 grid within district	BlockSkeleton
0	Chunk	64×64 tiles	GeneratorChunkData

Naming is locked. These terms replace all informal usage in the brief ("regional grid," "city-local," "atlas-level"). The workshop should use this vocabulary consistently.

Dimension locking required. The workshop must define the tile/cell dimensions at every tier and confirm they scale coherently from chunk to body. This becomes a canonical reference table — the spatial language for all future work.

Body size variation is absorbed at the area tier. Tiers 0-4 (chunk through province) have fixed dimensions. Different-sized bodies (large garden planet vs. small moon vs. different-sized planets) produce different numbers of areas. Area count is a derived field on the body, computed from body size (radius, surface area, or equivalent physical parameter). The generator reads area count and subdivides the heightmap accordingly. Everything below that subdivision is scale-invariant.

Workshop question: Define the formula that maps body size to area count. Confirm that the fixed dimensions at tiers 0-4 produce sensible results for both the largest and smallest inhabited bodies in the Reach.

---

Amendment 5: Determinism Rule — Correct Rationale

The ghost town narrative must be relegated to emergent consequence. The determinism rule's actual motivation must be stated clearly.

The brief currently weaves the "ghost city effect" through multiple sections as though it were a design goal: Paula's prosperity_delta architecture, the latent settlement principle, CL-Q3 (ruin lifecycle). Over four rounds of workshop discussion, a hypothetical edge case was elevated to a named architectural pattern. This must be corrected before the next workshop inherits it as design intent.

The determinism rule exists for one reason: the player must never see streets change when they return to a location. Layout is seed-locked because layout changes would be visible and jarring — the player's spatial memory of a place must be reliable. That is the full motivation. It is a player experience guarantee.

Economic state affects rendering — tile condition (Intact/Worn/Cracked/Broken), repair state, activity levels, visual prosperity signals — because these are continuous visual changes that don't break spatial memory. The two-field prosperity model (prosperity_baseline + prosperity_current) is the correct implementation mechanism for this rendering variation. prosperity_delta (the difference between them) should always be derived, never stored.

Ghost towns, ruin decay paths, and the narrative gap between planned prosperity and current prosperity are emergent consequences, not design goals. They may happen. They may be interesting when they happen. The workshop must not design features around them. Specifically:

• CL-Q3 (Ruin lifecycle) should be scoped as an emergent rendering outcome of the prosperity system, not as a dedicated design question requiring its own decay path mechanics.
• The "ghost city effect" framing should be removed from architectural descriptions. The correct framing is: "the determinism rule produces stable layouts; the prosperity rendering system produces visual variation; the combination can produce interesting emergent results including apparent decline."
• The latent settlement principle stands on its own merits (all plausible positions placed at generation, active/ghost driven by economic sim) without needing the ghost town narrative to justify it.

---

Amendment 6: 10×9 Weight Table Unlocked

The 10×9 economic_role → DistrictType weight table (lines 148-160 of the brief) is removed from Given Facts and moved to an open workshop question.

Lead challenge: The table determines district type distribution from a single axis (economic role). This produces implausible settlements at the extremes — energy-producing cities with zero Commercial and zero Entertainment districts. A mining town doesn't have zero entertainment because it's a mining town. It has rough entertainment because miners drink.

The table encodes what a city produces. It does not encode what a city needs. Every settlement with people in it needs residential space, commerce, social venues.

The workshop is directed to evaluate an alternative approach: population size and settlement age determine a baseline district mix (because people live there and need services), and economic role modifies the proportions and character of that baseline (a mining town's commercial district is rougher and smaller than a research hub's). Larger and older settlements have more variety because more people need more services. No settlement above a minimum population has zero of any essential district type.

The workshop may retain the weight table if it can demonstrate that it produces plausible settlements across all economic roles and WorldTiers. The workshop may replace it with a population-and-age-driven algorithm. The workshop may propose a hybrid. The requirement is that the output feels like somewhere people live.

---

Open Items Confirmed for Workshop

These items from the original analysis remain open and are confirmed as workshop scope:

1. Multi-body scoping. CityGenerationContext needs body_id or body-scoped city_id. Confirm the cascade runs independently per body and the struct reflects this.

2. Grid resolution confirmation. The 64×32 regional grid predates the spatial hierarchy defined in Amendment 4. Confirm that data resolutions at each tier of the hierarchy are appropriate and that no tier boundary creates ambiguity (e.g., a city straddling two cells with different values).

3. Player-experience validation. The workshop participant list has no dedicated player-experience advocate (OZZIE is not included). The lead should consider whether to add OZZIE for at least one round, or assign an existing participant to explicitly hold the question: "does this produce places that feel inhabited?"

---

Questions Eliminated by These Amendments

The following open questions from the original brief no longer require workshop resolution:

• L1-Q1 (authored rivers vs. drainage network) — rivers are fully generated
• L2-Q1 (city positions anchored vs. re-derived) — all positions are derived
• CL-Q4 (authored rivers vs. drainage network, elevated) — same as L1-Q1

---

This review was conducted as an external sanity check on architectural principles. The amendments above reflect lead decisions made during review. They are directives to the workshop, not suggestions.