Tighten sim rerreasoning caps and refresh simulate docs

Author: DeveshParagiri

docs/commands.md

@@ -376,8 +376,8 @@ extropy simulate -s asi-announcement --early-convergence off
 4. Resolves effective models/rate limits from CLI overrides then config defaults.
 5. Runs simulation loop:
    - seed + timeline + network exposures,
-   - chunked reasoning (two-pass by default, merged with `--merged-pass`),
-   - medium/high conversation interleaving,
+   - chunked reasoning (two-pass by default, merged with `--merged-pass`) with per-timestep reasoning budget,
+   - medium/high conversation interleaving with novelty + per-timestep conversation budget,
    - timestep summary + stopping checks.
 6. Persists run state to canonical `study.db` and writes results artifacts to `results/{scenario}/` (or `--output`).
 
@@ -462,6 +462,8 @@ Precedence:
 - `--early-convergence auto` uses scenario YAML value when set; otherwise runtime auto-rule applies (do not early-stop while future timeline events remain).
 - `low` fidelity skips conversations; `medium` and `high` enable conversations with stricter per-agent caps at lower fidelity.
 - `--retention-lite` drops full raw reasoning payload retention to reduce DB/storage volume.
+- Timeline events without explicit `exposure_rules` use bounded fallback filtering (not full-seed-rule replay).
+- `extreme` re-reasoning is bounded to a high-salience subset, not all aware agents.
 
 ### Failure Behavior
 

docs/pipeline/simulate.md

@@ -17,13 +17,22 @@ This is not a patch plan. It is a contract + current-state reality map.
 - Simulation is now scenario-centric in lookup order (`scenario_id` first, legacy IDs as fallback).
 - Runtime loop supports DB-backed resume/checkpoint behavior at timestep and chunk levels.
 - Timeline events support provenance epochs (`info_epoch`) and forced re-reasoning escalation.
+- Timeline fallback exposure no longer reuses full seed rule sets blindly:
+  - fallback rules are filtered to representative channel rules,
+  - direct timeline exposure is deduplicated per-agent per-event,
+  - direct timeline exposure is capped by intensity (`normal|high|extreme`).
 - Reasoning supports two modes:
   - default two-pass (role-play + classification),
   - optional merged single-pass (`--merged-pass`).
 - Fidelity modes actively control conversation behavior:
   - `low`: no conversations,
   - `medium`: bounded conversations after chunks,
   - `high`: deeper conversations + extra public-text classification.
+- Runtime now applies deterministic per-timestep budgets:
+  - bounded reasoning candidate set,
+  - bounded conversation count,
+  - novelty gate before conversation execution.
+- Reasoning prompt payload is now trimmed by fidelity (recent exposures + recent memory only).
 - Early convergence behavior is now explicit and overrideable (`auto|on|off`).
 - Runtime exports include `by_timestep.json`, `meta.json`, and conditional conversation/social artifacts.
 - State manager now auto-upgrades legacy simulation tables/columns (including timeline-provenance exposure fields) on startup.
@@ -273,8 +282,8 @@ Each timestep does:
    - seed,
    - timeline event (if this timestep has one),
    - network propagation,
-3. reason selected agents in chunks,
-4. interleave conversations after chunks (medium/high fidelity),
+3. select and cap reasoning candidates, then reason in chunks,
+4. interleave conversations after chunks (medium/high fidelity, novelty + budget gated),
 5. record social posts from sharers,
 6. apply conviction decay to non-reasoned agents,
 7. compute and save timestep summary,
@@ -288,6 +297,12 @@ Timeline exposures carry:
 - `info_epoch`,
 - optional `re_reasoning_intensity` (`normal|high|extreme`).
 
+When a timeline event does not provide explicit `exposure_rules`, runtime fallback is now bounded:
+- prefers rules authored for current timestep (else earliest authored seed step),
+- keeps representative rule(s) per channel rather than all overlapping seed rules,
+- deduplicates direct event exposure per agent,
+- applies an intensity-based direct-exposure cap to prevent saturation spikes.
+
 ### Reasoning behavior
 Default reasoning mode is two-pass:
 1. Pass 1 role-play response (free text + sentiment/conviction/share/action fields).
