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.

docs/api/SupplyChainService.openapi.yaml

@@ -672,6 +672,21 @@ components:
                         $ref: '#/components/schemas/BypassOption'
                 fetchedAt:
                     type: string
+                primaryChokepointWarRiskTier:
+                    type: string
+                    enum:
+                        - WAR_RISK_TIER_UNSPECIFIED
+                        - WAR_RISK_TIER_NORMAL
+                        - WAR_RISK_TIER_ELEVATED
+                        - WAR_RISK_TIER_HIGH
+                        - WAR_RISK_TIER_CRITICAL
+                        - WAR_RISK_TIER_WAR_ZONE
+                    description: |-
+                        *
+                         War risk tier derived from Lloyd's JWC Listed Areas + OSINT threat classification.
+                         This is a FREE field (no PRO gate) — it exposes the existing server-internal
+                         threatLevel from ChokepointConfig, making it available to clients for badges
+                         and bypass corridor scoring.
         BypassOption:
             type: object
             properties:
@@ -743,14 +758,14 @@ components:
                     type: string
                 hs2:
                     type: string
-                costIncreasePct:
+                supplyDeficitPct:
                     type: number
                     format: double
-                    description: Estimated annualized import cost increase as % of sector import value (HS 27 only; null for other sectors)
+                    description: Average refined-product supply deficit % under full closure (Gasoline/Diesel/Jet fuel/LPG average; HS 27 only)
                 coverageDays:
                     type: integer
                     format: int32
-                    description: Energy stockpile coverage in days (IEA data, HS 27 only; 0 for non-energy sectors)
+                    description: Energy stockpile coverage in days (IEA data, HS 27 only; 0 for non-energy sectors or net exporters)
                 warRiskPremiumBps:
                     type: integer
                     format: int32
@@ -772,7 +787,7 @@ components:
                          and bypass corridor scoring.
                 hasEnergyModel:
                     type: boolean
-                    description: Whether cost_increase_pct and coverage_days are modelled (true) or unavailable (false)
+                    description: Whether supply_deficit_pct and coverage_days are modelled (true) or unavailable (false)
                 unavailableReason:
                     type: string
                     description: Null/unavailable explanation for non-energy sectors