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

@@ -228,9 +228,10 @@ pub enum LedgerError {
         role: String,
     },
 
-    /// A balance sheet role (receivables, payables, withholdings, retained
-    /// earnings) can't move while its account holds a balance: the control
-    /// account must keep agreeing with what it controls.
+    /// A balance sheet role (withholdings, retained earnings) can't move
+    /// while its account holds a balance: the control account must keep
+    /// agreeing with what it controls. Receivables and payables refuse
+    /// with [`Self::DocumentRoleHoldsBalance`] instead.
     #[error(
         "{role} is in account {code} \"{name}\", which holds {balance}; move that balance to the \
          new account with a journal entry first, then assign the role"
@@ -608,6 +609,105 @@ pub enum LedgerError {
     #[error("payment of {0} exceeds remaining balance of {1}")]
     Overpayment(Decimal, Decimal),
 
+    /// A payment's details were refused (its reference): the message says
+    /// why.
+    #[error("{0}")]
+    InvalidPayment(String),
+
+    /// Receivables or payables can't move while their account holds a
+    /// balance (rules.md B-23, B-38): that balance is the documents', and
+    /// a hand entry moving it is refused by the control guard; it moves
+    /// with its documents (plan P4b S7).
+    #[error(
+        "{role} is in account {code} \"{name}\", which holds {balance} owed on its documents; \
+         the role can't move until that is settled (paid or voided) or until moving a balance \
+         with its documents is built: a hand entry to the account is refused"
+    )]
+    DocumentRoleHoldsBalance {
+        /// The role, e.g. "accounts receivable".
+        role: String,
+        /// The code of the account filling it now.
+        code: String,
+        /// That account's name.
+        name: String,
+        /// Its balance.
+        balance: rust_decimal::Decimal,
+    },
+
+    /// Receivables or payables can't move to an account holding lines
+    /// that are no document's (rules.md B-38 INVARIANT 1): they would
+    /// become hand lines on a control account.
+    #[error(
+        "account {code} \"{name}\" holds lines no invoice or bill carries (entry {entry} first), \
+         so it can't take the {role} role: give the role an account of its own"
+    )]
+    RoleAccountHasHandLines {
+        /// The role, e.g. "accounts receivable".
+        role: String,
+        /// The account's code.
+        code: String,
+        /// Its name.
+        name: String,
+        /// The first posted entry with such a line.
+        entry: u64,
+    },
+
+    /// A payment's deposit or payer account must be a postable asset or
+    /// liability that holds no role: a bank, a card, a member's payable
+    /// (plan P4b.3, "Payment accounts").
+    #[error(
+        "account {code} \"{name}\" can't take a payment: {why}; pay into or from a bank or card account (or a member's payable)"
+    )]
+    PaymentAccount {
+        /// The account's code.
+        code: String,
+        /// Its name.
+        name: String,
+        /// Why not, e.g. "it holds the accounts receivable role".
+        why: String,
+    },
+
+    /// A line on a receivables or payables control account carries no
+    /// document (rules.md B-23, B-38): the control account must always
+    /// equal its documents, so only the document commands post there.
+    #[error(
+        "account {account} is a control account (its balance is its invoices or bills): {at} can't be posted there by hand. Use books.create_invoice, books.receive_payment, books.create_bill or books.pay_bill; to void a document, books.reverse_entry of its entry"
+    )]
+    UntaggedControlLine {
+        /// The account's code and name, e.g. `1200 "Accounts Receivable"`.
+        account: String,
+        /// Which line, e.g. "line 1 of entry 14", "line 0 of the
+        /// recurring template".
+        at: String,
+    },
+
+    /// A reversal or payment would leave a document owing less than nothing
+    /// or more than its total at some date (rules.md B-38 INVARIANT 2): the
+    /// message says which document, when, and what to reverse first.
+    #[error("{0}")]
+    DocumentBounds(String),
+
+    /// A reversal of an entry an invoice or bill owns is dated before that
+    /// entry (rules.md B-9, B-38): a correction comes after what it
+    /// corrects.
+    #[error(
+        "entry {entry} belongs to {document} and is dated {original}: its reversal can't be dated before it, on {date}"
+    )]
+    DocumentReversalBeforeOriginal {
+        /// The entry reversed.
+        entry: u64,
+        /// The document, e.g. "invoice 7".
+        document: String,
+        /// The entry's date.
+        original: chrono::NaiveDate,
+        /// The reversal's date.
+        date: chrono::NaiveDate,
+    },
+
+    /// A document can't be voided as asked: the message says why.
+    #[error("{0}")]
+    InvalidVoid(String),
+
     /// Invoice/bill due date is before its date.
     #[error("due date {0} is before document date")]
     DueBeforeDate(String),