feat(arap)!: documents read their figures from standing lines; control accounts

refuse hand entries (P4b S1, part A)

Plan P4b (D-45), slice S1, the engine half: rules.md B-38.

- ledger-core: every receivables or payables line carries its document
  (Ledger.line_docs: DocRef, Movement, DocTag), written by the document
  commands in the step that posts it, derived on replay from the existing
  document events (the role's account as it stood then; payments by the
  ordinal rule), copied onto a reversal's mirror. Ledger::stands_on;
  doc_state / invoice_state / bill_state (total, paid, outstanding,
  status Open/Partial/Paid/WrittenOff/Void, overdue days) as of any day;
  ar_aging / ap_aging read them, so reversed payments and voids are right.
  The control guard (add_line, add_line_fx, post_entry,
  register_recurring) refuses untagged lines on receivables/payables,
  exempting a reversal's mirror of a legacy line; replay never refuses.
  Bounds (kernel::running_bounds, bounds_kept) on payments and reversals;
  a document reversal never dated before its entry; deposit/payer accounts
  must be cash-like and hold no role. New API: receive_payment_with /
  pay_bill_with (PaymentDetails: instrument, reference), void_document /
  check_void_document, control_check, payments_recorded,
  standing_payments, replay_reverse_entry. Invoice.amount_paid/status
  remain only as derived caches for the MCP layer until part B.
  cashflow bill_splits reads payments from the tags.
- ledger-store: journal feature document_standing (D-39 gated) for a
  payment accepted only because an earlier one was reversed;
  receive_payment_with / pay_bill_with (instrument journaled as
  entry.instrument_set, reference in the description), void_document;
  replay uses replay_reverse_entry; schema 15 drops the projection's
  amount_paid/status. Fixture p4-arap-before + golden figures written by
  the version before S1, adjudicated in arap_standing.rs.
- ledger-gui: party card, cash "coming up" and company owed totals read
  doc_state as of today (late from the derived state).
- Lean Documents.lean (control_agrees and friends); Kani
  bounds_check_matches_definition,
bounds_kept_is_the_definition_on_books_in_bounds;
  rules B-38, B-18/B-23 amended; bookspec `older = true` for legacy hand
  lines; tests that hand-post to 1200/2000 post as replay or renumbered.

Review fixes (both reviews of part A):
- control_role_of guards only an account the role is assigned to or one
  holding its documents' lines (a chart's own 1200 Equipment or card at
  2000 is free until a document posts there); payment accounts check
  other roles by holds_role (type-checked). The MCP tests that failed on
  the guard (oracle_mcp, spec_projects) pass unchanged.
- standing_payments leaves out reversals (sorted, deduped); replayed
  tags match the movement's side; payments_recorded counts every payment
  event (tagged or not, Ledger.payment_events) and refuses overflow.
- The record caches settled (paid + discounted + written off) and owed
  (Invoice/Bill.owed, never serialized): a void never reads as paid.
- assign_role: receivables/payables refuse moving onto an account with
  untagged lines (RoleAccountHasHandLines) and, on their control account
  holding a balance, say DocumentRoleHoldsBalance (no hand entry named);
  B-23 reworded. The reversal-mirror exemption only takes a hand line
  off (even chain depth); putting it back is refused.
- DocStatus Overpaid and Unattached; aging leaves out credit balances;
  ControlCheck.attention lists out-of-bounds and unattached documents.
- stands_on counts a chain in order; indexes (doc_index, doc_accounts,
  order_pos, reversed_by) keep the derived figures linear.
- Viewer reads a post-dated document as of its own date; one state per
  row. bounds_kept's side-crossing documented as intended.
- Tests: ten new spec_documents scenarios, stronger proptests, store
  proptest arap_props (live = replay = snapshot at every date, closed
  months), fuzz ops void/payments with details, a GUI post-dated test;
  Lean Step.assign / Step.release with unattached_zero kept; model
  limits stated in docs/testing.md and B-38.
Review fixes (CPA and engineering lenses): only an assigned role's
account or one holding document lines is a control account (a chart's
own 1200 asset stays free); a role can't move onto untagged lines or off
document lines (Lean Step.assign); a void's cache never reads as paid;
no Decimal sum panics; per-document indexes keep figures linear; a
replayed tag matches its side; the feature gate counts payment events;
a payment's reversal is never listed as standing; an overpaid document
has its own status; the viewer keeps post-dated documents.

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

crates/ledger-core/tests/spec_replayed_extremes.rs

@@ -283,22 +283,43 @@ fn a_draft_of_decimals_largest_is_refused_where_summed() {
     assert!(why.contains("too large to compute"), "{why}");
 }
 
-/// A document is restored as journaled: its total and balance are exact,
-/// or refused past exact arithmetic; aging sums by party, checked.
+/// A document is restored as journaled: its total is exact, or refused
+/// past exact arithmetic; what it owes is what the ledger lines tagged
+/// with it carry (rules.md B-38), exact, whatever the journal held (paid
+/// above its total included); aging refuses a document whose total it
+/// can't compute.
 #[test]
 fn documents_and_aging_are_exact_or_refused() {
     let mut l = Ledger::new(Currency::USD);
+    let ar = l
+        .add_account("1200", "Receivables", AccountType::Asset, None, false)
+        .unwrap();
+    let revenue = l
+        .add_account("4000", "Revenue", AccountType::Revenue, None, false)
+        .unwrap();
+    let cash = l
+        .add_account("1000", "Cash", AccountType::Asset, None, false)
+        .unwrap();
     let customer = l.add_customer("Client").unwrap();
     let line = |a: Decimal| DocumentLine {
         description: "x".into(),
         amount: a,
         class_id: None,
     };
+    // An entry as replay rebuilds it: Dr `dr` / Cr `cr` for `a`.
+    let replayed = |l: &mut Ledger, dr, cr, a: Decimal| {
+        let e = l.create_entry(d(2026, 3, 1), "replayed");
+        l.replay_add_line(e, dr, Side::Debit, usd(a)).unwrap();
+        l.replay_add_line(e, cr, Side::Credit, usd(a)).unwrap();
+        l.replay_post_entry(e).unwrap();
+        e
+    };
     let fine = vec![
         line(Decimal::new(1, 11)),
         line("9.99999999999".parse().unwrap()),
     ];
-    l.replay_invoice(1, customer, d(2026, 3, 1), d(2026, 3, 31), fine, 1)
+    let e1 = replayed(&mut l, ar, revenue, Decimal::TEN);
+    l.replay_invoice(1, customer, d(2026, 3, 1), d(2026, 3, 31), fine, e1)
         .unwrap();
     let inv = l.get_invoice(1).unwrap();
     assert_eq!(inv.total(), Ok(Decimal::TEN));
@@ -307,8 +328,9 @@ fn documents_and_aging_are_exact_or_refused() {
     // 62 days past due on June 1st: 61-90.
     assert_eq!(rows[0].days_90, Decimal::TEN);
     assert_eq!(rows[0].total(), Ok(Decimal::TEN));
-    // Two documents of half Decimal's largest each: each is exact, the
-    // party's aging bucket is not.
+    // Two documents of half Decimal's largest each, their totals exact; no
+    // line carries them (no entry could), so they owe nothing and age
+    // nowhere.
     let half = Decimal::MAX / Decimal::TWO;
     for id in [2, 3] {
         l.replay_invoice(
@@ -317,40 +339,44 @@ fn documents_and_aging_are_exact_or_refused() {
             d(2026, 3, 1),
             d(2026, 3, 31),
             vec![line(half)],
-            id,
+            100 + id,
         )
         .unwrap();
         assert_eq!(l.get_invoice(id).unwrap().total(), Ok(half));
+        let st = l.invoice_state(id, d(2026, 6, 1)).unwrap().unwrap();
+        assert_eq!(st.outstanding, Decimal::ZERO);
     }
-    assert!(too_large(l.ar_aging(d(2026, 6, 1))));
+    assert_eq!(
+        l.ar_aging(d(2026, 6, 1)).unwrap()[0].total(),
+        Ok(Decimal::TEN)
+    );
     // Paid more than its total, as journaled: a negative balance, exact.
-    l.replay_invoice_payment(1, Decimal::from(11), 9).unwrap();
+    let p = replayed(&mut l, cash, ar, Decimal::from(11));
+    l.replay_invoice_payment(1, Decimal::from(11), p).unwrap();
     assert_eq!(l.get_invoice(1).unwrap().balance(), Ok(-Decimal::ONE));
-    // A total of lines that overflow, and its balance.
+    let st = l.invoice_state(1, d(2026, 6, 1)).unwrap().unwrap();
+    assert_eq!(
+        (st.paid, st.outstanding),
+        (Decimal::from(11), -Decimal::ONE)
+    );
+    // A payment event naming an amount no line of its entry carries tags
+    // nothing, and is refused nothing (B-28).
+    l.replay_invoice_payment(1, -Decimal::ONE, p).unwrap();
+    assert_eq!(l.get_invoice(1).unwrap().balance(), Ok(-Decimal::ONE));
+    // A total of lines that overflow, and its balance; aging refuses it.
     l.replay_invoice(
         4,
         customer,
         d(2026, 3, 1),
         d(2026, 3, 31),
         vec![line(Decimal::MAX), line(Decimal::MAX)],
-        4,
+        104,
     )
     .unwrap();
     assert!(too_large(l.get_invoice(4).unwrap().total()));
     assert!(too_large(l.get_invoice(4).unwrap().balance()));
-    // A balance past exact arithmetic: a total of Decimal's largest paid
-    // a negative amount.
-    l.replay_invoice(
-        5,
-        customer,
-        d(2026, 3, 1),
-        d(2026, 3, 31),
-        vec![line(Decimal::MAX)],
-        5,
-    )
-    .unwrap();
-    l.replay_invoice_payment(5, -Decimal::ONE, 10).unwrap();
-    assert!(too_large(l.get_invoice(5).unwrap().balance()));
+    assert!(too_large(l.ar_aging(d(2026, 6, 1))));
+    assert!(too_large(l.invoice_state(4, d(2026, 6, 1))));
     // Bills alike.
     let vendor = l.add_vendor("Supplier").unwrap();
     l.replay_bill(
@@ -359,7 +385,7 @@ fn documents_and_aging_are_exact_or_refused() {
         d(2026, 3, 1),
         d(2026, 3, 31),
         vec![line(Decimal::MAX), line(Decimal::ONE)],
-        6,
+        106,
     )
     .unwrap();
     assert!(too_large(l.get_bill(1).unwrap().total()));