docs: define emergent world architecture

AGENTS.md

@@ -77,6 +77,47 @@ Preserve the simulation/presentation boundary.
 When adding a system, first prove the contract with one real gameplay use case.
 Do not extract generic frameworks before multiple real consumers justify them.
 
+## Emergent-world doctrine
+
+The game world is the source of narrative truth. Dialogue, tasks, quests, and
+visible happenings must arise from ordinary simulation state and events rather
+than maintaining parallel scripted copies.
+
+- Keep immutable definitions, authored instance placement, mutable state,
+  systems, and presentation as separate layers.
+- Persist stable IDs and primitive data only. Saved state must never contain
+  scripts, nodes, `NodePath`s, callables, or resource paths.
+- Mutate authoritative state before recording the fact that describes the
+  mutation. Facts may reference exact causes; they may not stand in for a
+  missing world change.
+- Treat dialogue prose as presentation. Semantic intents, selected response
+  IDs, action commands, commitments, and their causal world events are the
+  authoritative contract.
+- Treat quests as player-facing projections of real unresolved situations.
+  Never create quest-only enemies, items, damage, relationships, resources, or
+  completion facts.
+- Route player and NPC interactions through the same authoritative action and
+  capability contracts. Presentation can suggest or submit a command, but the
+  simulation must revalidate it.
+- Loaded visuals must not decide whether travel, work, growth, or distant
+  conflict completes. Presentation interpolates authoritative state and may
+  report local feasibility or obstruction.
+- Every generated action, situation, helper, dialogue intent, or consequence
+  must expose a concise reason trace with the definition and causal fact IDs
+  that justified it.
+- “Data-only content” means new combinations of existing typed predicates,
+  capabilities, effects, behavior profiles, and presentation cues. A genuinely
+  new mechanic adds one bounded reusable handler and tests; it does not add one
+  script per item, creature, quest, or conversation.
+- Prefer typed Godot resources, composition, deterministic registries, and
+  explicit strategy handlers. Do not introduce a universal reflection DSL or
+  rewrite the project as a full ECS.
+
+The intended extension path is therefore definition plus content pack, optional
+presentation cue, and authored placement or simulation spawn. A berry, bear,
+caravan, shortage, or conversation topic should reuse the same state, action,
+event, and presentation contracts that existing content uses.
+
 ## Resource and target rules
 
 Do not reintroduce abstract food/wood task-zone fallbacks.

docs/ARCHITECTURE_OVERVIEW.md

@@ -5,6 +5,30 @@ Serializable simulation records are authoritative; loaded Godot nodes present
 that state and contribute active-world facts such as positions and navigation
 results.
 
+## Emergent content and narrative boundary
+
+Definitions, authored placements, mutable records, systems, and presentation
+are separate layers. New content is registered through deterministic typed
+content packs and stable definition IDs. World targets expose capabilities in an
+active-context registry; player and NPC actors submit the same authoritative
+action commands. Presentation catalogs resolve stable cue IDs without entering
+headless simulation or saved state.
+
+World events describe completed authoritative mutations. Knowledge,
+relationships, unresolved situations, commitments, dialogue topics, and quest
+journal entries reference those exact facts instead of creating parallel quest
+state. Dialogue planning owns semantic intents and options; rendered prose and
+the Dialogue Manager balloon are replaceable presentation. Every generator
+returns its definition, causal references, and rejection/selection reason so a
+developer can trace why the world produced an outcome.
+
+Regional expansion uses one simulation authority. Locations, settlements,
+routes, mobile groups, people, cohorts, and polities are data records; loaded
+scenes are optional presentation contexts. Scheduled simulation-time work owns
+distant travel and completion, while visuals interpolate nearby state. This
+direction is governed by
+[ADR 0002](decisions/0002-emergent-world-content-and-narrative.md).
+
 ## Runtime flow
 
 ```text

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.