docs: define regional simulation contract

docs/LEARNING_ROADMAP.md

@@ -30,8 +30,16 @@ Do not advance because files exist. Advance when the exit test passes.
 
 The current implementation has completed ResourceNode migration through player
 parity, the Jajce scaffold/navigation proof, and the mandatory architecture
-gate below. See
-[ADR 0001](decisions/0001-simulation-authority-boundary.md).
+gate below. It also has a playable emergent Jajce proof: a real pantry shortage
+becomes knowledge, generated semantic dialogue, a journal projection, and an
+event-backed social commitment whose ordinary deposit outcome survives
+save/load. Definition packs now cover reusable items, resources, storage,
+enemies, and animals. Regional records, deterministic scheduled work, bounded
+presentation relevance, and the first authoritative caravan transfer form the
+next world-slice foundation. See
+[ADR 0001](decisions/0001-simulation-authority-boundary.md),
+[ADR 0002](decisions/0002-emergent-world-content-and-narrative.md), and the
+[regional simulation contract](REGIONAL_SIMULATION.md).
 
 ## Mandatory architecture gate
 

docs/README.md

@@ -23,6 +23,7 @@ captures are review artifacts, not runtime Godot resources.
 6. [`ACTION_SYSTEM_ARCHITECTURE.md`](ACTION_SYSTEM_ARCHITECTURE.md),
    [`ECONOMIC_EVENTS.md`](ECONOMIC_EVENTS.md),
    [`FOOD_STORAGE_ARCHITECTURE.md`](FOOD_STORAGE_ARCHITECTURE.md),
+   [`REGIONAL_SIMULATION.md`](REGIONAL_SIMULATION.md),
    [`SIMULATION_DEFINITIONS.md`](SIMULATION_DEFINITIONS.md), and
    [`SIMULATION_STATE_SCHEMA.md`](SIMULATION_STATE_SCHEMA.md) document the
    current data contracts.

docs/REGIONAL_SIMULATION.md

