nx_recon_lib.nx source

1// nx_recon_lib.nx -- F983: GENERAL THREE-WAY RECONCILIATION on the sovereign ledger. 2// 3// nx_trust proves three-way recon for IOLTA specifically. This lifts it to a PRIMITIVE any book can 4// use -- trust, operating, escrow, payroll -- by composing nx_ledger instead of re-deriving it. 5// 6// THE THREE LEGS (this is the actual accounting definition, not a simplification): 7// leg 1 SUBSIDIARY = sum of the individual sub-account balances (per client / per matter / per fund) 8// leg 2 CONTROL = the general-ledger control account for that book 9// leg 3 BANK = the bank statement balance, ADJUSTED for timing differences: 10// adjusted = statement + deposits_in_transit - outstanding_disbursements 11// A book is reconciled ONLY when all three are EQUAL. Two out of three is not reconciliation. 12// 13// ★FAIL-CLOSED, NEVER ROUNDED (the property that makes this worth having): a variance of ONE CENT is 14// reported as a variance. There is no tolerance band, no "materiality" threshold, no rounding to the 15// nearest dollar. Integer minor units end-to-end, so a difference either is zero or it is not. Auditors 16// and bar examiners do not accept "close enough", and neither does this organ. 17// 18// The variance SIGN is meaningful and preserved: positive = the first leg exceeds the second. 19// 20// SCALE ENVELOPE (declared): rec_subsidiary walks the caller's account list and calls led_balance per 21// account, so it is O(accounts x transfers). Fine for a firm-sized book; a per-account index is the 22// scale rung, same one declared in nx_ledger_lib. 23// license_tier: ORIGINAL No hw writes (Rule 26). LIB (no main). 24 25import "nx_ledger_lib.nx" 26 27const REC_BALANCED: i64 = 0 28const REC_SUB_VS_CTRL: i64 = 1 // leg1 != leg2 29const REC_BOOK_VS_BANK: i64 = 2 // leg2 != leg3(adjusted) 30const REC_BOTH: i64 = 3 // both broken 31 32// leg 1 -- sum the subsidiary sub-account balances. accts = array of *u8 pointers. 33func rec_subsidiary(prefix: *u8, accts: *i64, n: i64) -> i64 { 34 var total: i64 = 0 35 var i: i64 = 0 36 while i < n { 37 total = total + led_balance(prefix, accts[i] as *u8) 38 i = i + 1 39 } 40 return total 41} 42 43// leg 3 -- the bank statement adjusted for timing differences that have not yet cleared. 44// deposits_in_transit : recorded on our books, not yet on the statement -> ADD 45// outstanding_disburse : recorded on our books, not yet cleared the bank -> SUBTRACT 46func rec_adjusted_bank(statement: i64, deposits_in_transit: i64, outstanding_disburse: i64) -> i64 { 47 return statement + deposits_in_transit - outstanding_disburse 48} 49 50// THE RECONCILIATION. Writes the full picture to out[] so a caller can render a real worksheet: 51// out[0] = leg1 subsidiary out[1] = leg2 control out[2] = leg3 adjusted bank 52// out[3] = variance leg1-leg2 out[4] = variance leg2-leg3 53// Returns REC_BALANCED (0) only when BOTH variances are exactly zero; else a bitwise reason code. 54func rec_three_way(prefix: *u8, accts: *i64, n: i64, control: *u8, 55 statement: i64, deposits_in_transit: i64, outstanding_disburse: i64, 56 out: *i64) -> i64 { 57 let leg1: i64 = rec_subsidiary(prefix, accts, n) 58 let leg2: i64 = led_balance(prefix, control) 59 let leg3: i64 = rec_adjusted_bank(statement, deposits_in_transit, outstanding_disburse) 60 out[0] = leg1 61 out[1] = leg2 62 out[2] = leg3 63 out[3] = leg1 - leg2 64 out[4] = leg2 - leg3 65 var code: i64 = REC_BALANCED 66 if out[3] != 0 { code = code + REC_SUB_VS_CTRL } 67 if out[4] != 0 { code = code + REC_BOOK_VS_BANK } 68 return code 69} 70 71// 1 only if fully reconciled. No tolerance band by construction. 72func rec_is_balanced(prefix: *u8, accts: *i64, n: i64, control: *u8, 73 statement: i64, deposits_in_transit: i64, outstanding_disburse: i64) -> i64 { 74 let out: *i64 = sys_mmap(8 * 8) as *i64 75 if rec_three_way(prefix, accts, n, control, statement, deposits_in_transit, outstanding_disburse, out) == REC_BALANCED { return 1 } 76 return 0 77}