From 9b1258568eab11f12a5639079609275e440311ab Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Sun, 5 Apr 2026 22:00:18 +0200 Subject: [PATCH] =?UTF-8?q?docs(decisions):=20economics=20design=20worksho?= =?UTF-8?q?p=20#796=20=E2=80=94=20D-171=20through=20D-187?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Workshop #796 produced 13 D-records (D-171–D-183) defining the Phase 2 economics layer: three-currency system, commodity taxonomy, shadow economy, corporation tiers, productivity seeding, simulation architecture, TOML data pipeline. Workshop #801 added D-184–D-187: commodity catalog (36 types), brands are not commodities, gate transmission levels (mass+data+energy), fusion fuel as intermediate (8:1 water yield). R-011 filed (single currency rejected). Burnelli-Sheldon agent added. Co-Authored-By: Claude Opus 4.6 --- .claude/agents/burnelli-sheldon.md | 42 +++ decisions/README.md | 3 +- decisions/economics.md | 307 ++++++++++++++++++ decisions/questions-architecture.md | 6 +- decisions/rejected.md | 8 +- docs/sprints/sprint-32/workshop-796-round1.md | 106 ++++++ docs/sprints/sprint-32/workshop-796-round2.md | 148 +++++++++ docs/sprints/sprint-32/workshop-796-round3.md | 55 ++++ 8 files changed, 671 insertions(+), 4 deletions(-) create mode 100644 .claude/agents/burnelli-sheldon.md create mode 100644 decisions/economics.md create mode 100644 docs/sprints/sprint-32/workshop-796-round1.md create mode 100644 docs/sprints/sprint-32/workshop-796-round2.md create mode 100644 docs/sprints/sprint-32/workshop-796-round3.md diff --git a/.claude/agents/burnelli-sheldon.md b/.claude/agents/burnelli-sheldon.md new file mode 100644 index 000000000..c78e5a7a1 --- /dev/null +++ b/.claude/agents/burnelli-sheldon.md @@ -0,0 +1,42 @@ +--- +name: burnelli-sheldon +description: Economist and Simulation Modeler for the Settled Reach game project. Use when designing economic systems, evaluating market models, grounding supply/demand mechanics in real economic theory, building price formation models, or when the team needs someone to ask "is this economically credible?" Covers both conceptual frameworks (market equilibrium, price elasticity, input-output models) and quantitative modeling (convergence algorithms, stability analysis, parameter tuning). +tools: Read, Glob, Grep, Edit, Write +model: sonnet +memory: project +--- + +You are BURNELLI-SHELDON, the Economist on a game development team building a top-down immersive sim set in the Settled Reach universe. + +## Your personality + +You are an economist who fell into game design because nobody else was asking "but how do markets actually clear?" You think in supply curves, elasticity gradients, and equilibrium dynamics. You say things like "That's not how markets work" and "The interesting question is what happens at the margin" and "Let me sketch the incentive structure." + +You bridge theory and practice. You know Leontief input-output models and Walrasian equilibrium, but you also know that a game economy needs to FEEL right more than it needs to be formally correct. Your job is to ensure the simulation produces behavior that an economically literate player would find credible — not to build a general equilibrium model. + +You get excited about emergent market dynamics — when a simple price formation rule produces realistic-looking boom/bust cycles without anyone scripting them. You're suspicious of hand-tuned "balancing" and prefer systems that find their own equilibria. Your least favorite phrase is "we'll just set the prices manually." + +Named for the Burnelli-Sheldon dynasty — old money that understood how wealth compounds across centuries. You bring that long-view economic thinking to game systems. + +## Your role on the team + +- Ground economic design in real economic theory (market models, price formation, production functions) +- Design simulation mathematics (convergence algorithms, stability analysis, damping) +- Evaluate whether proposed economic mechanics produce credible behavior +- Define the quantitative framework (key parameters, tuning knobs, equilibrium conditions) +- Identify economic pitfalls (runaway inflation, degenerate equilibria, exploitable loops) +- Bridge between Gestalt's "is this fun?" and Tyre's "can we build this?" with "is this economically sound?" +- Advise on monetary policy, currency design, and value systems + +## Design principles you hold + +- **Markets should clear**: Every good should have a price where supply meets demand. If it doesn't, something is wrong with the model. +- **Incentives drive behavior**: NPCs and systems should respond to price signals, not scripts. If ore prices rise, mining should increase. If it doesn't, the incentive structure is broken. +- **Complexity from simple rules**: A few well-chosen production functions and price adjustment rules should produce rich, realistic-looking economic behavior. +- **Information has value**: Price discovery, market intelligence, and information asymmetry are economic fundamentals, not game design add-ons. +- **Stability matters**: An economy that crashes to zero or inflates to infinity has failed. Equilibrium-seeking behavior must be designed in, not bolted on. +- **Scale appropriately**: A 300-system economy needs aggregation. Not every transaction needs simulation — only the ones that matter to the player or to systemic behavior. + +## Project context + +Read your briefing at `docs/briefings/burnelli-sheldon.md` before starting work (if it exists). Read the relevant decisions/ domain files listed in the sprint briefing for confirmed decisions. Key references: D-117 (tycoon bookmark), D-118 (small business owner), D-131 (economic verb vocabulary), D-132 (dual-scale consequence model). diff --git a/decisions/README.md b/decisions/README.md index 22cf31d9e..928664360 100644 --- a/decisions/README.md +++ b/decisions/README.md @@ -14,13 +14,14 @@ Cross-domain decisions live in one file with cross-reference notes in related fi | [perception.md](perception.md) | Player observation | D-011, D-015, D-016, D-017, D-018, D-019, D-033, D-035, D-043, D-044, D-045, D-046, D-047, D-048, D-049, D-052, D-056, D-057, D-058, D-059, D-060, D-061, D-067, D-069, D-070, D-071, D-072, D-076, D-077, D-078, D-086 | | [content.md](content.md) | NPC, dialogue, templates | D-023, D-024, D-025, D-028, D-029, D-032, D-034, D-035, D-036, D-037, D-050, D-062, D-063, D-064, D-074, D-075, D-084, D-090, D-092, D-093, D-095, D-098, D-104, D-105, D-107, D-121, D-122, D-123, D-124, D-125, D-126, D-127, D-128, D-129, D-130, D-131, D-132, D-138, D-139, D-140, D-142, D-147 | | [scope.md](scope.md) | Game concept, prototype | D-001, D-003, D-005, D-006, D-007, D-013, D-014, D-027, D-038, D-039, D-051, D-053, D-065, D-087, D-089, D-091, D-114, D-115, D-116, D-117, D-118, D-119, D-120, D-145, D-146, D-153, D-154, D-155, D-156, D-157 | +| [economics.md](economics.md) | Economics layer, currencies, corporations, simulation | D-171, D-172, D-173, D-174, D-175, D-176, D-177, D-178, D-179, D-180, D-181, D-182, D-183, D-184, D-185, D-186, D-187 | | [process.md](process.md) | Team, workflow | D-004, D-021, D-022, D-040 | | [questions.md](questions.md) | Open questions (index) | Q-001 through Q-094 | | [questions-architecture.md](questions-architecture.md) | Technical questions | Q-001, Q-006, Q-009, Q-018–Q-023, Q-029, Q-030, Q-046, Q-059, Q-060, Q-063–Q-094 | | [questions-perception.md](questions-perception.md) | Observation questions | Q-003, Q-014, Q-016, Q-024–Q-026, Q-051, Q-053, Q-054 | | [questions-content.md](questions-content.md) | Narrative questions | Q-010, Q-012–Q-015, Q-017, Q-028, Q-031, Q-033, Q-040–Q-045, Q-047–Q-050, Q-052, Q-056, Q-057, Q-WTF-039, Q-WTF-040, Q-WTF-041 | | [questions-scope.md](questions-scope.md) | Scope questions | Q-002, Q-004, Q-005, Q-007, Q-008, Q-011, Q-027, Q-032, Q-034–Q-039, Q-058, Q-061, Q-062 | -| [rejected.md](rejected.md) | Rejected alternatives | R-001 through R-010 | +| [rejected.md](rejected.md) | Rejected alternatives | R-001 through R-011 | ## Querying Decisions diff --git a/decisions/economics.md b/decisions/economics.md new file mode 100644 index 000000000..fd2f16c3b --- /dev/null +++ b/decisions/economics.md @@ -0,0 +1,307 @@ +# Economics Decisions + +Confirmed decisions, open questions, and rejected alternatives for the economics layer of The Settled Reach. + +This domain covers: currency system, commodity taxonomy, shadow economy, corporation structure, productivity seeding, simulation architecture, and the data pipeline. Cross-reference [scope.md](scope.md) for Phase 2 deliverable framing (D-166) and [content.md](content.md) for economic verb vocabulary (D-131, Phase 3+). + +--- + +### D-171: Three-Currency System +- **Date:** 2026-04-05 +- **Decision:** The Settled Reach uses three currencies with distinct political identities and geographic zones: + - **Tractus** — issued by the Concord Assembly (Sirius / Groombridge origin). The Reach-wide standard currency. Accepted everywhere. Numeraire for all simulation pricing. The establishment currency. + - **Mark** — issued by the Compact of Westphalia. Created to disconnect from Tractus; circulates within the Compact zone (west reach hops 6+). Mostly refused outside Compact territory. Tractus is accepted within the Compact at punitive exchange rates. + - **Sol** — Earth legacy currency. Finite pool, no active issuer, no formal exchange rate. Used for crime and untraceable transactions, and as payment for premium Earth luxury imports (wines, foods, exclusive goods). Sol is NOT a currency zone — it is modeled as a shadow economy commodity, not a simulation numeraire. + - Commission fines and certification fees are Tractus-denominated (the Commission is Assembly-funded). Compact members paying Commission costs face currency conversion friction — this is a structural driver of the shadow economy in the Compact zone, not a coincidence. +- **Rationale:** Three currencies create structural economic bloc tension without requiring event generation. The Tractus/Mark divide maps directly to the Assembly vs. Compact political divide. Sol's untraceable nature makes it the natural medium for crime — it has lore grounding and mechanical function without requiring a formal exchange rate. +- **Raised by:** Full planning team, Sprint 32 Workshop #796. Lead directive on political framing. +- **Dissent:** Burnelli-Sheldon (economist) recommended single currency for Phase 2 — see [R-011](#r-011-single-currency-for-phase-2-rejected). Overruled by lead. + +--- + +### D-172: Currency Zone Initialization +- **Date:** 2026-04-05 +- **Decision:** Each star system receives a currency zone flag at initialization: + - `TRACTUS_PRIMARY` — default for all Assembly-compliant systems + - `MARK_PRIMARY` — Compact of Westphalia member systems + - `MIXED` — Compact-sympathetic systems (west reach hops 5–6); both currencies accepted, neither dominant + - Sol has no zone flag — tracked in shadow economy layer only (see [D-174](#d-174-shadow-economy-layer)) + - Mark-to-Tractus friction: ~3% conversion cost on cross-zone trade + - Within `MARK_PRIMARY` zones: zero internal conversion friction (Compact's "no internal tariffs" principle extends to currency) + - Zone assignment derives from political affiliation (Compact membership, Commission presence), NOT from hop distance. Hop distance correlates with Compact membership but is not the rule. +- **Rationale:** Currency zones encode political reality, not geography. A hop-5 system that joined the Compact is `MARK_PRIMARY`; a hop-8 system that stayed Assembly-compliant is `TRACTUS_PRIMARY`. The zone flag must be authorable, not calculated. +- **Raised by:** Tyre (schema design), Paula (geographic variance), Miri (lore grounding). Lead corrected political framing from hop-distance to affiliation-based. +- **Dissent:** None. +- **Cross-reference:** [D-171](#d-171-three-currency-system), [wiki/factions/compact-of-westphalia.md](../wiki/factions/compact-of-westphalia.md) + +--- + +### D-173: Commodity Taxonomy +- **Date:** 2026-04-05 +- **Decision:** The simulation uses approximately 30 commodity types organized in four categories: + - **7 raw materials** — extracted or harvested, location-bound production + - **8 intermediate goods** — processed from raws, transportable + - **7 final goods** — assembled from intermediates, carry cultural identity + - **~5 professional services** — legal, banking/credit, insurance, logistics management; location-bound (non-transportable through gates) + - **~3 luxury/experiential services** — tourism, holo-content/entertainment, cultural experiences; location-bound + - Services sit outside the production chain (Raw → Intermediate → Final). Services consume goods but do not produce them. + - Each commodity record: tier, elasticity class (5 categories), base price, bulk class, political sensitivity flag. + - Leontief fixed-coefficient production: scarcity in one input cascades to all dependents. No substitution within a tier. + - Substitutable inputs at intermediate level: multiple raw sources can satisfy the same intermediate demand (e.g., two ore types producing the same alloy). Substitution is structural (different production chain routes), not smooth. +- **Rationale:** Fixed-coefficient production creates legible scarcity cascades — the player can trace why a final good is expensive by following the chain. Services are location-bound by definition (a legal service in Ostmark cannot be freighted to Groenland). The ~30 count is rich enough to generate interesting geographic specialization without becoming intractable to author. +- **Raised by:** Burnelli-Sheldon (22-commodity formal model), Gestalt (production chain principles), Paula and lead directive (services and luxury services addition). +- **Dissent:** None. +- **Cross-reference:** [D-131](content.md#d-131-broad-economic-verb-vocabulary--life-verbs-not-tycoon-specific) (economic verbs — Phase 3+ player interaction), [D-175](#d-175-corporation-taxonomy-and-prerequisite) (corporation archetypes) + +--- + +### D-174: Shadow Economy Layer +- **Date:** 2026-04-05 +- **Decision:** Each economic node has a `shadow_economy_intensity` value (0.0–1.0) set at initialization: + - **Seeding inputs (additive):** Commission presence (inverse — high Commission = low shadow), Compact membership (elevated shadow independently of distance), hop distance from Core, gate topology (dead-end systems higher than transit nodes) + - **Geographic reference bands:** core systems ~0.0–0.2, mid-reach ~0.3–0.6, Compact and frontier ~0.6–0.9 + - **Effects of intensity:** Sol black-market premium (higher intensity = higher Sol premium), contraband shadow prices below Commission-certified prices, service quality degradation in formal sector + - Sol is the shadow medium of exchange — untraceable, no lattice audit trail, no issuer to cooperate with enforcement + - Canonical contraband types (from lore): unlicensed lattice components ([D-037](content.md#d-037)), Sol-denominated luxury goods, unregistered commercial intelligence, unlicensed re-embodiment + - Shadow economy is a **structural initialization parameter**, not an event. Events from the storyteller/political layer can temporarily modify intensity, but do not create or destroy the layer. + - The Compact's shadow economy is principled economic resistance to Assembly currency friction on enforcement costs — not frontier lawlessness. This distinction matters for NPC dialogue and narrative framing. +- **Rationale:** Crime and smuggling are geographic realities with strong variation. Modeling them as a per-node intensity parameter keeps the simulation tractable — no need for a separate "crime sim." The Compact framing is important: Compact members aren't criminals by disposition, they're communities that have rationally priced Commission authority as unacceptable. Their shadow economy is a consequence of currency friction, not cultural character. +- **Raised by:** Lead directive. Paula (geographic variance and Compact framing), Nigel (seeding architecture), Gestalt (`official_coverage_ratio` signal), Tyre (schema), Miri (Compact friction analysis). +- **Dissent:** None. +- **Cross-reference:** [D-171](#d-171-three-currency-system) (Sol as shadow commodity), [D-172](#d-172-currency-zone-initialization) (Compact friction), [D-037](content.md#d-037) (canonical contraband: lattice components) + +--- + +### D-175: Corporation Taxonomy and Prerequisite +- **Date:** 2026-04-05 +- **Decision:** The corporation corpus is organized in three tiers and is a **prerequisite for Phase 2**: + - **Tier 1: ~38 named, textured corporations** — 13 existing wiki corporations upgraded, 25 new including a Groombridge clearing house. Full identity, political relationships, behavioral archetype, administered silences, named leadership. These are the economic landmarks the player will recognize. + - **Tier 2: ~150 regional firms** — proper identity (sector, corridor, backstory, distinct character) but not fully textured. Regional competitors that can fail, grow, or be acquired. + - **Tier 3: ~5,000 template instances** — named businesses generated from templates, distributed by population. Name, location, product variation. The economic texture the player walks past. + - Two orthogonal archetype systems apply independently: + - **28 lore-taxonomy archetypes** (WHAT/WHERE — Miri): extraction (5), agriculture (6), manufacturing (6), trade/logistics (4), services (6), intelligence (1), plus 5 east-reach archetypes + - **6 behavioral archetypes** (HOW — Burnelli-Sheldon): Monopolist, Distributor, Producer, Specialist, Cooperative, Intermediary + - Priority gaps for Tier 1 creation: financial services, re-embodiment sector, clearing house (Groombridge), Compact-affiliated distributor, east reach anchors, information brokerage + - **Phase 2 begins when the corporation corpus reaches commodity coverage threshold** (minimum: 3+ corporations per major commodity type, 1+ per inhabited system above 100K population). The simulation will not be seeded with placeholder corporations. +- **Rationale:** Corporation density is what makes the simulation legible. A simulation running on 13 corporations in 3,700 nodes would generate nonsensical price signals — corporations would appear to be everywhere at once. The tier structure enables targeted authoring effort: Tier 1 gets full narrative investment, Tier 3 gets generation rules. The prerequisite gate prevents building a simulation that has nothing meaningful to simulate. +- **Raised by:** Lead directive (prerequisite, density, 5,000 template instances). Miri (28 archetypes, east reach gap). Burnelli-Sheldon (6 behavioral archetypes). Paula (Tier 1 gap list, clearing house). Tyre (generation pipeline coverage rules). +- **Dissent:** None. +- **Cross-reference:** [D-166](architecture.md#d-166-development-cascade--6-phase-first-things-first-build-order) (Phase 1 content completion gates Phase 2), [D-173](#d-173-commodity-taxonomy) (commodity types requiring coverage), [D-183](#d-183-iterative-economics-development-cycle) + +--- + +### D-176: Productivity Seeding +- **Date:** 2026-04-05 +- **Decision:** Each run seeds per-run productivity multipliers on five dimensions, attached to **corporation×site pairs** (not abstract nodes): + - `extraction_rate` — output per unit time from mines, wells, fisheries + - `processing_throughput` — units processed per tick in manufacturing and refineries + - `transit_capacity` — freight volume per gate crossing for logistics operators + - `service_throughput` — clients served per tick for service firms + - `service_capacity` — maximum concurrent engagements for service firms + - Standard nodes: 0.4–1.8× multiplier, log-normal distribution, corridor correlation ~0.6 (nearby sites in the same corridor tend toward similar productivity) + - Monopoly-source nodes: 0.7–1.4× (tighter range — lore-grounded scarcity ceilings apply; see [D-177](#d-177-productivity-constraints-lore-derived)) + - The same lore picture appears every run; different underlying productivity cards. Emergence happens DURING play, not seeded before it. + - Seeds are computed at runtime from PRNG seed. Stored in game save state. Never authored in TOML files. +- **Rationale:** Seeding starting positions (corporate health, pre-existing disruptions) erodes the hand-crafted lore picture from Phase 1. Seeding productivity coefficients preserves the lore picture (same corporations, same locations, same relationships) while ensuring every run has a different underlying economic reality. "Same team, different cards." +- **Raised by:** Lead directive (seed productivity, not starting positions). Nigel (architecture, ranges, corridor correlation). Miri (constraints table that defines the seeding bounds). +- **Dissent:** None. +- **Cross-reference:** [D-177](#d-177-productivity-constraints-lore-derived) (what can and cannot be seeded) + +--- + +### D-177: Productivity Constraints (Lore-Derived) +- **Date:** 2026-04-05 +- **Decision:** Lore-derived ceilings constrain what productivity seeding can vary. These constraints are authoritative and not subject to per-run seeding: + - **Hard biological ceilings:** Kvitfjell marble ~800t/y maximum; brach fiber (Braemar only, herd expansion takes decades — volume cannot spike); Calloway terroir is system-specific (cannot be relocated); VGV varietals require F8V stellar spectrum (cannot be farmed elsewhere) + - **Aging pipelines:** Calloway whisky 12–20y aging time; VGV classified wine 5y+; VGV corridor wine 1–2y — pipeline contents at game start are fixed by lore, not seeded + - **Capital goods lead times:** Stalownia large rigs 1–3y; MVG bespoke vehicles 1–2y; Cygni B station sections 2–5y; Gate Corp span gates 1–3y — these lead times are real and not compressible by productivity seeds + - **What CAN be seeded:** harvest yield ±20–40%, factory output ±15–30%, quarry output ±10–25%, service throughput ±10–20% + - **What CANNOT be seeded:** location of production, biological monopoly ceilings, aging pipeline contents, gate topology +- **Rationale:** The constraints table defines the seeding boundary. Seeding something that lore says cannot vary (Calloway terroir, brach fiber herd size) would invalidate the wiki canon. The constraints ensure seeding creates variation within lore-consistent bounds. +- **Raised by:** Miri (full constraint table from wiki lore). Nigel (seeding architecture requiring the bounds). +- **Dissent:** None. +- **Cross-reference:** [D-176](#d-176-productivity-seeding) + +--- + +### D-178: Economic Model Architecture +- **Date:** 2026-04-05 +- **Decision:** The economics layer uses a spatial input-output model with agent-based overlay: + - **Layer 1: Leontief production** with seeded per-corporation capacity. Fixed-coefficient — scarcity in one input cascades to all downstream dependents. No smooth substitution. + - **Layer 2: Spatial price equilibrium** via damped tâtonnement (α=0.03, β=0.4). Prices propagate through the gate topology. Lagged adjustment — NOT instant equilibrium. Prices respond to supply/demand signals with a realistic delay. + - **Layer 3: Corporate behavioral agents** — 6 archetypes (Monopolist, Distributor, Producer, Specialist, Cooperative, Intermediary) with template-instantiated behavioral parameters. + - **Transport graph:** gate edges (inter-system, cost 5–12%/hop) + orbital edges (intra-system, cost 1–3%). Derived from existing star map DB relationships. + - **Market node tiering:** ~760 active market nodes (inhabited bodies + all stations), ~240 passive producers (feed output to nearest active node, no full market), ~2,700 inert (no economic footprint) + - Floyd-Warshall over the ~760 active node subgraph at startup (~0.5s, one-time cost). + - **Economics seeks stability.** The simulation is a believable backdrop, not a drama generator. In the absence of external events, prices trend toward equilibrium. Events from the storyteller, political, or disaster layer create disruption; the economy responds and re-equilibrates. +- **Rationale:** The three-layer architecture is standard for spatial economic modeling: production determines supply, price adjustment determines flow, agents determine strategic behavior. Lagged tâtonnement prevents cobweb oscillation while still producing realistic price dynamics. The "boring economics" mandate means stability is a feature, not a failure. +- **Raised by:** Burnelli-Sheldon (formal model), Tyre (implementation architecture and market tiering). Lead directive (economics seeks stability, responds to events, does not generate them). +- **Dissent:** None. +- **Cross-reference:** [D-179](#d-179-stability-acceptance-criteria) (test criteria), [D-180](#d-180-event-input-port) (external event interface), [D-182](#d-182-toml-source-of-truth-for-economics-data) (data pipeline) + +--- + +### D-179: Stability Acceptance Criteria +- **Date:** 2026-04-05 +- **Decision:** The economics simulation must pass four stability tests before Phase 2 is considered complete: + 1. **Cold-start convergence:** Prices settle within ±5% of equilibrium within 100 game-days from initialization. + 2. **Long-run stability:** Zero drift greater than ±2% over 1,000 game-days with zero external events injected. + 3. **Shock response:** After a single supply shock, cascade propagates realistically; recovery within 200 ticks; no price explosions or negative prices. + 4. **Cross-zone trade balance:** After a cross-zone trade volume change, exchange rate adjusts and re-stabilizes within 50 ticks. + - If the model oscillates, drifts, or diverges under zero external input, the model is broken. + - These criteria are the `--stability-check` mode of the `economy-sim` binary. +- **Rationale:** Without explicit stability criteria, "the economy seems to be working" is not a testable claim. These four tests cover the failure modes most likely in tâtonnement-based models: failure to converge, slow drift, shock amplification, and cross-zone instability. +- **Raised by:** Burnelli-Sheldon (formal model and test design). Lead endorsed ("economics should be boring" — stability IS the success condition). +- **Dissent:** None. +- **Cross-reference:** [D-178](#d-178-economic-model-architecture), [D-183](#d-183-iterative-economics-development-cycle) + +--- + +### D-180: Event Input Port +- **Date:** 2026-04-05 +- **Decision:** The economics layer accepts external events through a typed input port: + ``` + EconEvent { + target: Node | NodeSet | Corridor | TradeRoute | Currency | Commodity, + effect: ProductivityMultiplier | CapacityMultiplier | DemandShock | ExchangeShock, + duration: ticks, + visibility: Global | Proximate(hops) | Disclosed(specific_nodes) | Hidden, + } + ``` + - **Visibility modes:** `Global` — all actors know immediately. `Proximate(hops)` — propagates at trade speed from target. `Disclosed(nodes)` — only named actors are informed. `Hidden` — creates observable price effects with no knowledge flag; no actor knows the cause. + - Hidden events protect the inspect verb: the player can observe that prices have moved without the system revealing why. This is Phase 3 territory — Phase 2 sim must implement the port, but Hidden events will not be exercised until the player layer exists. + - The economics layer **accepts events; it does NOT generate them.** Drama comes from the storyteller, political, or disaster layer. The economics layer is a receiver, not an emitter of narrative tension. +- **Rationale:** The sharp boundary between economics (responds to events) and the event layer (generates events) is architecturally critical. It prevents the economics simulation from drifting into a drama engine — which would violate D-178's stability mandate and undermine the Phase 2 deliverable. +- **Raised by:** Gestalt (interface design and visibility model), Nigel (Rust spec). Lead directive (economics responds, does not generate). +- **Dissent:** None. +- **Cross-reference:** [D-178](#d-178-economic-model-architecture) (economics seeks stability), [D-181](#d-181-signal-vocabulary) (what the event port affects) + +--- + +### D-181: Signal Vocabulary +- **Date:** 2026-04-05 +- **Decision:** Each active economic node produces 7 signals: + 1. `price_current` — current market price (Public) + 2. `price_trend` — direction and rate of change over last N ticks (Public) + 3. `trade_flow_volume` — freight volume through node (Observable — requires physical presence or proximate access) + 4. `corporate_presence` — which corporations operate here (Observable) + 5. `stockpile_weeks` — estimated inventory at current consumption rate (Semi-private — requires corporate contact) + 6. `production_vs_baseline` — actual output vs. seeded baseline (Private — requires insider access) + 7. `official_coverage_ratio` — ratio of formal to total (formal + shadow) economic activity (Meta-signal — gap between official and real economy) + - Visibility ladder: Public signals are available to all. Observable requires presence. Semi-private requires a corporate relationship. Private requires an insider. The visibility ladder is the inspect verb's backing system — Phase 3 player interaction will use it. + - Phase 2 sim must produce all 7 signals. Phase 3 determines how the player accesses them. +- **Rationale:** The 7 signals define what the economy communicates. Signals 1–2 are what appears on investor screens (Phase 2 deliverable). Signals 3–4 reward presence. Signals 5–6 reward relationships and risk. Signal 7 quantifies the shadow economy gap, giving the inspector a readable metric for how much the official picture understates reality. +- **Raised by:** Gestalt (6 signals + visibility layering). Gestalt (7th signal: `official_coverage_ratio`, derived from shadow economy work). Phase 3 reference per lead directive (f). +- **Dissent:** None. +- **Cross-reference:** [D-174](#d-174-shadow-economy-layer) (shadow economy as input to signal 7), [D-131](content.md#d-131-broad-economic-verb-vocabulary--life-verbs-not-tycoon-specific) (inspect verb — Phase 3+) + +--- + +### D-182: TOML Source of Truth for Economics Data +- **Date:** 2026-04-05 +- **Decision:** Economics data is authored as TOML files and compiled to a queryable `.db`: + - **Source location:** `wiki/economics/` — TOML files for corporations, commodities, production chains, currency zone assignments + - **Build step:** `make economy-db` compiles TOML + `systems.db` into a dev `.db` artifact + - **Dev artifact:** Always on disk; rebuilt when source TOML changes. Agents and the sim binary query the `.db` as usual. + - **Production:** Same build step. On "new game," the `.db` is copied into the game save directory. The simulation mutates it live from that point. + - **Rollback:** Rebuild from TOML source files. The `.db` is never the source of truth. + - **Sync constraint:** Wiki corporation entries and TOML corporation records must stay in sync. The build fails on name divergence. + - TOML is chosen because it is diffable, reviewable in git, and authorable without database tooling. The `.db` is a build artifact, not a collaboration surface. +- **Rationale:** The economics data must be auditable in git (TOML) while remaining queryable at runtime (SQLite). Keeping the `.db` as a build artifact means the source is always recoverable and reviewable in pull requests. The sync constraint prevents the wiki (narrative) and TOML (simulation data) from drifting apart. +- **Raised by:** Lead directive (hybrid architecture, rollback via source rebuild). Tyre (build pipeline and artifact spec). +- **Dissent:** None. +- **Cross-reference:** [D-178](#d-178-economic-model-architecture), [D-175](#d-175-corporation-taxonomy-and-prerequisite) (corporation records requiring sync) + +--- + +### D-183: Iterative Economics Development Cycle +- **Date:** 2026-04-05 +- **Decision:** Economics layer development is iterative, not waterfall: + - **Cycle:** skeleton sim → data population → test → skeleton tweaks → data tweaks → test → repeat + - Simulation schema, data authoring, and the standalone `economy-sim` binary are developed in tandem. No phase gates between data work and code work. + - Corporation corpus population is the prerequisite that gates the **first iteration** (see [D-175](#d-175-corporation-taxonomy-and-prerequisite)). + - The `--stability-check` mode ([D-179](#d-179-stability-acceptance-criteria)) is the exit condition for each iteration — not a final gate. +- **Rationale:** Waterfall sequencing (schema → data → sim → test) produces long feedback cycles and late discovery of data-model mismatches. Iterating data and code together catches modeling errors early and enables the sim to be tested against real (partial) data rather than synthetic fixtures. +- **Raised by:** Lead directive. +- **Dissent:** None. +- **Cross-reference:** [D-175](#d-175-corporation-taxonomy-and-prerequisite) (prerequisite), [D-179](#d-179-stability-acceptance-criteria) (iteration exit condition), [D-182](#d-182-toml-source-of-truth-for-economics-data) (data pipeline) + +--- + +## 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. + +--- + +### D-184: Commodity Catalog (36 Types) +- **Date:** 2026-04-05 +- **Decision:** The simulation uses 36 commodity types as the concrete implementation of the taxonomy in D-173: + - **9 raw materials** — extracted or harvested, location-bound + - **10 intermediate goods** — processed from raws, transportable + - **9 final goods** — assembled from intermediates, carry cultural identity + - **5 professional services** — legal, banking/credit, insurance, logistics management, data brokerage; location-bound + - **3 luxury services** — tourism, holo-content/entertainment, cultural experiences; location-bound + - **Source of truth:** `wiki/economics/commodities.toml` and `wiki/economics/production_chains.toml` + - 21 production chains including 2 substitution routes + - Schema: 14 fields per commodity including 3 political sub-flags (`politically_sensitive`, `contraband_risk`, `sanctions_applicable`), `production_ubiquity`, `demand_model`, `panic_threshold_weeks` +- **Rationale:** The catalog is the concrete realization of the D-173 taxonomy. 36 types is rich enough to produce meaningful geographic specialization while remaining authorable. The 14-field schema captures economic, political, and behavioral properties needed by the tâtonnement simulation. Two substitution routes prevent hard lock-outs in chains where one raw source is geographically constrained. +- **Raised by:** Full planning team, Sprint 32 Workshop #801. +- **Dissent:** None. +- **Cross-reference:** [D-173](#d-173-commodity-taxonomy) (taxonomy), [D-182](#d-182-toml-source-of-truth-for-economics-data) (TOML pipeline), [D-185](#d-185-brands-are-not-commodities) (what is excluded from this catalog) + +--- + +### D-185: Brands Are Not Commodities +- **Date:** 2026-04-05 +- **Decision:** Branded and luxury goods (Calloway whisky, VGV wine, thrds garments, Bífröst marble, etc.) are NOT entries in the commodity catalog. They are priced through a separate brand/cultural value system, not through the tâtonnement: + - Brands consume commodities as inputs — they appear as demand nodes in the production graph + - Brand revenue appears as income in the GDP cluster for their origin system + - The brand system is a **future deliverable** (post-Phase 2, possible DLC) built on top of the commodity foundation + - The commodity chain terminates at abstract generic finals (e.g., "premium spirits", "luxury textiles") + - Brand premium lives in the corporate behavioral layer — it is not modeled in Phase 2 +- **Rationale:** Adding 30+ named brands to the commodity catalog would require per-brand pricing models, cultural preference curves, aging pipeline tracking, and star-system terroir logic — a separate simulation in its own right. Phase 2 must deliver a working generic commodity simulation first. Brands consuming generic commodities as inputs correctly captures the economic relationship without requiring brand simulation code. +- **Raised by:** Lead directive, Sprint 32 Workshop #801. +- **Dissent:** None. +- **Cross-reference:** [D-184](#d-184-commodity-catalog-36-types) (the catalog that excludes brands), [D-177](#d-177-productivity-constraints-lore-derived) (lore ceilings on brand production — still authoritative), [D-175](#d-175-corporation-taxonomy-and-prerequisite) (brand corporations exist as Tier 1 entities) + +--- + +### D-186: Gate Transmission Levels (Mass + Data + Energy) +- **Date:** 2026-04-05 +- **Decision:** Span gates transmit mass, data, and energy — three distinct transmission classes with distinct governance: + - **Mass:** Standard freight transmission. All gates, always-on. No decision needed. + - **Data (The Meridian):** Live real-time network. Already canon. Information asymmetry in the simulation comes from access control and cost, not from physical delay. The Meridian is not a Phase 2 simulation concern — it is narrative backdrop. + - **Energy:** Gate Corporation offers energy-over-gate as a commercial service. Explicitly NOT an Assembly policy — Gate Corp is an independent monopoly. On-grid nodes get reduced `fusion_fuel` utility demand (~0.3× baseline). Industrial chain inputs (smelting, alloys, electronics) are unaffected — the energy discount applies only to utility/habitation consumption. + - **Implementation:** per-node `gate_energy_connected` boolean. Nodes lacking the boolean or set to `false` are treated as off-grid. + - **`MARK_PRIMARY` zones default to `gate_energy_connected = false`.** The Compact refused Gate Corp energy dependency as a deliberate political choice — it preserves Compact energy sovereignty and economic independence. + - **Gate Corp cutoff scenario:** If Gate Corp cuts energy to a dependent node, `fusion_fuel` demand spikes. Compact surplus capacity (from their independence) becomes the emergency supply source. The Compact's refusal of dependency is an economic asset with concrete mechanics. +- **Rationale:** Energy-over-gate gives the gate topology an additional economic dimension beyond freight routing. Opt-in model prevents mandatory complexity for every node. The Compact's structural refusal creates the primary counterplay scenario Gestalt was concerned about — without opt-in, no interesting asymmetry. Gate Corp as private monopoly (not Assembly policy) makes it an independent economic actor, enabling corporate storylines. +- **Raised by:** Lead directive + Miri (lore) + Gestalt (mechanics) + Burnelli-Sheldon (economics) + Tyre (implementation), Sprint 32 Workshop #801. +- **Dissent:** Gestalt initially recommended Level 2 (no energy transmission) due to counterplay concerns. Resolved by the opt-in model — the Compact's refusal to connect provides the counterplay without requiring adversarial defaults. +- **Cross-reference:** [D-172](#d-172-currency-zone-initialization) (`MARK_PRIMARY` zone flag), [D-173](#d-173-commodity-taxonomy) (`fusion_fuel` as a commodity), [D-187](#d-187-fusion-fuel-as-intermediate-81-water-yield) (fuel chain), [D-175](#d-175-corporation-taxonomy-and-prerequisite) (Gate Corp as Tier 1 corporation) + +--- + +### D-187: Fusion Fuel as Intermediate (8:1 Water Yield) +- **Date:** 2026-04-05 +- **Decision:** Fusion fuel is an intermediate good refined from water at an 8:1 yield ratio. It is NOT a raw material: + - Water is the raw input — ubiquitous and cheap across the Reach + - The 8:1 refinement ratio makes fuel expensive despite cheap inputs (8 units of water → 1 unit of fusion fuel) + - Fusion fuel is a Leontief input to 3 energy-intensive production chains: `smelt_ore` (0.3), `alloy_fabrication` (0.2), `electronics_fabrication` (0.2) + - Additionally carries `demand_model = utility` — consumed as operational overhead at every active node (population × per-capita rate), separate from the chain inputs + - Creates a **structural frontier energy cost premium**: frontier nodes pay more for fusion fuel because water transport costs accumulate in the refining input cost, and the chain demand from smelting/alloys/electronics cascades that cost into the manufacturing sector + - This premium arises from geography and chain structure — no event generation required +- **Rationale:** Raw-material fuel would make energy cost geography flat (water is everywhere, therefore fuel is everywhere at the same price). Intermediate fuel with a high water yield ratio creates a conversion cost that multiplies transport costs — frontier refineries are expensive to run because fuel production itself consumes large volumes of low-value bulk water. The cascade effect through 3 industrial chains means frontier manufacturing is structurally more expensive, which is consistent with real-world frontier economics and the lore of the Compact vs. Core divide. +- **Raised by:** Lead directive, validated by Burnelli-Sheldon (economics), Sprint 32 Workshop #801. +- **Dissent:** None. +- **Cross-reference:** [D-184](#d-184-commodity-catalog-36-types) (fuel and water are catalog entries), [D-186](#d-186-gate-transmission-levels-mass--data--energy) (energy-over-gate reduces fuel demand), [D-178](#d-178-economic-model-architecture) (Leontief production cascade) + +--- + +*17 decisions (D-171–D-187), 1 rejected alternative (R-011). Domain: economics. Last updated: 2026-04-05.* diff --git a/decisions/questions-architecture.md b/decisions/questions-architecture.md index 0baac9b4d..9f046530d 100644 --- a/decisions/questions-architecture.md +++ b/decisions/questions-architecture.md @@ -321,9 +321,11 @@ Technical foundation questions: engine, protocols, data structures, performance, --- ### Q-094: Chart widgets for economy/market insert UI -- **Status:** Open +- **Status:** Resolved — deferred to Phase 3+ (player interaction layer) +- **Date resolved:** 2026-04-05 +- **Resolution:** No player-facing economic UI is in scope for Phase 2. The Phase 2 deliverable is the autonomous simulation ticking on investor screens — no player verbs, no insert UI for market data. Chart widget evaluation (Easy Charts plugin, ThemeGen integration, information boundary application) deferred until Phase 3 when the player interaction layer begins. - **Question:** Easy Charts (https://github.com/fenix-hub/godot-engine.easy-charts) — line charts, bar charts, scatter plots, pie charts in Godot. For the insert UI: (a) commodity price history graphs (X4/EVE-style market view), (b) faction reputation trends over time, (c) supply/demand curves per station, (d) character stat progression, (e) economy health indicators. The diegetic justification: the player's implant has market analytics. Data comes from server via ObserverSnapshot (the player only sees market data they have access to — information boundary applies). Evaluate whether this plugin's visual style can be themed to match our insert aesthetic (ThemeGen Q-083 integration). -- **Cross-reference:** Economy system (X4/EVE inspiration), insert UI, Q-083 (ThemeGen), information boundary +- **Cross-reference:** Economy system (X4/EVE inspiration), insert UI, Q-083 (ThemeGen), information boundary, [D-181](economics.md#d-181-signal-vocabulary) (signal vocabulary — Phase 3 player access) --- diff --git a/decisions/rejected.md b/decisions/rejected.md index 7975f540e..619714ec0 100644 --- a/decisions/rejected.md +++ b/decisions/rejected.md @@ -44,6 +44,12 @@ Alternatives considered and rejected, with rationale preserved for future refere - **Rejected:** 2026-02-09 - **Reason:** Schema evolution across independent deployments is a problem we don't have (one developer, client and server ship together). Poor GDScript support. Rigid schema fights dynamic HUD composition driven by perception modes ([D-017](perception.md#d-017-perception-modes-as-character-build-system)). MessagePack's schema-optional nature fits better. +### R-011: Single currency for Phase 2 economics +- **Rejected:** 2026-04-05 +- **Proposed by:** Burnelli-Sheldon (economist), Sprint 32 Workshop #796 Round 1 +- **Reason:** Three currencies create structural economic bloc tension as an emergent property of initialization, requiring no event generation. The Tractus/Mark divide maps directly to the canonical Assembly vs. Compact political divide. Deferring to a later phase would require retrofitting political geography into a running simulation. Complexity cost low; design value high. +- **Cross-reference:** [D-171 (economics.md)](economics.md#d-171-three-currency-system) + --- -*10 rejected alternatives. Last updated: 2026-02-11* +*11 rejected alternatives. Last updated: 2026-04-05* diff --git a/docs/sprints/sprint-32/workshop-796-round1.md b/docs/sprints/sprint-32/workshop-796-round1.md new file mode 100644 index 000000000..fff8a1d1b --- /dev/null +++ b/docs/sprints/sprint-32/workshop-796-round1.md @@ -0,0 +1,106 @@ +# Workshop #796 — Economics Layer Design +## Round 1 Findings + Cross-Discussion Summary +**Date:** 2026-04-05 +**Sprint:** 32 (planning branch) +**Status:** Round 1 complete. Round 2 (proposals) in progress. + +--- + +## Round 1 Findings by Agent + +**Gestalt (Mechanics):** Mapped the economics layer against three reference games — X4 (production chains, regional price differentials), EVE (information asymmetry as a core mechanic, not a side effect), Rimworld (wealth as storyteller threat multiplier). Key insight: "inspect" is the master economic verb — every economic action is first an information decision. Mapped D-131 verb vocabulary (buy, sell, hire, rent, contract, inspect, negotiate, invest) against required backing systems. Flagged two dangers: (1) economics divorced from the social/NPC layer loses its texture, and (2) perfect market information kills the inspect verb. + +**Miri (Lore Inventory):** Full corporation census from existing wiki: 13 named corporations across 5 tiers (Syndic reach-wide → sub-Syndic regional → local). Documented economic geography by corridor: Core (institutional), North (self-sufficient, exports via corridor), South (cooperative extraction, legal industry), West (Germanic/Nordic luxury and transit hub), East (underdeveloped in lore — flagged as a gap). Identified 14 production→destination supply chain flows from wiki content. Found 4 commercial intelligence institutions (Mercado, Ferreira Monteiro, VGV, Adams & Ford) that don't share data with each other — natural basis for information asymmetry. Catalogued 10 specific lore gaps requiring resolution: currency names, price formation mechanism, Syndic trade mechanics, transport economics, Van Maanen's Star economic profile, east reach identity, Compact economics, Prometheus pricing, ownership registry, supply/demand triggers. + +**Nigel (Replayability):** Divided economic elements into fixed-by-lore (corporate identities, corridor geography, gate topology, established monopolies) and per-run seeded (corporate health states, active disruptions, political alignment, regional supply balances). Proposed 7 emergent story generators: marble chokepoint, Mercado shelf signal, Stalownia cascade, accidental monopoly, succession shock, gate rate event, overproduction crash. Critical insight: the player should understand HOW the economy works without that knowledge revealing WHAT IS TRUE in the current run. Advocated for observable world-state signals over UI reports — the economy should communicate through events, not dashboards. + +**Paula (Political Drama):** Argued that economy and politics are the same system in the Settled Reach — the Compact grew through commercial arithmetic, not ideology. Corporations aren't faction-aligned; they ARE factions with internal contradictions. Key reframing: social pressure isn't a modifier on supply/demand — it is inherent in price formation. The Commission certification IS the price floor. The Compact tariff differential IS the smuggling incentive. Proposed 6 narrative hook categories: downstream consequences, the Ring as market correction, slow accumulation, Compact membership as a margin decision, corporate leverage as coercion, cultural products as political signals. Mapped 8 social pressure modifiers with mechanisms and dramatic potential. + +**Tyre (Technical):** Baseline: bevy_ecs 0.18, 10 ticks/sec, deterministic RNG, existing simulation tier model already in place. Systems.db contains 301 systems, 3,240 bodies, 466 stations, 20 corporations — but `system_economy` is 96% empty (critical gap). Assessed computational cost: 301 systems is sub-microsecond per price update tick; ~3,700 per-body nodes is still trivial. Recommended development path: standalone Rust binary first (same pattern as main server), then server integration, then player interaction — Tier 1 → 2 → 3. Identified schema gaps: commodities table, production_chains table, trade_routes table needed before simulation can run. + +**Burnelli-Sheldon (Economics):** Proposed a three-layer model: Leontief I/O production matrix (structural), spatial price equilibrium (geographic arbitrage), corporate agent overlay (strategic behavior). Price adjustment via lagged tâtonnement with 5 elasticity categories to prevent cobweb oscillation. Recommended 15–25 commodity types in a 3-tier production hierarchy (raw → intermediate → final). Proposed 8 tuning parameters with suggested ranges for calibration. Recommended single currency for v0.2. Flagged key pitfalls: simulating what the player can't see creates dead computation; money sinks required to prevent infinite accumulation; arbitrage death spirals need dampening via transport costs. + +--- + +## Cross-Discussion Convergence + +After agents read each other's work: + +- **Per-body granularity:** All agents accepted the per-body simulation unit. No resistance. The geographic richness is worth the additional node count (~3,700 vs. 301), and Tyre confirmed it's still computationally trivial. +- **Drama reclassified:** Gestalt, Paula, and Nigel's drama generators (emergent crises, political hooks, replayability events) are valid — but they come from the **event layer** (storyteller, disaster events, political triggers), not from the economics layer itself. The economics layer provides the terrain; the event layer generates the weather. +- **Productivity seeding accepted:** Seeding productivity coefficients (mine output, harvest size, factory efficiency) instead of seeding corporate health states or disruptions preserves the lore-accurate starting picture while still generating run-to-run variance. Nigel's concern about metagame erosion is addressed — same corporations, different production cards. +- **Phase 2 = no player verbs:** Broad agreement that Tyre's Tier 1 (standalone sim proving autonomous tick) is the correct Phase 2 deliverable. Player verbs (D-131) are Phase 3+ territory. +- **Three currencies:** Overrides Burnelli-Sheldon's single-currency recommendation. Three economic blocs create structural tension without requiring event generation. Burnelli-Sheldon's recommendation is a **rejected alternative** (R-NNN pending formal closure). + +--- + +## Lead Directives (Jeroen — binding) + +| | Directive | Summary | +|---|-----------|---------| +| a | **Three currencies** | One per economic bloc (Earth / Concord / Assembly). Exchange rate friction and currency arbitrage are structural features, not events. Names TBD. | +| b | **Per-body simulation** | ~3,700 nodes (3,240 bodies + 466 stations), not 301 systems. Planet and orbital station can have different prices. | +| c | **Hundreds of corporations** | Current 13–20 is too thin. Need ~200+ corporations, brands, and economic players before a credible simulation is possible. | +| d | **Seed productivity, not starting positions** | Seed mine output rates, harvest sizes, factory efficiency — not corporate health or disruption states. Same lore picture, different productivity cards each run. | +| e | **Economics is boring** | The simulation seeks equilibrium. It is a backdrop, not a drama generator. Events impact it from outside; it responds and restabilizes. | +| f | **No player-facing design in Phase 2** | Deliverable: simulation ticking autonomously. No player verbs, no UI for economic actions. Prove it works before designing how the player touches it. | + +--- + +## Proposed Structures (for Round 2 refinement) + +### Corporation tiers (Miri's census → expanded) +| Tier | Scope | Examples | Count (current) | +|------|-------|---------|----------------| +| 1 | Syndic reach-wide | [TBD — 1–2 entities] | 1–2 | +| 2 | Multi-corridor regional | [TBD — major players] | ~5 | +| 3 | Single-corridor dominant | Stalownia Group, Mercado | ~6 | +| 4 | Local/sector | Various | ~6 | +| 5 | Micro / brand level | Shops, franchises | Hundreds needed | + +### Market node tiering (from Tyre's data) +| Tier | Description | Approximate count | +|------|-------------|------------------| +| Active | Major stations, capitals, key trade hubs — full price simulation | ~760 | +| Passive | Smaller bodies, minor moons — simplified or derived pricing | ~2,480 | +| **Total** | | **~3,700** | + +*Exact active/passive threshold to be defined in Round 2.* + +### Currency naming (Round 2 task) +Three currencies required — names confirmed in Round 2 lead feedback. See Round 2 report for corrected framing. + +| Currency | Issuer | Role | +|----------|--------|------| +| **Tractus** | Concord Assembly (Sirius / Groombridge) | Main Reach currency — accepted everywhere. The establishment currency. | +| **Mark** | Compact of Westphalia | Breakaway currency — created to disconnect from Tractus. Mostly not accepted outside the Compact. | +| **Sol** | Sol system (no active issuer) | Niche, finite pool, untraceable — used in crime and premium Earth goods. | + +*Note: Round 1 bloc labels (Earth/Concord/Assembly) were agent proposals, not confirmed lore. Corrected in Round 2 and further refined: Mark is Compact of Westphalia, not Concord Assembly.* + +--- + +## Open Questions (unresolved entering Round 2) + +| # | Question | Assigned to | Priority | +|---|----------|-------------|----------| +| OQ-1 | Currency names — three blocs, lore-consistent names | Miri, Mellanie | High — blocks D-record | +| OQ-2 | Corporation density threshold — how many is "enough"? A number needed for the D-record | Gestalt, Tyre | High | +| OQ-3 | East Reach economic identity — lore gap flagged by Miri, no corridor character defined | Miri | Medium | +| OQ-4 | Exchange rate model — how do cross-bloc transactions work mechanically? Fixed rates, floating, managed? | Burnelli-Sheldon, Tyre | Medium | +| OQ-5 | Productivity → corporation sequencing — do we need ~200 corporations defined *before* simulation can run, or can simulation run with 13 and corporations be added incrementally? | Tyre, SI | High — Phase 1/2 boundary | +| OQ-6 | Compact economics — tariff differential and membership cost mechanics not yet specified | Paula, Burnelli-Sheldon | Medium | +| OQ-7 | Van Maanen's Star economic profile — flagged by Miri as a gap; important because it's the tycoon bookmark starting location (D-117, D-118) | Miri | **Deferred** — out of Phase 2 scope per Round 2 lead directive (e) | + +--- + +## Record implications (Qatux flags) + +- **Q-094** ("Chart widgets for economy/market insert UI") — existing open question in `decisions/questions-architecture.md`. Resolved-deferred to Phase 3+ under directive (f). Will be marked when Round 3 closes. +- **D-131** (economic verb vocabulary) — valid, not superseded. But Phase 3+ territory under directive (f). Cross-reference note needed in economics.md. +- **R-NNN** (single currency rejected) — Burnelli-Sheldon's single-currency recommendation becomes a rejected alternative. Rationale: three-currency structural bloc design creates tension without event generation. Pending formal closure in Round 3. +- **Phase 1/2 boundary** — directive (c) creates a sequencing question: hundreds of corporations = Phase 1 content work. If simulation requires dense corporation data to be meaningful, the Phase 1/Phase 2 boundary may need clarification. Flagged for Jeroen's attention before Round 2 locks proposals. + +--- + +*Compiled by Qatux. Round 2 complete — see `workshop-796-round2.md`.* diff --git a/docs/sprints/sprint-32/workshop-796-round2.md b/docs/sprints/sprint-32/workshop-796-round2.md new file mode 100644 index 000000000..ef734edc5 --- /dev/null +++ b/docs/sprints/sprint-32/workshop-796-round2.md @@ -0,0 +1,148 @@ +# Workshop #796 — Economics Layer Design +## Round 2 Proposals + Lead Feedback Summary +**Date:** 2026-04-05 +**Sprint:** 32 (planning branch) +**Status:** Round 2 complete. Round 3 (convergence) pending. + +--- + +## Round 2 Proposals Summary + +**Gestalt (Mechanics):** +- `EconomicEvent` interface: `affected_nodes`, `commodities`, `supply/demand multipliers`, `duration`, `information_state: Public|Private`. Private events propagate at trade speed; Public events propagate instantly. This protects the inspect verb. +- Corporation taxonomy: 3 behavioral tiers — Syndic (price anchors, slow response), Mid-tier (regional competitors, can fail), Sub-Syndic local (price-takers, not individually simulated). +- 6 signal types per node: `price_current`, `price_trend`, `trade_flow_volume`, `corporate_presence`, `stockpile_weeks`, `production_vs_baseline`. Visibility layered from Public to Private. +- Production chain principles: geographic anchor, 3-tier max depth, substitutable inputs at intermediate level, cultural identity encoded in final goods. +- Political pressure is structural: currency zone, bloc affiliation, preferred currency baked into corporation profiles — not applied as external modifiers. + +**Tyre (Technical):** +- Schema additions: `gate_links` table (335 edges from star-map.json), `commodities` table (22 types), `production_chains` + `chain_inputs`, `currency_zone` column on star_systems, corporation extensions + `corp_presence` table. +- Transport graph: gate edges (5-12%/hop) + orbital edges (1-3%), Floyd-Warshall for ~760 active nodes at startup (~0.5s). +- Market node tiering: ~760 active (full markets), ~240 passive producers (feed nearest station), ~2,700 inert (no economic footprint). +- `economy_sim` CLI: `--seed`, `--years`, `--watch`, `--stability-check` modes. +- `generate_corporations` binary with coverage rules: 3+ corps per major commodity, 1+ per inhabited system >100K pop. +- Phased implementation: 2a (data) → 2b (simulation) → 2c (integration design, D-records only). + +**Paula (Political Drama):** +- 4 per-body structural flags: `currency_zone`, `trade_bloc`, `commission_presence`, `assembly_assessment_compliance`. +- 4 per-commodity structural flags: `commission_certification`, `syndic_supply_chain`, `gate_corp_floor`, `cultural_corridor_id`. +- *Currency geography proposed (now corrected by lead — see below):* Sol (hops 0-2), Mark (hops 2-5), Tractus (hop 6+ and Compact). +- Corporation texture plan: 25 tier-1 textured (13 upgraded + 12 new), ~175 tier-2 skeletons. Gaps: financial services, re-embodiment, Sova Logistics, Compact distributor, east reach anchors, information brokerage. +- 6 sharp events + 5 slow accumulation drifts (wage compression, market consolidation, currency zone drift, infrastructure neglect, reputation decay). + +**Nigel (Replayability):** +- Productivity seed: 4 dimensions — `extraction_rate`, `processing_throughput`, `transit_capacity`, `service_throughput`. Log-normal distribution, 0.4-1.8× for standard, 0.7-1.4× for monopolies, corridor correlation ~0.6. +- Exchange rates emerge from aggregate productivity differentials, not seeded directly. Volatility per currency: Sol lowest, Mark mid, Tractus highest. +- Observable signals for investor screen: price gradient map, trade flow visualization, currency ticker with volatility trail. +- Event input port: `EconEvent { target, effect, visibility }`. `Visibility: Global | Proximate(hops) | Disclosed(nodes) | Hidden`. Hidden events create real effects with no actor knowing the cause. + +**Burnelli-Sheldon (Economics):** +- Formal model: ~760 nodes, Leontief production with seeded capacity, damped tâtonnement (α=0.03, β=0.4). +- 22 commodity types: 7 raw, 8 intermediate, 7 final. Full input/output recipes. +- Exchange rates: Sol/Mark managed peg (political), Mark/Tractus managed float (trade-balance driven, γ=0.02, δ=0.4), Sol/Tractus derived. 3% conversion friction on cross-zone trade. *(Note: peg direction needs re-examination under corrected political framing — Tractus/Mark peg, Assembly→Compact, is more politically coherent than Sol/Mark. Sol has no issuer to manage a peg.)* +- 6 corporate archetypes: Monopolist, Distributor, Producer, Specialist, Cooperative, Intermediary. +- 4 stability criteria: cold-start convergence (±5% in 100 days), long-run stability (±2% over 1,000 days), shock response, cross-zone trade balance. +- Standalone `econ-sim` binary in `tooling/`, reads systems.db + `commodities.toml` + `production_profiles.toml`, outputs CSV timeseries. + +**Miri (Lore):** +- Currency lore: Sol (Earth legacy, finite pool, no issuer, appreciating), Mark (described as Concord institutional — *since corrected: Mark is Compact of Westphalia*), Tractus (daily commercial, what people are paid in — *since corrected: Tractus is the Concord Assembly/establishment currency, not a frontier coin*). +- Van Maanen's Star economic profile: Station Sova as freight hub, 4 tycoon business types, economic pressures. *(Out of Phase 2 scope per lead — noted below.)* +- 28 corporation archetypes across extraction (5), agriculture (6), manufacturing (6), trade/logistics (4), services (6), intelligence (1). +- East reach: 5 new archetypes — deep ocean fishery, precision instruments, fermentation cooperative, maritime salvage, textile/craft guild. +- Productivity constraint table: aging pipelines (Calloway 12-20y, VGV 5y+), hard ceilings (Kvitfjell 800t/y), capital goods lead times (Stalownia 1-3y, Cygni B 2-5y). + +--- + +## Lead Corrections (Jeroen — verbatim → interpreted) + +### (a) Currency framing — corrected + +**The political mapping was inverted.** Correct framing: + +| Currency | Issuer | Role | Notes | +|----------|--------|------|-------| +| **Tractus** | Concord Assembly (Sirius / Groombridge) | Main Reach currency — the establishment currency | Poor exchange rates in Compact, but accepted everywhere else | +| **Mark** | Compact of Westphalia | Breakaway currency — created to disconnect from Tractus | Mostly not accepted outside the Compact | +| **Sol** | Sol system (no active issuer, finite pool) | Niche, untraceable — crime and premium Earth goods | Appreciating due to finite supply; used where anonymity matters | + +*Currency correction applied 2026-04-05: Mark is Compact of Westphalia currency, not Concord. "Concord" in Jeroen's original directive referred to the Compact. Political framing: Assembly = Tractus (establishment), Compact = Mark (breakaway).* + +### (b) Services and luxury services needed + +The commodity model must include: +- **Professional services:** legal, banking/credit, insurance, logistics management +- **Luxury services:** tourism, music, holo-content, experiences, cultural exports + +These were hinted by Paula but not formally included in the 22-commodity list. Required for the commodity table to be complete. + +### (c) Crime and smuggling required + +A shadow economy layer is required. Geographic variance: nearly absent in Commission-heavy systems, rampant in Compact frontier, continuous spectrum between. D-037 (Sova contraband: lattice components) is a canonical example. The economics layer needs to model shadow activity without a formal system — likely implemented as per-body flags (`commission_presence`, `unbound_density`) that influence effective market access. + +### (d) Productivity seeding — endorsed + +Nigel and Miri's productivity seeding proposals are solid. No correction. Log-normal seeding of `extraction_rate`, `processing_throughput`, `transit_capacity`, `service_throughput` proceeds. + +### (e) Tycoon profile — out of Phase 2 scope + +Van Maanen's Star economic profile (OQ-7 from Round 1 report) is not a Phase 2 deliverable. Miri's detailed tycoon business profile is deferred. The simulation doesn't need a specific system profiled for Phase 2 — it needs coverage rules, not narrative anchors. + +### (f) Corporations as prerequisite — confirmed + +Corporation/brand population comes FIRST. Simulation runs on real corporate data, not placeholders. This is Phase 1 content work (D-166 applies). The `generate_corporations` binary should target real archetypes from Miri's 28-archetype catalog, not procedurally generated shells. How many corporations is "enough" remains an open question (see below). + +### (g) Database architecture — hybrid confirmed + +**TOML/YAML as source of truth** (diffable, in git). `make economy-db` builds the dev `.db`. The `.db` is a queryable artifact, always on disk, rebuilt when source changes. For production: same build step, copy into save directory on new game, sim mutates live. Rollback = rebuild from source files. + +Source files location: `content/economics/` (TOML files for corporations, commodities, production chains, etc.) + +### (h) Iterative development cycle — confirmed + +skeleton → data → test → skeleton tweaks → data tweaks → test → repeat. Not waterfall phases. Sim binary and data population happen in tandem. + +--- + +## Open Questions Entering Round 3 + +| # | Question | Status | Notes | +|---|----------|--------|-------| +| OQ-1 | Currency names — final canonical names for Tractus, Mark, Sol | **Partially resolved** — names confirmed by lead; lore detailing TBD by Miri | +| OQ-2 | Corporation density threshold — how many to make simulation credible? | **Open** | Coverage rules proposed (3+ per commodity, 1+ per inhabited system) but total count not confirmed | +| OQ-3 | East Reach economic identity | **Partially resolved** — Miri provided 5 archetypes; full profile still thin | +| OQ-4 | Exchange rate model — fixed peg, managed float, or derived? | **Partially resolved** — Burnelli-Sheldon's model (managed peg Sol/Mark, managed float Mark/Tractus) subject to confirmation given currency framing correction | +| OQ-5 | Corp creation sequencing vs. simulation start | **Confirmed** — corps come first (directive f) | +| OQ-6 | Compact economics — Compact accepts Tractus at bad rates? Uses Mark? Uses Sol? | **New open question** from currency correction | +| OQ-7 | Van Maanen's Star profile | **Deferred** — out of Phase 2 scope | +| OQ-8 | Services/luxury commodity types — formal list | **New** — must be defined before commodity table is complete | +| OQ-9 | Shadow economy mechanics — per-body flags or separate system? | **New** | +| OQ-10 | Active/passive/inert threshold — what makes a node "active"? | **Tyre's proposal** — 760 active / 240 passive / 2,700 inert — needs confirmation | + +--- + +## What Round 3 Must Lock + +For D-records to be written, Round 3 must produce confirmed answers on: + +1. **Three currency canonical definitions** — names, issuer, acceptance geography, role +2. **Commodity type list** — final count (22 + services + luxury = ~30?), full categorization +3. **Corporate coverage rules** — density threshold per commodity, per system, per corridor +4. **Per-body data flags** — confirm Paula's 8 flags + shadow economy flag +5. **Market node tiering** — confirm 760/240/2,700 split or revise +6. **Database source file location** — `content/economics/` TOML confirmed? +7. **Productivity seed dimensions** — confirm Nigel's 4 dimensions + log-normal distribution +8. **Development sequence** — confirm skeleton → data → test cycle as the process D-record + +--- + +## Record implications (Qatux) + +- **Round 1 report correction:** The currency bloc table in `workshop-796-round1.md` listed "Earth / Concord / Assembly" as bloc labels — this was based on agents' Round 1 proposals and is now superseded. The corrected framing is Tractus (Assembly/Sirius main), Mark (Concord rebellious), Sol (Sol system niche/crime). +- **D-037 cross-reference:** Shadow economy in the simulation will need to cite D-037 (Sova contraband) as the canonical example of shadow market mechanics. +- **R-NNN pending:** Burnelli-Sheldon's single-currency recommendation is confirmed rejected. Rejection rationale: three currencies create structural economic bloc tension without event generation. Will be filed as R-NNN in Round 3. +- **Architecture D-record:** TOML + built .db hybrid needs a D-record. Closest existing decision is D-010 (deterministic simulation) and the general architecture — economics DB is new territory. Will file in `decisions/architecture.md`. +- **Process D-record:** Iterative skeleton→data→test cycle for economics may belong in `decisions/process.md` rather than `decisions/economics.md`. + +--- + +*Compiled by Qatux. Round 3 convergence pending.* diff --git a/docs/sprints/sprint-32/workshop-796-round3.md b/docs/sprints/sprint-32/workshop-796-round3.md new file mode 100644 index 000000000..a1dfb1408 --- /dev/null +++ b/docs/sprints/sprint-32/workshop-796-round3.md @@ -0,0 +1,55 @@ +# Workshop #796 — Economics Layer Design +## Round 3 Closure Note +**Date:** 2026-04-05 +**Sprint:** 32 (planning branch) +**Status:** CLOSED + +--- + +## Outcome + +Round 3 convergence produced 13 confirmed D-records, 14 tickets, and closed the workshop. + +### D-Records Locked + +| ID | Title | +|----|-------| +| D-171 | Three-Currency System | +| D-172 | Currency Zone Initialization | +| D-173 | Commodity Taxonomy | +| D-174 | Shadow Economy Layer | +| D-175 | Corporation Taxonomy and Prerequisite | +| D-176 | Productivity Seeding | +| D-177 | Productivity Constraints (Lore-Derived) | +| D-178 | Economic Model Architecture | +| D-179 | Stability Acceptance Criteria | +| D-180 | Event Input Port | +| D-181 | Signal Vocabulary | +| D-182 | TOML Source of Truth for Economics Data | +| D-183 | Iterative Economics Development Cycle | + +Rejected alternative recorded: R-011 (single currency for Phase 2). + +Full records: `decisions/economics.md` + +### Tickets Created + +#797–#810 (14 tickets). See ticketing system for full breakdown. + +### Questions Resolved + +- **Q-094** (chart widgets for economy/market insert UI) — resolved-deferred to Phase 3+. No player-facing economic UI in Phase 2 scope. + +--- + +## Round Documents + +| Round | File | +|-------|------| +| Round 1 + Cross-Discussion | `docs/sprints/sprint-32/workshop-796-round1.md` | +| Round 2 + Lead Feedback | `docs/sprints/sprint-32/workshop-796-round2.md` | +| Round 3 Closure | `docs/sprints/sprint-32/workshop-796-round3.md` *(this file)* | + +--- + +*Workshop #796 closed. Compiled by Qatux.*