feat(reporting): flag large CF operating reconciling plug#732
Merged
Conversation
…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)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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)_check_operating_plug, wired into_validate_cash_flow. Appends aValidationResultwarning (per period column) when theIncreaseDecreaseInOtherOperatingCapitalNetrow exceeds 25% of theNetCashProvidedByUsedInOperatingActivitiesrow, or when operating cash is ~0 but the plug is material. Surfaces in the report envelope viaValidationLite, alongside the existing footing warnings.fact_grid(single source of truth).reports/fact_grid.py(the exact-magnitude log path)_CF_OPERATING_SUBTOTAL_QNAMEand_CF_PLUG_WARN_RATIO = 0.25constants._reconcile_operating_to_cashnow resolves the operating-subtotal id and elevates itsINFOlog toWARNING(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.pyTesting
uv run pytest tests/operations/roboledger/reports/→ 170 passed (incl. the 4 new);test_guard_rails.py→ 25 passed.ruff check/ruff format/basedpyrighton 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
residualinto the grid (more plumbing) — deferred.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.