…, plan 2026-04-26-001)

Three score-shape defects were over-promoting tiny states and
under-promoting non-SWF advanced economies in the v14 ranking. This
PR fixes all three in lockstep with a single cache prefix bump.

**Fix A — `scoreLogisticsSupply`** (`_dimension-scorers.ts:1387`)
The `100 × (1 - tradeExposure)` neutralizer correctly suppresses
global-stress penalties for closed economies, but the prior 0.5
default for missing tradeToGdp extended that suppression to tiny
states with no trade-to-GDP data at all (TV, PW, NR). Now: missing
tradeToGdp drops the exposure-weighted components (cov derate to
0.5) instead of imputing them at "average openness". Closed
economies WITH observed tradeToGdp keep the neutralizer.

**Fix C — `scoreSocialCohesion`** (`_dimension-scorers.ts:1623`)
Tiny peaceful states with no displacement registry entry were
collapsing to GPI alone (cov 0.55, score ~93). New gated impute:
when displacement is absent, impute at 70/0.6; when ALSO unrest is
absent (GPI-only mode), impute unrest at 70/0.5; otherwise (observed
displacement + zero unrest), keep historical "stable-absence ≈ 85"
anchor matching `IMPUTE.unhcrDisplacement` so Iceland/Norway don't
regress. Per-row imputation flags do NOT bubble up: dim-level
`imputationClass` stays null when GPI is observed.

**Fix B — `scoreSovereignFiscalBuffer`** (`_dimension-scorers.ts:1923`)
Non-SWF advanced economies (DE, JP, FR, IT, UK, US, NL, AT, BE, ES,
PT) were scoring 0/cov=1.0 — a deliberate "substantive absence"
penalty that empirically over-fired for countries holding reserves
through Treasury / central-bank channels. Reframed Path 3 to
"dim-not-applicable" (`score=0, coverage=0, observedWeight=0`):
score stays numeric per the `ResilienceDimensionScore.score:number`
contract; coverage=0 removes the dim from the recovery-domain
coverage-weighted mean. New `RESILIENCE_NOT_APPLICABLE_WHEN_ZERO_COVERAGE`
set in `_dimension-scorers.ts` mirrors the existing
`RESILIENCE_RETIRED_DIMENSIONS` pattern but gates exclusion at the
country level (zero-coverage = not-applicable for THIS country)
rather than the construct level (retired for ALL countries).
`computeLowConfidence` and `computeOverallCoverage` in `_shared.ts`
both apply the new filter so non-SWF advanced economies don't get
falsely flagged as low-confidence.

**U4 — Cache prefix bump v14→v15 + history v9→v10**
Source-of-truth in `_shared.ts`. 11 hardcoded literal sites updated
across `tests/`, `scripts/`, `api/health.js`. History bump in
lockstep prevents pre/post-fix points from mixing inside the 30-day
rolling trend window (memory: cache-prefix-bump-propagation-scope).

**U5 — Cohort anchor regression test**
`tests/resilience-cohort-bias-anchors.test.mts` (9 tests) pins the
v15 contract for TV/PW/NR (logisticsSupply ≤80, socialCohesion ≤83)
and DE/JP (sovereignFiscalBuffer score=0/cov=0/obsWeight=0). Future
construct edits cannot silently re-introduce the bias.

**U6 — Methodology docs** (`docs/methodology/country-resilience-index.mdx`)
v15 change-log entries for all three dims. The `sovereignFiscalBuffer`
section explicitly documents the construct reframing from
"substantive absence" to "dim-not-applicable" with rationale.

**U7 — Full-country dry-run script** (`scripts/dry-run-resilience-rebalance.mjs`)
One-shot validation runner (`npm run dryrun:resilience`). Reads
PRE/POST ranking snapshots from production Upstash (read-only),
emits CSV under `tmp/`, validates top-20 small-state composition
(target: drop from ~12 to ≤9). CI-gated, defense-in-depth path
validation, never logs Redis URL/token. Population sourced from
`economic:imf:labor:v1` (`ImfLaborEntry.populationMillions`), NOT
the static-country payload.

**Verification**
- 591/591 resilience tests pass (`npx tsx --test tests/resilience-*`).
- `npm run typecheck` clean (root + api configs).
- `npm run lint:md` clean.
- Plan reviewed across 5 Codex rounds before implementation
  (`docs/plans/2026-04-26-001-fix-resilience-small-state-bias-plan.md`).

**Post-merge**
Bulk-warm v15 via `seed-resilience-scores.mjs` cron (or manual).
Run `PRE_RANKING_KEY=resilience:ranking:v14 npm run dryrun:resilience`
to confirm cohort movement before the v14 TTL expires.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

…s fixes)

Self-review (ce-code-review) + user findings surfaced 5 substantive
issues that are addressed below in one fix-up commit. All 594 resilience
tests pass; typecheck clean (root + api).

**P1 — U2 outage gating (correctness)**
`scoreSocialCohesion`: when `displacementRaw == null` (UNHCR seeder
outage) AND `unrestCount === 0`, the unrest row was imputing at 70
(`socialCohesionGpiOnlyUnrest`) — conflating seed-outage with
country-absent-from-registry. Tiny peaceful states would still get
the GPI-only de-rate during transient seeder failures. Fix: gate the
GPI-only impute branch on `displacementRaw != null && displacementMetric == null`,
so outage collapses to the 85-anchor `unhcrDisplacement.score`
(matching the happy path). Regression test pins the discriminator.

