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/src/proofs.rs

@@ -1807,6 +1807,91 @@ fn unrecovered_cost_laws() {
     kani::cover!(u == 0 && revenue > expenses, "repaid, and more");
 }
 
+/// `kernel::running_bounds` (rules.md B-38 INVARIANT 2; the bounds every
+/// document command and reversal checks), for every total and every
+/// sequence of up to `N` dated movements a line could carry: it says
+/// Within exactly when every running balance is in `0 ..= total`, and
+/// otherwise names the first one that isn't, and which way it left.
+#[kani::proof]
+#[kani::unwind(6)]
+fn bounds_check_matches_definition() {
+    let total = any_amount();
+    kani::assume(total > 0);
+    let deltas: [i64; N] = core::array::from_fn(|_| any_amount());
+    let n = any_len();
+    let got = kernel::running_bounds(total, &deltas[..n]);
+    // The definition, in wide arithmetic: amounts are at most 2^40 and at
+    // most N are summed, so no prefix overflows (got is never Overflow).
+    let mut running = 0i64;
+    let mut first: Option<(usize, bool)> = None;
+    for (i, &d) in deltas[..n].iter().enumerate() {
+        running += d;
+        if first.is_none() && (running < 0 || running > total) {
+            first = Some((i, running < 0));
+        }
+    }
+    match first {
+        None => assert_eq!(got, kernel::Bounds::Within),
+        Some((i, true)) => assert_eq!(got, kernel::Bounds::Below(i)),
+        Some((i, false)) => assert_eq!(got, kernel::Bounds::Above(i)),
+    }
+    kani::cover!(
+        got == kernel::Bounds::Within && n == N,
+        "a whole history in bounds"
+    );
+    kani::cover!(matches!(got, kernel::Bounds::Below(_)), "overpaid");
+    kani::cover!(
+        matches!(got, kernel::Bounds::Above(_)),
+        "owes more than its total"
+    );
+}
+
+/// `kernel::bounds_kept` (the check every document command and reversal
+/// runs, rules.md B-38 INVARIANT 2): on books in bounds at every date it
+/// is the definition (`running_bounds` of the books after the step); and
+/// whenever it says Within, no running balance after the step is further
+/// outside `0 ..= total` than before it, so a step that mends books an
+/// earlier version left out of bounds is taken and none makes them worse.
+#[kani::proof]
+#[kani::unwind(6)]
+fn bounds_kept_is_the_definition_on_books_in_bounds() {
+    let total = any_amount();
+    kani::assume(total > 0);
+    let before: [i64; N] = core::array::from_fn(|_| any_amount());
+    let after: [i64; N] = core::array::from_fn(|_| any_amount());
+    let n = any_len();
+    let got = kernel::bounds_kept(total, &before[..n], &after[..n]);
+    let out = |r: i64| {
+        if r < 0 {
+            -r
+        } else if r > total {
+            r - total
+        } else {
+            0
+        }
+    };
+    let was_within = kernel::running_bounds(total, &before[..n]) == kernel::Bounds::Within;
+    if was_within {
+        assert_eq!(got, kernel::running_bounds(total, &after[..n]));
+    }
+    if got == kernel::Bounds::Within {
+        let (mut was, mut now) = (0i64, 0i64);
+        for i in 0..n {
+            was += before[i];
+            now += after[i];
+            assert!(out(now) <= out(was));
+        }
+    }
+    kani::cover!(
+        got == kernel::Bounds::Within && !was_within,
+        "a step that mends out-of-bounds books"
+    );
+    kani::cover!(
+        matches!(got, kernel::Bounds::Below(_)),
+        "a step that overpays"
+    );
+}
+
 // ---------------------------------------------------------------------------
 // The checker itself
 // ---------------------------------------------------------------------------