fix(supply-chain): address all code review findings from PR #2873 (#2878)

* fix(supply-chain): address all code review findings from PR #2873

- Rename costIncreasePct → supplyDeficitPct (semantic correction)
- Add primaryChokepointWarRiskTier to GetBypassOptionsResponse
- Consolidate ThreatLevel/threatLevelToWarRiskTier into _insurance-tier.ts
- Replace inline CpEntry/ChokepointStatusCacheEntry with ChokepointInfo
- Add outer cachedFetchJson wrapper (3 serial Redis reads → 1 on warm path)
- Add hs2 validation guard matching sibling handler pattern
- Extract CHOKEPOINT_STATUS_KEY constant; eliminate string literal duplication
- Add SCORE_RISK_WEIGHT/SCORE_COST_WEIGHT named constants; clamp liveScore ≥ 0
- Add Math.max(0,...) to liveScore for sub-1.0 cost multiplier corridors
- Fix closurePct: req.closurePct ?? 100 (was || which falsy-coalesced zero)
- Type fetchBypassOptions cargoType as CargoType (was implicit string)
- Add exhaustiveness check to threatLevelToInsurancePremiumBps switch
- Move TIER_RANK to module level in _insurance-tier.ts
- Update WIDGET_PRO_SYSTEM_PROMPT with both new PRO RPCs

* fix(supply-chain): fix supplyDeficitPct averaging and coverageDays sentinel

- Remove .filter(d > 0) from productDeficits: zero-deficit products have demand
  and must stay in the denominator to avoid overstating the average
- Clamp coverageDays = Math.max(0, effectiveCoverDays): prevents -1 net-exporter
  sentinel from leaking into the public API response
- Update proto comment: document 0 for net exporters
- Add test assertions for both contracts

* chore(api-docs): regenerate OpenAPI docs for coverage_days comment update

* refactor(supply-chain): use CHOKEPOINT_STATUS_KEY in chokepoint-status writer

The key was extracted to cache-keys.ts in the previous commit but the primary
writer (getChokepointStatus) and BOOTSTRAP_CACHE_KEYS still embedded the raw
string literal. Import the constant at both sites to complete the refactor.

* test: update supply-chain-v2 assertions for CHOKEPOINT_STATUS_KEY refactor

Handler now imports CHOKEPOINT_STATUS_KEY as REDIS_CACHE_KEY from cache-keys.ts
rather than defining a local constant. BOOTSTRAP_CACHE_KEYS also references the
constant. Update source-string assertions to match the new patterns.

* fix: keep BOOTSTRAP_CACHE_KEYS.chokepoints as string literal

bootstrap.test.mjs enforces string-literal values in BOOTSTRAP_CACHE_KEYS via
regex. CHOKEPOINT_STATUS_KEY is used in handler imports and is the primary dedup
win; the static registry entry stays as-is per test contract.

proto/worldmonitor/supply_chain/v1/get_bypass_options.proto

@@ -37,4 +37,5 @@ message GetBypassOptionsResponse {
   int32 closure_pct = 3;
   repeated BypassOption options = 4;    // ranked by live_score asc
   string fetched_at = 5;
+  WarRiskTier primary_chokepoint_war_risk_tier = 6; // war risk tier of the queried chokepoint
 }

proto/worldmonitor/supply_chain/v1/get_country_cost_shock.proto

@@ -24,14 +24,14 @@ message GetCountryCostShockResponse {
   string iso2 = 1;
   string chokepoint_id = 2;
   string hs2 = 3;
-  // Estimated annualized import cost increase as % of sector import value (HS 27 only; null for other sectors)
-  double cost_increase_pct = 4;
-  // Energy stockpile coverage in days (IEA data, HS 27 only; 0 for non-energy sectors)
+  // Average refined-product supply deficit % under full closure (Gasoline/Diesel/Jet fuel/LPG average; HS 27 only)
+  double supply_deficit_pct = 4;
+  // Energy stockpile coverage in days (IEA data, HS 27 only; 0 for non-energy sectors or net exporters)
   int32 coverage_days = 5;
   // War risk insurance premium in basis points for this chokepoint
   int32 war_risk_premium_bps = 6;
   WarRiskTier war_risk_tier = 7;
-  // Whether cost_increase_pct and coverage_days are modelled (true) or unavailable (false)
+  // Whether supply_deficit_pct and coverage_days are modelled (true) or unavailable (false)
   bool has_energy_model = 8;
   // Null/unavailable explanation for non-energy sectors
   string unavailable_reason = 9;