**P1 — Path-3 filter discriminator (correctness)**
`isExcludedFromConfidenceMean` was using `coverage === 0` alone to
decide "not-applicable". A real Path-2 SWF country with
`completeness === 0` (full scrape outage) would also produce
`coverage = 0` while keeping `observedWeight = 1` — and would be
silently filtered out of `computeLowConfidence` /
`computeOverallCoverage`, hiding a data outage from the operator.
Fix: discriminate via the unique Path-3 fingerprint
`coverage === 0 && observedWeight === 0 && imputedWeight === 0`.
Same tightening mirrored in the client widget. Regression test in
`construct-invariants.test.mts` exercises both Path 2 (completeness=0)
and Path 3 against the filter directly.

**P1 — Stale doc claim contradicts new behavior**
Block comment above `scoreSovereignFiscalBuffer` still asserted "score
0 with FULL coverage (substantive absence)" — directly contradicting
the new Path 3. Fix: rewrote block comment + grep-swept the repo for
the stale phrasing ("substantive absence", "FULL coverage", "no-SWF
countries score 0") in `_dimension-scorers.ts:160`,
`_indicator-registry.ts:1048`, and the Path 3 block comment itself.
The prior 5-round Codex review missed this because the contradiction
was in prose far from the changed code. Memory entry
`feedback_doc_drift_after_behavior_fix_needs_grep_sweep` already
covers this; this fix-up is the recurrence.

**P1 — Cross-surface drift (UI vs agent)**
The server now filters non-SWF `sovereignFiscalBuffer` from
`computeOverallCoverage`, but the client widget's
`formatResilienceConfidence` only filtered `RESILIENCE_RETIRED_DIMENSION_IDS`,
NOT the new not-applicable set. Result: non-SWF advanced economies
(DE/JP/FR/IT) showed lower Coverage% in the widget than the server's
`overallCoverage` field — same data, different number, agent vs UI
disagreement. Fix:
  - Mirror the server set client-side via
    `RESILIENCE_NOT_APPLICABLE_WHEN_ZERO_COVERAGE_IDS` in
    `resilience-widget-utils.ts`.
  - Apply the same triple-zero discriminator client-side.
  - Extend `RESILIENCE_RETIRED_DIMENSION_IDS` parity test to also
    parity-check the new set (catches drift automatically going forward).
  - Emit `imputationClass: 'not-applicable'` from Path 3 (the proto's
    documented 4-class taxonomy member, previously never used).
    Updated proto comment to document the structurally-not-applicable
    sentinel and its `coverage:0 + observed_weight:0` pairing.
  - Extend `formatDimensionConfidence` so per-dim row rendering
    uses `status: 'not-applicable'` (with the existing tooltip "Not
    applicable: structurally N/A for this country" and "—" symbol)
    instead of the misleading `status: 'absent'` ("Rare, indicates a
    data-collection bug").

**P1 — Dry-run script can exit 0 on broken payloads**
`scripts/dry-run-resilience-rebalance.mjs`: `indexRanking()` silently
accepted unknown shapes as `[]` and `NaN` scores; the cohort gate at
the end could then fall through to `process.exit(0)` on a fully
broken ranking. Since this is the post-merge validation gate for the
v15 rebalance, silent success is the wrong default. Fix: added
`assertRankingHealth(name, byIso2)` requiring >=20 indexed countries
and >=20 with finite scores; added `MIN_TOP20_POP_KNOWN` guard
requiring 15/20 of the top-20 to have known population before the
cohort gate fires. Three new exit codes (7, 8) for these classes.

**P2 — Extracted shared filter helper**
`isExcludedFromConfidenceMean` lives in `_dimension-scorers.ts` next
to the two sets. `computeLowConfidence` and `computeOverallCoverage`
in `_shared.ts` both consume it. Single source of truth — future
construct decisions update one site, not two.

**P3 — `unwrapEnvelope` guard tightened**
Tightened `if (raw && typeof raw === 'object' && 'data' in raw) return raw.data`
(always unwrap when wrapper shape detected) so a `{ data: null, ... }`
wrapper triggers the downstream FATAL guard instead of silently
returning the wrapper object as the payload.

**Verification**
- 594/594 resilience tests pass (`npx tsx --test tests/resilience-*`)
- `npm run typecheck` clean (root + api configs)
- New parity test: `RESILIENCE_NOT_APPLICABLE_WHEN_ZERO_COVERAGE` ↔
  `RESILIENCE_NOT_APPLICABLE_WHEN_ZERO_COVERAGE_IDS`
- New regression: outage-vs-absence in `scoreSocialCohesion`
- New regression: Path-2 completeness=0 NOT excluded by filter

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

…emit path

Doc-drift fixup caught by user review: the imputation-class taxonomy
table in country-resilience-index.mdx still claimed `not-applicable`
was "reserved for future dimensions" with "no current call site" —
contradicting both the §U3 changelog entry in the same doc AND the
runtime semantics introduced by this PR.

My earlier grep sweep (commit 575eae8) hit "substantive absence",
"FULL coverage", and "no-SWF countries score 0" but missed this
phrasing because it described the FUTURE state of the taxonomy
member rather than the prior behavior of the SWF dim. Same family
as memory `feedback_doc_drift_after_behavior_fix_needs_grep_sweep` —
the lesson is: when activating a previously-unused taxonomy member,
also grep for "reserved for future" / "not yet" / "no current call"
phrasing on that member.

Updates:
- Taxonomy table row for `not-applicable`: describes the runtime emit
  shape (`score=0, coverage=0, observedWeight=0, imputedWeight=0`),
  the discriminator vs Path 2 with `completeness=0` (must NOT be
  filtered as N/A), and the canonical example (sovereignFiscalBuffer
  for non-SWF countries).
- Closing paragraph: replaces the "reserved for future dimensions"
  claim with a description of the actual emit path, the
  `RESILIENCE_NOT_APPLICABLE_WHEN_ZERO_COVERAGE` opt-in set, and the
  `isExcludedFromConfidenceMean` single-source helper.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>