fix(regional-snapshots): mirror shared/geography.js into scripts/shared (#2954)

The derived-signals seed bundle failed on Railway with:

  [Regional-Snapshots] Error [ERR_MODULE_NOT_FOUND]: Cannot find module
    '/shared/geography.js' imported from /app/seed-regional-snapshots.mjs

Root cause: the Railway cron service for derived-signals deploys with
rootDirectory=scripts, so scripts/ becomes the container /app root. The
repo-root shared/ folder is NOT copied into the container.

seed-regional-snapshots.mjs imported '../shared/geography.js' which
resolved to /shared/geography.js at runtime and blew up. Same for four
scripts/regional-snapshot/* compute modules using '../../shared/...'.

Fix: mirror the runtime shared assets into scripts/shared/ and update
the five import paths.

- Add scripts/shared/geography.js (byte-for-byte copy of shared/geography.js)
- Add scripts/shared/package.json with {"type": "module"} so Node
  parses geography.js as ESM inside the rootDirectory=scripts deploy.
  scripts/package.json does NOT set type:module.
- scripts/shared/iso2-to-region.json and iso3-to-iso2.json were already
  mirrored from prior PRs, no change needed.
- scripts/seed-regional-snapshots.mjs:
    '../shared/geography.js' -> './shared/geography.js'
- scripts/regional-snapshot/actor-scoring.mjs:
  scripts/regional-snapshot/evidence-collector.mjs:
  scripts/regional-snapshot/scenario-builder.mjs:
    '../../shared/geography.js' -> '../shared/geography.js'
- scripts/regional-snapshot/balance-vector.mjs:
    '../../shared/geography.js' -> '../shared/geography.js'
    '../../shared/iso3-to-iso2.json' -> '../shared/iso3-to-iso2.json'

JSDoc type imports like {import('../../shared/regions.types.js').X}
are intentionally NOT changed. They live inside /** */ comments,
Node ignores them at runtime, and tsc still resolves them correctly
from the repo root during local typecheck.

Regression coverage: new tests/scripts-shared-mirror.test.mjs
1. Asserts scripts/shared/{geography.js, iso2-to-region.json,
   iso3-to-iso2.json, un-to-iso2.json} are byte-for-byte identical
   to their shared/ canonical counterparts.
2. Asserts scripts/shared/package.json has type:module.
3. For each regional-snapshot seed file, resolves every runtime
   "import ... from ...shared/..." to an absolute path and asserts
   it lands inside scripts/shared/. A regression that reintroduces
   "../shared/" from a scripts/ file or "../../shared/" from a
   scripts/regional-snapshot/ file will fail this check.

Verified with a temp-dir simulation of rootDirectory=scripts: all
five modules load clean. Full npm run test:data suite passes 4298/4298.

Secondary observation (not in this PR): the same log shows
Cross-Source-Signals missing 4 upstream keys (supply_chain:shipping:v2,
gdelt:intel:tone:{military,nuclear,maritime}), producing 0 composite
escalation zones. That is an upstream data-freshness issue in the
supply-chain and gdelt-intel seeders, not in this bundle.
This commit is contained in:
Elie Habib
2026-04-11 20:19:01 +04:00
committed by GitHub
parent cf028b34b2
commit da45e830c9
8 changed files with 397 additions and 6 deletions

View File

@@ -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',

View File

@@ -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<string, string>} */
const ISO3_TO_ISO2 = iso3ToIso2Raw;

View File

@@ -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;

View File

@@ -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'];

View File

@@ -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';

279
scripts/shared/geography.js Normal file
View File

@@ -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<string, string>} */
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;
}

View File

@@ -0,0 +1,3 @@
{
"type": "module"
}

View File

@@ -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 '<path>'` (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.`,
);
});
}
});