Why this PR?

Phase 1 (PR #2204) built buildSimulationPackageFromDeepSnapshot — it writes simulation-package.json to R2 with selected theaters, entities, event seeds, constraints, and evaluation targets. Phase 2 prerequisites (PR #2219) added getSimulationPackage RPC so agents can discover the latest package pointer from Redis.

This PR closes the loop: a simulation runner reads the package, runs a 2-round LLM actor simulation for maritime chokepoint + energy/logistics theaters, and writes simulation-outcome.json back to R2 with a Redis pointer. A new getSimulationOutcome RPC exposes the pointer to clients.

What changed

scripts/seed-forecasts.mjs — simulation runner core

• Constants: SIMULATION_OUTCOME_LATEST_KEY, task queue keys, lock keys, round token budgets, TTLs
• isMaritimeChokeEnergyCandidate(theater): Phase 2 scope gate — passes only maritime chokepoint + energy/logistics theaters
• buildSimulationRound1SystemPrompt(theater, pkg): structured prompt from entities, event seeds, constraints, evaluation targets, simulationRequirement. Produces 3 divergent paths (escalation/containment/spillover) with initialReactions and dominantReactions. All interpolated theater fields sanitized against prompt injection
• buildSimulationRound2SystemPrompt(theater, pkg, round1): builds 72h evolution prompt from round 1 path summaries. Produces keyActors, roundByRoundEvolution (2 entries), timingMarkers, stabilizers, invalidators, confidence, globalObservations, confidenceNotes
• extractSimulationRoundPayload(text, round): 3-stage extractor (strip think tags → fenced blocks → raw JSON → extractFirstJsonObject fallback) following same pattern as extractImpactExpansionPayload
• runTheaterSimulation(theater, pkg): calls callForecastLLM for round 1, then conditionally round 2 if round 1 succeeded. Round 2 failure is partial-valid (round 1 results preserved)
• writeSimulationOutcome(pkg, outcome, { storageConfig }): writes simulation-outcome.json to R2 via buildSimulationOutcomeKey, then writes SIMULATION_OUTCOME_LATEST_KEY to Redis with { runId, outcomeKey, schemaVersion, theaterCount, generatedAt } and TRACE_REDIS_TTL_SECONDS TTL
• Task queue: enqueueSimulationTask, claimSimulationTask (NX lock deduplication), completeSimulationTask, processNextSimulationTask (idempotency check against Redis pointer before LLM calls), runSimulationWorker({ once, runId })

scripts/process-simulation-tasks.mjs — standalone entry point

12-line script: loads env, delegates to runSimulationWorker. Supports --once and --run-id=<id> flags.

Proto + RPC — getSimulationOutcome

• New proto/worldmonitor/forecast/v1/get_simulation_outcome.proto with GetSimulationOutcomeRequest (optional runId query param) and GetSimulationOutcomeResponse (found, runId, outcomeKey, schemaVersion, theaterCount, generatedAt, note, error)
• service.proto updated with import + RPC
• make generate regenerated TypeScript server + client types
• server/worldmonitor/forecast/v1/get-simulation-outcome.ts: identical getRawJson + markNoCacheResponse pattern from PR feat(forecast): Phase 2 simulation package read path #2219
• server/worldmonitor/forecast/v1/handler.ts: wired getSimulationOutcome
• server/gateway.ts: slow cache tier (same reasoning as simulation package)

Bootstrap/health registration

• api/health.js: simulationOutcomeLatest added to STANDALONE_KEYS + ON_DEMAND_KEYS (WARN if empty, not CRIT — only written after simulation runs, not seeded)
• cache-keys.ts and bootstrap.js not touched (on-demand key, not seeded)

Tests — tests/forecast-trace-export.test.mjs

14 new tests across 4 suites:

• Prompt builders: theater label, 3 path IDs, entity IDs, seed IDs, simulationRequirement in R1; R1 summaries, ROUND 2 marker, actor IDs in R2
• extractSimulationRoundPayload: valid R1/R2, fenced blocks, think tag stripping, invalid JSON, missing paths, no valid pathId, extractFirstJsonObject fallback
• Outcome key builder: key ends in simulation-outcome.json, canonical Redis key, schema version v1
• writeSimulationOutcome: null when storageConfig absent, null when pkg has no runId

All 2316 tests pass. TypeScript clean.

Scope boundary (Phase 2)

Only maritime chokepoint + energy/logistics theaters are simulated. Third-order commodity expansion and additional theater classes are Phase 3.

Post-Deploy Monitoring & Validation

• Trigger a run: node scripts/seed-forecasts.mjs && node scripts/process-simulation-tasks.mjs --once
• Logs to watch: [processNextSimulationTask], [runSimulationWorker], [writeSimulationOutcome]
• Expected healthy: status: completed, theaterCount >= 1, R2 key forecast:simulation-outcome:latest present in Redis
• RPC check: GET /api/forecast/v1/get-simulation-outcome returns { found: true, theaterCount: N }
• Failure signal: status: completed_no_theaters → package has no maritime chokepoint + energy/logistics theaters; status: failed → LLM or R2 write error — check logs
• Validation window: first deep run after deploy
• Owner: @koala73

🤖 Generated with Claude Sonnet 4.6 (200K context) via Claude Code