Summary

• Adds buildSimulationPackageFromDeepSnapshot(snapshot, priorWorldState) to scripts/seed-forecasts.mjs — the bridge adapter from WorldMonitor's deep forecast pipeline to a MiroFish-compatible simulation package
• Writes simulation-package.json beside deep-snapshot.json in R2 via fire-and-forget (zero latency impact on the seed critical path)
• Phase 1 scope: maritime chokepoint + energy/logistics theaters only (Hormuz, Red Sea, Bab al-Mandab, Strait of Malacca, etc.)
• All builders are fully deterministic — no LLM call, fully cacheable, schema-stable

What's in simulation-package.json

Top-level fields per the gap spec (docs/internal/wm-mirofish-gap.md):

• schemaVersion: "v1" — explicit export contract version
• selectedTheaters — up to 3 top maritime/energy candidates with routeFacilityKey, commodityKey, topBucketId, rankingScore
• simulationRequirement — deterministic template paragraph per theater (route + commodity + horizon + reaction type)
• structuralWorld — frozen WorldMonitor truth layer: touching stateUnits, worldSignals, marketState buckets, situationClusters
• entities — 7 entity classes derived from actorRegistry, stateUnit.actors, evidence table, with fallback anchor set
• eventSeeds — live_news + observed_disruption seeds with relative timing (T+0h, T+12h±6h)
• constraints — hard route/commodity constraints, soft market admissibility + known invalidators
• evaluationTargets — deterministic per theater: escalation/containment/spillover paths + T+24h/T+48h/T+72h timing markers

Theater filter

A candidate qualifies for Phase 1 if:

1. routeFacilityKey is a key in CHOKEPOINT_MARKET_REGIONS (the known maritime chokepoints already expanded in PR feat(deep-forecast): Phase 2+3 scoring recalibration + autoresearch prompt self-improvement #2178)
2. topBucketId ∈ {energy, freight} OR commodityKey ∈ energy commodity set (crude_oil, lng, natural_gas, refined_products, petrochemicals)

Integration point

// In fast seed path — fire-and-forget, no await
const snapshotWrite = await writeDeepForecastSnapshot(snapshotPayload, { runId });
if (snapshotWrite?.storageConfig && candidates.length > 0) {
  writeSimulationPackage(snapshotPayload, { storageConfig: snapshotWrite.storageConfig })
    .catch((err) => console.warn(`[SimulationPackage] Write failed: ${err.message}`));
}

Tests

17 new tests in tests/forecast-trace-export.test.mjs ('simulation package export' suite):

• Theater filter: accept maritime+energy, reject non-chokepoint, reject non-energy bucket
• Null return when no qualifying candidates
• All required top-level fields present + schema version
• selectedTheaters shape (all fields, cap at 3)
• simulationRequirement deterministic content (route name, commodity, horizon)
• eventSeeds with live_news type and T+0h timing
• Constraints: hard route, hard commodity, soft admissibility
• Evaluation targets: 3 path types (escalation/containment/spillover), 3 timing markers
• Entity extraction from actorRegistry
• buildSimulationPackageKey format (/simulation-package.json suffix)

Post-Deploy Monitoring & Validation

• What to monitor: R2 bucket for */simulation-package.json keys appearing beside deep snapshot writes on Hormuz/Red Sea eligible runs
• Validation: node -e "import('./scripts/seed-forecasts.mjs').then(m => console.log(Object.keys(m)))" — confirm buildSimulationPackageFromDeepSnapshot, writeSimulationPackage, isMaritimeChokeEnergyCandidate are exported
• Expected healthy behavior: On a Hormuz/Red Sea run, R2 should have a simulation-package.json with selectedTheaters.length >= 1, schemaVersion: "v1", and constraints with at least one hard: true entry
• Failure signal: Console warn [SimulationPackage] Write failed: — non-critical, fire-and-forget write does not affect the main seed path
• Validation window: Next Hormuz/Red Sea deep forecast run after deploy

Context

This is Phase 1 of the WorldMonitor→MiroFish bridge defined in docs/internal/wm-mirofish-gap.md. The standalone package is consumable by MiroFish, any later simulator, or a structured LLM scenario-analysis workflow without human reformatting.

Phases 2 (theater-limited simulation) and 3 (outcome re-ingestion) are separate follow-up PRs.