Initial commit: Four-Quadrant Balance Sheet Matrix (FQBM) framework

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-22 23:39:47 -08:00
commit abed763a4f
51 changed files with 2923 additions and 0 deletions
--- a/docs/GAPS_AND_MISSING.md
+++ b/docs/GAPS_AND_MISSING.md
@@ -0,0 +1,152 @@
+# Complete IPSAS and FQBM Matrix — Gaps and Missing
+
+This document lists **all remaining IPSAS standards** and **all FQBM/Matrix gaps and missing elements** as of the current codebase. It extends [IPSAS_COMPLIANCE.md](IPSAS_COMPLIANCE.md).
+
+---
+
+## Part A — IPSAS: Full standards list and status
+
+| # | Standard | Status | Gap / note |
+|---|----------|--------|-------------|
+| **CF** | Conceptual Framework | Partial | A = L + E aligned; no revenue/expense/definition of surplus. |
+| **1** | Presentation of Financial Statements | Supported | Structure + current/non-current in `fqbm.ipsas.presentation`. |
+| **2** | Cash Flow Statements | Structure only | Template in `cash_flow_statement_structure()`; no activity classification from FQBM. |
+| **3** | Accounting Policies, Changes in Estimates and Errors | **Missing** | No policy note, prior-period adjustment, or error correction. |
+| **4** | Effects of Changes in Foreign Exchange Rates | Partial | S and pass-through only; no translation of FC assets/liabilities, no FX gain/loss disclosure. |
+| **5** | Borrowing Costs | **Missing** | No borrowing-cost capitalisation or expense classification. |
+| **6** | Consolidated and Separate Financial Statements | Partial | Sectoral (CB, bank) and consolidated view in presentation; no control definition or full consolidation mechanics. |
+| **7** | Investments in Associates | **Missing** | Not applicable to core FQBM; no equity method. |
+| **8** | Interests in Joint Ventures | **Missing** | Not applicable; no joint arrangement. |
+| **9** | Revenue from Exchange Transactions | **Missing** | No revenue recognition or measurement. |
+| **10** | Financial Reporting in Hyperinflationary Economies | **Missing** | No hyperinflation restatement (FQBM has inflation π but not restatement). |
+| **11** | Construction Contracts | **Missing** | Not applicable to monetary/financial core. |
+| **12** | Inventories | **Missing** | Not applicable. |
+| **13** | Leases | **Missing** | Not applicable to core; no right-of-use asset/lease liability. |
+| **14** | Events After the Reporting Date | **Missing** | No adjustment vs disclosure classification. |
+| **15** | Financial Instruments: Disclosure and Presentation | Partial | Presentation only; no disclosure (maturity, risk). |
+| **16** | Investment Property | **Missing** | Not applicable. |
+| **17** | Property, Plant, and Equipment | **Missing** | Not applicable; no PP&E or depreciation. |
+| **18** | Segment Reporting | **Missing** | No segment definition or segment P&L. |
+| **19** | Provisions, Contingent Liabilities and Contingent Assets | **Missing** | No provisions or contingencies. |
+| **20** | Related Party Disclosures | **Missing** | No related party identification or disclosure. |
+| **21** | Impairment of Non-Cash-Generating Assets | **Missing** | Not applicable to financial core. |
+| **22** | Disclosure of Financial Information About the General Government Sector | Partial | Sectoral structure supported; GGS boundary and entity list external. |
+| **23** | Revenue from Non-Exchange Transactions | **Missing** | No tax/transfer revenue. |
+| **24** | Presentation of Budget Information in Financial Statements | Structure only | Template in `budget_vs_actual_structure()`; budget data external. |
+| **25** | Employee Benefits | **Missing** | Not applicable to core. |
+| **26** | Impairment of Cash-Generating Assets | **Missing** | No impairment model. |
+| **27** | Agriculture | **Missing** | Not applicable. |
+| **28** | Financial Instruments: Presentation | Partial | Asset/liability split in statement of financial position. |
+| **29** | Financial Instruments: Recognition and Measurement | **Missing** | No measurement basis (amortised cost, FVOCI, FVPL) or ECL. |
+| **30** | Financial Instruments: Disclosures | **Missing** | No risk or maturity disclosure. |
+| **31** | Intangible Assets | **Missing** | Not applicable. |
+| **32** | Service Concession Arrangements: Grantor | **Missing** | Not applicable. |
+| **33** | First-Time Adoption of Accrual Basis IPSAS | **Missing** | Not applicable (no full IPSAS adoption). |
+| **34** | Separate Financial Statements | Partial | Entity-level (CB, bank) supported. |
+| **35** | Consolidated Financial Statements | Partial | Consolidated layout; no full consolidation rules. |
+| **36** | Investments in Associates and Joint Ventures | **Missing** | Not applicable. |
+| **37** | Joint Arrangements | **Missing** | Not applicable. |
+| **38** | Disclosure of Interests in Other Entities | **Missing** | No disclosure. |
+| **39** | Employee Benefits | **Missing** | Not applicable. |
+| **40** | Public Sector Combinations | **Missing** | Not applicable. |
+| **41** | Financial Instruments | **Missing** | No classification, measurement, or ECL. |
+| **42** | Social Benefits | **Missing** | Not applicable. |
+| **43** | Leases | **Missing** | Not applicable. |
+| **44** | Non-Current Assets Held for Sale and Discontinued Operations | **Missing** | Not applicable. |
+| **45** | Property, Plant, and Equipment | **Missing** | Not applicable. |
+| **46** | Measurement | **Missing** | No measurement basis (historical, FV, etc.). |
+| **47** | Revenue | **Missing** | No revenue model. |
+| **48** | Transfer Expenses | **Missing** | No transfer expense. |
+| **49** | Retirement Benefit Plans | **Missing** | Not applicable. |
+| **50** | Exploration for and Evaluation of Mineral Resources | **Missing** | Not applicable. |
+| **Cash basis** | Financial Reporting Under the Cash Basis | **Missing** | No cash-basis statement. |
+| **RPG 1** | Long-Term Sustainability of an Entity's Finances | Partial | Debt sustainability (r−g) in sovereign module; no full RPG 1 disclosure. |
+| **RPG 2** | Financial Statement Discussion and Analysis | **Missing** | No narrative. |
+| **RPG 3** | Reporting Service Performance Information | **Missing** | Not applicable. |
+| **SRS 1** | Climate-related Disclosures | **Missing** | Not applicable. |
+
+---
+
+## Part B — FQBM / Four-Quadrant Matrix: Gaps and missing
+
+### B.1 State vector and identities
+
+| Item | Status | Note |
+|------|--------|------|
+| **L_cb (central bank loans)** | **Added** | `FQBMState.L_cb` (default 0); central_bank_step updates L_cb; matrix uses state.L_cb. |
+| **Open-economy split A_dom / A_ext, L_dom / L_ext** | **Added** | `open_economy_view(A_dom, A_ext, L_dom, L_ext, E)` in `fqbm.state` returns identity check and totals. |
+| **Reporting period / reporting date** | **Added** | `FQBMState.reporting_date` (optional); `statement_of_financial_position(..., reporting_date=)` uses state.reporting_date when not passed. |
+
+### B.2 Four-quadrant matrix (Part I)
+
+| Item | Status | Note |
+|------|--------|------|
+| **Explicit four-quadrant layout** | **Added** | `fqbm.matrix.four_quadrant_matrix(state)` and `four_quadrant_summary(state)` return the 4-column matrix and identity check. |
+| **Quadrant balance checks** | **Added** | Summary includes `identity_A_eq_L_plus_E`. |
+| **Cross-sector consistency** | Partial | CB and bank identities implemented; no automatic check that matrix totals equal sectoral sums. |
+
+### B.3 White paper parts not implemented
+
+| Part | Topic | Status | Gap |
+|------|--------|--------|-----|
+| **VII** | Shadow banking and leverage | **Integrated** | `leverage_ratio()` in dashboard ratios; `margin_spiral_risk()` available; repo multiplier not modeled. |
+| **VIII** | Derivatives clearing and CCP | **Integrated** | `run_workbook(ccp_params=CCPParams(...))` returns `result["ccp"]` with identity and waterfall flag. |
+| **IX** | CBDC and digital reserve architecture | **Integrated** | `run_workbook(cbdc_params=CBDCParams(...))` applies deposit/reserve shift; `result["cbdc"]` has cbdc_liability. |
+| **XI** | Historical case expansion | **Partial** | Presets (1997, 2008, 2020, 2022) in scenarios; no narrative or coded “case” outputs. |
+
+### B.4 IPSAS presentation structures added (templates only where no FQBM data)
+
+| Item | Status | Location |
+|------|--------|----------|
+| Statement of financial position (IPSAS 1) | Supported | `statement_of_financial_position()` |
+| Budget vs actual (IPSAS 24) | Structure | `budget_vs_actual_structure()` |
+| Cash flow statement (IPSAS 2) | Structure | `cash_flow_statement_structure()` |
+| Statement of financial performance | Structure | `statement_of_financial_performance_structure()` |
+| Four-quadrant matrix | Supported | `fqbm.matrix.four_quadrant_matrix()` |
+
+### B.5 Other missing
+
+| Item | Status |
+|------|--------|
+| **Statement of changes in net assets/equity** | **Added** | `statement_of_changes_in_net_assets_structure()`. |
+| **Notes to the financial statements** | **Added** | `notes_to_financial_statements_structure()`. |
+| **Comparative period** | **Added** | `statement_of_financial_position_comparative(state_prior, state_current, entity)`. |
+| **Functional currency / presentation currency** | **Missing**. |
+| **Financial instrument maturity breakdown** | **Added** | `maturity_risk_disclosure_structure()` (maturity buckets, interest rate +100bp, credit exposure, ECL). |
+| **Interest rate sensitivity** | **Partial** | Column in maturity_risk_disclosure_structure. |
+| **Credit risk / ECL disclosure** | **Partial** | Columns in maturity_risk_disclosure_structure. |
+| **FX translation of FC positions** | **Added** | `fx_translate(fc_amount, S_prev, S_curr)`. |
+| **Cash flow from balance sheet changes** | **Added** | `cash_flow_from_state_changes(state_prev, state_curr)`. |
+
+---
+
+## Part C — Implementation checklist (done vs to do)
+
+### Done
+
+- IPSAS 1 statement of financial position (CB, bank, consolidated); uses state.L_cb and state.reporting_date.
+- IPSAS 24 budget vs actual template.
+- IPSAS 2 cash flow statement template; **cash_flow_from_state_changes(state_prev, state_curr)** infers amounts from Δstate.
+- Statement of financial performance template.
+- **Statement of changes in net assets** template.
+- **FX translation**: **fx_translate(fc_amount, S_prev, S_curr)**.
+- Four-quadrant matrix and summary; **L_cb** from state.
+- **L_cb in state**: `FQBMState.L_cb` and `reporting_date`; central_bank_step updates L_cb; differential model 12-element vector.
+- **Open economy**: **open_economy_view(A_dom, A_ext, L_dom, L_ext, E)**.
+- **Part VII**: Leverage ratio in dashboard; **run_workbook** exposes shadow metrics.
+- **Part VIII**: **run_workbook(ccp_params=CCPParams(...))** returns result["ccp"].
+- **Part IX**: **run_workbook(cbdc_params=CBDCParams(...))** applies deposit/reserve shift; result["cbdc"].
+
+### Optional work (completed)
+
+1. **Part VII**: **repo_multiplier(initial_collateral, haircut, rounds)** and **margin_spiral_simulation(...)** in `fqbm.sheets.shadow_banking`.
+2. **Part VIII**: **variation_margin_flow(mark_to_market_change)** and **ccp_clearing_simulation(vm_calls_per_period, liquidity_buffer_start)** in `fqbm.sheets.ccp`.
+3. **IPSAS**: **notes_to_financial_statements_structure()**; **statement_of_financial_position_comparative(state_prior, state_current, entity)**; **maturity_risk_disclosure_structure()** in `fqbm.ipsas.presentation`.
+
+---
+
+## References
+
+- [IPSAS_COMPLIANCE.md](IPSAS_COMPLIANCE.md) — Scope and how to use the IPSAS layer.
+- IPSASB (2025). *Handbook of International Public Sector Accounting Pronouncements*. IFAC.
+- White paper: Four-Quadrant Balance Sheet Matrix, Parts I–XVI.
--- a/docs/IPSAS_COMPLIANCE.md
+++ b/docs/IPSAS_COMPLIANCE.md
@@ -0,0 +1,144 @@
+# IPSAS Compliance Assessment — FQBM Framework
+
+This document assesses the Four-Quadrant Balance Sheet Matrix (FQBM) against **International Public Sector Accounting Standards (IPSAS)** issued by the IPSASB. The FQBM is a macroeconomic and institutional simulation framework; IPSAS applies to **entity-level general purpose financial reporting** by public sector entities. The assessment clarifies scope, alignment, and gaps.
+
+---
+
+## 1. Scope and applicability
+
+| Aspect | FQBM | IPSAS |
+|--------|------|--------|
+| **Primary purpose** | Monetary/fiscal simulation, stress testing, open-economy dynamics | Entity financial statements (audit-ready, general purpose) |
+| **Unit of account** | Sectoral balance sheets (CB, banks, sovereign), state vector **X** | Single public sector entity or consolidated government |
+| **Basis** | Identities (A = L + E), differentials, stochastic shocks | Accrual (or cash) basis, recognition, measurement, presentation |
+| **Output** | Time paths, ratios, stress tables, Monte Carlo distributions | Statement of financial position, statement of financial performance, cash flow statement, budget comparison |
+
+**Conclusion**: FQBM supports **analysis that can feed into** IPSAS-consistent reporting (e.g. central bank or government balance sheet layout, budget vs actual structure). It is not a substitute for full IPSAS-compliant financial statements. Compliance is assessed for **presentation and disclosure structures** that can be derived from or aligned with FQBM outputs.
+
+---
+
+## 2. IPSAS standards relevant to FQBM
+
+| Standard | Relevance | FQBM alignment / gap |
+|----------|-----------|------------------------|
+| **IPSAS 1** — Presentation of Financial Statements | Statement of financial position (balance sheet) structure, current/non-current classification, minimum line items | **Partial**: We provide an IPSAS 1-style layout (current/non-current) for central bank and commercial bank from state **X**. Minimum line items satisfied where FQBM has data (financial assets, cash/reserves, liabilities, net assets). |
+| **IPSAS 2** — Cash Flow Statements | Operating, investing, financing cash flows | **Gap**: FQBM does not model cash flows by activity. Cash flows can be inferred from balance sheet changes (e.g. ΔR, ΔC) but not classified by IPSAS 2 categories. |
+| **IPSAS 4** — Effects of Changes in Foreign Exchange Rates | FX translation, functional currency, presentation of FX differences | **Partial**: FQBM has exchange rate **S** and FX pass-through; no explicit translation of foreign-currency assets/liabilities or disclosure of FX gains/losses. |
+| **IPSAS 15 / 28 / 29 / 41** — Financial Instruments | Classification, measurement, disclosure of financial assets/liabilities | **Partial**: State variables (B, R, Loans, Deposits) map to financial instruments; no classification (amortised cost vs FVOCI etc.) or impairment model. |
+| **IPSAS 22** — Disclosure of Financial Information About the General Government Sector | Sectoral disaggregation (e.g. general government) | **Partial**: FQBM distinguishes CB, banks, sovereign; can support GGS-style disclosure structure if sector definitions are aligned. |
+| **IPSAS 24** — Presentation of Budget Information in Financial Statements | Budget vs actual comparison, material variances, comparable basis | **Gap**: No budget or appropriation model in FQBM. We provide a **structure** (budget, actual, variance) for users to populate from external budget data. |
+| **Conceptual Framework** | Definitions of assets, liabilities, net assets, revenue, expense | **Partial**: A = L + E and four-quadrant identity align with “assets” and “liabilities”; no revenue/expense or surplus/deficit from operations. |
+
+---
+
+## 3. Current/non-current classification (IPSAS 1)
+
+IPSAS 1 requires **current** and **non-current** classification for assets and liabilities unless a liquidity presentation is more appropriate.
+
+**Central bank (from FQBM state)**:
+
+| IPSAS 1-style line item | FQBM variable | Suggested classification | Notes |
+|-------------------------|---------------|---------------------------|--------|
+| Financial assets (at amortised cost / FV) | B (government bonds), L_cb (loans) | Non-current (hold-to-maturity / policy portfolio) or split by maturity | L_cb not in state; can be added. |
+| Cash and cash equivalents / Reserves | R | Current | |
+| Currency in circulation | C | Liability (current) | |
+| Liabilities (reserve accounts) | R (bank reserves) | Current | |
+| Net assets / Equity | E_cb | — | |
+
+**Commercial bank**:
+
+| IPSAS 1-style line item | FQBM variable | Suggested classification |
+|-------------------------|----------------|---------------------------|
+| Loans and receivables | Loans | Current / non-current by behavioural maturity if available |
+| Cash and balances at central bank | R (if attributed to bank) | Current |
+| Deposits from customers | Deposits | Current |
+| Net assets / Equity | E_b | — |
+
+The module `fqbm.ipsas.presentation` produces statement-of-financial-position layouts with these classifications where applicable.
+
+---
+
+## 4. Budget vs actual (IPSAS 24)
+
+IPSAS 24 requires comparison of **approved budget** (original/final) with **actual** amounts on a comparable basis, with explanations of material variances.
+
+**FQBM**: No budget or appropriation data. We provide:
+
+- A **template** for budget vs actual: line item, original budget, final budget, actual, variance, material (e.g. >10%).
+- **Actual** amounts can be filled from FQBM state (e.g. total assets, total liabilities, key aggregates). **Budget** columns must be supplied by the reporting entity.
+
+See `fqbm.ipsas.presentation.budget_vs_actual_structure()`.
+
+---
+
+## 5. Financial instruments (IPSAS 15, 28, 29, 41)
+
+- **Presentation**: Financial assets vs liabilities, and (where applicable) current vs non-current — supported by the IPSAS 1-style layout.
+- **Recognition and measurement**: FQBM does not implement measurement bases (amortised cost, FVOCI, FVPL) or impairment (e.g. ECL). **Gap** for full IPSAS 41 compliance.
+- **Disclosure**: No maturity breakdown, interest rate sensitivity, or credit risk disclosure. **Gap**; can be extended with user-supplied data.
+
+---
+
+## 6. Foreign exchange (IPSAS 4)
+
+- FQBM has **S** (exchange rate) and **FX pass-through** (e.g. π_import = β ΔS). Useful for **analysis** of FX effects on inflation and balance sheets.
+- **Gap**: No explicit translation of foreign-currency-denominated assets/liabilities, or separate disclosure of FX gains/losses in a performance statement.
+
+---
+
+## 7. Consolidation and general government (IPSAS 6, 22, 35)
+
+- FQBM **A_dom + A_ext = L_dom + L_ext + E** and sectoral breakdown (CB, banks, sovereign) support **consolidation logic** and sectoral views.
+- **IPSAS 22** (general government sector disclosure): FQBM can feed sectoral totals; exact GGS boundary and entity list must be defined by the reporting jurisdiction.
+
+---
+
+## 8. Compliance checklist (summary)
+
+| Requirement | Status | Notes |
+|-------------|--------|--------|
+| Statement of financial position (IPSAS 1) structure | **Supported** | Via `fqbm.ipsas.presentation.statement_of_financial_position()` |
+| Current/non-current classification | **Supported** | Applied in presentation layer for CB and bank |
+| Minimum line items (IPSAS 1) | **Partial** | Satisfied for items present in FQBM; no PP&E, inventories, etc. |
+| Cash flow statement (IPSAS 2) | **Not supported** | No activity classification of cash flows |
+| Budget vs actual (IPSAS 24) | **Structure only** | Template provided; budget data external |
+| Financial instrument measurement (IPSAS 41) | **Not supported** | No measurement basis or ECL |
+| FX translation (IPSAS 4) | **Partial** | Exchange rate and pass-through only |
+| Disclosure of GGS (IPSAS 22) | **Partial** | Sectoral structure supported |
+| Reporting period / reporting date | **Not defined** | FQBM is period-agnostic; user must set |
+
+---
+
+## 9. How to use the IPSAS layer in this codebase
+
+1. **Run the workbook** (or differential model) to obtain **state** (and optional stress, MC).
+2. **Call** `fqbm.ipsas.presentation.statement_of_financial_position(state, entity="central_bank")` (or `"commercial_bank"`, `"consolidated"`) to get an IPSAS 1-style layout.
+3. **Call** `fqbm.ipsas.presentation.budget_vs_actual_structure()` to get an empty DataFrame/template for IPSAS 24; fill budget from external source, actual from state where applicable.
+4. **Export** presentation outputs to Excel or include in reports alongside FQBM dashboards.
+
+For **full IPSAS compliance** at entity level, the reporting entity must:
+
+- Maintain recognition and measurement in line with IPSAS (e.g. IPSAS 41, 46).
+- Prepare cash flow statement (IPSAS 2) and statement of financial performance.
+- Populate budget information (IPSAS 24) and provide variance analysis.
+- Apply IPSAS 4 for FX and other standards as applicable.
+
+The FQBM IPSAS layer supports **presentation consistency** and **structural alignment** with IPSAS 1 and IPSAS 24, not end-to-end compliance by itself.
+
+---
+
+## 10. References
+
+- IPSASB (2025). *Handbook of International Public Sector Accounting Pronouncements*. IFAC.
+- IPSAS 1, *Presentation of Financial Statements*.
+- IPSAS 2, *Cash Flow Statements*.
+- IPSAS 4, *The Effects of Changes in Foreign Exchange Rates*.
+- IPSAS 24, *Presentation of Budget Information in Financial Statements*.
+- IPSAS 22, *Disclosure of Financial Information About the General Government Sector*.
+- IPSASB Conceptual Framework, *General Purpose Financial Reporting by Public Sector Entities*.
+
+---
+
+## 11. Complete IPSAS and Matrix gaps
+
+For a **full list of all remaining IPSAS standards** (1–50, cash basis, RPGs, Conceptual Framework) with status (supported / partial / missing) and **all FQBM/Matrix gaps** (L_cb, open-economy split, Parts VII–IX, reporting period, etc.), see **[GAPS_AND_MISSING.md](GAPS_AND_MISSING.md)**.
--- a/docs/REFERENCES.md
+++ b/docs/REFERENCES.md
@@ -0,0 +1,17 @@
+# References (Chicago Author–Date)
+
+Adrian, Tobias, and Hyun Song Shin. 2010. "Liquidity and Leverage." *Journal of Financial Intermediation*.
+
+Bank for International Settlements (BIS). 2017. *Basel III: Finalising Post-Crisis Reforms*.
+
+Borio, Claudio. 2014. "The Financial Cycle and Macroeconomics." *BIS Working Papers*.
+
+Dornbusch, Rudiger. 1976. "Expectations and Exchange Rate Dynamics." *Journal of Political Economy*.
+
+Federal Reserve. 2009–2023. *H.4.1 Statistical Release*.
+
+International Monetary Fund (IMF). 2014. *Government Finance Statistics Manual*.
+
+McLeay, Michael, Amar Radia, and Ryland Thomas. 2014. "Money Creation in the Modern Economy." *Bank of England Quarterly Bulletin*.
+
+Obstfeld, Maurice, and Kenneth Rogoff. 1995. *Foundations of International Macroeconomics*.
--- a/docs/framework_summary.md
+++ b/docs/framework_summary.md
@@ -0,0 +1,37 @@
+# FQBM Framework Summary
+
+## Core identity (Part I)
+
+- **Accounting**: \( A = L + E \)
+- **Open economy**: \( A_{dom} + A_{ext} = L_{dom} + L_{ext} + E \)
+
+Every financial asset is someone else’s liability (within or across borders).
+
+## Four-quadrant matrix
+
+| Assets (Dr) | Assets (Cr) | Liabilities (Dr) | Liabilities (Cr) |
+
+All monetary operations must balance across this structure.
+
+## Parts of the white paper
+
+| Part | Topic |
+|------|--------|
+| I | Accounting foundation |
+| II | Closed-economy monetary dynamics (CB, commercial bank) |
+| III | Open-economy extension (BoP, parity) |
+| IV | Capital flows and FX dynamics |
+| V | Sovereign risk and CDS |
+| VI | Commodity shock channel |
+| VII | Shadow banking and leverage |
+| VIII | Derivatives clearing and CCP |
+| IX | CBDC and digital reserve architecture |
+| X | Empirical regression appendix |
+| XI | Historical case expansion |
+| XII | Quantitative stress tables |
+| XIII | Monte Carlo simulation framework |
+| XIV | Full system differential model |
+| XV | Policy implications |
+| XVI | Simulation workbook architecture (eight sheets) |
+
+This codebase implements the simulation workbook (Part XVI), Monte Carlo (XIII), differential model (XIV), and empirical regressions (Part X).