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 NpcBlueprints 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 NpcBlueprints → 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):

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