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

chore(meta): plan Sprint 33: Pecunia

Browse Source 
Economics simulation sprint — skeleton binary through corporate agents.
13 tickets across server/copy/client/ci. Stability tests (D-179) are
the sprint exit condition.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-04-07 08:36:31 +02:00
co-authored by Claude Sonnet 4.6
parent 4028f71f2f
commit 7270b860cb
6 changed files with 356 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/backups/settledreach.db.backup
BIN
View File
Binary file not shown.
docs/sprints/sprint-33/ci.md
+41
View File
@@ -0,0 +1,41 @@
# Sprint 33: Pecunia — CI Tasks
**Goal:** Full economics simulation running — Leontief production, spatial price equilibrium, currency zones, corporate behavioral agents across all three corporation tiers, stability tests passing.
**Branch:** `sprint-33/ci`
**Agents:** Justine (build/deploy)
## New Tickets
| # | Title | Blocked by |
|---|-------|------------|
| #816 | Remove Qdrant semantic search infrastructure | — |
Use `tooling/db/ticket show <id>` for full ticket details.
## Notes
**#816 — Remove Qdrant semantic search infrastructure**
- The Qdrant index ('commonwealth' collection, 475 points, tower-of-joy:6333) is stale — it points at old worktree paths from previous sprints and nobody maintains it. Grep covers all current search needs.
- Five removal steps (all five must be done together for a clean removal):
1. Drop the Qdrant collection on `tower-of-joy:6333` — use the Qdrant HTTP API directly (`DELETE /collections/commonwealth`). Confirm the collection no longer exists before proceeding.
2. Remove `tooling/db/qdrant_connector.py`.
3. Remove the `/docs-search` skill (find it under `.claude/skills/`).
4. Remove Qdrant references from `tooling/db/config.json` and `.claude/rules/local-services.md`.
5. Remove `qdrant-search` and `qdrant-index` from the CLI tool table in `CLAUDE.md`.
- After removal, run a repo-wide grep for `qdrant` (case-insensitive) to catch any remaining references in other docs, rules, or briefings. Clean them up.
- No replacement tooling is needed — grep is sufficient and already in use.
- This is a low-priority maintenance ticket. Do not let it block other work. If the Qdrant server is unreachable when you attempt step 1, skip it and note in the PR that the collection deletion must be done manually.
## Dependency Chain
```
#816 (remove Qdrant) → standalone
```
## PR Workflow
When ready to submit, create a PR with `tea` CLI. **All flags are required** to avoid TTY prompts (see CLAUDE.md "Gitea access" section):
```bash
tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "chore(ci): description" --description "body" --base main --head sprint-33/ci
```
docs/sprints/sprint-33/client.md
+44
View File
@@ -0,0 +1,44 @@
# Sprint 33: Pecunia — Client Tasks
**Goal:** Full economics simulation running — Leontief production, spatial price equilibrium, currency zones, corporate behavioral agents across all three corporation tiers, stability tests passing.
**Branch:** `sprint-33/client`
**Agents:** Stig (UI dev)
## New Tickets
| # | Title | Blocked by |
|---|-------|------------|
| #818 | Create icon_tint.gdshader for runtime icon recoloring | — |
Use `tooling/db/ticket show <id>` for full ticket details.
## Key Decisions
- `decisions/architecture.md` — D-169 (implant UI component library), D-170 (HUD visibility groups)
## Notes
**#818 — Create icon_tint.gdshader for runtime icon recoloring**
- The implant HUD icon set (D-086, #795) references `icon_tint.gdshader` for runtime color replacement via ShaderMaterial. This shader was assumed to exist but was not authored during Sprint 32.
- The shader must handle two icon types:
- **Stroke-based icons** (majority of the set) — the icon is drawn as colored outlines/strokes on a transparent background. Recolor by replacing the stroke color at runtime.
- **Fill-based icons** (health cross, at minimum) — the icon is a solid filled shape. Recolor the fill.
- Integration spec: `docs/design/icon-set-v01.md` section 3.2 details the Godot ShaderMaterial parameter interface. Read that section before writing the shader.
- Placement: `client/ui/implant/` or `client/shaders/` — check where other shaders live in the client tree and follow the existing convention.
- The shader takes a `ShaderMaterial` parameter (the tint color) and outputs a recolored version of the source texture, preserving alpha. The icon textures are single-color SVG exports — the shader replaces the source color, not a specific channel.
- Test by attaching to an `ImplantDataRow` or standalone `TextureRect` with one of the HUD icon textures. Verify both stroke and fill icon types recolor correctly at all implant theme semantic colors (`ACCENT_ACTIVE`, `ACCENT_POSITIVE`, `ACCENT_NEGATIVE`, `ACCENT_WARNING`, per `client/ui/implant/default_implant.tres`).
- This is a standalone task — no server-side dependencies.
## Dependency Chain
```
#818 (icon_tint.gdshader) → standalone
```
## PR Workflow
When ready to submit, create a PR with `tea` CLI. **All flags are required** to avoid TTY prompts (see CLAUDE.md "Gitea access" section):
```bash
tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(ui): description" --description "body" --base main --head sprint-33/client
```
docs/sprints/sprint-33/copy.md
+85
View File
@@ -0,0 +1,85 @@
# Sprint 33: Pecunia — Copy Tasks
**Goal:** Full economics simulation running — Leontief production, spatial price equilibrium, currency zones, corporate behavioral agents across all three corporation tiers, stability tests passing.
**Branch:** `sprint-33/copy`
**Agents:** Mellanie (author), Miri (worldbuilding), Paula (narrative)
## New Tickets
| # | Title | Blocked by |
|---|-------|------------|
| #820 | Author MARK_PRIMARY currency zone assignments for Compact systems | — |
| #803 | Define shadow economy intensity ranges | — |
| #799 | Generate ~150 Tier-2 regional corporations | #798 (DONE) |
| #800 | Build corporation generation pipeline for Tier-3 | #798 (DONE) |
| #812 | Wiki commodity copy pass | — |
Use `tooling/db/ticket show <id>` for full ticket details.
## Key Decisions
- `decisions/economics.md` — D-171 (three-currency system: Tractus/Mark/Sol), D-172 (currency zone initialization: affiliation-based, NOT hop-distance), D-173 (commodity taxonomy), D-174 (shadow economy layer: Compact shadow is principled economic resistance, not frontier lawlessness), D-175 (corporation taxonomy: Tier 1/2/3 structure, prerequisite for Phase 2), D-182 (TOML source of truth), D-183 (iterative development cycle), D-184 (36-type commodity catalog), D-185 (brands not commodities)
- `decisions/architecture.md` — D-166 (Phase 2 deliverable: economics simulation with runtime-tweakable parameters)
## Notes
**#820 — Author MARK_PRIMARY currency zone assignments for Compact systems**
- The `currency_zone` column exists on `star_systems` (default `TRACTUS_PRIMARY`). Sol (GJ 0) is already `MIXED`. All other systems are currently `TRACTUS_PRIMARY`.
- Per D-172: 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. A hop-5 Assembly system stays `TRACTUS_PRIMARY`; a hop-8 Compact member is `MARK_PRIMARY`.
- Output: a TOML or JSON data file (e.g., `wiki/economics/currency_zones.toml`) that lists each Compact-member system_id and its zone flag (`MARK_PRIMARY` or `MIXED`). Systems not listed default to `TRACTUS_PRIMARY`.
- Miri owns the lore: which systems are Compact of Westphalia members? Cross-reference `wiki/factions/compact-of-westphalia.md` and system wiki pages. `MIXED` is for Compact-sympathetic systems where both currencies are accepted but neither dominates — use it for border/transitional systems.
- The import pipeline (`tooling/economy-db/import_economics.py` function `set_currency_zones`) already has a placeholder comment: "Future: Compact systems → MARK_PRIMARY (requires authored Compact membership data)." Your output feeds directly into that pipeline extension (server team #805 will wire it up).
- Compact members default to `gate_energy_connected = false` per D-186 — your zone assignments also drive that default, so precision matters.
**#803 — Define shadow economy intensity ranges**
- Output: `wiki/economics/shadow_economy.toml` with per-system-type intensity ranges.
- Geographic bands from D-174: core systems 0.0–0.2, mid-reach 0.3–0.6, Compact and frontier 0.6–0.9.
- Seeding inputs (additive, D-174): Commission presence (inverse — high Commission = low shadow), Compact membership (elevated independently of distance), hop distance from Core, gate topology (dead-end systems higher than transit nodes).
- Critical framing (D-174): The Compact's shadow economy is **principled economic resistance** to Assembly currency friction on enforcement costs — not frontier lawlessness. This distinction must be legible in the intensity value commentary and any associated narrative notes. Compact members at hop 6+ can have high intensity (0.7–0.8) while remaining culturally coherent citizens.
- The `official_coverage_ratio` signal (D-181 signal 7) is derived from this data — it is the gap between what the lattice audit trail sees and the real economic activity. Write the TOML so it is queryable by system_type and by specific system_id overrides.
- Paula owns the narrative framing. Miri owns geographic distribution. Mellanie owns the file structure and prose flavor.
**#799 — Generate ~150 Tier-2 regional corporations**
- #798 (archetype taxonomy) is DONE. `wiki/economics/archetypes/lore.toml` (28 lore-taxonomy archetypes: extraction, agriculture, manufacturing, trade/logistics, services, intelligence, east-reach) and `wiki/economics/archetypes/behavioral.toml` (6 behavioral archetypes) are the templates.
- Output: TOML records in `wiki/economics/corporations/tier2/` — one file per corporation or one file per corridor/sector (your call, but keep it reviewable in git).
- Each record needs: name, sector (lore archetype), corridor, backstory, distinct character, behavioral archetype. Plus: `products[]` — 2–5 branded product names based on primary commodity and cultural corridor. Brands are authored, not templated (D-185).
- Distribution: across all corridors including east reach. East reach was flagged as a gap in D-175 — ensure coverage there. Coverage rule: every commodity type must have at least one Tier-2 producer; every major corridor must have at least one Tier-2 firm.
- These corporations are the regional competitors — the ones that can fail, grow, or be acquired. Give them distinct character: each should feel like a real business with a particular personality, not a slot-filler. A Cooperative in Braemar behaves and speaks differently from an Intermediary in the Compact zone.
- The Tier-2 corpus feeds #809 (server corporate agents) — server team will read `behavioral_archetype` from these records to instantiate simulation parameters. Keep that field clean.
**#800 — Build corporation generation pipeline for Tier-3**
- Note: this ticket is assigned to the **server team** (it is a Rust binary). The copy team's dependency is upstream: the archetype TOML files in `wiki/economics/archetypes/` must be finalized before the pipeline runs. Verify with server team that `lore.toml` and `behavioral.toml` schemas are stable before Sprint 33 mid-point.
- Copy team action for this ticket: review and sign off on the generated output (`generated_corporations.toml`) for lore consistency. The Tier-3 instances stock brands from Tier-1 and Tier-2 corporations in the same supply chain corridor — Paula should verify the brand attribution feels geographically coherent.
**#812 — Wiki commodity copy pass**
- 36 commodity stub pages exist at `wiki/economics/commodities/` — currently auto-generated field tables only (no flavor text).
- Output: flesh out each stub with flavor text, lore context, and production chain descriptions.
- Reference: `wiki/economics/commodities/index.md` for the full list. Reference: `wiki/economics/commodities.toml` and `wiki/economics/production_chains.toml` for the technical data to translate into prose.
- Voice: these pages appear in the implant wiki (GTTR equivalent for economic data). Write them as objective technical/commercial entries — not marketing copy, not academic dry. The voice of an economic intelligence briefing that a trader would actually read.
- Key commodities to handle with care:
- `fusion_fuel` — intermediate, not raw; 8:1 water yield ratio (D-187); utility demand at every node; frontier premium is structural, not event-driven.
- Services (`commission_certification`, `financial_services`, `medical_reembodiment`, `insurance`, `entertainment`, `hospitality`) — location-bound, non-transportable through gates; they consume goods but do not produce them.
- Brands are NOT commodities (D-185) — do not create stub pages for Calloway whisky, VGV wine, etc. The catalog terminates at abstract generic finals (e.g., "premium spirits").
- Mellanie owns the writing. Paula reviews for narrative voice consistency. Miri flags any lore collisions.
## Dependency Chain
```
#820 (Compact zone assignments) → feeds server #805 corp pipeline
#803 (shadow economy ranges) → feeds server #808 currency zones ticket
#799 (Tier-2 corps) ──────────────────────────────→ #809 (server: corporate agents)
#800 (Tier-3 pipeline, server executes) ──────────→ #809 (server: corporate agents)
#812 (commodity copy) → standalone, no code blockers
```
#799 and #803 are the sprint-critical outputs — server team cannot close #808 and #809 without them. Start these first.
## PR Workflow
When ready to submit, create a PR with `tea` CLI. **All flags are required** to avoid TTY prompts (see CLAUDE.md "Gitea access" section):
```bash
tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(copy): description" --description "body" --base main --head sprint-33/copy
```
docs/sprints/sprint-33/joint.md
+83
View File
@@ -0,0 +1,83 @@
# Sprint 33: Pecunia — Joint Notes
**Goal:** Full economics simulation running — Leontief production, spatial price equilibrium, currency zones, corporate behavioral agents across all three corporation tiers, stability tests passing.
## Sprint Completion Proof
When Sprint 33 is done, you can:
1. **Run `economy-sim --stability-check`** and see all four D-179 tests pass: cold-start convergence (±5% within 100 days), long-run stability (no drift > ±2% over 1,000 days), shock response (recovery within 200 ticks, no negative prices), cross-zone re-stabilization (within 50 ticks).
2. **See Compact systems with `MARK_PRIMARY` currency zones** in `server/data/systems.db` — `SELECT system_id, currency_zone FROM star_systems WHERE currency_zone != 'TRACTUS_PRIMARY'` returns a non-trivial list matching Compact membership.
3. **See 150 Tier-2 corporations** in `wiki/economics/corporations/tier2/` with distinct names, corridors, backstories, and branded product lists.
4. **See `generated_corporations.toml`** with 5,000+ Tier-3 template instances covering all inhabited systems.
5. **Read 36 commodity wiki pages** at `wiki/economics/commodities/` with full flavor text, lore context, and production chain descriptions.
6. **See `wiki/economics/shadow_economy.toml`** with per-system-type intensity ranges authored and annotated.
7. **See the `icon_tint.gdshader`** in the client with recoloring working on both stroke and fill icon types at all implant theme semantic colors.
8. **Grep for `qdrant`** in the repo and find no references (removal complete).
## Phase 2 Context
Phase 2 deliverable (D-166): "Economics spreadsheets/graphs with runtime-tweakable simulation."
Sprint 33 is the first economics implementation sprint. The economics schema (`#804`, DONE), commodity catalog (`wiki/economics/commodities.toml`), and production chains (`wiki/economics/production_chains.toml`) were completed in Sprint 32. The Tier-1 corporation corpus (38 named corporations, `#797`, DONE) and archetype taxonomy (`#798`, DONE) are also in place.
This sprint builds the simulation binary and completes the corporation corpus (Tier 2 authored, Tier 3 generated). It does not close Phase 2 — the phase deliverable includes the full signal pipeline and runtime-tweakable parameters, which will be Sprint 34+ work. But passing all four stability tests in Sprint 33 validates the model architecture and unblocks everything downstream.
## Pre-Sprint Checklist
Before any simulation code is written, verify:
| Item | Owner | Status |
|------|-------|--------|
| `server/data/systems-schema.sql` has `currency_zone` on `star_systems` | server | Done (#804) |
| `corp_presence` table exists in schema | server | Done (#804) |
| `wiki/economics/commodities.toml` — 36 types present | copy | Done (#801) |
| `wiki/economics/production_chains.toml` — 21 chains present | copy | Done (#801) |
| `wiki/economics/archetypes/lore.toml` — 28 archetypes defined | copy | Done (#798) |
| `wiki/economics/archetypes/behavioral.toml` — 6 archetypes defined | copy | Done (#798) |
| 38 Tier-1 corporations in DB + wiki | copy | Done (#797) |
## Cross-Team Dependencies
The server simulation chain (#806 → #807 → #808 → #809) has hard blockers on copy team output:
- **#809 (corporate agents)** cannot be started until #799 (Tier-2 corps) is in a queryable state. Server team must be able to read `behavioral_archetype` from Tier-2 TOML records.
- **#808 (currency zones)** consumes `wiki/economics/shadow_economy.toml` (#803) for per-node `shadow_economy_intensity`. Copy team should deliver #803 by mid-sprint.
- **#805 (corp pipeline)** will wire in Compact zone assignments from #820. Copy team must finalize the list of `MARK_PRIMARY` system IDs before #805 runs its full validation pass.
- **#800 (Tier-3 pipeline)** is a server Rust binary but reads archetype TOML format authored by copy. Schema for `wiki/economics/archetypes/` must be stable before #800 starts. Server and copy teams: align on this format in the first two days of the sprint.
## Iterative Development Cycle (D-183)
This sprint follows the iterative economics cycle: skeleton sim (#806) → data population (copy work running in parallel) → test (#807 stability) → currency layer (#808) → agents (#809). Copy and server work in parallel — they are not sequentially gated except at the #809 merge point.
If stability tests fail in #807, do not proceed to #808 until Tests 1 and 2 pass. The tâtonnement parameters (α=0.03, β=0.4) are starting values — Dudley/Tyre should tune them if the model oscillates or drifts. Report to team lead before making architectural changes.
## Dependency Chain
```
Server chain:
#813 (energy-over-gate schema) ─────────────────────────────────────────┐
#805 (corp pipeline + validation) → #806 (skeleton sim) |
→ #807 (trade flows + stability) |
→ #808 (currency zones) ←───┘
→ #809 (corporate agents)
Copy unblocks server:
#820 (MARK_PRIMARY assignments) → feeds #805 validation
#803 (shadow economy ranges) → feeds #808 shadow modifier
#799 (Tier-2 corps) ─────────────────────────────────────────────────→ #809
#800 (Tier-3 pipeline, server executes) ───────────────────────────→ #809
Independent:
#812 (commodity copy) → standalone
#818 (icon_tint shader, client) → standalone
#816 (remove Qdrant, CI) → standalone
```
## Not In Scope
- Phase 2 signal delivery to the Godot client — that is Phase 4 player interaction territory
- Event input port exercising — port is stubbed in #809, not exercised until Phase 3+
- Heightmap batch (#794) — deferred from Sprint 32, carries into a later sprint
- Character creation UI (#694, #618, #619) — Phase 4
- World generation — Phase 5
docs/sprints/sprint-33/server.md
+103
View File
@@ -0,0 +1,103 @@
# Sprint 33: Pecunia — Server Tasks
**Goal:** Full economics simulation running — Leontief production, spatial price equilibrium, currency zones, corporate behavioral agents across all three corporation tiers, stability tests passing.
**Branch:** `sprint-33/server`
**Agents:** Dudley (simulation dev), Tyre (architecture), Hoshe (QA)
## New Tickets
| # | Title | Blocked by |
|---|-------|------------|
| #813 | Energy-over-gate schema extension | — |
| #805 | Extend economy-db with corporation pipeline and validation | #804 (DONE) |
| #806 | Build skeleton economy_sim binary | #805 |
| #807 | Add trade flows and stability testing | #806 |
| #808 | Add currency zones and exchange rates | #807 |
| #809 | Add corporate agent behavior | #808, #799, #800 |
Use `tooling/db/ticket show <id>` for full ticket details.
## Key Decisions
- `decisions/economics.md` — D-171 (three-currency system), D-172 (currency zone initialization), D-173 (commodity taxonomy), D-174 (shadow economy layer), D-175 (corporation taxonomy), D-176 (productivity seeding), D-177 (productivity constraints), 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), D-183 (iterative development cycle), D-184 (commodity catalog 36 types), D-185 (brands not commodities), D-186 (gate transmission levels), D-187 (fusion fuel as intermediate)
- `decisions/architecture.md` — D-166 (development cascade: Phase 2 deliverable = economics spreadsheets/graphs with runtime-tweakable simulation)
## Notes
**#813 — Energy-over-gate schema extension**
- `currency_zone` column already exists on `star_systems` (`server/data/systems-schema.sql`). Need to add `gate_energy_connected` boolean column to the appropriate node table.
- Per D-186: `MARK_PRIMARY` zones default to `gate_energy_connected = false` (Compact refused Gate Corp dependency deliberately). All other zones default to `true`.
- Demand reduction: nodes with `gate_energy_connected = true` get ~0.3× `fusion_fuel` utility demand. The reduction applies only to utility/habitation consumption — industrial chain inputs (`smelt_ore` 0.3, `alloy_fabrication` 0.2, `electronics_fabrication` 0.2) are unaffected.
- This is a schema + migration ticket. No simulation logic yet — that is consumed by #806.
- The `gate_energy_connected` field will be read by the sim binary when it computes per-node utility demand.
**#805 — Extend economy-db with corporation pipeline and validation**
- The existing import pipeline (`tooling/economy-db/import_economics.py`) already handles: gate_links, commodities, production_chains, currency_zone on star_systems. The `corp_presence` table exists in schema but the comment at line 12 reads "Does NOT populate corp_presence — that's a future pipeline step." This is that step.
- Extend the pipeline to: read `wiki/corporations/*.md` and/or the DB `corporations` table, populate `corp_presence` rows from authored location data, validate that wiki corporation names match DB `corporations.proper_name` records (sync constraint from D-182), enforce coverage rules: 3+ corporations per major commodity type, 1+ per inhabited system with population > 100K.
- Add chain completeness validation: every intermediate commodity must have at least one production chain that produces it.
- Coverage validation failures must be hard errors (non-zero exit), not warnings. The Phase 2 prerequisite from D-175 requires this gate.
- Input: `wiki/corporations/` markdown files, `server/data/systems.db` (corporations and system_economy tables). Output: populated `corp_presence` table.
**#806 — Build skeleton economy_sim binary**
- New Rust binary at `tooling/econ-sim/`. Follow patterns from `server/src/bin/atlas/` for CLI structure (argparse via clap, SQLite reads via rusqlite).
- Loads transport graph from `systems.db` (`gate_links` table, bidirectional). Reads economy config from the built `.db` (commodities, production_chains, chain_inputs, corp_presence).
- Seeds per-corporation productivity from PRNG seed (D-176): five dimensions (`extraction_rate`, `processing_throughput`, `transit_capacity`, `service_throughput`, `service_capacity`). Log-normal distribution, 0.4–1.8× multiplier for standard nodes, 0.7–1.4× for monopoly-source nodes. Corridor correlation ~0.6 — nearby sites should draw correlated samples.
- Initial scope: Leontief production + consumption + price adjustment (Layer 1 only, per D-178). No inter-system trade flows, no currency zones, no corporate behavior.
- Outputs per-node CSV with: node_id, commodity_id, supply, demand, price, tick.
- The `--stability-check` flag is scaffolded here but not yet meaningful — it will be exercised in #807.
- Lore-derived constraints from D-177 must be respected: do not seed location of production, biological monopoly ceilings, aging pipeline contents, or gate topology.
**#807 — Add trade flows and stability testing**
- Extends the binary from #806 with Layer 2 (spatial price equilibrium via damped tâtonnement, α=0.03, β=0.4, per D-178).
- Prices propagate through the gate transport graph. Lagged adjustment — not instant equilibrium. Transport costs: 5–12%/hop on gate edges, 1–3% on orbital edges.
- Market node tiering (D-178): ~760 active market nodes (inhabited bodies + all stations), ~240 passive producers (feed output to nearest active node), ~2,700 inert. Floyd-Warshall over active subgraph at startup (~0.5s expected, one-time cost).
- Stockpile buffers per node: prevents instantaneous price explosions on single-tick supply disruptions.
- `--stability-check` mode must now pass Tests 1 and 2 from D-179:
- Test 1: Cold-start convergence — prices settle within ±5% of equilibrium within 100 game-days.
- Test 2: Long-run stability — zero drift > ±2% over 1,000 game-days with zero external events.
- If the model oscillates or diverges under no external input, that is a broken model, not a feature. Tune α/β first before concluding the model is wrong.
**#808 — Add currency zones and exchange rates**
- Extends the binary with Layer 2 currency dynamics (per D-171, D-172).
- Three currencies: Tractus (numeraire), Mark (Compact zone), Sol (shadow only — no formal exchange rate, modeled as shadow economy commodity per D-174).
- Cross-zone conversion friction: ~3% cost on Tractus↔Mark trade. Zero internal friction within `MARK_PRIMARY` zones (Compact "no internal tariffs" principle).
- Exchange rate float driven by trade balance — Tractus/Mark rate adjusts over time based on cross-zone import/export imbalances.
- Shadow economy modifier: apply per-node `shadow_economy_intensity` (0.0–1.0, from authored `wiki/economics/shadow_economy.toml` — authored by copy team in #803) to adjust shadow pricing signals. The `official_coverage_ratio` signal (D-181 signal 7) is derived from this.
- `--stability-check` must now also pass Tests 3 and 4 from D-179:
- Test 3: Shock response — after single supply shock, cascade propagates realistically, recovery within 200 ticks, no price explosions or negative prices.
- Test 4: Cross-zone trade balance — after cross-zone trade volume change, exchange rate adjusts and re-stabilizes within 50 ticks.
- Compact zone connectivity: `gate_energy_connected = false` nodes (from #813) should show elevated `fusion_fuel` utility demand in their signals.
**#809 — Add corporate agent behavior**
- Extends the binary with Layer 3 (corporate behavioral agents, per D-178).
- Six behavioral archetypes (D-175): Monopolist, Distributor, Producer, Specialist, Cooperative, Intermediary. Parameters are template-instantiated — read archetype templates from `wiki/economics/archetypes/behavioral.toml`, then instantiate per corporation from the populated `corp_presence` table.
- Corporations must be loaded from the DB (populated by #805 and seeded by copy team work in #799/#800). Do not hardcode corporation data.
- Each archetype has distinct price-setting behavior, trade routing preferences, and response to competitor presence. Details in `decisions/economics.md` D-175 and `wiki/economics/archetypes/behavioral.toml`.
- The event input port (D-180) is stubbed here — define the `EconEvent` struct with all fields (`target`, `effect`, `duration`, `visibility`) and a no-op handler. The port is not exercised until Phase 3, but must compile.
- All 7 signals from D-181 must be produced per active node: `price_current`, `price_trend`, `trade_flow_volume`, `corporate_presence`, `stockpile_weeks`, `production_vs_baseline`, `official_coverage_ratio`.
- This ticket closes the sprint: when all four stability tests pass with corporate agents active, the Phase 2 economics simulation is functionally complete.
- Blocked by #808 (currency layer must be in place) and #799/#800 (copy team corporation corpus must be available in DB).
## Dependency Chain
```
#813 (energy-over-gate schema) → consumed by #806, #808
#805 (corp pipeline + validation) → #806 (skeleton sim)
→ #807 (trade flows + stability)
→ #808 (currency zones)
→ #809 (corporate agents)
#799 (Tier-2 corps, copy) ─────────────────────────────────┐
#800 (Tier-3 pipeline, server) ────────────────────────────→ #809 (corporate agents)
```
Note: #800 (Tier-3 generation pipeline) is assigned to the server team (it is a Rust binary), but its output depends on archetype taxonomy (#798, DONE) from copy. Coordinate with copy team on `wiki/economics/archetypes/` TOML format before starting #800.
## PR Workflow
When ready to submit, create a PR with `tea` CLI. **All flags are required** to avoid TTY prompts (see CLAUDE.md "Gitea access" section):
```bash
tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(simulation): description" --description "body" --base main --head sprint-33/server
```