@@ -0,0 +1,134 @@
+# Regional simulation contract
+
+The regional layer extends the Jajce simulation without multiplying scene-tree
+managers. One authority owns every loaded and unloaded location, settlement,
+route, mobile group, named person, population cohort, polity, scheduled job,
+and objective world fact. A settlement or caravan scene is presentation, never
+a second simulation.
+
+This contract implements the direction accepted in
+[ADR 0002](decisions/0002-emergent-world-content-and-narrative.md).
+
+## Authoritative records
+
+`RegionalWorldState` is a canonical, primitive-only aggregate of:
+
+- `LocationStateRecord`: globally unique location identity and spatial context;
+- `SettlementStateRecord`: location, polity, tier, founding group, stockpile,
+  and exact history references;
+- `RouteStateRecord`: stable endpoints and simulation-time travel duration;
+- `MobileGroupStateRecord`: location or route state, detailed members, cohort
+  members, cargo, capacity, and exact cargo/history facts;
+- `PersonStateRecord`: a persistent named person at a location or in a group;
+- `PopulationCohortRecord`: a conserved anonymous population count at a
+  location or in a group;
+- `PolityStateRecord` and `DiplomaticRelationRecord`: sparse political
+  membership and pairwise state.
+
+Every ID is unique across record families. Every address includes the world and
+location, so equal local coordinates in different locations cannot create a
+false witness, target, or relationship. Membership and route references are
+validated transactionally before a replacement state is published. Canonical
+serialization sorts record families and IDs, making checksums independent of
+construction order.
+
+The current local `SimulationStateRecord` remains the v15 Jajce save boundary.
+Regional state is deliberately carried in its own versioned service envelope
+until one playable route consumes it; this avoids placing speculative regional
+fields in every local save. The merge into the production save manifest must
+retain this canonical regional payload rather than copying its fields into
+scene nodes.
+
+## Deterministic work
+
+`RegionalJobScheduler` orders jobs by:
+
+```text
+(due_tick, phase, entity_id, stable_sequence)
+```
+
+The queue and execution cursor are serialized together. Budgets may defer due
+jobs but cannot reorder, drop, or change them. Tests require budgets of one,
+eight, and unlimited jobs to produce the same ordered results and checksum,
+including work scheduled by another job during execution.
+
+`KeyedRandom` derives a decision from world seed, system ID, entity ID, and
+occurrence. It does not consume a shared stream, so loading a context or
+changing the job budget cannot alter another entity's result.
+
+`AnalyticalRegionalUpdates` advances elapsed-tick linear, exponential, and
+periodic processes without replaying every omitted tick. New distant systems
+should schedule threshold/completion work or compute from `last_updated_tick`;
+they should not add another global per-tick scan.
+
+## First caravan proof
+
+`RegionalCaravanService` is the first complete regional transaction. It owns a
+single envelope containing regional state, the due-job queue, the indexed world
+event store, and the next event ID.
+
+Departure performs one atomic sequence:
+
+1. validate group, route, endpoints, cargo availability, and capacity;
+2. withdraw exact cargo from the origin settlement;
+3. place that cargo in the mobile group;
+4. put the group on the route with authoritative departure/arrival ticks;
+5. record cargo-loaded and departed facts;
+6. schedule one deduplicated arrival job.
+
+Arrival atomically moves the group to the destination, transfers exact cargo
+to its stockpile, records arrived and cargo-deposited facts, and cites the prior
+fact in the causal chain. Any invalid reference, duplicate job, capacity
+failure, event collision, or handler failure restores all affected authorities.
+
+Presentation mode is intentionally absent from those decisions. Always-loaded,
+never-loaded, and load/unload executions must preserve cargo, headcount, facts,
+arrival tick, queue state, and checksum. Nearby visuals may interpolate route
+progress; they do not report elapsed travel completion.
+
+## Presentation relevance
+
+`PresentationRelevancePolicy` is a pure query over an active context and
+candidate descriptors. It selects at most 40 detailed visuals in stable order,
+after rejecting foreign worlds, contexts, and locations. Explicit pins,
+player-affecting threats, situation or commitment participants, leaders, and
+unique owners are mandatory. If mandatory candidates exceed the limit, the
+policy fails closed instead of silently erasing an important identity.
+
+`PresentationNavRequestBudget` admits at most two new navigation requests per
+frame. Both policies expose selected/rejected IDs and reason traces and do not
+enter authoritative saves.
+
+## Scale workload
+
+The regional structural workload is fixed at five settlements, 20 caravans of
+12 detailed members, 2,000 persistent named people, 50,000 aggregate
+residents, and metadata for no more than 40 detailed active visuals. It proves
+record validity, global-ID uniqueness, headcount/cargo conservation,
+deterministic scheduler budgets, an empty final backlog, repeatable checksums,
+and measured construction/execution/serialization time.
+
+This is a headless data-and-scheduler baseline. It does not claim rendered
+frame time, a complete market/economy, chunked persistence, or weak-PC GPU
+performance. Those claims require separate active-world and hardware captures.
+
+## Next integrations
+
+Build in this order, keeping each step behind conservation and continuation
+tests:
+
+1. make the Jajce route proof callable from the production regional facade and
+   save manifest;
+2. migrate legacy global world-target registries to explicit active contexts;
+3. make player and NPC work submit the same concrete action commands;
+4. segment high-volume event history and save regional records in atomic,
+   lazily loaded chunks;
+5. schedule 20 ordinary caravan trades across five settlement economies;
+6. promote/demote presentation and population fidelity while pinning named and
+   causally referenced people;
+7. add data-defined settlement projects, tier promotion, offices, diplomacy,
+   armies, campaigns, and aggregate conflict.
+
+Do not add city or kingdom special cases to `SimulationManager`. A new domain
+mechanic adds one reusable record/handler and ordinary world facts; new content
+combines existing definitions in `.tres` packs.