2 Commits

Author	SHA1	Message	Date
Elie Habib	abdcdb581f	feat(resilience): SWF manifest expansion + KIA split + new schema fields (#3391) ... * feat(resilience): SWF manifest expansion + KIA split + new schema fields Phase 1 of plan 2026-04-25-001 (Codex-approved round 5). Manifest-only data correction; no construct change, no cache prefix bump. Schema additions (loader-validated, misplacement-rejected): - top-level: aum_usd, aum_year, aum_verified (primary-source AUM) - under classification: aum_pct_of_audited (fraction multiplier), excluded_overlaps_with_reserves (boolean; documentation-only) Manifest expansion (13 → 21 funds, 6 → 13 countries): - UAE: +ICD ($320B verified), +ADQ ($199B verified), +EIA (unverified — loaded for documentation, excluded from scoring per data-integrity rule) - KW: kia split into kia-grf (5%, access=0.9) + kia-fgf (95%, access=0.20). Corrects ~18× over-statement of crisis-deployable Kuwait sovereign wealth (audit found combined-AUM × 0.7 access applied $750B as "deployable" against ~$15B actual GRF stabilization capacity). - CN: +CIC ($1.35T), +NSSF ($400B, statutorily-gated 0.20 tier), +SAFE-IC ($417B, excluded — overlaps SAFE FX reserves) - HK: +HKMA-EF ($498B, excluded — overlaps HKMA reserves) - KR: +KIC ($182B, IFSWF full member) - AU: +Future Fund ($192B, pension-locked) - OM: +OIA ($50B, IFSWF member) - BH: +Mumtalakat ($19B) - TL: +Petroleum Fund ($22B, GPFG-style high-transparency) Re-audits (Phase 1E): - ADIA access 0.3 → 0.4 (rubric flagged; ruler-discretionary deployment empirically demonstrated) - Mubadala access 0.4 → 0.5 (rubric flagged); transparency 0.6 → 0.7 (LM=10 + IFSWF full member alignment) Rubric (docs/methodology/swf-classification-rubric.md): - New "Statutorily-gated long-horizon" 0.20 access tier added between 0.1 (sanctions/frozen) and 0.3 (intergenerational/ruler-discretionary). Anchored by KIA-FGF (Decree 106 of 1976; Council-of-Ministers + Emir decree gate; crossed once in extremis during COVID). Seeder: - Two new pure helpers: shouldSkipFundForBuffer (excluded/unverified decision) and applyAumPctOfAudited (sleeve fraction multiplier) - Manifest-AUM bypass: if aum_verified=true AND aum_usd present, use that value directly (skip Wikipedia) - Skip funds with excluded_overlaps_with_reserves=true (no double-counting against reserveAdequacy / liquidReserveAdequacy) - Skip funds with aum_verified=false (load for documentation only) Tests (+25 net): - 15 schema-extension tests (misplacement rejection, value-range gates, rationale-pairing coherence, backward-compat with pre-PR entries) - 10 helper tests (shouldSkipFundForBuffer + applyAumPctOfAudited predicates and arithmetic; KIA-GRF + KIA-FGF sum equals combined AUM) - Existing manifest test updated for the kia → kia-grf+kia-fgf split Full suite: 6,940 tests pass (+50 net), typecheck clean, no new lint. Predicted ranking deltas (informational, NOT acceptance criteria per plan §"Hard non-goals"): - AE sovFiscBuf likely 39 → 47-49 (Phase 1A + 1E) - KW sovFiscBuf likely 98 → 53-57 (Phase 1B) - CN, HK (excluded), KR, AU acquire newly-defined sovFiscBuf scores - GCC ordering shifts toward QA > KW > AE; AE-KW gap likely 6 → ~3-4 Real outcome will be measured post-deploy via cohort audit per plan §Phase 4. * fix(resilience): completeness denominator excludes documentation-only funds PR-3391 review (P1 catch): the per-country `expectedFunds` denominator counted ALL manifest entries (`funds.length`) including those skipped from buffer scoring by design — `excluded_overlaps_with_reserves: true` (SAFE-IC, HKMA-EF) and `aum_verified: false` (EIA). Result: countries with mixed scorable + non-scorable rosters showed `completeness < 1.0` even when every scorable fund matched. UAE (4 scorable + EIA) would show 0.8; CN (CIC + NSSF + SAFE-IC excluded) would show 0.67. The downstream scorer then derated those countries' coverage based on a fake-partial signal. Three call sites all carried the same bug: - per-country `expectedFunds` in fetchSovereignWealth main loop - `expectedFundsTotal` + `expectedCountries` in buildCoverageSummary - `countManifestFundsForCountry` (missing-country path) All three now filter via `shouldSkipFundForBuffer` to count only scorable manifest entries. Documentation-only funds neither expected nor matched — they don't appear in the ratio at all. Tests added (+4): - AE complete with all 4 scorable matched (EIA documented but excluded) - CN complete with CIC + NSSF matched (SAFE-IC documented but excluded) - Missing-country path returns scorable count not raw manifest count - Country with ONLY documentation-only entries excluded from expectedCountries Full suite: 6,944 tests pass (+4 net), typecheck clean. * fix(resilience): address Greptile P2s on PR #3391 manifest Three review findings, all in the manifest YAML: 1. **KIA-GRF access 0.9 → 0.7** (rubric alignment): GRF deployment requires active Council-of-Ministers authorization (2020 COVID precedent demonstrates this), not rule-triggered automatic deployment. The rubric's 0.9 tier ("Pure automatic stabilization") reserved for funds where political authorization is post-hoc / symbolic (Chile ESSF candidate). KIA-GRF correctly fits 0.7 ("Explicit stabilization with rule") — the same tier the pre-split combined-KIA was assigned. Updated rationale clarifies the tier choice. Rubric's 0.7 precedent column already lists "KIA General Reserve Fund" — now consistent with the manifest. 2. **Duplicate `# ── Australia ──` header before Oman** (copy-paste artifact): removed the orphaned header at the Oman section; added proper `# ── Australia ──` header above the Future Fund entry where it actually belongs (after Timor-Leste). 3. **NSSF `aum_pct_of_audited: 1.0` removed** (no-op): a multiplier of 1.0 is identity. The schema field is OPTIONAL and only meant for fund-of-funds split entries (e.g. KIA-GRF/FGF). Setting it to 1.0 forced the loader to require an `aum_pct_of_audited` rationale paragraph with no computational benefit. Both the field and the paragraph are now removed; NSSF remains a single- sleeve entry that scores its full audited AUM. Full suite: 6,944 tests pass, typecheck clean.	2026-04-25 12:02:48 +04:00
Elie Habib	1dc807e70f	docs(resilience): PR 4a — SWF classification rubric (tiers + precedents, no manifest changes) (#3376) ... * docs(resilience): PR 4a — SWF classification rubric (tiers + precedents, no manifest changes) PR 4a of cohort-audit plan 2026-04-24-002. First half of the plan's PR 4 (full-manifest re-rate) split into: - PR 4a (this): pure documentation — central rubric defining tiers + concrete precedents per axis. No manifest changes. - PR 4b (deferred): apply the rubric to revise specific coefficients in `scripts/shared/swf-classification-manifest.yaml`. Behaviour- changing; belongs in a separate PR with cohort snapshots and methodology review. This split addresses the plan's concern that PR 4 "may not be outcome- predetermined" by separating the evaluative framework from its application. PR 4a makes every current manifest value evaluable against a benchmark; PR 4b applies the benchmark. Shipped - `docs/methodology/swf-classification-rubric.md` — new doc. Sections: 1. Introduction + scope (rubric vs manifest boundary) 2. Access axis: 5 named tiers (0.1, 0.3, 0.5, 0.7, 0.9) w/ concrete precedents per tier, plus edge cases for fiscal-rule caps (Norway GPFG) and state holding companies (Temasek) 3. Liquidity axis: 6 tiers (0.1, 0.3, 0.5, 0.7, 0.9, 1.0) w/ precedents + listed-vs-directly-owned real-estate edge case 4. Transparency axis: 6 tiers grounded in LM Transparency Index + IFSWF membership + annual-report granularity, plus edge cases for LM=10 w/o holdings-level disclosure and sealed filings (KIA) 5. Current manifest × rubric alignment — 24 coefficients reviewed; 6 flagged as "arguably higher/lower under the rubric" with directional-impact analysis marked INFORMATIONAL, not motivation for revision 6. How-to-use playbook for manifest-edit PRs (add/revise/rubric- revise workflows) Findings (informational only — no PR changes) Six ratings flagged as potentially under-/over-stated against the rubric. Per the plan's anti-pattern note (rank-targeted acceptance criteria), the flags are INFORMATIONAL: a future manifest-edit PR should revise only when the rubric + cited evidence support the change, not to hit a target ranking. Flagged (with directional impact if revised upward): - Mubadala access 0.4 → arguably 0.5; transparency 0.6 → 0.7 (haircut 0.12 → 0.175, +46% access × transparency product) - PIF access 0.4 → arguably 0.5; liquidity 0.4 → arguably 0.3 (net small effect — opposite directions partially cancel) - KIA transparency 0.4 → arguably 0.5 (haircut +25%) - QIA access 0.4 → arguably 0.5; transparency 0.4 → arguably 0.5 (haircut +56%) - GIC access 0.6 → arguably 0.7 (haircut +17%) Not flagged: GPFG, ADIA, Temasek (all 9 coefficients align with their rubric tiers). Verified - `npm run test:data` — 6694 pass / 0 fail (unchanged — pure docs PR) - `npm run typecheck` / `typecheck:api` — green - `npm run lint:md` — clean Not in this PR - Manifest coefficient changes (PR 4b) - Cohort-sanity snapshot before/after (PR 4b) - Live-data audit of IFSWF engagement + LM index current values (requires web fetch — not in scope for a doc PR) * fix(resilience): PR 4a review — resolve GIC/ADIA rubric contradictions + flag-count Addresses P1 + 2 P2 Greptile findings on #3376 (draft). 1. **P1 — GIC tier contradiction.** GIC was listed as a canonical 0.7 ("Explicit stabilization with rule") precedent AND rated 0.6 in the alignment table with an "arguably 0.7" note. That inconsistency makes the rubric unusable as-is for PR 4b review. Removed GIC from the 0.7 precedent list and explicitly marked it as a 0.7 *candidate* (pending PR 4b evaluation), not a 0.7 *precedent*. KIA General Reserve Fund stays as the canonical 0.7 example; Norway GPFG remains the borderline case for fiscal-rule caps. 2. **P2 — ADIA liquidity midpoint inconsistency.** Methodology text said the rubric uses "midpoint" for ranged disclosures and cited ADIA 55-70% → 0.7 tier. But midpoint(55-70) = 62.5%, which sits in the 0.5 tier band (50-65%). Fixed the methodology to state the rubric uses the **upper-bound** of a disclosed range (fund's own statement of maximum public-market allocation), which keeps ADIA at 0.7 tier (70% upper bound fits 65-85% band). Added forward- compatibility note: if future ADIA disclosures tighten the range so the upper bound drops below 65%, the rubric directs the rating to 0.5. 3. **P2 — Flag-count header.** "(6 of 24 coefficients)" was wrong; the enumeration below lists 8 coefficients across 5 funds. Corrected to "8 coefficients across 5 funds" with the fund-by-fund count inline so the header math is self-verifying. Verified - `npm run lint:md` — clean - `npm run typecheck` — green (pure docs PR, no behaviour change) This PR remains in draft pending #3380 (PR 3A — net-imports denominator) merge per the plan's PR 4 → after PR 3A sequencing.	2026-04-24 18:32:17 +04:00