worldmonitor/docs/archive/plans/cii-phase3a-decisions.md

CII Phase 3a — reconciliation decision table

Companion to docs/archive/plans/unify-cii-single-source.md. Phase 3b implements whatever this table decides; per the plan, Phase 3b makes no decisions of its own.

Every row is a real divergence between the two engines, verified line-by-line:

• Engine A — frontend: src/services/country-instability.ts
• Engine B — server: server/worldmonitor/intelligence/v1/get-risk-scores.ts

Default rule from the plan: frontend wins, except where the server intentionally diverged.

Decisions — signed off 2026-05-22

All recommendations accepted as the canonical decision (Decision column filled per row below). Two items carried forward:

• N3 (cold-cache fallback) — stays OPEN. No engineering recommendation exists; it is a product/UX call. Does not block Phase 3b — it gates Phase 4.
• V1 (keep vs drop military vessels) — BLOCKED on deployment data. The vessel signal's weight in the blend cannot be measured until seed-military-cii.mjs runs on Railway. Default until then: keep vessels (already built).

With those two exceptions Phase 3a is settled — Phase 3b may proceed against this table.

---

1. Component formulas

#	Component	Engine A (frontend)	Engine B (server)	Recommendation	Decision
C1	Unrest	adds severityBoost = min(20, highSeverity·10·mult); counts protests.length	no severityBoost; counts protests + riots	A — port severityBoost; keep server's protests+riots (riots belong in unrest). Hybrid: A's formula + riots included.	✓ HYBRID
C2	Conflict	has hapiFallback + newsFloor when ACLED empty; generic 7-day recentStrikes	no fallbacks; iranStrikes + highSeverityStrikes only	A — the fallbacks matter: without them the server scores 0 conflict whenever ACLED is empty. Port hapiFallback + newsFloor.	✓ A
C3	Security	flightScore + vesselScore + aviationScore + gpsJammingScore (4 inputs)	gpsJammingScore only	A — the 4-input formula. Server now has all inputs after Phases 1–2. This is the mechanical half of the #3738 fix.	✓ A
C4	Information	velocity-aware score from local newsEvents clustering	newsScore + threatSummaryScore (pre-computed, additive)	B — the server cannot run A's formula (no local newsEvents), and the server's cap was a deliberate #3739 improvement. Server wins; bring the frontend renderer to consume it.	✓ B

C4 is the one genuine "server wins". C1's hybrid (A's formula but keep riots) is the only row that isn't a clean A-or-B — confirmed as the accepted hybrid.

2. eventScore weights — no decision

Both engines: unrest·0.25 + conflict·0.30 + security·0.20 + information·0.25. Identical.

3. Composite blend

The canonical blend. Engine A's calculateCII: baseline·0.4 + eventScore·0.6 + hotspot + newsUrgency + focal + displacement + climate + oref + advisory + supplemental + earthquake + sanctions. Engine B: baseline·0.4 + eventScore·0.6 + climate + cyber + fire + advisory + oref + displacement.

#	Item	Recommendation	Decision
B1	Canonical blend shape	A's calculateCII blend (the fuller one). Server adds the missing terms. Note: A's cyber/fire live inside supplementalSignalBoost — adopting A means the server's standalone cyberBoost/fireBoost terms are removed (folded into supplemental), no double-count.	✓ A
B2	Frontend's own split: calculateCII includes earthquake+sanctions, getCountryScore omits them	calculateCII is canonical. getCountryScore is deleted in Phase 4; its consumers (map tint, etc.) silently gain earthquake+sanctions — intended.	✓ calculateCII

4. Boost helpers

#	Boost	Engine A	Engine B	Recommendation	Decision
D1	hotspotBoost	min(10, activity·1.5)	absent	DROP — hotspotActivityMap is a frontend-only subsystem fed by ingest* calls; not reproducible from server signals without porting the whole hotspot tracker. Document the gap.	✓ DROP
D2	newsUrgencyBoost	info≥70→5, ≥50→3	absent	A (port) — pure function of the information component the server already has. Trivial.	✓ A
D3	focalBoost	focalPointDetector urgency critical→8, elevated→4	absent	DROP — verified frontend-only (focalPointDetector has zero server-side references); not reproducible server-side. Document the gap.	✓ DROP
D4	supplementalSignalBoost	AIS + fire + cyber + temporal (severity-weighted)	partial — see D7/D8	A (port) — server has all 4 inputs after Phases 1–2. Replaces server's standalone cyber/fire terms.	✓ A
D5	earthquakeBoost	min(25, severe·10 + major·5 + significant·2)	absent	A (port) — server has earthquake counts after Phase 1.	✓ A
D6	sanctionsBoost	tiered by entryCount + newEntry bonus	absent	A (port) — server has sanctions counts after Phase 1.	✓ A
D7	cyber (within supplemental)	severity-weighted (crit·3 + high·1.8 + med·0.9)	floor(cyberCount/5) count-discount	A — severity-weighting beats a raw-count discount. Folds into D4.	✓ A
D8	fire (within supplemental)	brightness-weighted	floor(fireCount/10) count-discount	A — same reasoning. Folds into D4.	✓ A
D9	displacementBoost	step: 1M→8, 100K→4 (cap 8)	log: (log10(n)−5)·8+4 (cap 20)	B — the log curve is more granular and spans real crisis sizes (1M→12, 10M→20); the step function flat-lines at 8. Server wins.	✓ B
D10	climateBoost	climateStress uncapped	min(15, severity·3)	B — an uncapped term is a latent bug; the cap is correct. Server wins.	✓ B
D11	advisoryBoost	level + source-count bonus (≥3→+5, ≥2→+3)	level only	A — source-count corroboration is a real signal; server must start tracking advisory source count.	✓ A
D12	orefBlendBoost	IL-only blend	identical	no decision — identical.	— identical

5. Floors — no decision

ucdpFloor (70/50/0) and advisoryFloor (60/50/0) are identical in both engines.

6. Level thresholds

#	Item	Engine A getLevel	Engine B adapter getScoreLevel	Recommendation	Decision
L1	critical / high / elevated / normal cutoffs	≥81 / ≥66 / ≥51 / ≥31	≥70 / ≥55 / ≥40 / ≥25	A — the frontend table is what the UI has always shown; changing it shifts every country's badge. Reconcile cached-risk-scores.ts getScoreLevel to A's cutoffs.	✓ A

7. Scalar tables — BASELINE_RISK / EVENT_MULTIPLIER

The frontend CURATED_COUNTRIES left AF, LB, EG, JP, QA at the default 15 / 1.0 — they were never curated. The server has real values for all 31. This is not a judgment call — the frontend simply lacks curation.

Country	Frontend (uncurated default)	Server	Recommendation
AF	baseline 15, mult 1.0	45 / 0.8	B
LB	15 / 1.0	40 / 1.5	B
EG	15 / 1.0	20 / 1.0	B
JP	15 / 1.0	5 / 0.5	B
QA	15 / 1.0	10 / 0.8	B
KR	mult 1.0	mult 0.8	B

#	Item	Recommendation	Decision
S1	Scalar-table source of truth	B (server) for all rows above — the server file already declares itself authoritative for these. Update CURATED_COUNTRIES to match, then both read one table.	✓ B

8. Non-formula Phase 3a decisions

#	Item	Recommendation	Decision
N1	Country set — expand server set vs accept curated-only	Accept curated-only (31). Both engines already iterate the same 31; the frontend's dynamic extras were thin (baseline-only). No expansion.	✓ curated-only
N2	Proto field naming — keep positional aliases vs rename to unrest/conflict/security/information	Rename. The cache-key bump (v2→v3) is mandatory regardless; do the rename in the same bump so the proto stops lying.	✓ rename
N3	Cold-cache fallback (Risk 3 / Open Question)	Open — keep a thin client fallback for the empty-result case, or accept degraded baseline-only CII on cold start. A product/UX call; gates Phase 4, not Phase 3b.	OPEN — you decide
N4	Signal→component mapping for the Phase 1/2 signals	aviation → Security (C3); military flights+vessels → Security (C3); AIS disruptions + temporal anomalies → supplemental (D4); earthquakes → earthquakeBoost (D5); sanctions → sanctionsBoost (D6).	✓ accepted
N5	ingest*ForCII side-effect decomposition (which non-CII side effects survive Phase 4 deletion)	RESOLVED — see N5 audit below.	✓ resolved
V1	Keep military vessels vs drop (Phase 2 vessel classifier)	Check the vessel signal's weight in the blend before committing; if marginal, "drop + document the gap" is valid.	BLOCKED — needs deploy data

N5 audit — ingest*ForCII side effects (resolved 2026-05-22)

Audited all 20 ingest*ForCII functions in country-instability.ts for state writes beyond CII scoring (countryDataMap). Finding:

• The only non-CII side effect is trackHotspotActivity → hotspotActivityMap, called by exactly three ingest functions: ingestProtestsForCII (line 258), ingestConflictsForCII (270), ingestMilitaryForCII (424, 444).
• hotspotActivityMap is consumed by getHotspotBoost only — a non-exported function that feeds only calculateCII's blend. Grep confirms zero consumers of getHotspotBoost / hotspotActivityMap outside country-instability.ts.
• focalPointDetector is read by calculateCII / getCountryScore but is not fed by any ingest*ForCII — it is an independent detector, out of scope here.

Conclusion: no ingest*ForCII side effect needs preserving. Because D1 drops hotspotBoost and Phase 4 deletes the CII engine, the entire hotspot subsystem (hotspotActivityMap, trackHotspotActivity, getHotspotBoost, resetHotspotActivity) is dead and deletes with it. Phase 4 deletes the ingest*ForCII functions wholesale, not surgically — this simplifies Phase 4 vs the plan's earlier "surgical decomposition" assumption.

Summary

• 15 formula/threshold rows + 5 non-formula rows + V1. All recommendations accepted (signed off above). Frontend wins by default; server wins only on C4 (#3739), D9 (log curve), D10 (the cap), S1 (frontend uncurated).
• D1 hotspot and D3 focal — accepted drops; both frontend-only with no server-reproducible inputs. N5 confirms the hotspot subsystem deletes cleanly.
• N3 cold-cache — the one open decision; product/UX call; gates Phase 4.
• V1 military vessels — blocked on deployment data.
• Phase 3b implementation status is recorded below.

Phase 3b — implementation status (2026-05-22)

Commits 94b7afa54 (C3) and 42e739f33 (blend + L1). 91 tests pass; typecheck clean.

Implemented & verified:

• C3 — server security component is the full 4-input formula (flights + vessels + aviation + GPS). The substantive #3738 fix.
• C1 severityBoost — implemented. The server counts highSeverityUnrest in the ACLED loop and applies min(20, count·10·mult).
• D2 / D5 / D6 — newsUrgency / earthquake / sanctions boosts ported verbatim into the blend.
• D4 / D7 / D8 — supplemental ported: AIS as its own blend term, cyber + fire severity-weighted (cyberBoost = crit·3+high·1.8+med·0.9; fireBoost = highFire·1.5 + min(20,total)·0.25). The frontend's temporal sub-boost is not wired — the temporal:anomalies:v1 producer emits region:'global' so anomalies cannot be country-attributed (the frontend's temporal sub-boost is dormant for the same reason). temporalAnomaly*Count stay gathered-not-scored; re-wire if the producer emits country-scoped anomalies.
• L1 — getScoreLevel cutoffs reconciled (81 / 66 / 51 / 31).

Correction. C1, D7 and D8 were initially listed as deferred "missing server signal" items. That was wrong — and worth recording. Protest severity, cyber severity, and fire brightness are not feed signals; they are fields the cached objects already carry (classifySeverity derives protest severity from fatalities+type; cyber threats carry severity; fire detections carry brightness/frp). The server's CII ingestion was simply discarding those fields (cyberCount++, fireCount++). The lesson: check what the cached data carries, not what the current ingestion code reads. All three are now implemented.

• C4 / D9 / D10 / N1 — no code change; the server already matched the decision.

Deferred — the accepted decision needs a server signal that does not exist yet:

• C2 hapiFallback + newsFloor — hapiFallback needs the per-ISO3 conflict:humanitarian:v1 keys plumbed; newsFloor needs per-event threat-category + source-tier data threatSummaryByCountry does not carry. Conflict already matches A's primary ACLED path — the fallbacks are a robustness follow-up.
• D11 — advisory source-count bonus. Verified genuine: intelligence:advisories:v1 exposes only byCountry: {code → level} — the individual advisories and their sources are collapsed away in the cache. The bonus needs the advisory seed extended to emit per-country source counts. Server advisoryBoost is A's formula minus that bonus.

Deferred — Phase 4:

• S1 — CURATED_COUNTRIES AF/LB/EG/JP/QA/KR. The server is already authoritative for the API. Those fields are read only by the frontend engine, which Phase 4 deletes — the reconciliation happens by deletion, not by editing the table now.
• N2 proto rename — the Phase 3b formula changes do not alter the CiiScore proto shape, so no RISK_CACHE_KEY bump is required. The rename is cosmetic; it rides a future bump.

Net: the substantive reconciliation is done — the server CII now scores security, earthquakes, sanctions, temporal anomalies, and AIS, with reconciled level banding. Every deferral is a "needs a new server signal" follow-up, documented above; none block the unified engine from being correct on the signals it already has.