@@ -298,6 +313,7 @@ Merged mode (`--merged-pass`) combines both in one schema/call.
 Important current behavior:
 - open-ended outcomes are not classified in Pass 2; they remain in free-text reasoning.
 - high fidelity adds separate public-text classification pass for public position.
+- reasoning context is trimmed to recent exposure/memory windows by fidelity to bound token growth.
 
 Primary file:
 - `extropy/simulation/reasoning.py`
@@ -311,13 +327,22 @@ Primary file:
 
 Committed agents are protected from routine multi-touch re-reasoning unless forced by timeline policy.
 
+Additional runtime gating now applies before calls:
+- explicit forced IDs are no longer expanded to all aware agents under `extreme`,
+- forced expansion uses a bounded high-salience subset (directly impacted + nearby connected + sharers),
+- per-timestep reasoning budget caps total LLM calls.
+
 ### Conversation behavior by fidelity
 - `low`: no conversations executed.
 - `medium`: conversations enabled; per-agent cap 1 per timestep; 4-message conversations.
 - `high`: per-agent cap 2 per timestep; 6-message conversations.
 
 Conversation outcomes can override provisional reasoning state.
 
+Conversation execution now also requires:
+- per-timestep global conversation budget not exhausted,
+- novelty gate pass (material shift/uncertainty/share signal from fresh reasoning).
+
 Primary file:
 - `extropy/simulation/conversation.py`
 
@@ -399,7 +424,7 @@ Open-ended outcomes live in reasoning text, not in structured Pass 2 outcome pay
 `--resume` requires `--run-id`; incorrect run-id usage can lead to user confusion about expected continuation behavior.
 
 ### 6) Prompt/context size grows with memory and history
-High-fidelity prompts include richer memory and context windows, which improves realism but increases token load and cost volatility.
+Prompt growth is now bounded by fidelity-window trims, but high-fidelity runs still carry materially higher token/cost load than low fidelity.
 
 ### 7) Legacy fallback paths still exist
 Simulation still includes legacy lookup fallbacks (`population_id`, `network_id`) which can mask schema drift in older studies.

examples/study-03/scenario/iran-strikes/scenario.v1.yaml

@@ -290,7 +290,26 @@ timeline:
     credibility: 0.95
     ambiguity: 0.28
     emotional_valence: -0.72
-  exposure_rules: null
+  exposure_rules:
+  - channel: military_official_channels
+    when: military_connection in ('Active duty', 'Veteran', 'Immediate family member')
+      or reservist_or_national_guard == True
+    probability: 1.0
+    timestep: 0
+  - channel: broadcast_breaking_news
+    when: primary_info_source == 'Cable/broadcast TV news'
+    probability: 0.95
+    timestep: 0
+  - channel: push_notification_online_news
+    when: primary_info_source == 'Online news sites' and tech_adoption_posture in
+      ('Early adopter', 'Innovator', 'Early majority adopter')
+    probability: 0.95
+    timestep: 0
+  - channel: social_media_viral_spread
+    when: social_media_behavior in ('Active poster/Influencer', 'Occasional poster')
+      and primary_info_source == 'Social media'
+    probability: 0.92
+    timestep: 0
   description: 'Week 1: Iranian missile retaliation kills US troops; gas prices surge
     and markets crash'
   re_reasoning_intensity: extreme
@@ -309,7 +328,29 @@ timeline:
     credibility: 0.94
     ambiguity: 0.28
     emotional_valence: -0.8
