jpmschweitzer/settled-reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(decisions): D-189 brand layer architecture, D-190 volume calibration, D-191 Atlas Phase 3 scope

Browse Source 
Sprint 34 planning workshop output:
- D-189: Brand layer architecture — 8 categories, administered pricing model,
  halo/volume tiers, 10K minor brands, Gemma 2 naming, corp tax/GDP, verb ladder
- D-190: Brand volume calibration — population-relative scale for ~80B Reach
- D-191: Atlas of the Reach Phase 3 — terrain-aware city placement, sequential
  settlement growth, Gemma 2 geographic naming, 9 MVP overlays, heightmap viewer

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-04-10 21:04:41 +02:00
co-authored by Claude Opus 4.6
parent a9bd3ca408
commit b69645d35c
2 changed files with 222 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
decisions/architecture.md
+84 -1
View File
@@ -654,4 +654,87 @@ Technical foundation decisions that constrain implementation: engine, client-ser
---
*51 decisions. Last updated: 2026-04-06 (D-188 biome_summary → planet_class rename)*
### D-191: Atlas of the Reach — Phase 3 Scope and Pipeline
- **Date:** 2026-04-10
- **Decision:** Phase 3 delivers the Atlas of the Reach as an extension of the implant map (`implant/map`), adding planetary and regional zoom levels to the existing star map. The Atlas is a read-only spatial intelligence tool — the player looks at it to plan, not to execute actions. It serves dual purpose: gameplay information layer and world-texture content system.
**1. Zoom Hierarchy**
- 4 levels: Reach map (Phase 1, exists) → System view (orbital diagram, new) → Planetary view (hemisphere, new) → Regional view (hundreds-of-km, new — core Phase 3 deliverable)
- Atlas is the star map extended downward, not a separate app. `implant/map` at different zoom levels.
- Station maps and underground/cave city maps are DEFERRED to a later sprint (similar bounded generation pattern).
**2. Existing Foundation**
- 2,394 heightmap PNGs (1024×512 equirectangular, production quality)
- 2,394 markers.json files with procedural geometry (rivers, oceans, mountains) — all names null, all cities/roads/rail/POIs empty
- Planet-gen pipeline (`tooling/planet-gen/`) explicitly designed for Phase 3: `render_heightmap.py` line 26-27 defers cultural overlay to the atlas app
- 301 systems in systems.db, 273 inhabited bodies, 466 stations, 668 gate links
**3. Content Pipeline — Sequential Settlement Growth Simulation**
- City placement is terrain-aware and sequential (not scatter)
- Capital first: favor river mouths (~50% of capitals), scored by habitability (temperature, moisture, slope), coastal access, flat hinterland
- Subsequent cities: grow along rail corridors from capital (multi-source Dijkstra on cost grid)
- At cities 3–4: first foothold on a new continent if one exists (port city)
- Roads and rail: A* pathfinding on terrain cost grid (water=impassable, mountains=expensive, rivers=cheap corridors), minimum spanning tree — NO straight lines
- Quadrant distribution: after 2 cities in the same map quadrant, subsequent cities must prefer unoccupied quadrants unless those quadrants have no habitable land
- Variation: ±25% noise on scoring per seed — same terrain, different seed → different city network
- Settlement pattern modifies spacing (`urban_concentrated`=tight, `dispersed`=wide)
- All systems same depth, scaled by population. No manual tier classification.
**4. Naming Pipeline — Gemma 2 Voice Pipeline**
- Geographic names generated by the existing Gemma 2 voice pipeline (`server/src/voice/`, `sr-voice` binary)
- Input: body wiki page (`planet_class`, `cultural_corridor`, `settlement_pattern`, population, economic_role, atmospheric_tone) + corridor naming palette
- Output: culturally-appropriate names for rivers, oceans, mountains, regions, cities
- Corridor palettes: north_reach (Anglo-Saxon), south_reach (Iberian/Portuguese), east_reach (East Asian), west_reach (Germanic/Nordic), inner_orbit (institutional Latin/Anglo)
- Dual purpose: Phase 3 content generation AND quality/consistency test of the in-game LLM pipeline
- Batch throughput: ~80 min for all 2,394 bodies (placement) + ~40 min for 273 inhabited (naming). Parallelizable.
- Earth-name blocklist as post-processing safety net. Dedup check against full name corpus.
**5. Core Systems as Templates**
- Core systems (Gateway/Sirius, Groombridge/Lendel, etc.) hand-authored as templates
- Templates establish rulesets and quality bar for the generator
- Generator produces all remaining bodies → hand-author refinements over the batch
- Lendel (GJ 380c) is the first proving ground: arid, `urban_concentrated`, financial hub, 900M pop
**6. Atlas Panel Architecture**
- FULLSCREEN implant app (z=20), same component library as economics panel
- 3 navigation levels: system picker → orbital diagram → body atlas (heightmap + overlays)
- Heightmap displayed as `Texture2D` with pan/zoom
- Marker overlay renders cities, roads, rail, POIs, named features on top of heightmap
- Click city → City Data Panel (name, population, currency zone, Commission presence, shadow economy zone, gate distance, economics panel link)
- Economics panel link: click-through to Phase 2 economics panel pre-filtered to that node — primary Phase 2/3 integration point
**7. Overlay System — 9 MVP Overlays**
- 5 always-on: terrain, infrastructure, named features, gate/spaceport POIs, political zones
- 4 toggleable: population density, production zones, shadow economy zones (broad bands), corporate presence (Tier 1 only)
- Deferred overlays visible in toggle bar but locked with unlock requirements shown on hover (creates pull toward Phase 4+ systems)
- Maps to D-181 signal visibility ladder
**8. Settlement Data Model**
- markers.json schema per body: `cities` (name, lat/lon, population_tier, primary_function, gate_terminal, continent_id), `roads` (path polylines, connects), `railroads` (path polylines, connects), `pois` (name, kind, position), plus existing rivers/oceans/mountains with names filled
- Population tier → city count: `floor(log10(pop/1M))`, modified by `settlement_pattern`
- Gate terminal POI: at largest population center, sometimes scattered to a smaller one
- Moons: same depth as planets, scale with population
**9. Implementation Pipeline**
- Python: `tooling/planet-gen/generate_atlas.py` — reuses `planet_simulation.simulate()`, adds `city_placement.py`, `infrastructure_gen.py`, `gemma_naming.py`, `markers_writer.py`
- `make atlas-generate` runs the full batch. Deterministic per seed. Incremental (skips up-to-date bodies).
- Pipeline order: simulate terrain → analyze (continents, habitability, river mouths, cost grid) → place cities sequentially → generate infrastructure (A* MST) → name via Gemma 2 → write markers.json
**10. MVP Completion Criteria**
1. Navigation chain works end-to-end (Reach → system → planet → regional)
2. Regional map content complete for all inhabited bodies
3. Population-scaled depth (core systems rich, frontier sparse)
4. City data panel works (click any city, see data + economics link)
5. Economics panel integration works (link opens Phase 2 panel filtered to node)
6. All 9 MVP overlays present and functional
7. Atlas is read-only (no verbs execute from map)
8. Stations show at system view with mini data panel (no drill-down)
- **Rationale:** The heightmap pipeline was designed with Phase 3 in mind — 2,394 base maps exist. The critical path is content (filling empty markers.json arrays), not technology (the atlas panel follows the established implant component pattern). Sequential settlement growth simulation produces more realistic city networks than scatter placement — each city's location is informed by previous placements, terrain, and economic logic. Using the Gemma 2 voice pipeline for naming tests the in-game LLM quality while generating content. Population-scaled depth without manual tier classification keeps the pipeline simple and the authoring burden manageable.
- **Raised by:** Full planning team workshop, Sprint 34 (#748). Participants: Gestalt (systems design), Tyre (technical architecture), Miri (worldbuilding), with Jeroen as workshop participant.
- **Dissent:** None.
- **Cross-reference:** [D-166](architecture.md#d-166) (development cascade — Phase 3), [D-036](content.md#d-036) (Sova as canonical setting), [D-093](architecture.md#d-093) (Sova spatial layout), [D-094](architecture.md#d-094) (district hierarchy), [D-095](architecture.md#d-095) (Horizon stations), [D-170](architecture.md#d-170) (HUD visibility/implant apps), [D-169](architecture.md#d-169) (implant component library), [D-181](economics.md#d-181-signal-vocabulary) (signal vocabulary/visibility ladder), [D-174](economics.md#d-174-shadow-economy-layer) (shadow economy intensity), [D-175](economics.md#d-175-corporation-taxonomy-and-prerequisite) (corporation taxonomy), [D-138](architecture.md#d-138) (Gemma 2 voice pipeline)
---
*52 decisions. Last updated: 2026-04-10 (D-191 Atlas of the Reach — Phase 3 scope and pipeline)*
decisions/economics.md
+138 -1
View File
@@ -304,4 +304,141 @@ This domain covers: currency system, commodity taxonomy, shadow economy, corpora
---
*17 decisions (D-171–D-187), 1 rejected alternative (R-011). Domain: economics. Last updated: 2026-04-05.*
### D-189: Brand Layer Architecture
- **Date:** 2026-04-10
- **Decision:** The simulation supports a brand layer above the commodity tâtonnement. Brands are NOT commodities (D-185). They consume commodities as demand nodes and are priced through an administered pricing model with cultural premium curves. The brand layer serves dual purposes: economic simulation (demand nodes, pricing, GDP contribution) and queryable localized content for client UI (bar shelves, restaurant menus, shop displays, entertainment listings).
**1. Brand Taxonomy**
- 8 categories: `terroir`, `heritage_craft`, `tech_premium`, `cultural`, `service_premium`, `commodity_branded`, `design_heritage`, `platform_catalogue`
- `value_trajectory`: `appreciating` | `depreciating` | `timeless` (first-class field)
- 3 scale tiers for generated brands: local (1–3 systems), regional (corridor-scale), reach-wide budget (everywhere, corridor-neutral naming, no cultural premium)
**2. Pricing Model**
```
brand_price = max(price_floor, [base_cost × (1 + target_margin) + cultural_premium × (1 + veblen × scarcity)] × value_trajectory_factor × currency_factor)
```
- Cultural premium split into `identity_term` + `exotic_term` with `exotic_floor` to support 3 curve types: Scarcity-Distance (artisan), Dual-Peak (media/content), Aspirational Gradient (tech)
- Two-component scarcity: structural (`production_volume / addressable_demand` ratio, permanent) + situational (stockpile depletion, temporary)
- Veblen per-location derived: `veblen_base × income_quintile × corridor_affinity` — zero authoring cost
- `cost_passthrough_ratio`: insulates brand pricing from tâtonnement volatility (low 0.10–0.25 for terroir, high 0.50–0.75 for tech)
- `value_trajectory_factor`: appreciating goods gain value with vintage age, depreciating goods lose value with a floor, timeless = 1.0; updated per game-year
**3. Halo/Volume Tier Structure**
- Universal pattern: every notable brand has a halo product (defines identity ceiling) + volume tier(s) (makes the brand economically relevant at population scale ~80B)
- `halo_lift_factor`: volume tier borrows a fraction of the halo's cultural premium
- Direction inverts by category: terroir pushes scarcity up, tech/media pushes quality up from a mass base
- Brands without volume tiers are economically marginal regardless of prestige — population asymmetry (10B systems vs. 50k) makes this structurally necessary
**4. Brand Census**
- Notable (hand-authored): 120–170 corps with TOML records; ~28 currently named
- Minor (template-generated): ~10,000 brands from ~120–130 template definitions (35–40 archetypes × 3 sub-variants), corridor-specific naming patterns, 3 scale tiers
- Naming patterns: corridor-appropriate — north_reach = British/Australian inflection, east_reach = Korean/Japanese, west_reach = German/Dutch/Nordic, south_reach = Portuguese/Swahili, inner_corridor = pan-corridor neutral, frontier = founder surname + noun
- Queryable content: `brand_products JOIN corp_presence` filtered by location and `product_subcategory`; sub-millisecond at 10K+ rows — primary use case alongside economic simulation
**5. DB Schema**
- `brand_products`: `brand_product_id`, `corp_id`, `product_name`, `brand_category` (8 values), `value_trajectory`, `scarcity_class` (`capped` / `constrained` / `scalable` / `unlimited`), `product_subcategory`, `base_premium_multiplier`, `premium_floor`, `origin_system`, `terroir_locked`, `currency_denomination`, `shadow_viable`, `brand_tier` (`halo` / `volume`), `halo_brand_id` (for volume tiers)
- `brand_inputs`: `brand_product_id`, `commodity_id`, `quantity`
- `system_fiscal`: `system_id`, `corp_tax_rate`, `collection_efficiency` (derived from `shadow_economy_intensity`)
- `corp_financial_state` + `corp_lifecycle_events` tables for acquisition/startup lifecycle
- Composite index on `brand_products(corp_id, brand_category)` for UI queries
**6. Corp Tax & GDP**
- Corp tax = `revenue × (1 - category_deduction) × tax_rate × collection_efficiency`
- Category deductions: terroir 0.30, geological 0.20, tech 0.60, media 0.15, vehicles 0.55, apparel 0.45
- Tax flows to HQ system; GDP computed every 100 ticks
- `collection_efficiency = 1.0 - shadow_economy_intensity × 0.6`
- Visible line item when player owns a company
**7. Player Verb Ladder**
- 6 stages: Operate → Specialize → Distribute → Create → Scale → Corporate
- Founding verbs: `brand`, `register`, `market`
- Content verbs: `acquire-rights`, `royalty-contract`, `exclusive-window`
- Corporate verbs: `acquire`, `merge`, `spin-off`, `license-out`
- Temporal verbs: `cellar` (appreciating), `refresh` (depreciating), `license-legacy` (EOL)
- `authenticate` is the mechanically richest new verb — 3 service economies: expert appraisal (artisan), Commission inspection (tech/vehicles), Meridian rights lookup (content)
**8. Acquisition & Startup Lifecycle**
- Corp lifecycle states: Founded → Growing → Active → Distressed → Acquired/Dissolved
- Startup triggers: market gap, spin-off, player-founded, storyteller event
- Acquisition triggers: financial distress, strategic AI acquisition, player-initiated, hostile takeover event
- Player acquisition and mergers are in scope; if acquisition exists, startups must exist (or the well dries)
- Phase 2: corp health tracking as passive metric. Phase 3: lifecycle state machine, startup generation, player acquisition
**9. Events**
- `BrandPrestigeShock` via EconEvent port (D-180) — very occasional scandal events (pollution, fraud)
- Exponential decay with authored half-life
- Direct-vector only: events hit the brand's known vectors (commodity input price, production location); no indirect cascading beyond that
**10. Phase 2 Boundary**
- Phase 2 (this sprint cycle): brand corps as commodity demand stubs in tâtonnement, `brand_products` / `brand_inputs` / `system_fiscal` schema, `corp_financial_state` passive tracking, `generate_brands` pipeline
- Brand layer (post-Phase 2): pricing engine, awareness propagation, cultural preference curves, aging pipeline simulation, lifecycle state machine, player acquisition verbs
**11. Named Brand Corps (~28)**
| Corp | Category | Origin |
|------|----------|--------|
| Calloway Distillery | terroir | north_reach |
| VGV | terroir | west_reach |
| thrds | heritage_craft | north_reach |
| Bífröst Marmor | terroir | north_reach / Compact |
| Destilaria Confluência | terroir | south_reach |
| Lento | terroir | south_reach |
| Veldfontein Botanical | terroir + heritage_craft | south_reach |
| Comptoir Lendel | terroir + service_premium | inner_core |
| Maison Cinq | design_heritage | inner_core / Gateway |
| MVG (Manifattura Veicoli Gherardi) | design_heritage | west_reach Italian |
| Higashiyama Vehicle Engineering | tech_premium + design_heritage | east_reach |
| Rijdbaar Personal Mobility | design_heritage | west_reach / Compact |
| Byeolbit Entertainment | cultural + platform | east_reach |
| Leerfeld Records | cultural | west_reach / Compact |
| Vuma Sound | cultural | south_reach |
| Resonance Premium | platform_catalogue | inner_core |
| Dalbit Systems | tech_premium + platform | east_reach |
| Arclamp | cultural + design_heritage | inner_core |
| Kellervolk | cultural | Compact |
| Hangang Studio | platform_catalogue | east_reach |
| Hanyang Precision | — (Tier 1, branded_products) | — |
| Sato Medical | — (Tier 1, branded_products) | — |
| Takamori Lattice | — (Tier 1, branded_products) | — |
| Thalassa Resort | — (Tier 1, branded_products) | — |
| Somatic Futures | — (Tier 1, branded_products) | — |
| The Registry | — (Tier 1, branded_products) | — |
| Meridian Risk | — (Tier 1, branded_products) | — |
- **Rationale:** Administered pricing is the correct model because brands violate all three tâtonnement assumptions: heterogeneity (Calloway ≠ VGV ≠ generic spirits), supply inelasticity (terroir production cannot respond to price signals per D-177), and Veblen demand effects (prestige goods can have upward-sloping demand). The one-way interface (commodity prices → brand input costs; brand output prices do NOT feed back into tâtonnement) is architecturally clean and matches the D-178 layer model. The identity/exotic split in cultural premium is the minimal structural addition needed to produce all three observed pricing curves (Scarcity-Distance, Dual-Peak, Aspirational Gradient). Population asymmetry (~80B total Reach population, systems ranging from 10B to <50k) makes the halo/volume tier pattern structurally necessary — brands from tiny worlds are astronomically exclusive and need volume derivatives to be economically relevant.
- **Raised by:** Full planning team workshop, Sprint 34 (#811).
- **Dissent:** None.
- **Cross-reference:** [D-185](#d-185-brands-are-not-commodities) (brands are not commodities), [D-184](#d-184-commodity-catalog-36-types) (commodity catalog), [D-177](#d-177-productivity-constraints-lore-derived) (productivity constraints), [D-175](#d-175-corporation-taxonomy-and-prerequisite) (corporation taxonomy), [D-178](#d-178-economic-model-architecture) (economic model architecture), [D-180](#d-180-event-input-port) (event input port), [D-181](#d-181-signal-vocabulary) (signal vocabulary), [D-173](#d-173-commodity-taxonomy) (commodity taxonomy), [D-171](#d-171-three-currency-system) (three-currency system), [D-131](scope.md#d-131-economic-verb-vocabulary) (economic verb vocabulary), [D-118](scope.md#d-118-small-business-owner-starting-state) (small business owner starting state)
---
### D-190: Brand Volume Calibration — Population-Relative Scale
- **Date:** 2026-04-10
- **Decision:** All brand production and distribution volume numbers must be specified relative to a reference population, not as absolute counts. Volume without a reference population is not meaningful at Reach scale:
- **Scale reference table (~80B Reach):**
- Single-system local phenomenon: 100M–500M (1–5% of a 10B system)
- Corridor-known hit: 250M–1B (~0.5% of corridor addressable population)
- Reach-wide genuine hit: ~1B (1 in 100 Reach population)
- All-time Reach canonical: 2B–5B (1 in 20–50 Reach population)
- **Earth rule of thumb:** multiply Earth-scale phenomenon volumes by 12–15× for comparable cultural penetration. A 100M-seller on Earth ≈ 1.2–1.5B in the Reach.
- **40M benchmark:** 40M units/streams Reach-wide = 0.04% penetration — a cult hit or successful regional release, not a cultural touchstone. 40M within a single large system (10B population) = 0.4% — respectable but not legendary.
- **Authoring rule:** wiki volume figures for media brands and any good with `brand_category = cultural` must include a `reference_population` annotation alongside the count. "40M" is incomplete; "40M (west_reach corridor, ~10B addressable)" is correct. This applies to corporation production ceilings, media distribution figures, and market penetration estimates in wiki pages and TOML files.
- **Structural scarcity principle:** for physical brand goods, production volume only has meaning relative to addressable demand. The `structural_scarcity_base` parameter in the brand pricing layer (D-189) is derived from this ratio: `1.0 - min(1.0, annual_volume / (addressable_population × demand_rate))`. A 12,000-unit/year artisan product against 100M addressable consumers yields structural_scarcity_base ≈ 0.88 — perpetually near-maximum scarcity regardless of local stockpile state. This scarcity floor is permanent, not situational.
- **Rationale:** The Reach's population asymmetry (core systems 10B+, frontier systems under 50K) makes absolute volume numbers meaningless without a reference population. Without an explicit calibration rule, brand and media content significance will be systematically miscalibrated across all authoring. The structural scarcity principle connects volume calibration to the administered pricing model: a brand's Veblen premium floor is derived from the same population-relative ratio, ensuring that pricing and authoring are grounded in the same underlying reality.
- **Raised by:** Jeroen (population asymmetry insight), Burnelli-Sheldon (structural scarcity derivation and calibration table), Sprint 34 Workshop #811.
- **Dissent:** None.
- **Cross-reference:** [D-189](#d-189-brand-layer-architecture) (structural_scarcity_base parameter), [D-177](#d-177-productivity-constraints-lore-derived) (lore-constrained production ceilings), [D-175](#d-175-corporation-taxonomy-and-prerequisite) (corporation production volumes)
---
## Rejected Alternatives
### R-011: Single currency for Phase 2 (rejected)
- **Date:** 2026-04-05
- **Proposed by:** Burnelli-Sheldon (economist), Sprint 32 Workshop #796 Round 1
- **Proposal:** Use a single currency for the Phase 2 economics simulation to reduce model complexity. Exchange rate mechanics could be added in a later phase.
- **Rejected because:** Three currencies create structural economic bloc tension as an emergent property of initialization — no event generation required. The Tractus/Mark divide maps directly to the Assembly vs. Compact political divide that is already canonical lore. Deferring currencies to a later phase would require retrofitting political geography into an already-running simulation. The complexity cost of three currencies is low; the design value is high.
- **Raised by:** Lead directive overruling the recommendation.
---
*19 decisions (D-171–D-187, D-189–D-190), 1 rejected alternative (R-011). Domain: economics. Last updated: 2026-04-10.*