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

# Sprint 25: Emerge — Server Tasks

**Goal:** Prove the generator can extrapolate from minimal input — a rural Krenn village from zone type and culture profile alone, no per-location spec.

**Branch:** `server`
**Agents:** Dudley (simulation dev), Tyre (architect)

## New Tickets

| # | Title | Blocked by |
|---|-------|------------|
| #611 | NpcBlueprint struct design | #609 (copy), #610 (copy) |
| #612 | Template assembly generator | #609, #610, #611 |
| #613 | NPC generation pipeline | #611, #612 |

Use `tooling/db/ticket show <id>` for full details.

## Key Decisions

- `decisions/scope.md` — D-114 (generator-first proof-of-life), D-119 (generator spike critical path), D-115 (skills + bookmark only for creation)
- `decisions/content.md` — D-122 (all NPCs generated), D-128 (culture implicit in location), D-129 (NPC personality: traits + behavior first), D-121 (voice culture-driven), D-123 (AI content templating via culture vectors)
- `decisions/architecture.md` — D-012 (chunk-based map, borderless generation future)

## What Exists

- **`server/src/simulation/generator.rs`** (576 lines) — `DistrictSkeleton` data model, `DistrictType`, `ZoningType`, `SocialSitePlacement`, `TriangleAssignment`, `BlockSkeleton`. This is the Phase 1 *data model* — struct definitions for what a generated district looks like. The *generator logic* that produces these structs from input parameters does not yet exist.
- **`server/src/npc/generate.rs`** — existing NPC generator taking a `RoleDefinition` (the 10-axis model: Want, Secret, Relationships, Tolerance, DailyRoutine, InformationInventory, Contentment, PersonalityTraits, TellSystem, SkillSet). Generates a fully-populated NPC entity via `SimRng` (deterministic, seeded). Sprint 25 work extends this pipeline, it does not replace it.
- **`server/src/npc/`** — full NPC component set: `awareness.rs`, `background.rs`, `disclosure.rs`, `generate.rs`, `interaction.rs`, `mod.rs`, `mood.rs`, `relationships.rs`, `routine.rs`, `tell_state.rs`, `tolerance.rs`, `trait_modifiers.rs`, `vision.rs`.
- **`server/src/content/`** — content loading: `entanglement.rs`, `hot_reload.rs`, `instantiation.rs`, `line_pool.rs`, `loader.rs`, `spawn.rs`, `template.rs`, `types.rs`.

## Notes

**#611 — NpcBlueprint struct design**

- Blocked by #609 and #610 (copy team delivers these first). Read those documents before writing the struct.
- This struct is the *interface* between the generator and all downstream systems: rendering, voice, AI templating, simulation.
- Must encode: trait set (from D-129), observable behavior surface (what a bystander can read), relationships (Sims + Rimworld style per D-129), role/occupation, cultural markers (feeds D-121 voice pipeline and D-123 AI templating), zone-type affiliation.
- The existing `RoleDefinition` in `npc/generate.rs` covers the 10-axis model. `NpcBlueprint` is a higher-level generator output that wraps role + cultural context + zone parameters. Think of `RoleDefinition` as "what the generator uses internally" and `NpcBlueprint` as "what the generator exports."
- Write the struct in `server/src/npc/blueprint.rs` (new file). Add a D-record reference in `decisions/architecture.md` or `decisions/content.md` when the struct is settled.
- Must be serializable (Serde) for inspection output (the sprint proof dumps the blueprint JSON to stdout).

**#612 — Template assembly generator**

- Blocked by #609, #610, #611.
- Input: zone type parameter (from zone identity spec), culture profile (from Krenn culture profile), seed (u64). No per-location spec. The whole point is extrapolating from minimal input.
- Output: a `DistrictSkeleton` (already defined in `server/src/simulation/generator.rs`) with `SocialSitePlacement` entries populated and `NpcBlueprint`s attached to each role slot.
- NOT procedural geography — template assembly. The generator picks a zone template from the zone identity taxonomy and fills it. The template provides the shape; the culture profile and seed provide the variety.
- Write generator logic in `server/src/simulation/generator.rs` (add below existing structs) or extract to `server/src/simulation/template_assembly.rs` — architect's call.
- The generator must be callable standalone (not as a bevy system) for the sprint proof (see joint.md).
- Determinism: use `SimRng` (ChaCha20, existing in `server/src/simulation/rng.rs`). Same seed + same zone type + same culture profile → same output.

**#613 — NPC generation pipeline**

- Blocked by #611 and #612.
- Wire the template generator output into actual NPC entity spawning.
- Input: `DistrictSkeleton` with `NpcBlueprint`s → spawn ECS entities using the existing `npc/generate.rs` pipeline, extended to accept cultural markers from the blueprint.
- The existing `RoleDefinition` in `npc/generate.rs` needs a cultural marker field (or the blueprint drives trait selection to match the culture profile).
- Proof-of-life test (in the sprint proof): print generated NPC trait sets and observable behaviors to stdout. A human reading the output should be able to say "yes, this NPC could plausibly exist in the Krenn System."
- D-129: traits + behavior first. The proof gate is not rendering — it is legibility from text output alone.

## Dependency Chain

```
copy #609 (zone spec) ──┐
                        ├──> #611 (NpcBlueprint) ──> #612 (template gen) ──> #613 (NPC pipeline)
copy #610 (culture) ───┘
```

Server work begins when copy delivers #609 and #610. #611 must be complete before #612 starts. #613 follows #612.

## 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): generator spike — NpcBlueprint, template assembly, NPC pipeline" --description "body" --base main --head server
```