-  exposure_rules: null
+  exposure_rules:
+  - channel: push_notification_online_news
+    when: primary_info_source in ('Podcasts', 'Print media') and tech_adoption_posture
+      not in ('Technophobe/Avoider', 'Late majority adopter')
+    probability: 0.8
+    timestep: 1
+  - channel: broadcast_breaking_news
+    when: age >= 50 and primary_info_source != 'Avoids news'
+    probability: 0.85
+    timestep: 1
+  - channel: social_media_viral_spread
+    when: age < 40 and social_media_behavior in ('Passive consumer', 'Occasional poster')
+    probability: 0.88
+    timestep: 1
+  - channel: broadcast_breaking_news
+    when: political_engagement_level == 'Highly engaged partisan'
+    probability: 0.9
+    timestep: 1
+  - channel: social_media_viral_spread
+    when: age >= 40 and social_media_behavior != 'Non-user' and primary_info_source
+      == 'Social media'
+    probability: 0.82
+    timestep: 1
   description: 'Week 3: Iran blockades the Strait of Hormuz; oil hits $140/barrel;
     gas tops $6/gallon nationally'
   re_reasoning_intensity: extreme
@@ -329,7 +370,24 @@ timeline:
     credibility: 0.93
     ambiguity: 0.28
     emotional_valence: -0.85
-  exposure_rules: null
+  exposure_rules:
+  - channel: personal_network_word_of_mouth
+    when: primary_info_source == 'Local news' or social_media_behavior == 'Non-user'
+    probability: 0.75
+    timestep: 2
+  - channel: broadcast_breaking_news
+    when: primary_info_source == 'Local news'
+    probability: 0.8
+    timestep: 2
+  - channel: personal_network_word_of_mouth
+    when: supply_chain_job_exposure == True or employment_sector in ('Federal government',
+      'State/local government')
+    probability: 0.85
+    timestep: 2
+  - channel: social_media_viral_spread
+    when: economic_anxiety > 0.6 and social_media_behavior != 'Non-user'
+    probability: 0.78
+    timestep: 2
   description: 'Week 5: Economic cascade — unemployment spikes, food prices surge,
     oil briefly hits $180/barrel after Iran strikes Saudi oil facilities'
   re_reasoning_intensity: extreme
@@ -350,7 +408,24 @@ timeline:
     credibility: 0.91
     ambiguity: 0.28
     emotional_valence: -0.6
-  exposure_rules: null
+  exposure_rules:
+  - channel: personal_network_word_of_mouth
+    when: primary_info_source == 'Avoids news' and extraversion > 0.5
+    probability: 0.65
+    timestep: 3
+  - channel: broadcast_breaking_news
+    when: urban_rural == 'Rural' and age >= 45
+    probability: 0.8
+    timestep: 3
+  - channel: personal_network_word_of_mouth
+    when: urban_rural == 'Rural' and primary_info_source not in ('Cable/broadcast
+      TV news', 'Online news sites')
+    probability: 0.7
+    timestep: 3
+  - channel: social_media_viral_spread
+    when: war_escalation_fear > 0.7 and social_media_behavior != 'Non-user'
+    probability: 0.85
+    timestep: 3
   description: 'Week 8: Strait partially reopened; Russia and China back Iran; 400,000
     US jobs lost; midterm framing intensifies'
   re_reasoning_intensity: high
@@ -371,7 +446,16 @@ timeline:
     credibility: 0.82
     ambiguity: 0.28
     emotional_valence: -0.7
-  exposure_rules: null
+  exposure_rules:
+  - channel: personal_network_word_of_mouth
+    when: primary_info_source == 'Avoids news' and extraversion <= 0.5
+    probability: 0.45
+    timestep: 4
+  - channel: broadcast_breaking_news
+    when: midterm_turnout_propensity in ('Rarely votes', 'Never votes') and primary_info_source
+      != 'Avoids news'
+    probability: 0.6
+    timestep: 4
   description: 'Week 10: Leaked intelligence report suggests Iran is reconstituting
     uranium enrichment at undisclosed backup sites; ceasefire talks stall'
   re_reasoning_intensity: high
@@ -392,7 +476,11 @@ timeline:
     credibility: 0.93
     ambiguity: 0.28
     emotional_valence: -0.45
-  exposure_rules: null
+  exposure_rules:
+  - channel: personal_network_word_of_mouth
+    when: 'true'
+    probability: 0.55
+    timestep: 5
   description: 'Week 12: Fragile ceasefire reached through Omani/Qatari mediation;
     oil drops to $105; total US economic cost exceeds $800 billion'
   re_reasoning_intensity: high