fix(sec): compose total debt across the styles filers actually tag

total_debt read LongTermDebt, else LongTermDebtNoncurrent/Current, plus one of
ShortTermBorrowings/CommercialPaper. That misses two whole tagging styles, and
it feeds net_debt -> net_debt_to_ebitda -> the categorical leverage read, so the
misses were not absences but confident wrong answers: Coca-Cola scored on 0.25bn
of commercial paper against ~39bn of debt, Verizon on 21.78bn of current
maturities against ~165bn, AT&T and Exxon produced no value at all against 134bn
and 33bn tagged. Measured over 19 large caps and 14 REITs, 11 were wrong or
absent and the rest are unchanged.

Each concept's span is now respected. LongTermDebt already includes current
maturities (Apple tags all three: 71.34 + 11.01 = 82.30), so only true
short-term borrowing is added. LongTermDebtAndCapitalLeaseObligations — what KO,
HD, T, XOM and CVX tag, and nothing read before — is noncurrent and takes a
current complement, and DebtCurrent *is* that whole complement rather than an
addition to it.

The REIT branch needed disambiguating: NotesPayable is not the same line across
issuers. MAA tags NotesPayable 5.66bn = UnsecuredDebt 5.30bn + SecuredDebt
0.36bn exactly, so there it is the total and adding the secured side
double-counts; EQR tags it alongside a larger SecuredDebt, where it is only the
unsecured component. UnsecuredDebt's presence separates them.

A component alone is no longer reported as a total. Chevron tags full debt only
in its 10-K, so its 10-Q carried 0.40bn of short-term borrowing; Boston
Properties tags SecuredDebt 4.28bn against ~15bn real. net_debt needs both sides
and yields nothing when either is missing, so None costs a leverage read where
the fragment produced a confidently wrong one.

Snapshots are immutable, so this corrects new filings only; stored history needs
scripts/reparse_fundamentals.py, which cannot complete until the EQR/931182
collision is retired.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Lo99z3jWqu9X9ueBU3Z3D

tests/unit/test_sec_facts_parser.py

@@ -538,3 +538,88 @@ def test_a_wrong_declared_year_end_no_longer_collides_two_periods():
     keys = {(r.fiscal_year, r.fiscal_period) for r in res.rows}
     assert len(keys) == 2, f"periods collided on one key: {keys}"
     assert keys == {(2026, "Q1"), (2026, "Q2")}
+
+
+# --- debt composition across the tagging styles large filers actually use ----
+# Values are the real shapes measured 2026-08; before this composition, seven of
+# nineteen sampled large caps carried a materially wrong or absent total_debt.
+
+_RD = date(2026, 3, 28)
+
+
+def _f(concept, val):
+    return Fact("us-gaap", concept, "USD", None, _RD, val, 2026, "Q2")
+
+
+def test_debt_from_a_noncurrent_lease_aggregate_adds_its_current_side():
+    """KO/HD/T/XOM/CVX tag LongTermDebtAndCapitalLeaseObligations, which nothing
+    read before — AT&T reported no debt at all against 134bn tagged."""
+    facts = [_f("LongTermDebtAndCapitalLeaseObligations", 134_630), _f("DebtCurrent", 9_320)]
+    assert _compose_debt(facts, _RD) == 143_950
+
+
+def test_debt_current_is_the_whole_current_side_not_an_addition():
+    """DebtCurrent already spans short-term borrowing AND current maturities, so
+    adding commercial paper on top would count it twice."""
+    facts = [
+        _f("LongTermDebtNoncurrent", 22_840),
+        _f("DebtCurrent", 11_300),
+        _f("LongTermDebtCurrent", 6_460),
+        _f("CommercialPaper", 4_840),
+    ]
+    assert _compose_debt(facts, _RD) == 34_140
+
+
+def test_debt_falls_back_to_the_split_current_parts():
+    facts = [
+        _f("LongTermDebtNoncurrent", 36_890),
+        _f("LongTermDebtCurrent", 3_900),
+        _f("ShortTermBorrowings", 10_670),
+    ]
+    assert _compose_debt(facts, _RD) == 51_460
+
+
+def test_notes_payable_is_the_unsecured_side_when_nothing_names_it():
+    """Realty Income and VMRK tag a secured and an unsecured side, no aggregate."""
+    facts = [_f("NotesPayable", 25_090), _f("SecuredDebt", 40), _f("CommercialPaper", 1_400)]
+    assert _compose_debt(facts, _RD) == 26_530
+
+
+def test_an_explicit_unsecured_side_wins_over_notes_payable():
+    """MAA tags NotesPayable 5.66bn = UnsecuredDebt 5.30bn + SecuredDebt 0.36bn, so
+    NotesPayable is the total there and adding SecuredDebt to it double-counts.
+    Preferring the explicit unsecured side reproduces the total either way."""
+    facts = [_f("NotesPayable", 5_660), _f("UnsecuredDebt", 5_300), _f("SecuredDebt", 360)]
+    assert _compose_debt(facts, _RD) == 5_660
+
+
+def test_one_side_of_a_reits_debt_is_not_a_total():
+    """Boston Properties tags SecuredDebt 4.28bn and commercial paper against ~15bn
+    of real debt; Ventas the same shape. Composing from one side invents a total."""
+    assert _compose_debt([_f("SecuredDebt", 4_280), _f("CommercialPaper", 750)], _RD) is None
+    assert _compose_debt([_f("UnsecuredDebt", 5_300)], _RD) is None
+
+
+def test_current_maturities_alone_are_not_a_total():
+    """LongTermDebtCurrent used to stand in for the whole long-term side, which
+    reports the slice due within a year as if it were the debt."""
+    assert _compose_debt([_f("LongTermDebtCurrent", 6_460)], _RD) is None
+
+
+def test_an_aggregate_beats_the_reit_parts():
+    """AvalonBay tags all three; summing the parts would understate the total."""
+    facts = [_f("LongTermDebt", 9_020), _f("SecuredDebt", 700), _f("UnsecuredDebt", 7_410),
+             _f("CommercialPaper", 920)]
+    assert _compose_debt(facts, _RD) == 9_940
+
+
+def test_a_short_term_only_filing_reports_no_total_at_all():
+    """Chevron tags its full debt only in the 10-K, so a 10-Q carries 0.40bn of
+    short-term borrowing alone — reporting that as *total* debt reads as a
+    near-unlevered issuer carrying 50bn. None costs a leverage read; the partial
+    value produces a confidently wrong one."""
+    assert _compose_debt([_f("ShortTermBorrowings", 401)], _RD) is None
+
+
+def test_no_debt_facts_at_all_is_still_none():
+    assert _compose_debt([_f("CashAndCashEquivalentsAtCarryingValue", 100)], _RD) is None