feat: plan bounded event history rollups

docs/REGIONAL_SIMULATION.md

@@ -86,6 +86,39 @@ 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.
 
+## Event retention and daily rollups
+
+`WorldEventRetentionPlanner` is a pure, deterministic query over a complete
+`WorldEventStore`. It returns a canonical `WorldEventRetentionPlan`; it never
+deletes, replaces, or mutates source facts. The plan keeps the current day plus
+the configured number of prior days raw. Only older event types explicitly
+listed by the caller are eligible for aggregation.
+
+An eligible transaction must have a stable world and location plus either one
+positive `item_id`/`amount` pair or a positive multi-item `cargo_ledger`.
+`WorldEventDailyRollupRecord` groups those contributions by day, world,
+location, event type, and item. It retains the event count, total amount,
+tick/event-ID bounds, and a checksum of the exact contributing event IDs.
+`WorldEventDailyRollupStore` provides canonical serialization and indexed
+day/location/type/item queries. Incomplete or ambiguous transaction payloads
+remain raw rather than being guessed into a rollup.
+
+Pinned fact IDs and caller-supplied causal fact IDs must exist in the source
+store and always remain raw. Payload `cause_event_id` and `cause_event_ids`
+references must resolve to prior facts; every referenced cause remains raw even
+when its dependent transaction can be rolled up. Missing, dangling, or
+non-prior causes fail the whole plan. Per-event reason traces, reciprocal causal
+edges, source-ID fingerprints, and deterministic count telemetry survive the
+plan's primitive-only round trip.
+
+This is a planning foundation, not an active retention authority. A future
+integration must collect external references from knowledge, relationships,
+situations, commitments, journals, and regional history; verify the plan's
+source checksum immediately before applying it; and publish the retained raw
+store, rollup store, and chunk manifest in one atomic transaction. A rollup is
+aggregate history and must never satisfy a consumer that requires an exact
+ordinary world fact.
+
 ## Presentation relevance
 
 `PresentationRelevancePolicy` is a pure query over an active context and
@@ -109,8 +142,9 @@ 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.
+frame time, a complete market/economy, production-integrated chunked history
+retention, or weak-PC GPU performance. Those claims require separate
+active-world and hardware captures.
 
 ## Next integrations
 
@@ -121,8 +155,8 @@ tests:
    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;
+4. integrate the retention/rollup and chunk codecs as one atomic,
+   lazily loaded history transaction;
 5. schedule 20 ordinary caravan trades across five settlement economies;
 6. promote/demote presentation and population fidelity while pinning named and
    causally referenced people;