diff --git a/docs/LEARNING_ROADMAP.md b/docs/LEARNING_ROADMAP.md index 0a89dd5..1042767 100644 --- a/docs/LEARNING_ROADMAP.md +++ b/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 diff --git a/docs/README.md b/docs/README.md index 226d71e..851f971 100644 --- a/docs/README.md +++ b/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. diff --git a/docs/REGIONAL_SIMULATION.md b/docs/REGIONAL_SIMULATION.md new file mode 100644 index 0000000..5458eef --- /dev/null +++ b/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.