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/invariants.rs

@@ -32,11 +32,17 @@ fn usd(amount: u64) -> Money {
 /// Post a balanced entry in one call. Panics on programmer error: fixtures
 /// must be valid by construction.
 fn post(ledger: &mut Ledger, date: NaiveDate, description: &str, lines: &[(AccountId, Side, u64)]) {
-    let id = ledger.create_entry(date, description);
-    for (account, side, amount) in lines {
-        ledger.add_line(id, *account, *side, usd(*amount)).unwrap();
-    }
-    ledger.post_entry(id).unwrap();
+    // As replay posts it: these books hold hand lines on receivables or
+    // payables (1200, 2000), which books an earlier version wrote still
+    // hold and every report must read; the control guard (rules.md B-38)
+    // refuses them as new work.
+    ledger_core::parties::replaying(|| {
+        let id = ledger.create_entry(date, description);
+        for (account, side, amount) in lines {
+            ledger.add_line(id, *account, *side, usd(*amount)).unwrap();
+        }
+        ledger.post_entry(id).unwrap();
+    })
 }
 
 struct Company {
@@ -649,21 +655,26 @@ fn random_balanced_journals_preserve_invariants() {
         c.rent,
     ];
 
-    for i in 0..300u32 {
-        let total = rng.next(100_000) + 100;
-        let nd = (rng.next(3) + 1) as usize;
-        let nc = (rng.next(3) + 1) as usize;
-        let id = ledger.create_entry(date(21), &format!("random {i}"));
-        for part in split_total(&mut rng, total, nd) {
-            let acct = accounts[rng.next(accounts.len() as u64) as usize];
-            ledger.add_line(id, acct, Side::Debit, usd(part)).unwrap();
+    // As replay posts them: random lines land on receivables and
+    // payables by hand, as books an earlier version wrote can hold them
+    // (the control guard, rules.md B-38, refuses them as new work).
+    ledger_core::parties::replaying(|| {
+        for i in 0..300u32 {
+            let total = rng.next(100_000) + 100;
+            let nd = (rng.next(3) + 1) as usize;
+            let nc = (rng.next(3) + 1) as usize;
+            let id = ledger.create_entry(date(21), &format!("random {i}"));
+            for part in split_total(&mut rng, total, nd) {
+                let acct = accounts[rng.next(accounts.len() as u64) as usize];
+                ledger.add_line(id, acct, Side::Debit, usd(part)).unwrap();
+            }
+            for part in split_total(&mut rng, total, nc) {
+                let acct = accounts[rng.next(accounts.len() as u64) as usize];
+                ledger.add_line(id, acct, Side::Credit, usd(part)).unwrap();
+            }
+            ledger.post_entry(id).unwrap();
         }
-        for part in split_total(&mut rng, total, nc) {
-            let acct = accounts[rng.next(accounts.len() as u64) as usize];
-            ledger.add_line(id, acct, Side::Credit, usd(part)).unwrap();
-        }
-        ledger.post_entry(id).unwrap();
-    }
+    });
 
     // Every invariant still holds after 300 random balanced entries.
     let tb = trial_balance(&ledger);
@@ -1484,27 +1495,61 @@ fn a_period_ending_inside_a_closed_period_cannot_close() {
 }
 
 /// Replay (for journaling stores) rebuilds invoice and bill records
-/// exactly: ids follow the allocator, payments accumulate, vendors tag
-/// the entries. A record replayed out of order is refused.
+/// exactly: ids follow the allocator, each record tags its entry's control
+/// line and each payment its entry's (rules.md B-38), vendors tag the
+/// entries. A record replayed out of order is refused.
 #[test]
 fn replayed_documents_and_payments_rebuild_the_records() {
     use ledger_core::DocumentStatus;
     let mut l = books_with("2000", "Accounts Payable", AccountType::Liability, false);
+    let cash = l.chart().find_by_code("1000").unwrap().id;
+    let ap = l.chart().find_by_code("2000").unwrap().id;
+    let ar = l
+        .add_account(
+            "1200",
+            "Accounts Receivable",
+            AccountType::Asset,
+            None,
+            false,
+        )
+        .unwrap();
+    let revenue = l
+        .add_account("4000", "Revenue", AccountType::Revenue, None, false)
+        .unwrap();
+    let expense = l
+        .add_account(
+            "6999",
+            "General Expenses",
+            AccountType::Expense,
+            None,
+            false,
+        )
+        .unwrap();
+    // An entry as replay rebuilds it from its own events.
+    let entry = |l: &mut Ledger, dr, cr, n: u64| {
+        let e = l.create_entry(date(5), "replayed");
+        l.replay_add_line(e, dr, Side::Debit, usd(n)).unwrap();
+        l.replay_add_line(e, cr, Side::Credit, usd(n)).unwrap();
+        l.replay_post_entry(e).unwrap();
+        e
+    };
     let c = l.add_customer("Acme").unwrap();
     let v = l.add_vendor("Vend").unwrap();
 
     let inv = l.next_invoice_id();
+    let e = entry(&mut l, ar, revenue, 100);
     assert_eq!(
-        l.replay_invoice(inv + 1, c, date(5), date(30), doc(100), 10),
+        l.replay_invoice(inv + 1, c, date(5), date(30), doc(100), e),
         Err(LedgerError::ReplayIdMismatch(inv + 1, inv))
     );
-    l.replay_invoice(inv, c, date(5), date(30), doc(100), 10)
+    l.replay_invoice(inv, c, date(5), date(30), doc(100), e)
         .unwrap();
     // Each later record replays at the id the allocator now predicts.
     let mut ids = vec![inv];
-    for entry in [13, 14] {
+    for _ in 0..2 {
         let next = l.next_invoice_id();
-        l.replay_invoice(next, c, date(5), date(30), doc(1), entry)
+        let e = entry(&mut l, ar, revenue, 1);
+        l.replay_invoice(next, c, date(5), date(30), doc(1), e)
             .unwrap();
         ids.push(next);
     }
@@ -1512,38 +1557,52 @@ fn replayed_documents_and_payments_rebuild_the_records() {
     ids.dedup();
     assert_eq!(ids.len(), 3);
     assert!(ids.iter().all(|&i| l.get_invoice(i).is_some()));
-    l.replay_invoice_payment(inv, Decimal::from(30), 11)
-        .unwrap();
-    l.replay_invoice_payment(inv, Decimal::from(20), 12)
-        .unwrap();
+    for n in [30, 20] {
+        let p = entry(&mut l, cash, ar, n);
+        l.replay_invoice_payment(inv, Decimal::from(n), p).unwrap();
+        assert_eq!(
+            l.line_doc(p, 1).map(|t| t.doc),
+            Some(ledger_core::DocRef::Invoice(inv))
+        );
+    }
     let i = l.get_invoice(inv).unwrap();
     assert_eq!(i.amount_paid, Decimal::from(50));
     assert_eq!(i.balance().unwrap(), Decimal::from(50));
     assert_eq!(i.status, DocumentStatus::Partial);
+    let st = l.invoice_state(inv, date(31)).unwrap().unwrap();
+    assert_eq!(
+        (st.paid, st.outstanding),
+        (Decimal::from(50), Decimal::from(50))
+    );
 
     let bill = l.next_bill_id();
+    let e = entry(&mut l, expense, ap, 100);
     assert_eq!(
-        l.replay_bill(bill + 1, v, date(5), date(30), doc(100), 20),
+        l.replay_bill(bill + 1, v, date(5), date(30), doc(100), e),
         Err(LedgerError::ReplayIdMismatch(bill + 1, bill))
     );
-    assert_eq!(l.entry_vendor(20), None);
-    l.replay_bill(bill, v, date(5), date(30), doc(100), 20)
+    assert_eq!(l.entry_vendor(e), None);
+    l.replay_bill(bill, v, date(5), date(30), doc(100), e)
         .unwrap();
-    assert_eq!(l.entry_vendor(20), Some(v));
+    assert_eq!(l.entry_vendor(e), Some(v));
     let mut ids = vec![bill];
-    for entry in [23, 24] {
+    for _ in 0..2 {
         let next = l.next_bill_id();
-        l.replay_bill(next, v, date(5), date(30), doc(1), entry)
+        let e = entry(&mut l, expense, ap, 1);
+        l.replay_bill(next, v, date(5), date(30), doc(1), e)
             .unwrap();
         ids.push(next);
     }
     ids.sort();
     ids.dedup();
     assert_eq!(ids.len(), 3);
-    l.replay_bill_payment(bill, Decimal::from(30), 21).unwrap();
-    l.replay_bill_payment(bill, Decimal::from(70), 22).unwrap();
+    let mut last = 0;
+    for n in [30, 70] {
+        last = entry(&mut l, ap, cash, n);
+        l.replay_bill_payment(bill, Decimal::from(n), last).unwrap();
+    }
     let b = l.get_bill(bill).unwrap();
     assert_eq!(b.amount_paid, Decimal::from(100));
     assert_eq!(b.status, DocumentStatus::Paid);
-    assert_eq!(l.entry_vendor(22), Some(v));
+    assert_eq!(l.entry_vendor(last), Some(v));
 }