Skip to content

feat(reporting): flag large CF operating reconciling plug#732

Merged
jfrench9 merged 1 commit into
mainfrom
feat/cf-operating-plug-warning
Jun 6, 2026
Merged

feat(reporting): flag large CF operating reconciling plug#732
jfrench9 merged 1 commit into
mainfrom
feat/cf-operating-plug-warning

Conversation

@jfrench9
Copy link
Copy Markdown
Member

@jfrench9 jfrench9 commented Jun 6, 2026

Summary

The indirect cash-flow statement foots to actual cash by booking the aggregate non-cash operating adjustment onto IncreaseDecreaseInOtherOperatingCapitalNet (in _reconcile_operating_to_cash). That makes the CF articulate by construction — correct, but it also silently absorbs any investing/financing flow misclassification, so a genuine error never trips the tie-out. This PR surfaces a plug that is large relative to operating cash, turning that silent failure mode into a visible, non-blocking warning. It came out of the CF gain/loss-reversal investigation: the reversal itself is already handled by the plug (the statement foots); this just makes a suspiciously large plug visible.

Changes

reports/guard_rails.py (the user-visible render-time path)

  • New _check_operating_plug, wired into _validate_cash_flow. Appends a ValidationResult warning (per period column) when the IncreaseDecreaseInOtherOperatingCapitalNet row exceeds 25% of the NetCashProvidedByUsedInOperatingActivities row, or when operating cash is ~0 but the plug is material. Surfaces in the report envelope via ValidationLite, alongside the existing footing warnings.
  • Imports the shared threshold + CF qname constants from fact_grid (single source of truth).

reports/fact_grid.py (the exact-magnitude log path)

  • Added _CF_OPERATING_SUBTOTAL_QNAME and _CF_PLUG_WARN_RATIO = 0.25 constants.
  • _reconcile_operating_to_cash now resolves the operating-subtotal id and elevates its INFO log to WARNING (with the exact plug amount and % of operating cash) when the plug crosses the threshold; denominator is post-plug operating cash, floored by ΔCash to avoid divide-by-zero.

tests/.../test_guard_rails.py

  • 4 tests: large plug warns, small plug silent, zero-operating + material plug warns, no-plug-row silent.

Testing

  • uv run pytest tests/operations/roboledger/reports/170 passed (incl. the 4 new); test_guard_rails.py → 25 passed.
  • ruff check / ruff format / basedpyright on the changed files → clean (0 errors); pre-commit hooks passed on the commit.
  • just test-all (full suite): not run this session.

Notes / Follow-ups

  • Warning-only — the CF still foots and renders; no change to any reported number. This only adds a diagnostic.
  • Row-level approximation: the plug line also carries any tenant-mapped "other operating capital" content, but it's a system catch-all rarely mapped directly, so the rendered row value approximates the pure plug. An exact threshold would thread the Phase-1 residual into the grid (more plumbing) — deferred.
  • Threshold (25%) is a first cut; tune once there's real multi-tenant data on typical plug magnitudes.
  • The design doc (local/docs/ref/reporting.md §4.3, gitignored) was corrected locally to note the CF validator is wired and the plug heuristic exists — not part of this diff.
  • Itemizing the plug's components (gain/loss on disposal, unrealized MTM, …) into their own CF lines remains the documented future enrichment; this PR only flags magnitude.

…perating cash

_reconcile_operating_to_cash foots the indirect CF to actual cash by booking the
aggregate non-cash operating adjustment (gain/loss on disposal, unrealized MTM, …)
onto IncreaseDecreaseInOtherOperatingCapitalNet — correct, but it silently absorbs
any investing/financing misclassification too. Surface a large plug:

- guard_rails._check_operating_plug (wired into _validate_cash_flow) appends a
  ValidationResult warning when the plug exceeds 25% of operating cash, so it
  shows in the render envelope (ValidationLite), not just logs
- _reconcile_operating_to_cash elevates its INFO log to WARNING at the same
  threshold, with the exact plug magnitude and %
- shared _CF_PLUG_WARN_RATIO + CF qname constants keep the two paths in lockstep
- 4 guard-rails tests (large warns, small silent, zero-operating warns, no-plug silent)
@jfrench9 jfrench9 merged commit 267f6c4 into main Jun 6, 2026
7 checks passed
@jfrench9 jfrench9 deleted the feat/cf-operating-plug-warning branch June 6, 2026 19:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant