docs/MISSING_COMPONENTS_AND_DOCUMENTATION.md

# Missing Components and Required Documentation

Consolidated list of **missing components** (code/IPSAS/FQBM) and **documentation that is required** or recommended for the FQBM project. Derived from [GAPS_AND_MISSING.md](GAPS_AND_MISSING.md) and [IPSAS_COMPLIANCE.md](IPSAS_COMPLIANCE.md).

---

## 1. Missing components (code / functionality)

### 1.1 IPSAS standards (missing or partial)

| Component | Standard / area | Required for |
|-----------|------------------|--------------|
| Accounting policies, prior-period adjustments, error correction | IPSAS 3 | Full IPSAS 3 compliance |
| Borrowing costs capitalisation / expense | IPSAS 5 | Borrowing cost treatment |
| Revenue recognition and measurement | IPSAS 9, 47 | Statement of financial performance |
| Hyperinflation restatement | IPSAS 10 | High-inflation reporting |
| Events after the reporting date (adjust vs disclose) | IPSAS 14 | Post–reporting-date events |
| Provisions and contingent liabilities/assets | IPSAS 19 | Provisions note |
| Related party identification and disclosure | IPSAS 20 | Related party note |
| Revenue from non-exchange (taxes, transfers) | IPSAS 23 | Government revenue |
| Financial instrument recognition/measurement (amortised cost, FVOCI, FVPL, ECL) | IPSAS 29, 41 | Full instrument accounting |
| Disclosure of interests in other entities | IPSAS 38 | Consolidation disclosure |
| Measurement basis (historical cost, FV, etc.) | IPSAS 46 | Measurement policy |
| Transfer expenses | IPSAS 48 | Transfer expense classification |
| Cash-basis financial statement | Cash basis IPSAS | Cash-basis reporters |
| Financial Statement Discussion and Analysis (narrative) | RPG 2 | Management commentary |
| Functional currency / presentation currency | General | Multi-currency reporting |

### 1.2 FQBM / matrix (missing or partial)

| Component | Description | Required for |
|-----------|-------------|---------------|
| Cross-sector consistency check | Automatic check that four-quadrant matrix totals equal sectoral (CB + bank) sums | Matrix validation |
| Budget / appropriation model | Internal representation of budget and appropriations (not only template) | IPSAS 24 actual vs budget from FQBM |
| Historical case narrative / coded outputs | Part XI: structured narrative or coded “case” outputs for 1997, 2008, 2020, 2022 | Case study reporting |
| Real data pipelines | Automated download of Fed H.4.1, BIS, IMF (e.g. for regressions) | Empirical use without manual data |

### 1.3 White paper / framework (out of scope but listed for completeness)

| Component | Note |
|-----------|------|
| Full CCP balance-sheet dynamics | Part VIII: margin flows and default waterfall exist; full clearing balance sheet not modeled. |
| CBDC in state vector | **Done**: `FQBMState.cbdc_liability`; workbook updates it on CBDC shift; IPSAS presentation shows it. |
| Repo multiplier in workbook | **Done**: wired into `run_workbook` (optional `shadow_params`); dashboard includes `repo_multiplier`. |

---

## 2. Required or recommended documentation

### 2.1 Documentation that does not exist (required or recommended)

| Document | Purpose | Priority |
|----------|---------|----------|
| **White paper (canonical source)** | The full FQBM white paper as a single file (e.g. `docs/WHITE_PAPER.md` or PDF) so the framework is versioned with the code | High – README and framework_summary refer to “the white paper” but it is not in the repo |
| **User guide / tutorial** | Step-by-step: install, run workbook, run Monte Carlo, interpret stress tables, use scenarios, export Excel, use IPSAS layer | High – README is short; no walkthrough |
| **API reference** | Documented list of public functions/classes, parameters, and return types (e.g. Sphinx or MkDocs, or a single `API.md`) | Medium – only docstrings in code |
| **Data dictionary** | Definition of every state variable (B, R, C, Loans, …), sheet inputs/outputs, and regression variables (columns for Model 1–3) | Medium – scattered in docstrings |
| **Changelog** | `CHANGELOG.md` or release notes for versions (e.g. 0.1.0, 0.2.0) | Low |
| **Contributing / development** | How to add a sheet, add a scenario, run tests, code style | Low |

### 2.2 Documentation that exists but could be extended

| Document | Status / remaining gap |
|----------|------------------------|
| **README.md** | No “Quick start” example with copy-paste code; no table of contents; Streamlit and scenarios could be in a single “Optional features” section. |
| **docs/framework_summary.md** | One sentence per Part (I–XVI) and module mapping in place. |
| **docs/IPSAS_COMPLIANCE.md** | Section 3 still says “L_cb not in state” – should say L_cb is in state. Compliance checklist could reference new helpers (comparative, notes, maturity/risk). |
| **docs/GAPS_AND_MISSING.md** | B.3 table says “repo multiplier not modeled” but `repo_multiplier()` exists – could say “repo multiplier implemented; not in dashboard”. |
| **docs/REFERENCES.md** | Weblinks added (IPSASB, Handbook, BIS, BIS bulk, IMF, Fed H.4.1, Fed Data Download). |
| **docs/RECOMMENDATIONS.md** | Created: consolidated list of recommendations and suggestions. |
| **Inline docstrings** | Some modules lack “Part X” references or “Required columns” for regression DataFrames. |

---

## 3. Summary checklist

Implementation status: structures and code listed below have been added (templates for IPSAS; cross-sector check; budget_actual_from_state; get_case_narrative; docs added or updated). Real data pipelines remain optional.

### Missing components (to implement if targeting full IPSAS / completeness)

- [x] IPSAS 3: Accounting policies / prior-period adjustment / error correction — `accounting_policies_structure()`
- [x] IPSAS 5: Borrowing costs — `borrowing_costs_structure()`
- [x] IPSAS 9/47: Revenue recognition — `revenue_recognition_structure()`
- [x] IPSAS 10: Hyperinflation restatement — `hyperinflation_restatement_structure()`
- [x] IPSAS 14: Events after the reporting date — `events_after_reporting_date_structure()`
- [x] IPSAS 19: Provisions and contingencies — `provisions_contingencies_structure()`
- [x] IPSAS 20: Related party disclosure — `related_party_disclosure_structure()`
- [x] IPSAS 23: Revenue from non-exchange transactions — `revenue_non_exchange_structure()`
- [x] IPSAS 29/41: Financial instrument measurement and ECL — `financial_instruments_measurement_structure()`
- [x] IPSAS 38: Disclosure of interests in other entities — `interests_in_other_entities_structure()`
- [x] IPSAS 46: Measurement basis — `measurement_basis_structure()`
- [x] IPSAS 48: Transfer expenses — `transfer_expenses_structure()`
- [x] Cash-basis statement — `cash_basis_statement_structure()`
- [x] RPG 2: Financial Statement Discussion and Analysis (narrative) — `fs_discussion_and_analysis_structure()`
- [x] Functional / presentation currency — state fields + `functional_presentation_currency_structure()`
- [x] Cross-sector matrix consistency check — `cross_sector_consistency_check()` in fqbm.matrix
- [x] Budget/appropriation model (optional) — `budget_actual_from_state()` in presentation
- [x] Historical case narrative or coded outputs (Part XI) — `get_case_narrative(name)` in scenarios.presets
- [x] Real data pipelines (optional) — `fqbm.data.pipelines`: fetch_fed_h41, fetch_bis_series, fetch_imf_series

### Required documentation (to add)

- [x] **White paper** in repo — `docs/WHITE_PAPER.md` (placeholder)
- [x] **User guide / tutorial** — `docs/USER_GUIDE.md`
- [x] **API reference** — `docs/API_REFERENCE.md`
- [x] **Data dictionary** — `docs/DATA_DICTIONARY.md`
- [x] **Changelog** — `CHANGELOG.md`
- [x] **Contributing / development** — `CONTRIBUTING.md`
- [x] Update **IPSAS_COMPLIANCE.md** (L_cb in state; new helpers)
- [x] Update **GAPS_AND_MISSING.md** (repo_multiplier in dashboard note)
- [x] Extend **framework_summary.md** (module mapping)

---

## 4. References

- [GAPS_AND_MISSING.md](GAPS_AND_MISSING.md) – Full IPSAS and FQBM gap list
- [IPSAS_COMPLIANCE.md](IPSAS_COMPLIANCE.md) – Scope and use of the IPSAS layer
- [RECOMMENDATIONS.md](RECOMMENDATIONS.md) – Additional recommendations and suggestions
- [framework_summary.md](framework_summary.md) – Core identity and Parts I–XVI
- [REFERENCES.md](REFERENCES.md) – Chicago Author–Date references and weblinks