diff --git a/decisions/architecture.md b/decisions/architecture.md index 7f986b70a..3a33d0e8e 100644 --- a/decisions/architecture.md +++ b/decisions/architecture.md @@ -1667,6 +1667,7 @@ Technical foundation decisions that constrain implementation: engine, client-ser - **Raised by:** Burnelli, economic-built-world workshop round 2, 2026-05-25. - **Cross-reference:** [D-194](#d-194) (district mix — upstream), [D-184](content.md#d-184) (commodity catalog — amended), [D-199](#d-199) (read-set — amended), [D-220](#d-220) (density), [D-197](#d-197) (prosperity), [D-142](content.md#d-142) (zone types — downstream), [D-176](#d-176), [D-180](#d-180) (EconEvent — overlay trigger), [D-198](#d-198) (condition overlay — amended), [D-229](#d-229) - **Dissent:** None +- **Re-amended 2026-05-31 (D-237 — authored specialization layer):** The settlement's `dominant_bulk_class` and `dominant_production_ubiquity` are now sourced from the authored specialization layer (D-237) rather than derived directly from the highest-output production chain. Derivation chain: (1) If `system_economy.economic_specialization` is authored → resolve via `specialization_vocabulary(economic_specialization)` → `(commodity_id, production_ubiquity_override)` → `(BulkClass, ProductionUbiquity)`. Use the vocabulary-specified `ProductionUbiquity` (which may override the catalog default per the equal-or-higher rule). (2) If `economic_specialization` is NULL → run the deterministic-varied heuristic (D-237 §fallback: seed-hashed weighted draw over the vocabulary using `economic_role` + corp HQ signals + noise term) → same projection. In both cases the resolved `(BulkClass, ProductionUbiquity)` populates `CityGenerationContext.dominant_bulk_class` and `CityGenerationContext.dominant_production_ubiquity`. Frozen-amber constraint unchanged: `fill_chunk(ctx, seed)` holds no `PressureState` reference. Within-system body variation (weighted draw over body-level candidates anchored to system commodity) remains seed-hashed. **Groombridge clarification:** The vocabulary expresses district-level character. Singular MonopolySource-class landmarks within a Specialist district (e.g. GSH within Groombridge's `financial_hub` cluster) are expressed via D-222 multi-block reservation + D-232 hero-element pin, not via composite vocabulary values. --- @@ -1700,4 +1701,26 @@ Technical foundation decisions that constrain implementation: engine, client-ser --- -*95 decisions (D-001 through D-235, excluding gaps). Last updated: 2026-05-25 (economic-built-world workshop rounds 2–3 — D-229 building-property-tag schema, D-230 FillChunk execution, D-231 door/interior contract, D-232 architecture-flavor as an economically-gated/seed-drawn/wiki-biased trait-template catalog [round-3 rewrite], D-233 economic block-fill, D-234 morphology→street, D-235 exterior visual grammar + asset fallback hierarchy). D-101/D-104/D-105/D-107 superseded in part by D-232.* +### D-237: Authored per-system specialisation layer — `economic_specialization` + `cultural_specialization` + `dominant_faction` +- **Date:** 2026-05-31 +- **Decision:** Each inhabited star system carries three authored per-system identity fields, statically compiled from `wiki/economics/system_specialization.toml` at build time via `import_economics.py`. These fields constitute the lore-authored identity layer above the heuristic and are the primary source for D-233/D-232/D-214 generator inputs for named systems. All three fields are static (t=0), deterministic (D-010), and NULL-safe (NULL = heuristic fallback runs). + + **(1) `system_economy.economic_specialization TEXT` (new column).** A 27-value curated vocabulary compiled from `wiki/economics/specialization_vocabulary.toml` into a `specialization_vocabulary` DB table. Each value maps to `(commodity_id, production_ubiquity_override_or_null)` → `(BulkClass, ProductionUbiquity)` for D-233. Scale is encoded in the value (no separate scale column): `breadbasket` pins `ProductionUbiquity = Specialist` where the catalog default would be `Ubiquitous`; `terroir_agriculture` pins `MonopolySource`. Equal-or-higher rule: a `production_ubiquity_override` may only be equal or higher concentration than the commodity's global default (CI hard error V-SES-03). Authored for ~80–100 named systems; deterministic-varied heuristic fallback for ~200 unnamed systems (seed-hashed weighted draw over the vocabulary: W_ROLE_PRIMARY=8,000 bps, W_CORP=5,000 bps, W_NOISE=400 bps to every vocabulary value; same seed+system_id always produces the same value; the noise term ensures ~5–10% of unnamed systems draw an off-primary value, preventing all unnamed agricultural worlds from being identical). + + **(2) `system_economy.cultural_specialization TEXT` (new column).** Directs D-232's template pool when a system's cultural character diverges from corridor baseline. Single field carrying two value sub-types: *activity/character values* (`agrarian`, `industrial_heritage`, `institutional`, `scholarly`, `artistic`, `financial_technocratic`, `cosmopolitan`, `compact_cooperative`, etc.) and *heritage-type values* (`scottish`, `vietnamese`, `zulu`, `afrikaans_cape`, `tagalog`, `chinese`, `italian_northern`, `french_provencal`, `norse_compact`, etc.). Heritage values take precedence when both apply. `NULL` = use corridor default (D-232 existing algorithm). Authored for ~60–100 systems where the corridor default would produce wrong D-232 architectural draws in Phase 4 (not a thin Phase 6 concern: a Vietnamese-founded system in the east_reach Korean/Japanese corridor draws the wrong templates without an explicit pin). Does NOT replace `system_culture.cultural_register` (prose NPC/dialogue voice); consumed by the physical generator only. + + **(3) `system_factions.dominant_faction TEXT` — populated, not added.** Column already exists (D-199 field 4); VALUES for named systems are authored in this pass via `system_specialization.toml`. 8-value vocabulary: `concord_assembly | compact | compact_sympathetic | syndic_dominant | veil_institute | independent | disputed | mixed`. `lattice_commission` is dropped — the Commission is a regulatory body under Assembly authority, not a governing faction; ACB and Bastion are `concord_assembly`. Authored for ~40–60 named systems; existing Commission-presence + currency-zone derivation serves as fallback. + + **Groombridge landmark mechanism:** Where a system's authored identity includes a singular MonopolySource-class institution within a Specialist-scale district (Groombridge: `financial_hub`/Specialist + GSH clearing house), the district character is encoded as Specialist in the vocabulary. The singular landmark is expressed via D-222 multi-block reservation + D-232 `atlas_body_trait_bias` hero pin — not via a composite vocabulary value. The vocabulary expresses district-level character; landmark-level identity is the D-232/D-222 mechanism. + + **CI guardrails:** 6 hard errors (vocabulary FK integrity, inhabitance coverage, production_ubiquity monotonicity, vocabulary constraint for all three fields); 8 soft warnings (MonopolySource review list, distribution balance, prose/field divergence, D-172 faction/currency alignment, Compact monoeconomy flag, authoring gap lists). Full CI spec in `docs/workshops/system-economic-specialization/workshop-outcomes.md §8`. + + **Source:** `wiki/economics/system_specialization.toml` (per-system entries) + `wiki/economics/specialization_vocabulary.toml` (vocabulary definition). Both added to `IMPORT_ECONOMICS_SOURCES` for meta-stamp tracking. `system_economy` gains two new columns via `COLUMN_MIGRATIONS` in `import_economics.py`; `specialization_vocabulary` is a new read-only reference table. +- **Rationale:** The pre-existing D-233 heuristic (`economic_role` + corp HQ + `planet_class` → dominant commodity) fails predictably for: (1) output-vs-input confusions (Cygni B: heuristic sees ore inputs, not freight_hauler outputs); (2) political mandates (Groombridge: financial infrastructure is an institutional choice, not geographic necessity); (3) terroir-locked production (D-177 systems: catalog defaults are globally ubiquitous, not locally monopolistic); (4) service economies (Prometheus, Keid: no heuristic path from available signals to the correct identity). The three-field authored layer resolves all four failure modes. Three fields are the minimum that changes how a system reads without redundancy: economic → D-233 block fill, cultural → D-232 template selection, faction → D-214 political archetype. `cultural_specialization` is a Phase 4 correctness requirement, not Phase 6 enrichment. +- **Raised by:** System economic-specialization workshop, 2026-05-31. Burnelli-Sheldon (schema, vocabulary, CI, fallback algorithm), Miri (must-pin list, scale gap, D-177 terroir pins, cultural heritage vocabulary), Paula (faction vocabulary, Compact rules, heritage-divergence cultural scope, D-172 compliance), human checkpoint (dual-axis design, scale-in-vocabulary, faction authored, Groombridge landmark mechanism, deterministic-varied fallback). +- **Dissent:** None. +- **Cross-reference:** [D-233](#d-233) (re-amended — economic block-fill now sourced from this layer), [D-184](content.md#d-184) (commodity catalog), [D-199](#d-199) (CityGenerationContext read-set — extended), [D-232](#d-232) (architecture-flavor template draw — consumes `cultural_specialization`), [D-214](#d-214) (PoliticalArchetype — consumes `dominant_faction`), [D-172](content.md#d-172) (currency zone alignment — `dominant_faction = compact` validates), [D-174](#d-174) (shadow economy intensity — `compact` elevates), [D-177](content.md#d-177) (productivity constraints — informs monopolistic pins), [D-220](#d-220) (density), [D-197](#d-197) (prosperity), [D-222](#d-222) (multi-block reservation — Groombridge landmark mechanism), [D-178](#d-178) (rolling economy — not touched; this is t=0 authored layer only) + +--- + +*96 decisions (D-001 through D-237, excluding gaps). Last updated: 2026-05-31 (system-economic-specialization workshop — D-237 authored per-system specialization layer: `economic_specialization` + `cultural_specialization` + `dominant_faction`; D-233 re-amended to source from D-237 authored layer).* diff --git a/docs/diagrams/architecture/specialization-layer.d2 b/docs/diagrams/architecture/specialization-layer.d2 new file mode 100644 index 000000000..e4ffb98a7 --- /dev/null +++ b/docs/diagrams/architecture/specialization-layer.d2 @@ -0,0 +1,83 @@ +# D-237: Authored per-system specialisation layer and its consumers +# Shows the three authored fields, their sources, and downstream generator consumers. + +direction: right + +source: "wiki/economics/\nsystem_specialization.toml" { + shape: document + style.fill: "#e8f4e8" +} + +vocab: "wiki/economics/\nspecialisation_vocabulary.toml" { + shape: document + style.fill: "#e8f4e8" +} + +db: "systems.db" { + shape: cylinder + style.fill: "#f0f0f0" + + econ: "system_economy\n.economic_specialization" + cult: "system_economy\n.cultural_specialization" + fact: "system_factions\n.dominant_faction" + specvocab: "specialization_vocabulary\n(compiled reference table)" +} + +fallback: "Deterministic-varied\nheuristic fallback\n(seed-hashed weighted draw\nW_ROLE=8000, W_CORP=5000,\nW_NOISE=400)" { + shape: hexagon + style.fill: "#fff3cd" +} + +d233: "D-233\nEconomic block-fill\n(BulkClass × ProductionUbiquity\n→ coverage, vocabulary,\noperations surface)" { + shape: rectangle + style.fill: "#dce8f5" +} + +d232: "D-232\nArchitecture-flavor\n(template pool selection\nfor corridor vs\nheritage-divergent systems)" { + shape: rectangle + style.fill: "#dce8f5" +} + +d214: "D-214\nPoliticalArchetype\n(settlement spatial layout:\ncommission radial /\ncorporate campus /\ncooperative distributed)" { + shape: rectangle + style.fill: "#dce8f5" +} + +d174: "D-174\nShadow economy\nintensity" { + shape: rectangle + style.fill: "#e8dce8" +} + +d172: "D-172\nCurrency zone\nvalidation" { + shape: rectangle + style.fill: "#e8dce8" +} + +groombridge: "Groombridge\nlandmark mechanism:\nfinancial_hub (Specialist)\n+ GSH hero-element\nvia D-222 + D-232 pin" { + shape: oval + style.fill: "#fde8cc" +} + +source -> db.econ: "import_economics.py\nimport_system_specialization()" { + style.stroke-dash: 3 +} +source -> db.cult: { + style.stroke-dash: 3 +} +source -> db.fact: { + style.stroke-dash: 3 +} +vocab -> db.specvocab: "compiled reference" { + style.stroke-dash: 3 +} + +db.econ -> d233: "primary source\n(authored wins)" +db.econ -> fallback: "NULL → heuristic" +fallback -> d233 + +db.cult -> d232: "D-232 template\npool override" +db.fact -> d214 +db.fact -> d174 +db.fact -> d172 + +d233 -> groombridge: "Specialist district\ncharacter" diff --git a/docs/diagrams/architecture/specialization-layer.png b/docs/diagrams/architecture/specialization-layer.png new file mode 100644 index 000000000..cd31d1cec Binary files /dev/null and b/docs/diagrams/architecture/specialization-layer.png differ