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-store/tests/store.rs

@@ -1006,6 +1006,12 @@ mod refusals {
         Bill(u64, u32, u32, i64),
         ReceivePayment(u64, u32, i64, u64),
         PayBill(u64, u32, i64, u64),
+        /// A payment with its method and reference (plan P4b S1): an
+        /// invoice's (true) or a bill's, id, day, cents, account, payment
+        /// method (maybe unknown), reference (none, a good one, two lines).
+        PayWith(bool, u64, u32, i64, u64, Option<u64>, u8),
+        /// Void an invoice (true) or a bill: id, day, reason (good, blank).
+        Void(bool, u64, u32, bool),
         AddClass(u8),
         SetLineClass(u64, usize, Option<u32>),
         SetEntryVendor(u64, Option<u64>),
@@ -1101,6 +1107,18 @@ mod refusals {
                 .prop_map(|(i, d, a, c)| Op::ReceivePayment(i, d, a, c)),
             (0u64..4, 0u32..120, arb_cents(), 0u64..10)
                 .prop_map(|(b, d, a, c)| Op::PayBill(b, d, a, c)),
+            (
+                any::<bool>(),
+                0u64..4,
+                0u32..120,
+                arb_cents(),
+                0u64..10,
+                prop::option::of(0u64..4),
+                0u8..3
+            )
+                .prop_map(|(k, i, d, a, c, m, r)| Op::PayWith(k, i, d, a, c, m, r)),
+            (any::<bool>(), 0u64..4, 0u32..120, any::<bool>())
+                .prop_map(|(k, i, d, r)| Op::Void(k, i, d, r)),
             (0u8..3).prop_map(Op::AddClass),
             (id.clone(), 0usize..4, prop::option::of(0u32..4))
                 .prop_map(|(e, i, c)| Op::SetLineClass(e, i, c)),
@@ -1286,6 +1304,32 @@ mod refusals {
                 .receive_payment(i, day(d), Decimal::new(a, 2), c)
                 .map(drop),
             Op::PayBill(b, d, a, c) => store.pay_bill(b, day(d), Decimal::new(a, 2), c).map(drop),
+            Op::PayWith(invoice, i, d, a, c, m, r) => {
+                let details = ledger_core::PaymentDetails {
+                    instrument: m,
+                    reference: [None, Some("ch_3Nx 0042"), Some("two\nlines")][r as usize]
+                        .map(str::to_string),
+                };
+                if invoice {
+                    store
+                        .receive_payment_with(i, day(d), Decimal::new(a, 2), c, &details)
+                        .map(drop)
+                } else {
+                    store
+                        .pay_bill_with(i, day(d), Decimal::new(a, 2), c, &details)
+                        .map(drop)
+                }
+            }
+            Op::Void(invoice, i, d, reason) => {
+                let doc = if invoice {
+                    ledger_core::DocRef::Invoice(i)
+                } else {
+                    ledger_core::DocRef::Bill(i)
+                };
+                store
+                    .void_document(doc, day(d), if reason { "duplicate" } else { " " })
+                    .map(drop)
+            }
             Op::AddClass(n) => store.add_class(["A", "B", ""][n as usize]).map(drop),
             Op::SetLineClass(e, i, c) => store.set_line_class(e, i, c),
             Op::SetEntryVendor(e, v) => store.set_entry_vendor(e, v),
@@ -2762,8 +2806,10 @@ fn searching_entries_filters_and_pages() {
     );
 }
 
-/// The database's invoice row follows its payments: amount paid and
-/// open / partial / paid, matching the ledger.
+/// The database's invoice row keeps no figure of its own (schema 15,
+/// rules.md B-38): what it has been paid is the ledger's, read from the
+/// lines tagged with it, so a reversed payment no longer counts; the row
+/// is the same before and after each payment, and verify agrees.
 #[test]
 fn the_database_tracks_what_an_invoice_has_been_paid() {
     use ledger_core::arap::DocumentLine;
@@ -2784,24 +2830,37 @@ fn the_database_tracks_what_an_invoice_has_been_paid() {
             }],
         )
         .unwrap();
-    let row = |dir: &std::path::Path| -> (String, String) {
+    let row = |dir: &std::path::Path| -> String {
         let conn = rusqlite::Connection::open(dir.join(ledger_store::db_file())).unwrap();
-        conn.query_row(
-            "SELECT amount_paid, status FROM invoices WHERE id = ?",
-            [inv as i64],
-            |r| Ok((r.get(0)?, r.get(1)?)),
-        )
+        conn.query_row("SELECT * FROM invoices WHERE id = ?", [inv as i64], |r| {
+            Ok(format!(
+                "{:?}",
+                (0..6)
+                    .map(|i| r.get_ref(i).map(|v| format!("{v:?}")))
+                    .collect::<Vec<_>>()
+            ))
+        })
         .unwrap()
     };
-    assert_eq!(row(&dir).1, "open");
-    store
+    let before = row(&dir);
+    let paid = |s: &Store| {
+        s.ledger()
+            .invoice_state(inv, day(31))
+            .unwrap()
+            .unwrap()
+            .paid
+    };
+    let p = store
         .receive_payment(inv, day(10), Decimal::from(40), cash)
         .unwrap();
-    assert_eq!(row(&dir), ("40".into(), "partial".into()));
+    assert_eq!(paid(&store), Decimal::from(40));
+    store.reverse_entry(p, day(12), "Bounced").unwrap();
+    assert_eq!(paid(&store), Decimal::ZERO);
     store
         .receive_payment(inv, day(20), Decimal::from(60), cash)
         .unwrap();
-    assert_eq!(row(&dir), ("100".into(), "paid".into()));
+    assert_eq!(paid(&store), Decimal::from(60));
+    assert_eq!(row(&dir), before, "the row holds no figure");
     store.verify().unwrap();
 }