gamedev-the-steward/docs/REGIONAL_SIMULATION.md

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.

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:

(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.