docs: define emergent world architecture

docs/decisions/0002-emergent-world-content-and-narrative.md

@@ -0,0 +1,130 @@
+# ADR 0002: Content and narrative project authoritative world state
+
+- **Status:** Accepted
+- **Date:** 2026-08-12
+
+## Context
+
+The prototype already records stable simulation identities, economy events,
+knowledge, relationships, and knowledge-gated opportunities. Those foundations
+produce honest cause and effect, but several extension paths still depend on
+hard-coded action, item, enemy, animal, storage, interaction, and presentation
+branches. The existing opportunity proof also stops before player knowledge,
+commitment, generated dialogue, and regional simulation.
+
+If content, dialogue, and quests each gain their own mutable representations of
+the world, they will drift from the economy, combat, relationships, and NPC
+behavior. If distant settlements depend on loaded scenes, presentation state
+will change simulation outcomes. Conversely, an unrestricted reflection DSL or
+premature ECS would hide gameplay rules and make validation harder.
+
+## Decision
+
+The Steward will use an emergent-world architecture built from five distinct
+layers:
+
+1. Typed immutable definitions grouped in validated `.tres` content packs.
+2. Authored instance descriptors with stable contextual identity.
+3. Versioned mutable records containing stable IDs and primitive values only.
+4. Focused systems that validate commands and mutate records.
+5. Replaceable presentation bindings selected by stable cue IDs.
+
+Content packs enumerate definitions explicitly. A deterministic catalog rejects
+duplicate IDs, unknown references, invalid categories, and unavailable strategy
+handlers. Packs do not silently override each other. Saved worlds retain mutable
+instance state and definition IDs; current-build definition values provide the
+balance rules after load.
+
+Player and NPC interactions converge on the same `ActionCommand` contract.
+Targets advertise typed capabilities through context-scoped registries, while
+systems revalidate range, availability, reservation, costs, permissions, and
+expected revision before applying typed effects or a bounded custom handler.
+
+Meaningful actions mutate authoritative state first and then append structured
+world facts. Knowledge, relationships, situations, commitments, dialogue, and
+history reference those facts by stable ID. Every generated result includes a
+reason trace suitable for tests and developer inspection.
+
+A world situation is a bounded projection of an unresolved authoritative
+condition and its evidence. A quest journal stores only player discovery and
+tracking metadata for that situation. Accepting help creates a social
+commitment; it does not reserve the world or prevent another actor from solving
+the problem. Resolution, supersession, release, and failure refer to ordinary
+world events and apply idempotent economy or social consequences.
+
+Dialogue is deterministic and offline. The simulation selects semantic intents,
+topics, options, and actions from current knowledge, relationships, roles,
+situations, commitments, and history. Rendered prose is derived presentation and
+is never authoritative save state. Dialogue Manager v3 is isolated behind a
+presenter adapter; its conditions and mutations do not own game rules.
+
+One regional simulation owns settlements, routes, mobile groups, people,
+cohorts, polities, scheduled jobs, and objective history. Loaded world scenes
+are optional contexts. Distant travel and work resolve from deterministic
+scheduled state; nearby visuals only interpolate or report local feasibility.
+Frame budgets may defer due work but may not reorder it or alter outcomes.
+
+Simulation relevance has four intended tiers: active detailed presentation,
+local abstract individuals, distant named people/mobile groups, and aggregate
+settlement cohorts. Named or causally important identities are pinned and may
+not be erased by aggregation.
+
+## Data-only extension boundary
+
+No-code authoring is guaranteed for new combinations of registered typed
+predicates, capabilities, effects, behavior profiles, dialogue intents,
+situation objectives, and presentation cues. A fundamentally new mechanic adds
+one explicit reusable strategy handler with focused tests. It does not add a
+private script to every content instance, nor does it expand a universal
+reflection-based language.
+
+## Consequences
+
+- Existing stable IDs remain append-only. Renames require aliases and explicit
+  save migration.
+- Definition, state, system, and presentation changes are reviewed separately
+  even when delivered in one vertical slice.
+- Headless simulation cannot load presentation catalogs or assets.
+- Quest and dialogue tests assert exact causal facts and semantic options rather
+  than prose alone.
+- World registries become context-scoped before more locations are loaded.
+- Visual travel must be replaced by simulation-time route authority before
+  regional scale is considered correct.
+- Global scans, unbounded history, and monolithic saves must be measured and
+  replaced by indexes, scheduled work, retention/rollups, and chunking as the
+  regional workload grows.
+- The first proof is one complete Jajce shortage conversation and commitment;
+  the first regional proof is one exact caravan transfer between Jajce and an
+  abstract settlement.
+
+## Rejected alternatives
+
+- **Scripted quest and dialogue graphs as authority:** fast for isolated content,
+  but duplicates world state and cannot guarantee systemic resolution.
+- **One simulation manager and scene per settlement or caravan:** creates
+  identity collisions, freezes unloaded work, and multiplies global registries.
+- **Runtime free-form language generation:** non-deterministic and outside the
+  offline, inspectable simulation contract.
+- **Universal ECS or reflection DSL now:** too broad for the proven consumers
+  and obscures validation and save compatibility.
+
+## Staged migration
+
+1. Add content catalogs, indexed world facts, scoped target capabilities, and
+   shared action-command value contracts.
+2. Complete the Jajce knowledge, situation, commitment, and generated-dialogue
+   slice using ordinary economy actions.
+3. Migrate enemies, animals, resources, items, storage, and presentation cues
+   one record family at a time.
+4. Introduce regional identity, deterministic scheduled jobs, authoritative
+   routes, and one exact caravan transfer.
+5. Add relevance tiers, history rollups/chunked persistence, settlement growth,
+   and polity systems only behind deterministic conservation and performance
+   gates.
+
+## Revisit when
+
+Revisit this decision only if measured vertical slices show that typed
+definitions and bounded handlers cannot express recurring content safely, or if
+another authority model demonstrably improves deterministic unloaded simulation,
+save migration, and explainability together.