docs(decisions): D-220 settlement density model — tile scale, density classes, vertical pressure

Five density classes (Frontier→Compressed) driven by four pressures
(utility cost, terrain, economic gravity, political). Amends D-201
tile scale to 1m with 0.5m subtile. Calibrated against real-world
settlements (Kiruna, Uzès, Kanazawa, Paris).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

decisions/architecture.md

@@ -1237,4 +1237,142 @@ Technical foundation decisions that constrain implementation: engine, client-ser
 
 ---
 
-*79 decisions (D-001 through D-218, excluding gaps). Last updated: 2026-05-02 (D-218 — WorldTier canonical values, generation cascade workshop Sprint 38)*
+### D-220: Settlement Density Model — Tile Scale, Density Classes, and Vertical Pressure
+- **Date:** 2026-05-03
+- **Decision:** Settlement footprint, building height, and basement depth are all driven by a single **density scalar** on each settlement, derived from population, available land, terrain constraints, and economic pressure. This decision establishes the tile scale, the density classification system, and the rules for how density shapes the built environment.
+
+  **Tile scale (amends D-201 Tier 0):**
+
+  | Unit | Dimensions | Real-world size | Notes |
+  |------|-----------|-----------------|-------|
+  | Subtile | 1×1 | 0.5m × 0.5m | Rendering unit — character positioning, furniture placement, visual detail |
+  | Tile | 1×1 | 1m × 1m | Spatial unit — generation pipeline, pathfinding, district grids |
+  | Chunk | 64×64 tiles | 64m × 64m | Streaming unit (was 32m at 0.5m/tile; now 64m at 1m/tile) |
+  | Block | 128×128 tiles | 128m × 128m | 2×2 chunks |
+  | District | 512×512 tiles | 512m × 512m = 0.262 km² | 4×4 blocks |
+
+  Each tile contains 2×2 subtiles. The generation cascade operates in tiles. The renderer subdivides to subtiles for visual fidelity. All higher tiers (Province, Area, Body) remain as defined in D-201.
+
+  **Density classes:**
+
+  Density is measured in people per km² of settlement footprint. It is the primary driver of settlement character — not population alone. The same population at different densities produces completely different settlements.
+
+  | Class | Density (ppl/km²) | Horizontal character | Vertical character | Infrastructure cost | Who builds at this density |
+  |-------|-------------------|---------------------|-------------------|--------------------|-----------------------------|
+  | Frontier | ~400 | Large gaps between structures, open ground dominant, private roads | 1 floor, no basement | Very high per-capita (long utility runs, private maintenance) | **The very rich** (villa estates, corp executive compounds, prestige vanity builds) OR **the very poor** (pre-utility squatter settlements, homesteads with no services). Frontier density is a luxury or an absence, never the default. |
+  | Settled | ~1,500 | Planned grid, moderate spacing, shared streets, visible utility corridors | 1-2 floors, optional basement | Efficient — the utility-cost-optimized default | **Default for most Reach colonies.** Every meter of sewer, power conduit, and road is new capital expenditure on a virgin world. Settled density is what you get when infrastructure cost constrains the plan. Kiruna is the archetype. |
+  | Established | ~3,000 | Mixed residential, shared walls appearing, streets narrowing, green space intentional not incidental | 2-3 floors, basement common | Amortized — mature infrastructure absorbing incremental growth | **Mature settlements.** Second-generation growth over an existing utility grid. The settlement has existed long enough for the infrastructure investment to pay off and densification to begin. Tiel, Périgueux. |
+  | Dense | ~6,000 | Shared walls dominant, narrow streets, minimal private outdoor space, commercial ground floors | 3-6 floors, 1-2 basement levels (parking, storage, utilities) | High per-area but efficient per-capita | **Economic hubs.** Transit nodes, extraction chokepoints, terrain-constrained sites where the jobs pull people in faster than the settlement can spread. Kanazawa, Uzès. Density is a signal that economic gravity is compressing the settlement. |
+  | Compressed | ~15,000 | Vertical dominant, street canyons, multi-use buildings, public space carved from built volume | 6-12+ floors, 2-3 basement levels (metro, parking, utilities, subsurface logistics) | Very high per-area, requires vertical infrastructure (elevators, pressurized systems, multi-level utilities) | **Extreme economic pull.** Major corp HQs, gate-adjacent trade hubs, capital worlds. Rare in the Reach. The land itself is too valuable for anything but vertical. Paris, Amsterdam inner ring. |
+
+  **What drives density — the four pressures:**
+
+  1. **Utility cost (compressing force).** The dominant pressure on new colonies. Infrastructure is expensive per meter. This pushes settlements toward Settled as the floor, not Frontier. Every colony pays this tax unless someone absorbs the cost deliberately.
+
+  2. **Economic pull (compressing force).** Jobs, trade, resources, transit — anything that draws people to a specific location faster than the settlement can grow outward. The stronger the pull, the higher the density. Corp HQ worlds, gate-adjacent systems, extraction sites all have high economic pull. This is the force that pushes settlements from Settled through Dense to Compressed.
+
+  3. **Terrain constraint (compressing or dispersing force).** Coastal strips, canyon floors, mountain passes compress settlements along one axis (Bisbee: 2.5km × 300m). Open plains allow radial spread. River valleys elongate. The terrain doesn't set the density class directly — it shapes the footprint geometry within that class.
+
+  4. **Wealth/status (dispersing force — at a premium).** The only force that pushes density DOWN below the utility-cost floor. Low density in an otherwise dense settlement is conspicuous consumption of space — private utility runs, private road maintenance, private security perimeters. Villa estates, executive compounds, prestige campuses. This is Frontier density as luxury, not as poverty.
+
+  **The U-shaped wealth curve:**
+
+  Density has a U-shaped relationship with wealth. The very rich and the very poor both live at low density — but for opposite reasons. The rich can afford the infrastructure cost of space. The poor live where no infrastructure exists. Everyone in between clusters at Settled-to-Dense because that's what utility economics demands.
+
+  The player reads this instantly: low-density district on a dense world = money. Low-density district on a frontier world = nothing built yet. Same tile spacing, completely different story — and `prosperity_baseline` (D-197) disambiguates. High prosperity + low density = wealth. Low prosperity + low density = absence.
+
+  **Density → vertical pressure mapping:**
+
+  Density drives building height and basement depth via simple thresholds. These are tendencies, not hard limits — individual buildings vary, but the district-level character follows the pattern.
+
+  | Density class | Typical above-ground floors | Typical basement levels | Vertical pressure description |
+  |---------------|---------------------------|------------------------|------------------------------|
+  | Frontier | 1 | 0 | Single-story. Horizontal only. |
+  | Settled | 1-2 | 0-1 | Mostly single-story, occasional two-story. Basement where terrain allows. |
+  | Established | 2-3 | 1 | Two-story default. Three-story at intersections and commercial streets. Basements standard. |
+  | Dense | 3-6 | 1-2 | Multi-story default. Ground-floor commercial. Structured parking appears underground. |
+  | Compressed | 6-12+ | 2-3 | Highrises. Street canyons. Multi-level subsurface: parking, metro, utilities, logistics. |
+
+  The transition from "buildings grow out" to "buildings grow up" happens at Dense. Below Dense, the settlement solves population pressure by adding more districts horizontally. At Dense and above, horizontal expansion is constrained (by terrain, by utility cost, by land value) and vertical growth begins.
+
+  The transition from "no basement" to "buildings grow down" happens at Established. Below Established, basements are optional amenities. At Established and above, basements become structural necessities — storage, utilities, parking that can't fit at grade.
+
+  **Density derivation:**
+
+  The density scalar for a settlement is derived from existing systems.db data:
+
+  ```
+  base_density = SETTLED_DEFAULT  // 1,500/km² — the utility-cost floor
+  
+  // Economic pull increases density
+  if economic_role in [transit, commercial, manufacturing]:
+      base_density *= 1.5–2.0
+  if is_corp_hq_world:
+      base_density *= 1.5
+  if gate_adjacent:
+      base_density *= 1.3
+  
+  // Terrain constraint modulates
+  if terrain_constraint_factor > threshold:  // coastal strip, canyon, etc.
+      base_density *= 1.2–1.8
+  
+  // Wealth disperses (for specific districts within a settlement)
+  if district.prosperity_baseline > 0.8:
+      effective_density *= 0.4–0.6  // villa district within a dense city
+  
+  // Clamp to class boundaries
+  density_class = classify(effective_density)
+  ```
+
+  The exact multipliers are tunable. The structure — base at Settled, economic pull compresses, wealth disperses — is the locked architectural decision.
+
+  **Settlement footprint formula:**
+
+  ```
+  footprint_km2 = population / effective_density
+  district_count = ceil(footprint_km2 / 0.262)
+  grid_side = ceil(sqrt(district_count))
+  ```
+
+  Not all districts within the grid are built. A Settled-density village of 2,000 people covers ~1.3 km² = 5 districts in a 3×3 grid, but only 5 of 9 grid cells contain structures. The remaining 4 are open ground, agricultural land, or wilderness. The fill ratio increases with density class:
+
+  | Density class | Typical grid fill ratio | What fills the empty cells |
+  |---------------|------------------------|---------------------------|
+  | Frontier | 20-40% | Wilderness, private grounds, no development |
+  | Settled | 50-70% | Agricultural plots, utility corridors, planned expansion reserves |
+  | Established | 70-90% | Parks, low-density transition zones, institutional grounds |
+  | Dense | 90-100% | Nearly full — remaining gaps are intentional public space |
+  | Compressed | 100% | Full. No gaps. Every cell is built. |
+
+  **Reference calibration (real-world sanity check):**
+
+  | Real settlement | Pop | Real area | Real density | Model class | Model area | Match quality |
+  |----------------|-----|-----------|-------------|-------------|------------|---------------|
+  | Wadenoijen, NL | 695 | 0.10 km² | 6,950/km² | Dense | 0.12 km² | Close |
+  | Kerk-Avezaath, NL | 1,250 | 0.40 km² | 3,125/km² | Established | 0.42 km² | Close |
+  | Bisbee, AZ | 5,000 | 1.50 km² | 3,333/km² | Established | 1.67 km² | Close |
+  | Kiruna, SE | 17,000 | 11.40 km² | 1,491/km² | Settled | 11.33 km² | Near-exact |
+  | Périgueux, FR | 30,000 | 9.82 km² | 3,055/km² | Established | 10.00 km² | Near-exact |
+  | Tiel, NL | 39,000 | 13.00 km² | 3,000/km² | Established | 13.00 km² | Exact |
+  | Kanazawa DID, JP | 466,000 | 59.00 km² | 7,898/km² | Dense | 77.67 km² | Reasonable |
+  | Paris proper, FR | 2,040,000 | 105.00 km² | 19,429/km² | Compressed | 136.00 km² | Reasonable |
+
+  The model is calibrated to real-world settlements. Discrepancies come from the square-grid assumption (real settlements elongate along rivers, coasts, and roads) and from the discrete density class boundaries (continuous real densities mapped to five bins).
+
+  **Interaction with other D-records:**
+
+  - **D-194 (district mix):** District *types* are still determined by the three-component mix. Density determines how much *space* those districts occupy and how they're spaced.
+  - **D-197 (prosperity_baseline):** Disambiguates the wealth curve. Same low density reads as luxury (high prosperity) or absence (low prosperity).
+  - **D-201 (spatial hierarchy):** Tile scale amended from 0.5m to 1m with 0.5m subtile. Chunk real-world size doubles from 32m to 64m. All higher tiers unchanged.
+  - **D-215 (spatial arrangement patterns):** The five archetype patterns operate within the footprint that density determines. CompanyTown spine is longer at Settled density, compressed vertically at Dense density.
+  - **D-216 (BlockIrregularity):** Irregularity affects street grid geometry within a district. Density affects building height and spacing within that geometry. Orthogonal — a Dense district can be Organic (irregular streets, tall buildings) or Grid (regular streets, tall buildings).
+
+- **Rationale:** Population alone cannot determine settlement character. A village of 2,000 at medieval European density (Kerk-Avezaath, 3,200/km²) and a homestead spread of 2,000 at frontier density (400/km²) produce a 10× footprint difference. In the Reach, utility cost on virgin worlds is the dominant constraint, making Settled (~1,500/km²) the natural floor. The density scalar unifies footprint calculation, vertical pressure, and inter-building spacing into a single derivable parameter. The tile/subtile split preserves 0.5m visual fidelity for character movement and furniture placement without inflating the generation pipeline's spatial grid.
+- **Ticket:** (pending — implementation tickets to be created when cascade Tier 3/4 work begins)
+- **Raised by:** Jeroen + Claude, design session 2026-05-03. Grounded against real-world settlement data (Wadenoijen, Kerk-Avezaath, Uzès, Tiel, Périgueux, Kiruna, Kanazawa, Paris, Bisbee, Alice Springs, Brasília).
+- **Cross-reference:** D-194 (district mix), D-197 (prosperity_baseline), D-201 (spatial hierarchy — tile scale amendment), D-215 (spatial arrangement patterns), D-216 (BlockIrregularity)
+- **Dissent:** None
+
+---
+
+*80 decisions (D-001 through D-220, excluding gaps). Last updated: 2026-05-03 (D-220 — Settlement Density Model, design session)*