docs(resilience): sync methodology/proto/widget to 6-domain + 3-pillar reality (#3264)

Brings every user-facing surface into alignment with the live resilience
scorer. Zero behavior change: overall_score is still the 6-domain
weighted aggregate, schemaVersion is still 2.0 default, and every
existing test continues to pass.

Surfaces touched:
- proto + OpenAPI: rewrote the ResiliencePillar + schema_version
  descriptions. 2.0 is correctly documented as default; shaped-but-empty
  language removed.
- Widget: added missing recovery: 'Recovery' label (was rendering
  literal lowercase recovery before), retitled footer data-version chip
  from Data to Seed date so it is clear the value reflects the static
  seed bundle not every live input, rewrote help tooltip for 6 domains
  and 3 pillars and called out the 0.25 recovery weight.
- Methodology doc: domains-and-weights table now carries all 6 rows
  with actual code weights (0.17/0.15/0.11/0.19/0.13/0.25), Recovery
  section header weight corrected from 1.0 to 0.25, new Pillar-combined
  score activation (pending) section with the measured Spearman 0.9935,
  top-5 movers, and the activation checklist.
- documentation.mdx + features.mdx: product blurbs updated from 5
  domains and 13 dimensions to 6 domains and 19 dimensions grouped into
  3 pillars.
- Tests: recovery-label regression pin, Seed date label pin, clarified
  pillar-schema degenerate-input semantics.

New scaffolding for defensibility:
- docs/snapshots/resilience-ranking-2026-04-21.json frozen published
  tables artifact with methodology metadata and commit SHA.
- docs/snapshots/resilience-pillar-sensitivity-2026-04-21.json live
  Redis capture (52-country sample) combining sensitivity stability
  with the current-vs-proposed Spearman comparison.
- scripts/freeze-resilience-ranking.mjs refresh script.
- scripts/compare-resilience-current-vs-proposed.mjs comparison script.
- tests/resilience-ranking-snapshot.test.mts 13 assertions auto
  discovered from any resilience-ranking-YYYY-MM-DD.json in snapshots.

Verification: npm run typecheck:all clean, 390/390 resilience tests
pass.

Follow-up: pillar-combined score activation. The sensitivity artifact
shows rank-preservation Spearman 0.9935 and no ceiling effects, which
clears the methodological bar. Blocker is messaging because every
country drops ~13 points under the penalty, so activation PR ships with
re-anchored release-gate bands, refreshed frozen ranking, and a v2.0
methodology note.
This commit is contained in:
Elie Habib
2026-04-21 22:37:27 +04:00
committed by GitHub
parent e878baec52
commit 502bd4472c
21 changed files with 2414 additions and 94 deletions

View File

@@ -141,10 +141,11 @@ components:
schemaVersion:
type: string
description: |-
Phase 2 T2.1: "1.0" (default, preserves the current response shape)
or "2.0" (adds pillars; keeps overall_score / baseline_score / etc.
populated for one release cycle for backward compat). Controlled at
response build time by the RESILIENCE_SCHEMA_V2_ENABLED env flag.
Phase 2 T2.1/T2.3: "2.0" is the current default (adds pillars; keeps
overall_score / baseline_score / etc. populated for backward compat).
"1.0" is the legacy opt-out shape (pillars empty) retained for one
release cycle. Controlled at response build time by the
RESILIENCE_SCHEMA_V2_ENABLED env flag (defaults to "true" → v2).
ResilienceDomain:
type: object
properties:
@@ -220,25 +221,32 @@ components:
score:
type: number
format: double
description: Pillar score in [0, 100]. 0 when shipped empty (T2.1).
description: Pillar score in [0, 100], coverage-weighted mean of member domains.
weight:
type: number
format: double
description: 'Pillar weight in the overall combine. Per the plan: 0.40 / 0.35 / 0.25.'
description: 'Pillar weight in the pillar-combined score. Per the plan: 0.40 / 0.35 / 0.25.'
coverage:
type: number
format: double
description: Coverage in [0, 1]. 0 when shipped empty (T2.1).
description: Coverage in [0, 1], mean of member-domain average dimension coverage.
domains:
type: array
items:
$ref: '#/components/schemas/ResilienceDomain'
description: |-
Phase 2 T2.1 of the country-resilience reference-grade upgrade plan.
Three-pillar response shape that regroups the existing 5 domains into
long-run capacity, current shock pressure, and recovery capability.
Shipped as a shaped-but-empty payload in T2.1 (score=0, coverage=0);
real aggregation lands in T2.3 / PR 4 of the Phase 2 rebuild.
Phase 2 T2.1/T2.3 of the country-resilience reference-grade upgrade plan.
Three-pillar response shape that regroups the 6 ResilienceDomains
(economic, infrastructure, energy, social-governance, health-food,
recovery) into long-run capacity (structural-readiness), current shock
pressure (live-shock-exposure), and recovery capability (recovery-capacity).
Pillar scores and coverage are real coverage-weighted aggregates computed
from the constituent domains; see _pillar-membership.ts for the mapping.
The top-level overall_score on GetResilienceScoreResponse remains a
domain-weighted aggregate (Σ domain.score * domain.weight) for this
release cycle; a pillar-combined score with penalty term is staged in
_shared.ts#penalizedPillarScore and validated by
scripts/validate-resilience-sensitivity.mjs ahead of the activation PR.
GetResilienceRankingRequest:
type: object
GetResilienceRankingResponse: