test(differential): booking + balance + clamp oracle vs beancount (C1) (#210)

* test(differential): validate booking against beancount as ground-truth oracle

Snapshot tests only prove output didn't change, not that it's correct — a
booking bug gets frozen into the snapshot (as the pre-beancount#1656 trial_balance
snapshot did). This adds Layer 1 of the correctness plan: load each fixture
through both rustfava (rustledger engine) and beancount and assert the booked
per-account inventories agree to the cent.

- test_booked_inventories_match_beancount over example/long-example/
  query-example/off-by-one — all currently match (long-example alone has ~193
  cost lots), so this locks in booking correctness going forward.
- test_failing_balance_assertion_is_surfaced — xfail(rustledger#1663): the
  load() path emits no error for a failing `balance` (only validate() does), so
  a wrong assertion is silently shown as passed. Documents the defect as an
  executable check; flips to passing when the engine surfaces balance errors.

beancount is already a test dependency (beancount-compat extra).

* test(differential): C1 now passes on v0.18.0; add clamped-total oracle

- test_failing_balance_assertion_is_surfaced: flip from xfail to a positive
  assertion — v0.18.0 (rustledger 3.1.0 / beancount#1663) reports balance failures on
  load and carries a non-zero diff, closing the C1 gap end to end.
- test_passing_balance_assertion_is_green: guard the zero-diff mapping (a
  passing balance must stay diff_amount=None, not render as failed).
- test_clamped_totals_match_beancount_balance_at_cutoff: the time-filter (engine
  clamp) opening balances must reconstruct the correct closing totals — the path
  rustledger#1656 broke. Clamp long-example to 2014 and assert each account's
  total (opening + in-window) equals beancount's balance as of the cutoff, per
  (currency, cost) lot. Excludes the clamp-specific Equity:Opening-Balances.

Author: robcohen

tests/test_differential_beancount.py

@@ -0,0 +1,209 @@
+"""Differential correctness tests: rustfava (rustledger engine) vs beancount.
+
+rustfava aims for beancount compatibility, so beancount's own loader is a
+ground-truth *oracle* that the snapshot tests lack — a snapshot only proves the
+output did not change, not that it is correct. These tests load the same ledger
+through both engines and assert the booked results agree, so a booking or
+balance-handling divergence fails loudly instead of being frozen into a
+snapshot.
+
+This is Layer 1 of the correctness testing plan. Start here when a report shows
+a wrong number: if the booked inventories already differ from beancount, the
+bug is in loading/booking, not in the report layer.
+"""
+
+from __future__ import annotations
+
+import datetime
+from collections import defaultdict
+from decimal import Decimal
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+
+# beancount is the ground-truth oracle (installed via the `beancount-compat`
+# test extra). Skip cleanly rather than fail if it is somehow absent.
+beancount_loader = pytest.importorskip("beancount.loader")
+
+from rustfava.rustledger import loader as rf_loader  # noqa: E402
+from rustfava.rustledger.backend import get_engine  # noqa: E402
+from rustfava.rustledger.types import directives_from_json  # noqa: E402
+from rustfava.rustledger.types import directives_to_json  # noqa: E402
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+DATA = Path(__file__).parent / "data"
+
+# Fixtures whose booking rustfava must reproduce exactly. These span
+# held-at-cost lots, prices, multiple currencies, a pad/balance pair (example)
+# and a date-boundary case (off-by-one); long-example alone has ~193 cost lots.
+LEDGERS = ["example", "long-example", "query-example", "off-by-one"]
+
+# Type of `cost` normalized to beancount's 4-tuple identity — deliberately
+# dropping rustfava's extra ``number_total`` field so two engines' economically
+# equal lots compare equal here (that extra field leaking into lot identity is
+# a separate defect; this oracle should not be sensitive to it).
+CostKey = tuple[Decimal | None, str | None, object, str | None]
+AccountInventory = dict[tuple[str | None, CostKey | None], Decimal]
+
+
+def _cost_key(cost: object) -> CostKey | None:
+    if cost is None:
+        return None
+    number = getattr(cost, "number", None)
+    return (
+        Decimal(number) if number is not None else None,
+        getattr(cost, "currency", None),
+        getattr(cost, "date", None),
+        getattr(cost, "label", None),
+    )
+
+
+def _account_inventories(
+    entries: Iterable[object],
+) -> dict[str, AccountInventory]:
+    """Fold every posting into ``{account: {(currency, cost): Decimal}}``.
+
+    Works for both engines because rustfava registers its directive/posting
+    types against beancount's ABCs, so the ``postings``/``units``/``cost``
+    attribute shape is identical.
+    """
+    inv: dict[str, AccountInventory] = defaultdict(
+        lambda: defaultdict(Decimal)
+    )
+    for entry in entries:
+        for posting in getattr(entry, "postings", []):
+            units = posting.units
+            if units is None or units.number is None:
+                continue
+            key = (units.currency, _cost_key(posting.cost))
+            inv[posting.account][key] += Decimal(units.number)
+    # Drop keys/accounts that net to exactly zero.
+    return {
+        account: {k: v for k, v in lots.items() if v != 0}
+        for account, lots in inv.items()
+        if any(v != 0 for v in lots.values())
+    }
+
+
+@pytest.mark.parametrize("ledger", LEDGERS)
+def test_booked_inventories_match_beancount(ledger: str) -> None:
+    """Per-account booked inventories must equal beancount's, to the cent."""
+    path = str(DATA / f"{ledger}.beancount")
+    bc_entries, _bc_errors, _ = beancount_loader.load_file(path)
+    rf_entries, _rf_errors, _ = rf_loader.load_uncached(path)
+
+    bc_inv = _account_inventories(bc_entries)
+    rf_inv = _account_inventories(rf_entries)
+
+    # Compare per account for a readable diff on failure.
+    assert set(rf_inv) == set(bc_inv), (
+        f"account set differs: only-rustfava={set(rf_inv) - set(bc_inv)}, "
+        f"only-beancount={set(bc_inv) - set(rf_inv)}"
+    )
+    for account in sorted(bc_inv):
+        assert rf_inv[account] == bc_inv[account], (
+            f"inventory mismatch for {account}: "
+            f"rustfava={rf_inv[account]} beancount={bc_inv[account]}"
+        )
+
+
+def _balance_dirs(entries: Iterable[object]) -> list[object]:
+    return [e for e in entries if type(e).__name__ in {"Balance", "RLBalance"}]
+
+
+def test_failing_balance_assertion_is_surfaced() -> None:
+    """A failing `balance` must produce an error AND a non-zero diff.
+
+    Regression for rustledger#1663 / the C1 gap: `load()` (the display path)
+    previously reported no error for a failing assertion, so the journal showed
+    it as passed. rustledger 3.1.0 (v0.18.0) reports balance failures on load
+    and carries `diff` on the directive; the journal's red/green keys off a
+    present ``diff_amount``.
+    """
+    src = (
+        "2024-01-01 open Assets:Cash USD\n"
+        "2024-01-01 open Expenses:X USD\n"
+        '2024-01-02 * "t"\n'
+        "  Expenses:X   5 USD\n"
+        "  Assets:Cash\n"
+        "2024-01-03 balance Assets:Cash   999 USD\n"
+    )
+    entries, errors, _ = rf_loader.load_string(src, "<differential>")
+    assert any(
+        "balance" in str(getattr(e, "message", e)).lower() for e in errors
+    ), "a failing balance assertion produced no error"
+    (bal,) = _balance_dirs(entries)
+    # Real balance is -5, asserted 999 -> non-zero diff -> renders as failed.
+    assert bal.diff_amount is not None
+    assert bal.diff_amount.number != 0
+
+
+def test_passing_balance_assertion_is_green() -> None:
+    """A passing `balance` must be silent: no error, and no diff_amount.
+
+    Guards the zero-diff mapping — the engine sends `diff = 0` on a passing
+    assertion, and carrying that through would mark every passing balance
+    ``diff_amount`` (i.e. failed) in the journal.
+    """
+    src = (
+        "2024-01-01 open Assets:Cash USD\n"
+        "2024-01-01 open Expenses:X USD\n"
+        '2024-01-02 * "t"\n'
+        "  Expenses:X   5 USD\n"
+        "  Assets:Cash\n"
+        "2024-01-03 balance Assets:Cash   -5 USD\n"
+    )
+    entries, errors, _ = rf_loader.load_string(src, "<differential>")
+    assert errors == []
+    (bal,) = _balance_dirs(entries)
+    assert bal.diff_amount is None
+
+
+def test_clamped_totals_match_beancount_balance_at_cutoff() -> None:
+    """The time-filter (engine clamp) opening balances must reconstruct the
+    correct closing totals — the path that rustledger#1656 broke.
+
+    Clamping to ``[begin, end)`` yields synthesized opening balances plus
+    in-window postings; summed per account that equals the ledger's balance as
+    of ``end`` (every posting dated before ``end``). Cross-check that against
+    beancount, per account and per (currency, cost) lot. The synthesized
+    ``Equity:Opening-Balances`` contra is clamp-specific, so exclude it.
+    """
+    path = str(DATA / "long-example.beancount")
+    begin, end = "2014-01-01", "2015-01-01"
+    cutoff = datetime.date(2015, 1, 1)
+    opening = "Equity:Opening-Balances"
+
+    rf_entries, _, _ = rf_loader.load_uncached(path)
+    clamped = directives_from_json(
+        get_engine().clamp_entries(
+            directives_to_json(list(rf_entries)), begin, end
+        )["entries"]
+    )
+    rf_inv = {
+        a: v
+        for a, v in _account_inventories(clamped).items()
+        if a != opening
+    }
+
+    bc_entries, _, _ = beancount_loader.load_file(path)
+    before_cutoff = [
+        e
+        for e in bc_entries
+        if getattr(e, "date", cutoff) < cutoff
+    ]
+    bc_inv = {
+        a: v
+        for a, v in _account_inventories(before_cutoff).items()
+        if a != opening
+    }
+
+    assert set(rf_inv) == set(bc_inv)
+    for account in sorted(bc_inv):
+        assert rf_inv[account] == bc_inv[account], (
+            f"clamped total mismatch for {account}: "
+            f"rustfava={rf_inv[account]} beancount={bc_inv[account]}"
+        )