settled-reach/docs/sprints/sprint-35/server.md

# Sprint 35: Atlas — Server Tasks

**Goal:** Launch Phase 3 — build the atlas generation pipeline (terrain population, city placement, Gemma naming) and lay the brand layer DB schema, so all inhabited bodies have generated markers and the economics simulation uses world-seeded randomness.

**Branch:** `sprint-35/server`
**Agents:** Dudley (simulation/tooling), Tyre (architecture)

## New Tickets

| # | Title | Blocked by |
|---|-------|------------|
| #826 | Thread world seed from StartupMessage into economy simulation | — |
| #827 | Add brand_products, brand_inputs, system_fiscal schema and Phase 2 demand stubs | — |
| #839 | Batch populate terrain_reference column in systems.db bodies table | — |
| #832 | Build generate_atlas.py — terrain-aware sequential city placement and infrastructure generation | #839 |
| #833 | Gemma 2 batch naming pipeline for atlas geographic features | #832 |

## Key Decisions

- `decisions/architecture.md` — D-188 (biome_summary → planet_class rename, affects pipeline scripts), D-191 (Atlas Phase 3 scope — full pipeline spec: city placement algorithm, infrastructure gen, naming, markers.json schema)
- `decisions/economics.md` — D-189 (brand layer architecture — DB schema per section 5), D-190 (brand volume calibration — population-relative scale), D-185 (brands are not commodities — brand corps are commodity demand nodes), D-175 (corp taxonomy — Tier 1 brand corps), D-182 (TOML source of truth — make economy-db extends to brand tables)

## Notes

### #826 — Thread world seed into economy simulation

Small, self-contained. `server/src/simulation/mod.rs` initializes `EconSimResource` with `try_load_economy(0)` — the `0` is a hardcoded seed. Wire in the `world_seed` from `StartupMessage` (received during the IPC handshake). The seed is already available in the simulation startup path; find where `StartupMessage` is handled and thread the value through to `try_load_economy()`. Start here — it unblocks nothing else but is low-risk and closes the Sprint 34 loose end.

### #827 — Brand layer DB schema and Phase 2 demand stubs

Per D-189 section 5, add five new tables to `db/schema.sql` (or `server/data/systems-schema.sql` if that is the brand-layer schema file — check which file `make economy-db` reads):

- `brand_products` — full column list in D-189 section 5
- `brand_inputs` — `brand_product_id`, `commodity_id`, `quantity`
- `system_fiscal` — `system_id`, `corp_tax_rate`, `collection_efficiency`
- `corp_financial_state` — passive tracking (Phase 2: health metric only)
- `corp_lifecycle_events` — Phase 3 lifecycle state machine (Phase 2: stub table with correct schema)

Add composite index on `brand_products(corp_id, brand_category)` for UI queries (D-189 section 5).

