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

Sprint 12: Build — Server Tasks

Goal: Lay the production-layer foundations — simulation tier system, sound event pipeline, visual grammar, and knowledge boundary enforcement — and complete all v0.1 copy authoring so content packs, opening hooks, and world-building docs are done.

Branch: server Agents: Dudley (simulation dev), Tyre (architect), Hoshe (QA)

Carry-over from Sprint 11

None. Sprint 11 was 7/7 done.

New Tickets

#	Title	Blocked by
#93	Tier marker components	—
#94	Active tier simulation	#93
#99	Tier transition logic	#93
#138	Information tag schema	—
#139	Component-level access control	#138
#124	Sound event system — server	—
#193	Line previewer CLI	—

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

Key Decisions

• decisions/architecture.md — D-020 (Godot + Rust IPC), D-041 (Knowledge Graph data model), D-066 (dual-scale grid: 0.5m sim, 1m visual)
• decisions/perception.md — D-017 (perception modes), D-018 (three-range sound model)
• decisions/scope.md — D-027 (vertical slice), D-053 (movement stance system)

Notes

#93 — Tier marker components

• Epic #40 (Simulation Tier System) is entirely unstarted — this is the entry point.
• Deliver three zero-sized marker components: ActiveSim, BackgroundSim, StateSaved.
• Add a TierPlugin that registers them. Tag-based: systems query With<ActiveSim> to scope work to nearby NPCs only.
• Lives in server/src/simulation/tier.rs (file exists; currently stubs the stance system — check before overwriting).
• Integration point: all NPC behavior systems in server/src/simulation/ should gain With<ActiveSim> query filters once this exists.

#94 — Active tier simulation

• Full behavior systems (movement, perception, dialogue, monologue) run at 10–20 ticks/sec for ActiveSim NPCs only.
• Practically: add With<ActiveSim> filter to the movement, pathfinding, observation, and monologue systems in server/src/simulation/.
• No new systems needed yet — this is scope-gating existing ones.
• Blocked by #93 (marker components must exist first).

#99 — Tier transition logic

• Promote StateSaved → BackgroundSim → ActiveSim when player approaches; demote on departure.
• Budget: 2–5ms reactivation. Use SpatialIndex trait (see server/src/simulation/ — check if SpatialIndex already exists from earlier sprints; if not, #340 defines it but is still backlog — implement the naive Vec version inline for now).
• Tier transitions fire on position-change events. Wire to the existing movement system in server/src/simulation/movement.rs.
• Blocked by #93.

#138 — Information tag schema

• Completes the knowledge graph work from Sprints 2–3 (#361–367 all done).
• Define ObserverAccess enum: Public, OwnerOnly, FactionOnly(faction_id), RelationshipGated(threshold), KnowledgeGated(flag).
• Add as component metadata attribute — each ECS component that carries sensitive data gets an #[access = ...] annotation (or a companion AccessRule component).
• Lives in server/src/knowledge/types.rs (already exists — add to the existing types file).
• This schema is what #139 enforces.

#139 — Component-level access control

• Query filter layer: observer queries (the observer/ module under server/src/perception/) must respect ObserverAccess tags before returning data.
• Implement as a filter function on the observer snapshot builder: filter_by_access(observer_entity, component_access_rule, kg: &KnowledgeGraph) -> bool.
• The KnowledgeGraph component (done, server/src/knowledge/graph.rs) provides the knowledge state needed for KnowledgeGated checks.
• Blocked by #138.

#124 — Sound event system — server

• SoundEventEmitter component: emits typed events (Footstep, Voice, Machinery, Alert, Ambient) with position, intensity, RangeCategory (Close/Medium/Long per D-018).
• SoundEventQueue resource: collects events each tick, fans out to subscribers (client bridge + NPC awareness).
• Wire into the bridge: sound events within player LOS range → included in ObserverSnapshot as a sound_events vec.
• Existing audio manager on client (client/scripts/autoloads/audio_manager.gd) expects a sound_events array in the snapshot — confirm field name matches.
• Unblocked (standalone). #125 on client is blocked on this.

#193 — Line previewer CLI

• Rust binary (tooling/line-previewer or server/src/bin/line_preview.rs) sharing code with the dialogue pipeline.
• MVP: (1) load YAML content pack, (2) set filter context via CLI flags (--character smuggler --knows smuggling_operation), (3) print matching lines, (4) --explain mode shows why each line matched/filtered, (5) sequence preview for ordered monologue.
• Shares server/src/content/ types (LinePool, ContentLoader).
• This tool is what Mellanie needs before authoring content packs — unblocks #190, #191, #192.

Dependency Chain

#93 (tier markers) → #94 (active sim) → #99 (tier transitions)
#138 (access schema) → #139 (access control)
#124 (sound events) — standalone, unblocks client #125
#193 (line previewer) — standalone, unblocks copy #190, #191, #192

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): Sprint 12 server — tier system, sound events, KG access control" --description "body" --base main --head server