feat: integrate regional caravan persistence

docs/REGIONAL_SIMULATION.md

@@ -1,10 +1,11 @@
 # Regional simulation contract
 
-> **Implementation status (2026-08-13):** The record, scheduler, caravan,
+> **Implementation status (2026-08-23):** The record, scheduler, caravan,
 > chunk, file-generation, relevance, and navigation-budget contracts are
-> implemented and tested. They are still an additive regional package; the
-> playable Jajce `SimulationManager` and `SaveSlotStore` remain the local
-> production authority until the integrations listed at the end land.
+> implemented and tested. `SimulationManager` now owns a production regional
+> facade for one inbound Jajce route, and `SaveSlotStore` persists local and
+> regional authority in one checked manifest. The scale economy and chunked
+> long-horizon history remain separate integrations.
 
 The regional layer extends the Jajce simulation without multiplying scene-tree
 managers. One authority owns every loaded and unloaded location, settlement,
@@ -38,12 +39,10 @@ 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 v16 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.
+The current local `SimulationStateRecord` remains the unchanged v16 Jajce
+record. `SimulationSaveManifest` v1 combines that record with the canonical
+`RegionalSimulationFacade` envelope and checksums both authorities. Regional
+fields are not copied into local records or scene nodes.
 
 ## Deterministic work
 
@@ -92,6 +91,30 @@ 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.
 
+## Production facade and combined save
+
+`RegionalSimulationFacade` is now owned by the production `SimulationManager`.
+It bootstraps an authored Travnik-to-Jajce route and advances the same
+`RegionalCaravanService` before each committed local tick. Its bounded public
+command can depart one exact delivery; arrival remains scheduled simulation
+work and does not depend on a loaded caravan visual.
+
+The route transports `regional_trade_goods`, a catalogued item with no local
+storage tag. Jajce starts with no regional stock and Travnik starts with four
+units, so the facade cannot duplicate the playable pantry's food or the
+woodpile's wood. Local and regional event-ID spaces remain deliberately
+separate until an explicit cross-domain history contract exists.
+
+`SimulationSaveManifest` stores exactly the local v16 record, its checksum, the
+regional facade envelope, its checksum, and the manifest schema/version. It
+rejects checksum tampering and mismatched world, seed, active location, or
+tick. Combined restore is transactional across both authorities. Existing raw
+local v16 quicksaves remain loadable and bootstrap an idle regional route at
+the restored seed and tick. Explicit non-Jajce adapter scopes continue to use
+their local v16 boundary until a matching regional facade exists. That fallback
+is allowed only while the regional facade equals its deterministic idle
+bootstrap; Jajce delivery commands are rejected outside the combined scope.
+
 ## Event retention and daily rollups
 
 `WorldEventRetentionPlanner` is a pure, deterministic query over a complete
@@ -157,14 +180,12 @@ active-world and hardware captures.
 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. integrate the retention/rollup and chunk codecs as one atomic,
+1. integrate the retention/rollup and chunk codecs as one atomic,
    lazily loaded history transaction;
-3. schedule 20 ordinary caravan trades across five settlement economies;
-4. promote/demote presentation and population fidelity while pinning named and
+2. schedule 20 ordinary caravan trades across five settlement economies;
+3. promote/demote presentation and population fidelity while pinning named and
    causally referenced people;
-5. add data-defined settlement projects, tier promotion, offices, diplomacy,
+4. add data-defined settlement projects, tier promotion, offices, diplomacy,
    armies, campaigns, and aggregate conflict.
 
 Context-owned world-target registries and the first shared player/NPC activity