swaits/wanderbooks
1
0 Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

P3: party totals by what moved the money, once (defects 14, 11, 24)

Browse Source 
Each party's part of an entry is signed as its own account would show it,
with a direction and its cash and in-kind amounts; a reversal is its
original negated. Totals on a cash or all basis: for a member, all equals
the members' equity statement and cash the K-1's cash. Money is cash,
cards and the financing accounts, and a liability credit never pays its
own creditor (creditor_of), so accruals and declared distributions count
once. tin_last4 from the TIN or W-9 facts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T3gXMVt7XJPi6ens1or9Dj
This commit is contained in:
swaitsandClaude Opus 5.5 committed 2026-10-21 12:12:26 -06:00
1 parent 9ab003d0d1
commit c2ceabbae9
52 files changed
+7535 -560
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

crates/ledger-core/src/shares.rs
+308 -52
View File
@@ -9,22 +9,58 @@
//! itself ([`Share::Derived`]).
//!
//! ```text
//! GOAL: "what did we pay each of them?" right when one entry was with
//! several parties, with apportioning the human controls exactly.
//! GOAL: "what did we pay each of them, and what did we get from each?"
//! right when one entry was with several parties, with apportioning
//! the human controls exactly, every part signed as the party's own
//! account would show it, and a reversal always the opposite of what
//! it reverses.
//! SOURCE: DECISION (owner, 2026-10-15): no "joint" party; a joint
//! transaction is with both members, each with their share, and
//! shares can be apportioned explicitly ("do you allow for
//! controlled apportioning?" Yes). docs/parties-and-attachments.md
//! "Shares".
//! "Shares". rules.md B-35 (the sign, direction and money of a
//! part; DECISION, owner, 2026-10-20: a member's entry counts what
//! moved their capital).
//! DEFINITIONS:
//! flow: crate::parties::entry_flow(entry, money).
//! target: flow.net when it is not zero, else the entry's total debits
//! (a member contributing property moves no money but is still all
//! theirs). magnitude = |target|; sign = the sign of target (positive
//! when net is zero).
//! A member: a PartyMember (party, income share, capital account,
//! distributions account), passed in by the caller from the company's
//! settings ([[company.members]]); core doesn't read the settings.
//! target (target(), rules.md B-35 item 3): what the shares split,
//! signed debit-positive as a line on the parties' own account would
//! be (positive: the company paid or gave; negative: it received),
//! with its direction (paid, received, neither) and what of it moved
//! as money (cash) and as property (in_kind), in this order of cases:
//! 1. A period's closing entry: the parties' own-account movement (the
//! members' equity, when every party named is a member), else its
//! total debits; neither: a close moves nothing with anyone.
//! 2. A reversal: its original's target negated, paid and received
//! swapped (kernel::reverse_target), from its root original down;
//! never read from its own lines (parties::entry_flow isn't odd
//! for one liability paying down another).
//! 3. Every party named has the member role in the directory and the
//! entry moves equity other than retained earnings (E): E, received
//! when a contribution (E < 0), paid when a distribution (E > 0).
//! Of a contribution, in_kind is the property it brought in (asset
//! accounts neither cash nor receivables: the K-1 worksheet's test,
//! k1 INVARIANT 3), at most |E|, and cash the rest (what the K-1
//! counts as cash: money, or what a member paid for the company).
//! Of a distribution, cash is the money it paid (case 4's net, at
//! most E) and in_kind the property it gave up, at most what is
//! left; the rest, credited to a liability that isn't money for the
//! entry (distributions payable, or what the members are owed when
//! they are named its creditors), is still owed and counts as
//! nothing until it is paid (kernel::party_target INVARIANT 2).
//! 4. Money moved (parties::entry_flow net, a liability owed to a
//! party named not counted as money: MoneyAccounts::for_parties):
//! the net, paid (+) or received (−), all of it cash.
//! 5. Otherwise the movement of the parties' own accounts (payables,
//! receivables, liabilities owed to a party named: a bill −, an
//! invoice +, a fee on the issuer's own card −), else the total
//! debits; neither.
//! magnitude = |target.amount|.
//! A member (PartyMember): a party, income share, capital account,
//! distributions account, passed in by the caller from the company's
//! settings ([[company.members]]); core doesn't read the settings. Only
//! a derived split among several members reads them (INVARIANT 10),
//! and the server journals that split as amounts once the entry is
//! posted, so posted history never depends on today's settings.
//! INVARIANTS (of an entry's shares, checked by check_shares, journaled):
//! 1. No party appears twice; every party is in the directory.
//! 2. All shares are one kind: all Amount, all Percent, or all Derived.
@@ -33,14 +69,16 @@
//! 100.
//! 5. At most one party has a vendor record: a 1099 counts a payment
//! toward a single vendor.
//! INVARIANTS (of resolve, against the entry's lines and the members):
//! 6. Resolved amounts sum to target exactly, and each has target's sign.
//! INVARIANTS (of split and resolve, against the entry's lines, the
//! target and the members):
//! 6. The parts sum to target.amount exactly, and each has its sign (a
//! zero part is a plain zero, never "-0").
//! 7. Amount: each party gets sign × its amount; refused unless the
//! amounts sum to magnitude.
//! 8. Percent: each party gets magnitude × percent / 100 rounded toward
//! zero to the cent; the cents left over (fewer than one per party)
//! go to the first party in order. Then the sign.
//! 9. Derived, one party: it gets target.
//! 9. Derived, one party: it gets target.amount.
//! 10. Derived, several parties: every one must be a member (else
//! refused: give amounts or percents). If the entry has a line on any
//! named member's capital or distributions account, each member gets
@@ -48,21 +86,49 @@
//! to magnitude (else refused). Otherwise each gets their income share
//! of magnitude, the shares rescaled to the members named, rounded as
//! in 8 (remainder to the first).
//! 11. A reversal's parts are its original's negated: its target is the
//! original's negated, and its lines are the original's with every
//! side flipped (Ledger::reverse_entry), so every magnitude above is
//! the same.
//! 12. Each part's cash and in_kind have its sign, |cash| + |in_kind| ≤
//! |part|, and over the parts they sum to the target's cash and
//! in_kind exactly: in_kind is shared by each part's size, cash by
//! what is left of each (k1's share_property: in proportion, to the
//! cent, leftover cents by largest remainder, ties to the party
//! listed first in the company's members), so a member's in-kind part
//! of a joint contribution is the property the K-1 worksheet counts
//! for them.
//! SCENARIOS:
//! 1. Reimbursing both members $100.00 (Dr 2100 / Cr 1000), both named,
//! derived, 50/50: $50.00 each.
//! derived, 50/50: $50.00 each, paid, cash.
//! 2. A joint contribution (Dr 1000 300 / Cr 3000 200 / Cr 3001 100):
//! derived from the capital lines, Tobin −200.00, Morgan −100.00
//! (received).
//! derived from the capital lines, Tobin −200.00, Morgan −100.00,
//! received, cash.
//! 3. A property contribution (Dr Equipment 1000 / Cr 3000 500 / Cr 3001
//! 500): net is zero; target is the total, 500.00 each.
//! 500): −500.00 each, received, in kind; its reversal +500.00 each,
//! paid, in kind.
//! 4. $100.00 split 1/3 each three ways by percent 33.33, 33.33, 33.34:
//! 33.33, 33.33, 33.34. By 33.333/33.333/33.334: 33.34, 33.33, 33.33
//! (the leftover cent to the first).
//! 5. Amounts of $60.00 and $30.00 on a $100.00 payment: refused.
//! 6. A bill for $80.00 tagged with its vendor (Dr expense / Cr
//! payables): −80.00, neither; its reversal +80.00, neither.
//! 7. A joint contribution of cash and property (Dr 1000 600, Dr 1500
//! 400 / Cr 3000 500, Cr 3001 500): −500.00 each, received, of it
//! −300.00 cash and −200.00 in kind (the K-1 worksheet's SCENARIO 3).
//! 8. A distribution declared to one member (Dr 3000 200 / Cr
//! Distributions Payable 200): +200.00, neither, nothing counted; its
//! payment (Dr Distributions Payable 200 / Cr 1000 200) is the 200.00
//! paid, once.
//! 9. Equipment carried at 1,000 less 300 depreciated, and 100 in cash,
//! distributed to one member (Dr 3000 800, Dr accumulated
//! depreciation 300 / Cr equipment 1000, Cr 1000 100): +800.00, paid,
//! of it 100.00 cash and 700.00 in kind.
//! ```
use crate::{AccountId, JournalEntry, PartyId, Side};
pub use crate::kernel::Direction;
use crate::kernel::{self, PartyTarget};
use crate::{AccountId, AccountType, EntryId, JournalEntry, Ledger, LedgerError, PartyId, Side};
use rust_decimal::Decimal;
use serde::{Deserialize, Serialize};
@@ -202,28 +268,6 @@ pub fn check_shares_journaled(
Ok(())
}
/// What the shares are split over: the entry's flow net, else its total
/// debits (the module's DEFINITIONS).
/// Refused (TooLargeToCompute), never a panic, when a sum is past exact
/// arithmetic: a draft's lines and an entry's shares are as journaled, of
/// any size (rules.md B-28).
pub fn share_target(
entry: &JournalEntry,
money: &crate::parties::MoneyAccounts,
) -> Result<Decimal, crate::LedgerError> {
let net = crate::parties::entry_flow(entry, money)?.net;
if net.is_zero() {
entry
.lines()
.iter()
.filter(|l| l.side == Side::Debit)
.try_fold(Decimal::ZERO, |s, l| s.checked_add(l.amount.amount))
.ok_or_else(|| too_large(format!("entry {}'s debits", entry.id())))
} else {
Ok(net)
}
}
/// The refusal of a sum past exact arithmetic.
fn too_large(what: String) -> crate::LedgerError {
crate::LedgerError::TooLargeToCompute(what)
@@ -259,23 +303,182 @@ fn split_first(magnitude: Decimal, weights: &[Decimal]) -> Option<Vec<Decimal>>
Some(parts)
}
/// Each party's exact part of what `entry` moved (the module's INVARIANTS
/// 6–10), in the shares' order. Refused, with why, when the shares can't
/// resolve against these lines and members.
pub fn resolve(
/// What an entry's shares split, and what of it counts (the module's
/// DEFINITIONS: target; rules.md B-35).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Target {
/// The whole, signed debit-positive as a line on the parties' own
/// account would be.
pub amount: Decimal,
/// Which way value moved with the parties.
pub direction: Direction,
/// What of `amount` moved as money: counted on both bases.
pub cash: Decimal,
/// What of `amount` moved as property: counted on basis "all".
pub in_kind: Decimal,
/// Which side the parts count on in a party's totals: the direction
/// of the entry's root original (itself, unless it is a reversal), so
/// a reversal nets what it reverses (B-35 item 4).
pub counts_as: Direction,
}
/// One party's part of an entry (the module's INVARIANTS 6-12).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Part {
/// The party.
pub party: PartyId,
/// Its part of the target, with the target's sign.
pub amount: Decimal,
/// What of it moved as money.
pub cash: Decimal,
/// What of it moved as property.
pub in_kind: Decimal,
}
/// An entry's target and each party's part of it ([`resolve`]).
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Resolved {
/// What the shares split.
pub target: Target,
/// Each party's part, in the shares' order.
pub parts: Vec<Part>,
}
impl Resolved {
/// The part of `party`, when the entry names it.
pub fn part(&self, party: PartyId) -> Option<&Part> {
self.parts.iter().find(|p| p.party == party)
}
}
/// What entry `id`'s shares split (the module's DEFINITIONS: target).
/// `shares` are passed, not read from the ledger, so a proposed set can be
/// checked; they cover the whole reversal chain (Ledger::set_entry_parties
/// INVARIANT 5). Refused (TooLargeToCompute), never a panic, when a sum is
/// past exact arithmetic: a draft's lines are as journaled, of any size
/// (rules.md B-28).
pub fn target(
ledger: &Ledger,
id: EntryId,
shares: &[PartyShare],
money: &crate::parties::MoneyAccounts,
) -> Result<Target, LedgerError> {
let entry = ledger.get_entry(id).ok_or(LedgerError::UnknownEntry(id))?;
let (root, depth) = crate::parties::root_original(ledger, entry);
let base = original_target(ledger, root, shares, money)?;
let t = if depth % 2 == 1 {
kernel::reverse_target(base)
.ok_or_else(|| too_large(format!("entry {id}'s reversal target")))?
} else {
base
};
Ok(Target {
amount: t.amount,
direction: t.direction,
cash: t.cash,
in_kind: t.in_kind,
counts_as: base.direction,
})
}
/// The target of an entry that reverses none (the module's DEFINITIONS:
/// target, cases 1 and 3-5).
fn original_target(
ledger: &Ledger,
entry: &JournalEntry,
shares: &[PartyShare],
money: &crate::parties::MoneyAccounts,
) -> Result<PartyTarget<Decimal>, LedgerError> {
let past_exact = || too_large(format!("entry {}'s target", entry.id()));
let named: Vec<PartyId> = shares.iter().map(|s| s.party).collect();
let money = money.for_parties(ledger, &named);
let parties: Vec<&crate::Party> = named.iter().filter_map(|p| ledger.get_party(*p)).collect();
let members_only = !named.is_empty()
&& parties.len() == named.len()
&& parties
.iter()
.all(|p| p.roles.contains(&crate::Role::Member));
let owed = |a: AccountId| parties.iter().any(|p| p.creditor_of.contains(&a));
let retained = ledger.role_account(&crate::RETAINED_EARNINGS);
let receivables = ledger.role_account(&crate::RECEIVABLES);
let payables = ledger.role_account(&crate::PAYABLES);
let kind = |a: AccountId| ledger.chart().get(a).map(|x| x.account_type);
// Property: the K-1 worksheet's test (k1 INVARIANT 3).
let property = |a: AccountId| {
kind(a) == Some(AccountType::Asset) && !money.cash.contains(&a) && Some(a) != receivables
};
let add = |t: &mut Decimal, v: Decimal| -> Result<(), LedgerError> {
*t = t.checked_add(v).ok_or_else(past_exact)?;
Ok(())
};
let zero = Decimal::ZERO;
let (mut equity, mut prop_in, mut prop_out, mut own, mut debits) =
(zero, zero, zero, zero, zero);
for l in entry.lines() {
let v = l.amount.amount;
let signed = kernel::signed(l.side, v).ok_or_else(past_exact)?;
let k = kind(l.account);
if k == Some(AccountType::Equity) && Some(l.account) != retained {
add(&mut equity, signed)?;
}
if property(l.account) {
match l.side {
Side::Debit => add(&mut prop_in, v)?,
Side::Credit => add(&mut prop_out, v)?,
}
}
let theirs = k == Some(AccountType::Liability) && owed(l.account);
if theirs || Some(l.account) == payables || Some(l.account) == receivables {
add(&mut own, signed)?;
}
if l.side == Side::Debit {
add(&mut debits, v)?;
}
}
let property = if equity < zero { prop_in } else { prop_out };
let capital = members_only.then_some((equity, property));
if ledger.is_closing_entry(entry.id()) {
let t = kernel::party_target(capital, zero, own, debits).ok_or_else(past_exact)?;
return Ok(PartyTarget {
amount: t.amount,
direction: Direction::Neither,
cash: zero,
in_kind: zero,
});
}
let net = crate::parties::entry_flow(entry, &money)?.net;
kernel::party_target(capital, net, own, debits).ok_or_else(past_exact)
}
/// Split `whole` (at most the sum of `sizes`) over `sizes` in proportion,
/// to the cent, leftover cents by largest remainder (k1's
/// share_property), ties to the earlier in `order` (each part's rank).
/// None past exact arithmetic.
fn share_by(whole: Decimal, sizes: &[Decimal], order: &[usize]) -> Option<Vec<Decimal>> {
let ranked: Vec<Decimal> = order.iter().map(|&i| sizes[i]).collect();
let shared = crate::k1::share_property(whole, &ranked, 2).ok()?;
let mut out = vec![Decimal::ZERO; sizes.len()];
for (k, &i) in order.iter().enumerate() {
out[i] = shared[k];
}
Some(out)
}
/// Each party's part of `target` (the module's INVARIANTS 6-12), in the
/// shares' order. Refused, with why, when the shares can't resolve against
/// these lines and members.
pub fn split(
entry: &JournalEntry,
shares: &[PartyShare],
target: &Target,
members: &[PartyMember],
) -> Result<Vec<(PartyId, Decimal)>, String> {
let target = share_target(entry, money).map_err(|e| e.to_string())?;
) -> Result<Vec<Part>, String> {
let past_exact = || too_large(format!("entry {}'s shares", entry.id())).to_string();
let magnitude = target.abs();
let signed = |v: Decimal| if target.is_sign_negative() { -v } else { v };
let magnitude = target.amount.abs();
let Some(first) = shares.first() else {
return Ok(Vec::new());
};
let parts: Vec<Decimal> = match first.share {
let sizes: Vec<Decimal> = match first.share {
Share::Amount(_) => {
let amounts: Vec<Decimal> = shares
.iter()
@@ -355,9 +558,62 @@ pub fn resolve(
}
}
};
// Ties go to the party listed first in the company's members, as on
// the K-1 worksheet; other parties after them, in the shares' order.
let mut order: Vec<usize> = (0..shares.len()).collect();
order.sort_by_key(|&i| {
members
.iter()
.position(|m| m.party == shares[i].party)
.unwrap_or(members.len() + i)
});
let (cash, in_kind) = (target.cash.abs(), target.in_kind.abs());
let in_kind_sizes = if in_kind.is_zero() {
vec![Decimal::ZERO; sizes.len()]
} else {
share_by(in_kind, &sizes, &order).ok_or_else(past_exact)?
};
let left: Vec<Decimal> = sizes
.iter()
.zip(&in_kind_sizes)
.map(|(s, k)| s.checked_sub(*k))
.collect::<Option<_>>()
.ok_or_else(past_exact)?;
let cash_sizes = if cash == checked_sum(left.iter().copied()).ok_or_else(past_exact)? {
left
} else if cash.is_zero() {
vec![Decimal::ZERO; sizes.len()]
} else {
share_by(cash, &left, &order).ok_or_else(past_exact)?
};
let negative = target.amount < Decimal::ZERO;
let signed = |v: Decimal| if negative && !v.is_zero() { -v } else { v };
Ok(shares
.iter()
.zip(parts)
.map(|(s, v)| (s.party, signed(v)))
.enumerate()
.map(|(i, s)| Part {
party: s.party,
amount: signed(sizes[i]),
cash: signed(cash_sizes[i]),
in_kind: signed(in_kind_sizes[i]),
})
.collect())
}
/// Entry `id`'s target and each party's exact part of it (the module's
/// INVARIANTS 6-12), in the shares' order. Refused, with why, when the
/// shares can't resolve against these lines and members.
pub fn resolve(
ledger: &Ledger,
id: EntryId,
shares: &[PartyShare],
money: &crate::parties::MoneyAccounts,
members: &[PartyMember],
) -> Result<Resolved, String> {
let entry = ledger
.get_entry(id)
.ok_or_else(|| LedgerError::UnknownEntry(id).to_string())?;
let target = target(ledger, id, shares, money).map_err(|e| e.to_string())?;
let parts = split(entry, shares, &target, members)?;
Ok(Resolved { target, parts })
}