docs: add current developer feature index

2026-08-13 00:26:55 +02:00
parent 149e043f86
commit 9872b986b6
21 changed files with 1296 additions and 45 deletions
@@ -0,0 +1,117 @@
+# Feature slice: regional simulation and persistence
+
+The regional package is the scale foundation for one authority spanning
+settlements, routes, caravans, named people, aggregate cohorts, and polities.
+It is intentionally additive: the current Jajce `SimulationManager` remains
+the playable local facade while the regional contracts prove deterministic
+unloaded work and conservation in isolation.
+
+## Regional record model
+
+`RegionalWorldState` is a primitive-only, versioned aggregate with deterministic
+indexes for:
+
+- `LocationStateRecord` — world/location identity, type, address, and history;
+- `SettlementStateRecord` — location/polity, tier, founding group, stockpile;
+- `RouteStateRecord` — endpoints, travel ticks, direction, history;
+- `MobileGroupStateRecord` — caravan/army identity, membership, route state,
+  cargo ledger, capacity, arrival/departure ticks, and cargo event cursor;
+- `PersonStateRecord` — globally unique named people and memberships;
+- `PopulationCohortRecord` — conserved aggregate residents;
+- `PolityStateRecord` and `DiplomaticRelationRecord` — sparse regional politics.
+
+Membership is explicit and validated: a person is at one location or in one
+mobile group, routes connect existing locations, groups reference existing
+routes/members, and IDs are globally unique and append-only. Records contain
+stable IDs and primitive values only; no scene, `NodePath`, resource, or
+callable can enter the regional payload.
+
+## Deterministic scheduled work
+
+`ScheduledJobRecord` and `RegionalJobScheduler` order due work by:
+
+```text
+(due_tick, phase, entity_id, stable_sequence)
+```
+
+The scheduler supports O(log n) insertion/cancellation, deterministic due
+draining, repeats, dedupe keys, a serialized cursor, and strict restore
+validation. A frame or service budget may process one, eight, or unlimited jobs
+per call, but all budgets must produce the same order, checksum, and final
+backlog. Dynamic jobs inserted while draining are ordered into the same queue,
+not handled by an ad-hoc frame loop.
+
+`KeyedRandom` derives values from `(world_seed, system_id, entity_id,
+occurrence)`, so update order and save/load do not consume another entity's
+random stream. `AnalyticalRegionalUpdates` advances elapsed needs, growth, and
+periodic work from last-updated ticks instead of scanning every entity each
+tick.
+
+## The caravan proof
+
+`RegionalCaravanService` owns an envelope containing `RegionalWorldState`,
+`RegionalJobScheduler`, and `WorldEventStore`. `depart()` validates origin,
+destination, route, cargo capacity, group status, and exact state; it withdraws
+the cargo and schedules a typed arrival. The arrival handler updates the group,
+deposits the exact cargo into the destination settlement, and appends the causal
+load/depart/arrive/deposit chain. Presentation mode is an input label for the
+test, never an authority branch.
+
+The service is transactional: invalid jobs, forged event pairs, stale event
+cursors, duplicate departure pairs, and malformed restore envelopes fail with
+no partial mutation. `to_dictionary()`, `from_dictionary()`, and `checksum()`
+provide deterministic save/restore. The test runs always-loaded, never-loaded,
+and load/unload presentation modes through the same authoritative service.
+
+## Chunked persistence
+
+`RegionalChunkedPersistence` captures the service into a manifest plus fixed
+primitive chunks:
+
+- one global index;
+- one location chunk per location;
+- one mobile-group chunk per group;
+- one scheduler chunk;
+- fixed-size event segments.
+
+Each descriptor contains record count, byte size, and SHA-256 checksum. Restore
+rejects missing, duplicated, unknown, reordered, tampered, out-of-scope, or
+non-primitive chunks. `load_active_location_metadata()` reads the global index
+and one location while retaining authoritative references to unloaded chunks.
+
+`RegionalChunkedFileStore` writes immutable fixed-width generation directories,
+validates a temporary generation before install, updates a small current
+pointer, recovers the newest valid generation when the pointer is stale, and
+keeps at least two valid generations when pruning. It uses Godot's available
+flush/close/rename primitives; a platform fsync is not exposed by this layer.
+The store has explicit path, file-count, chunk-size, generation-size, and
+primitive-tree bounds.
+
+## Current integration boundary
+
+The regional package is not yet the production authority for `main.tscn`:
+
+- Jajce local saves still use `SaveSlotStore` and `SimulationStateRecord` v16;
+- `RegionalCaravanService` is a complete isolated transfer proof, not the live
+  economy's 20-trade scheduler;
+- event retention/rollups and regional chunk files are not yet one integrated
+  long-horizon save transaction;
+- loaded/unloaded local NPC travel still has the old active-visual boundary;
+- cohort promotion, settlement growth, offices, diplomacy, armies, and
+  aggregate conflict remain planned.
+
+Do not create one `SimulationManager` per settlement or caravan. The next
+production step is an explicit regional facade that delegates to these records
+and services, while the active adapter presents only a bounded relevant context.
+
+## Scale evidence
+
+`RegionalScaleBenchmark` builds five settlements, 20 caravans × 12 named
+members, 2,000 named people, 50,000 aggregate residents, and 2,025 jobs. It
+proves conservation, canonical roundtrip, budget parity, and repeatable
+checksums. It does **not** claim rendered frame time, a complete market, a
+30-day economy, or weak-PC GPU performance.
+
+See [Regional simulation contract](REGIONAL_SIMULATION.md),
+[regional baseline 01](benchmarks/REGIONAL_SCALE_BASELINE_01.md), and
+[Testing and benchmarks](FEATURE_TESTING_AND_BENCHMARKS.md).