diff --git a/scripts/regional-snapshot/actor-scoring.mjs b/scripts/regional-snapshot/actor-scoring.mjs index 852e611d5..32ed2f9ad 100644 --- a/scripts/regional-snapshot/actor-scoring.mjs +++ b/scripts/regional-snapshot/actor-scoring.mjs @@ -3,7 +3,9 @@ // Phase 0: lightweight extraction. Phase 1+ adds dedicated actor tracking. import { clip, num } from './_helpers.mjs'; -import { REGIONS } from '../../shared/geography.js'; +// Use scripts/shared mirror (not repo-root shared/): Railway service has +// rootDirectory=scripts so ../../shared/ escapes the deploy root. +import { REGIONS } from '../shared/geography.js'; const ALIASES = { iran: 'Iran', irgc: 'IRGC', tehran: 'Iran', diff --git a/scripts/regional-snapshot/balance-vector.mjs b/scripts/regional-snapshot/balance-vector.mjs index e7352eb1f..55bd0eaa1 100644 --- a/scripts/regional-snapshot/balance-vector.mjs +++ b/scripts/regional-snapshot/balance-vector.mjs @@ -4,8 +4,10 @@ // docs/internal/pro-regional-intelligence-appendix-scoring.md. import { clip, num, weightedAverage, percentile } from './_helpers.mjs'; -import { getRegionCountries, getRegionCorridors, countryCriticality, REGIONS } from '../../shared/geography.js'; -import iso3ToIso2Raw from '../../shared/iso3-to-iso2.json' with { type: 'json' }; +// Use scripts/shared mirror (not repo-root shared/): Railway service has +// rootDirectory=scripts so ../../shared/ escapes the deploy root. +import { getRegionCountries, getRegionCorridors, countryCriticality, REGIONS } from '../shared/geography.js'; +import iso3ToIso2Raw from '../shared/iso3-to-iso2.json' with { type: 'json' }; /** @type {Record} */ const ISO3_TO_ISO2 = iso3ToIso2Raw; diff --git a/scripts/regional-snapshot/evidence-collector.mjs b/scripts/regional-snapshot/evidence-collector.mjs index 435b31779..d9fbb8d3e 100644 --- a/scripts/regional-snapshot/evidence-collector.mjs +++ b/scripts/regional-snapshot/evidence-collector.mjs @@ -4,7 +4,9 @@ // balance drivers, narrative sections, and triggers. import { num } from './_helpers.mjs'; -import { REGIONS } from '../../shared/geography.js'; +// Use scripts/shared mirror (not repo-root shared/): Railway service has +// rootDirectory=scripts so ../../shared/ escapes the deploy root. +import { REGIONS } from '../shared/geography.js'; const MAX_EVIDENCE_PER_SNAPSHOT = 30; diff --git a/scripts/regional-snapshot/scenario-builder.mjs b/scripts/regional-snapshot/scenario-builder.mjs index 8175a8290..0aa8bdc34 100644 --- a/scripts/regional-snapshot/scenario-builder.mjs +++ b/scripts/regional-snapshot/scenario-builder.mjs @@ -4,7 +4,9 @@ // "Scenario Set Normalization". import { num } from './_helpers.mjs'; -import { REGIONS } from '../../shared/geography.js'; +// Use scripts/shared mirror (not repo-root shared/): Railway service has +// rootDirectory=scripts so ../../shared/ escapes the deploy root. +import { REGIONS } from '../shared/geography.js'; /** @type {import('../../shared/regions.types.js').ScenarioHorizon[]} */ const HORIZONS = ['24h', '7d', '30d']; diff --git a/scripts/seed-regional-snapshots.mjs b/scripts/seed-regional-snapshots.mjs index 160085333..5818e7021 100644 --- a/scripts/seed-regional-snapshots.mjs +++ b/scripts/seed-regional-snapshots.mjs @@ -21,7 +21,11 @@ import { pathToFileURL } from 'node:url'; import { loadEnvFile, getRedisCredentials, writeExtraKeyWithMeta } from './_seed-utils.mjs'; -import { REGIONS, GEOGRAPHY_VERSION } from '../shared/geography.js'; +// Use scripts/shared mirror rather than the repo-root shared/ folder: the +// Railway bundle service sets rootDirectory=scripts, so `../shared/` resolves +// to filesystem / on deploy and the import fails with ERR_MODULE_NOT_FOUND. +// scripts/shared/* is kept in sync with shared/* via tests. +import { REGIONS, GEOGRAPHY_VERSION } from './shared/geography.js'; import { computeBalanceVector, SCORING_VERSION } from './regional-snapshot/balance-vector.mjs'; import { buildRegimeState } from './regional-snapshot/regime-derivation.mjs'; diff --git a/scripts/shared/geography.js b/scripts/shared/geography.js new file mode 100644 index 000000000..a21a7a7f7 --- /dev/null +++ b/scripts/shared/geography.js @@ -0,0 +1,279 @@ +// Hierarchical geography for the Regional Intelligence Model. +// Layers (aggregate upward): Display Region -> Theater -> Corridor -> Node. +// +// Used by: +// - scripts/seed-regional-snapshots.mjs (snapshot writer) +// - scripts/regional-snapshot/* (compute modules) +// - server/worldmonitor/intelligence/v1/* (Phase 1+ RPC handlers) +// - src/components/RegionalIntelligenceBoard (Phase 1 UI) +// +// Region taxonomy is anchored to World Bank region codes (EAS/ECS/LCN/MEA/NAC/SAS/SSF) +// with strategic overrides applied to shared/iso2-to-region.json (built once from +// https://api.worldbank.org/v2/country?format=json&per_page=300). +// +// Strategic overrides (deviations from raw WB classification): +// - AF, PK: WB has them in MEA; we put them in south-asia (geographic/strategic) +// - TR: WB has it in ECS; we put it in mena (Levant/Syria/refugee policy frame) +// - MX: WB has it in LCN; we put it in north-america (USMCA strategic frame) +// - TW: WB does not list Taiwan; manually added to east-asia +// +// Country and corridor criticality weights match the formulas in +// docs/internal/pro-regional-intelligence-appendix-scoring.md. + +import iso2ToRegionData from './iso2-to-region.json' with { type: 'json' }; + +/** @type {import('./regions.types.js').RegionId[]} */ +export const REGION_IDS = [ + 'mena', + 'east-asia', + 'europe', + 'north-america', + 'south-asia', + 'latam', + 'sub-saharan-africa', + 'global', +]; + +export const GEOGRAPHY_VERSION = '1.0.0'; + +/** + * Eight display regions. `forecastLabel` matches the free-text region strings + * the existing forecast handler does substring matching against, so the same + * label flows end-to-end without taxonomy mismatch. + */ +export const REGIONS = [ + { + id: 'mena', + label: 'Middle East & North Africa', + forecastLabel: 'Middle East', + wbCode: 'MEA', + theaters: ['levant', 'persian-gulf', 'red-sea', 'north-africa'], + feedRegion: 'middleeast', + mapView: 'mena', + keyCountries: ['SA', 'IR', 'IL', 'AE', 'EG', 'IQ', 'TR'], + }, + { + id: 'east-asia', + label: 'East Asia & Pacific', + forecastLabel: 'East Asia', + wbCode: 'EAS', + theaters: ['east-asia', 'southeast-asia'], + feedRegion: 'asia', + mapView: 'asia', + keyCountries: ['CN', 'JP', 'KR', 'TW', 'AU', 'SG', 'ID'], + }, + { + id: 'europe', + label: 'Europe & Central Asia', + forecastLabel: 'Europe', + wbCode: 'ECS', + theaters: ['eastern-europe', 'western-europe', 'baltic', 'arctic'], + feedRegion: 'europe', + mapView: 'eu', + keyCountries: ['DE', 'FR', 'GB', 'UA', 'RU', 'PL', 'IT'], + }, + { + id: 'north-america', + label: 'North America', + forecastLabel: 'North America', + wbCode: 'NAC', + theaters: ['north-america'], + feedRegion: 'us', + mapView: 'america', + keyCountries: ['US', 'CA', 'MX'], + }, + { + id: 'south-asia', + label: 'South Asia', + forecastLabel: 'South Asia', + wbCode: 'SAS', + theaters: ['south-asia'], + feedRegion: 'asia', + mapView: 'asia', + keyCountries: ['IN', 'PK', 'BD', 'LK', 'AF'], + }, + { + id: 'latam', + label: 'Latin America & Caribbean', + forecastLabel: 'Latin America', + wbCode: 'LCN', + theaters: ['latin-america', 'caribbean'], + feedRegion: 'latam', + mapView: 'latam', + keyCountries: ['BR', 'AR', 'CO', 'CL', 'VE', 'PE'], + }, + { + id: 'sub-saharan-africa', + label: 'Sub-Saharan Africa', + forecastLabel: 'Africa', + wbCode: 'SSF', + theaters: ['horn-of-africa', 'sahel', 'southern-africa', 'central-africa'], + feedRegion: 'africa', + mapView: 'africa', + keyCountries: ['NG', 'ZA', 'KE', 'ET', 'SD', 'CD'], + }, + { + id: 'global', + label: 'Global', + forecastLabel: '', + wbCode: '1W', + theaters: ['global-markets'], + feedRegion: 'worldwide', + mapView: 'global', + keyCountries: ['US', 'CN', 'RU', 'DE', 'JP', 'IN', 'GB', 'SA'], + }, +]; + +/** + * Theaters group countries into geopolitical-strategic units smaller than + * regions. Cross-source signals and military posture data already use these + * theater names where applicable. + */ +export const THEATERS = [ + // MENA + { id: 'levant', label: 'Levant', regionId: 'mena', corridorIds: [] }, + { id: 'persian-gulf', label: 'Persian Gulf', regionId: 'mena', corridorIds: ['hormuz'] }, + { id: 'red-sea', label: 'Red Sea', regionId: 'mena', corridorIds: ['babelm', 'suez'] }, + { id: 'north-africa', label: 'North Africa', regionId: 'mena', corridorIds: [] }, + // East Asia + { id: 'east-asia', label: 'East Asia', regionId: 'east-asia', corridorIds: ['taiwan-strait'] }, + { id: 'southeast-asia', label: 'Southeast Asia', regionId: 'east-asia', corridorIds: ['malacca', 'south-china-sea'] }, + // Europe + { id: 'eastern-europe', label: 'Eastern Europe', regionId: 'europe', corridorIds: ['bosphorus'] }, + { id: 'western-europe', label: 'Western Europe', regionId: 'europe', corridorIds: ['english-channel'] }, + { id: 'baltic', label: 'Baltic', regionId: 'europe', corridorIds: ['danish'] }, + { id: 'arctic', label: 'Arctic', regionId: 'europe', corridorIds: [] }, + // North America + { id: 'north-america', label: 'North America', regionId: 'north-america', corridorIds: ['panama'] }, + // South Asia + { id: 'south-asia', label: 'South Asia', regionId: 'south-asia', corridorIds: [] }, + // LatAm + { id: 'latin-america', label: 'Latin America', regionId: 'latam', corridorIds: [] }, + { id: 'caribbean', label: 'Caribbean', regionId: 'latam', corridorIds: ['panama'] }, + // SSA + { id: 'horn-of-africa', label: 'Horn of Africa', regionId: 'sub-saharan-africa', corridorIds: ['babelm'] }, + { id: 'sahel', label: 'Sahel', regionId: 'sub-saharan-africa', corridorIds: [] }, + { id: 'southern-africa', label: 'Southern Africa', regionId: 'sub-saharan-africa', corridorIds: ['cape-of-good-hope'] }, + { id: 'central-africa', label: 'Central Africa', regionId: 'sub-saharan-africa', corridorIds: [] }, + // Global + { id: 'global-markets', label: 'Global Markets', regionId: 'global', corridorIds: [] }, +]; + +/** + * Corridors are the chokepoint and trade-route layer where transmission + * mechanics actually live. `chokepointId` links to the existing seeded data + * at `supply_chain:chokepoints:v4` and `scripts/seed-chokepoint-baselines.mjs`. + * + * Tier and weight match the criticality table in the scoring appendix. + */ +export const CORRIDORS = [ + // Tier 1 (~20% of global oil transit, top trade volume) + { id: 'hormuz', label: 'Strait of Hormuz', theaterId: 'persian-gulf', chokepointId: 'hormuz', tier: 1, weight: 1.0 }, + { id: 'suez', label: 'Suez Canal', theaterId: 'red-sea', chokepointId: 'suez', tier: 1, weight: 1.0 }, + { id: 'babelm', label: 'Bab el-Mandeb', theaterId: 'red-sea', chokepointId: 'babelm', tier: 1, weight: 0.9 }, + { id: 'taiwan-strait', label: 'Taiwan Strait', theaterId: 'east-asia', chokepointId: 'taiwan_strait',tier: 1, weight: 0.9 }, + { id: 'bosphorus', label: 'Bosphorus', theaterId: 'eastern-europe', chokepointId: 'bosphorus', tier: 1, weight: 0.7 }, + // Tier 2 + { id: 'malacca', label: 'Strait of Malacca', theaterId: 'southeast-asia', chokepointId: 'malacca', tier: 2, weight: 0.8 }, + { id: 'panama', label: 'Panama Canal', theaterId: 'north-america', chokepointId: 'panama', tier: 2, weight: 0.6 }, + { id: 'danish', label: 'Danish Straits', theaterId: 'baltic', chokepointId: 'danish', tier: 2, weight: 0.5 }, + // Tier 3 (reroute paths and secondary) + { id: 'cape-of-good-hope', label: 'Cape of Good Hope', theaterId: 'southern-africa', chokepointId: null, tier: 3, weight: 0.4 }, + { id: 'south-china-sea', label: 'South China Sea', theaterId: 'southeast-asia', chokepointId: null, tier: 3, weight: 0.6 }, + { id: 'english-channel', label: 'English Channel', theaterId: 'western-europe', chokepointId: null, tier: 3, weight: 0.4 }, +]; + +/** + * Country criticality weights for the weighted-tail domestic fragility score. + * Higher weight = country dominates region risk. + * + * Methodology (per scoring appendix): + * 1.0: controls a tier-1 corridor, OR top-10 oil/gas producer, OR top-5 region GDP + * 0.6: controls a tier-2 corridor, OR top-20 oil/gas producer, OR top-10 region GDP + * 0.3: default for other countries + */ +export const COUNTRY_CRITICALITY = { + // Tier-1 corridor controllers + top-10 producers + top-5 region GDP + IR: 1.0, // Hormuz controller + OM: 1.0, // Hormuz controller (other side) + AE: 1.0, // Persian Gulf, top oil producer + SA: 1.0, // Top oil producer + EG: 1.0, // Suez controller + YE: 1.0, // Bab el-Mandeb controller + CN: 1.0, // Taiwan Strait, top region GDP + TW: 1.0, // Taiwan Strait + TR: 1.0, // Bosphorus controller + US: 1.0, // Top-10 producer, dominant region GDP + RU: 1.0, // Top oil/gas producer + CA: 1.0, // Top oil producer + // Tier-2 corridor controllers + top-20 producers + top-10 region GDP + MY: 0.6, // Malacca + SG: 0.6, // Malacca + ID: 0.6, // Malacca, regional GDP + PA: 0.6, // Panama + DK: 0.6, // Danish Straits + DE: 0.6, // Top region GDP + FR: 0.6, + GB: 0.6, + JP: 0.6, + IN: 0.6, // Top region GDP, growing producer + BR: 0.6, // Top region GDP, top-20 producer + MX: 0.6, + KR: 0.6, + IL: 0.6, // Strategic significance in MENA + IQ: 0.6, // Top-20 producer + KW: 0.6, // Top-20 producer + QA: 0.6, // Top-20 LNG producer + NG: 0.6, // Top-20 oil producer + AU: 0.6, // Top LNG producer, regional GDP + // Everything else defaults to 0.3 +}; + +export const DEFAULT_COUNTRY_CRITICALITY = 0.3; + +// ──────────────────────────────────────────────────────────────────────────── +// Helper functions +// ──────────────────────────────────────────────────────────────────────────── + +/** @type {Record} */ +const ISO2_TO_REGION = iso2ToRegionData; + +/** @param {string} regionId */ +export function getRegion(regionId) { + return REGIONS.find((r) => r.id === regionId) ?? null; +} + +/** @param {string} regionId */ +export function getRegionCountries(regionId) { + const out = []; + for (const [iso, rid] of Object.entries(ISO2_TO_REGION)) { + if (rid === regionId) out.push(iso); + } + return out; +} + +/** @param {string} iso2 */ +export function regionForCountry(iso2) { + return ISO2_TO_REGION[iso2] ?? null; +} + +/** @param {string} regionId */ +export function getRegionTheaters(regionId) { + return THEATERS.filter((t) => t.regionId === regionId); +} + +/** @param {string} theaterId */ +export function getTheaterCorridors(theaterId) { + return CORRIDORS.filter((c) => c.theaterId === theaterId); +} + +/** @param {string} regionId */ +export function getRegionCorridors(regionId) { + const theaterIds = new Set(getRegionTheaters(regionId).map((t) => t.id)); + return CORRIDORS.filter((c) => theaterIds.has(c.theaterId)); +} + +/** @param {string} iso2 */ +export function countryCriticality(iso2) { + return COUNTRY_CRITICALITY[iso2] ?? DEFAULT_COUNTRY_CRITICALITY; +} diff --git a/scripts/shared/package.json b/scripts/shared/package.json new file mode 100644 index 000000000..3dbc1ca59 --- /dev/null +++ b/scripts/shared/package.json @@ -0,0 +1,3 @@ +{ + "type": "module" +} diff --git a/tests/scripts-shared-mirror.test.mjs b/tests/scripts-shared-mirror.test.mjs new file mode 100644 index 000000000..3aae0f0dd --- /dev/null +++ b/tests/scripts-shared-mirror.test.mjs @@ -0,0 +1,97 @@ +import { describe, it } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { dirname, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const repoRoot = resolve(__dirname, '..'); + +// The Railway "derived-signals" seed bundle deploys with rootDirectory=scripts, +// which means the repo-root `shared/` folder is NOT present in the container. +// Scripts that need shared/* assets at runtime must import them from +// `scripts/shared/*` instead. `scripts/shared/*` is a byte-for-byte mirror +// of the subset of `shared/*` used by the Railway seeders. +// +// This test locks the mirror so a drift between `shared/X` and +// `scripts/shared/X` cannot slip through code review. When adding new +// mirrored files, append them to MIRRORED_FILES. + +const MIRRORED_FILES = [ + 'geography.js', + 'iso2-to-region.json', + 'iso3-to-iso2.json', + 'un-to-iso2.json', +]; + +describe('scripts/shared/ mirrors shared/', () => { + for (const relPath of MIRRORED_FILES) { + it(`${relPath} is identical between shared/ and scripts/shared/`, () => { + const canonical = readFileSync(join(repoRoot, 'shared', relPath), 'utf-8'); + const mirror = readFileSync(join(repoRoot, 'scripts', 'shared', relPath), 'utf-8'); + assert.equal( + mirror, + canonical, + `scripts/shared/${relPath} drifted from shared/${relPath}. ` + + `Run: cp shared/${relPath} scripts/shared/${relPath}`, + ); + }); + } + + it('scripts/shared has a package.json marking it as ESM', () => { + // Required because scripts/package.json does NOT set "type": "module", + // so scripts/shared/geography.js (ESM syntax) would otherwise be parsed + // ambiguously when Railway loads it from rootDirectory=scripts. + const pkg = JSON.parse(readFileSync(join(repoRoot, 'scripts/shared/package.json'), 'utf-8')); + assert.equal(pkg.type, 'module'); + }); +}); + +describe('regional snapshot seed scripts use scripts/shared/ (not repo-root shared/)', () => { + // Guards the Railway rootDirectory=scripts runtime: an import whose + // resolved absolute path falls OUTSIDE scripts/shared/ (e.g. repo-root + // shared/) will ERR_MODULE_NOT_FOUND at runtime on Railway because the + // shared/ dir is not copied into the deploy root. + const FILES_THAT_MUST_USE_MIRROR = [ + 'scripts/seed-regional-snapshots.mjs', + 'scripts/regional-snapshot/actor-scoring.mjs', + 'scripts/regional-snapshot/balance-vector.mjs', + 'scripts/regional-snapshot/evidence-collector.mjs', + 'scripts/regional-snapshot/scenario-builder.mjs', + ]; + + const scriptsSharedAbs = resolve(repoRoot, 'scripts/shared'); + + // Match any runtime `import ... from ''` (ignores JSDoc `import()` + // type annotations which live inside /** */ comments). Only looks at + // lines that start with optional whitespace + `import`. + const RUNTIME_IMPORT_RE = /^\s*import\s[^\n]*?\bfrom\s+['"]([^'"]+)['"]/gm; + + for (const rel of FILES_THAT_MUST_USE_MIRROR) { + it(`${rel} resolves all shared/ imports to scripts/shared/`, () => { + const src = readFileSync(join(repoRoot, rel), 'utf-8'); + const fileAbs = resolve(repoRoot, rel); + const fileDir = dirname(fileAbs); + + const offending = []; + for (const match of src.matchAll(RUNTIME_IMPORT_RE)) { + const specifier = match[1]; + // Only inspect relative paths that land in a shared/ directory. + if (!/\/shared\//.test(specifier)) continue; + if (!specifier.startsWith('.')) continue; + const resolved = resolve(fileDir, specifier); + if (!resolved.startsWith(scriptsSharedAbs)) { + offending.push(` ${specifier} → ${resolved}`); + } + } + + assert.equal( + offending.length, + 0, + `${rel} has runtime import(s) that escape scripts/shared/:\n${offending.join('\n')}\n` + + `Railway service rootDirectory=scripts means these paths escape the deploy root. ` + + `Mirror the needed file into scripts/shared/ and update the import.`, + ); + }); + } +});