Also author `wiki/economics/corporations/brands.toml` (new file) with TOML records for the 4 canonical brand corps: Calloway Distillery, Vins de Grand Vide, thrds, Bífröst Marmor. Each record registers those corps as commodity demand stubs at their home market nodes — they consume generic commodity inputs (per D-185: brands consume commodities, not the reverse). The copy team (#830) is authoring these same entries to `tier1.toml`; coordinate — the brand corps should appear in `tier1.toml` (copy) AND have separate `brand_products` entries (this ticket). Do not duplicate data; confirm the split before writing.

Extend `make economy-db` to compile brand tables alongside the existing pipeline. Add validation rules V-B01 through V-B05 (defined in the ticket description).

### #839 — Batch populate terrain_reference

The `bodies` table in `server/data/systems.db` has a `terrain_reference` column that is NULL for all 273 inhabited bodies. Write a batch script (Python fits alongside the existing `tooling/planet-gen/` scripts) that:

1. Queries all body rows with NULL `terrain_reference`
2. Constructs the expected wiki heightmap path: `wiki/star-systems/{system_slug}/bodies/{body_id}/heightmap.png`
3. Verifies the file exists
4. Updates the column

Log any bodies where the heightmap is missing so they can be flagged. This is the prerequisite for `#832` — `generate_atlas.py` reads `terrain_reference` to find the heightmap. Keep the script simple; it's a data population pass, not logic.

### #832 — Build generate_atlas.py

New Python pipeline at `tooling/planet-gen/generate_atlas.py`. Reuses `planet_simulation.simulate()` for terrain data. Per D-191 section 3 and 9:

**Pipeline order:**
1. Load heightmap via `terrain_reference` (populated by #839)
2. Analyze terrain: continent detection (flood-fill), habitability scoring (temperature + moisture + slope), river mouth identification
3. Place cities sequentially:
   - Capital first: ~50% at river mouths, scored by habitability + coastal access + flat hinterland
   - Rail corridor growth: cities 2-N follow the capital's terrain corridor
   - New continent ports at cities 3-4 (cross-continent expansion)
4. Generate infrastructure: A* pathfinding for roads and rail on terrain cost grid, MST network connecting cities
5. Apply quadrant distribution constraint (cities should not all cluster in one area)
6. Apply ±25% noise for variation
7. Compute city count from population: `floor(log10(pop / 1_000_000))`, modified by `settlement_pattern` from systems.db
8. Write `markers.json` per body (schema per D-191 section 8: cities with lat/lon/population_tier/primary_function/gate_terminal/continent_id, roads, railroads, POIs)

**make target:** `make atlas-generate` — incremental, skips bodies where `markers.json` already populated. Deterministic per seed.

Naming step is NOT in this ticket — city names will be blank strings in this pass; `#833` fills them. Gate terminal POI: place at largest population center, occasionally scatter to a smaller one (per D-191).

Existing files to reuse: `tooling/planet-gen/planet_simulation.py`, `tooling/planet-gen/biome_config.py`. The `generate.py` script already calls `_build_markers()` for rivers/oceans/mountains — extend that structure rather than replacing it.

### #833 — Gemma 2 batch naming pipeline

Extend `generate_atlas.py` with `tooling/planet-gen/gemma_naming.py` — a batch client for the `sr-voice` binary. Per D-191 and D-191 cross-reference to D-138 (Gemma 2 voice pipeline):

For each body, send corridor-appropriate naming prompts:
- Prompt context: `planet_class`, `cultural_corridor`, `settlement_pattern`, `atmospheric_tone` + corridor palette
- Name: rivers, oceans, mountain ranges, regions, city names (already placed by #832, just unnamed)
- Naming patterns per D-189: `north_reach` → British/Australian inflection, `east_reach` → Korean/Japanese, `west_reach` → German/Dutch/Nordic, `south_reach` → Portuguese/Swahili, `inner_corridor` → pan-corridor neutral, `frontier` → founder surname + noun

Post-processing:
- Earth-name blocklist (filter obvious Earth names that slip through)
- Dedup check against full name corpus per body
- Estimated runtime: ~80 min for all 2,394 bodies — make this batch incremental

This ticket serves dual purpose: Phase 3 content delivery AND a quality test of the Gemma 2 naming pipeline ahead of its broader use.

The `sr-voice` binary lives in `server/src/voice/` — check existing voice pipeline callers in the codebase for the batch invocation pattern before writing new code.

## Dependency Chain

```
#826 (seed wiring) — standalone, start first (small)

#827 (brand schema + demand stubs) — standalone, parallel track

#839 (terrain_reference populate) → #832 (generate_atlas.py) → #833 (Gemma naming)
```

`#839 → #832 → #833` are sequential. `#826` and `#827` are fully parallel to the atlas chain. Atlas pipeline is the sprint's critical path.

## PR Workflow

```bash
tea pr create --repo jpmschweitzer/settled-reach --login schweitz \
  --title "feat(simulation): atlas generation pipeline and brand schema" \
  --description "Sprint 35 server work: terrain_reference population, generate_atlas.py, Gemma naming, brand DB schema, world seed wiring" \
  --base main --head sprint-35/server
```