cashflow source pure

1const MaxAccounts = periods.MaxAccounts

1const MaxEntries = periods.MaxEntries

1const NumCategories = 3

1const (
2	CategoryOperating Category = 1 // trading: the working-capital cycle
3	CategoryInvesting Category = 2 // long-lived assets and investments
4	CategoryFinancing Category = 3 // capital and borrowings
5)

 1const (
 2	// ReasonConflict is an entry whose non-cash legs classify to more than
 3	// one category. [Unresolved.Categories] names them, and names at least
 4	// two.
 5	ReasonConflict Reason = 1
 6
 7	// ReasonUndeclared is an entry with a non-cash leg whose account has no
 8	// policy rule. [Unresolved.Codes] names them. An undeclared account is
 9	// named rather than defaulted, because a default bucket turns a missing
10	// declaration into a figure nobody questions.
11	//
12	// It takes precedence over [ReasonConflict] when an entry has both an
13	// undeclared code and two declared categories, because the undeclared
14	// code is the actionable half: declaring it may resolve the entry, and
15	// reporting a conflict while concealing a missing declaration would send
16	// the reader to re-examine a policy that is not yet complete.
17	ReasonUndeclared Reason = 2
18
19	// ReasonUnbalanced is an entry all of whose legs are declared cash
20	// accounts and whose cash legs do not net to zero.
21	//
22	// [journal.Book] cannot produce one: a balanced entry whose every leg is
23	// cash has equal debits and credits over cash and therefore nets to zero,
24	// which makes it a [Report.NetZero] item instead. So this reason is
25	// reachable only from a hand-built entry slice, the same class
26	// [p/periods] documents for its own hand-built Report.
27	//
28	// It exists rather than being folded into [ReasonConflict] because a
29	// conflict carrying an EMPTY [Unresolved.Categories] is indistinguishable
30	// from a bug in this package, and a census item a reader cannot tell from
31	// a defect is not a census item. Found by writing the test for the
32	// conflict case, not by reading the code.
33	ReasonUnbalanced Reason = 3
34)

 1var (
 2	// ErrInvalidWindow is a window failing [periods.Window.Valid].
 3	ErrInvalidWindow = errors.New("cashflow: invalid window")
 4
 5	// ErrTooManyAccounts is a chart longer than [MaxAccounts].
 6	ErrTooManyAccounts = errors.New("cashflow: chart length exceeds MaxAccounts")
 7
 8	// ErrChartNotSorted is a chart whose codes are not strictly ascending.
 9	// Membership here is a binary search, so the ordering is load-bearing
10	// rather than cosmetic.
11	ErrChartNotSorted = errors.New("cashflow: chart codes not strictly ascending")
12
13	// ErrInvalidKind is a chart row whose Kind is outside journal's five.
14	ErrInvalidKind = errors.New("cashflow: invalid account kind")
15
16	// ErrTooManyEntries is an entry slice longer than [MaxEntries].
17	ErrTooManyEntries = errors.New("cashflow: entry count exceeds MaxEntries")
18
19	// ErrEntriesNotSorted is an entry slice not strictly ascending by ID.
20	ErrEntriesNotSorted = errors.New("cashflow: entry IDs not strictly ascending")
21
22	// ErrTooManyPostings is an entry with more than
23	// [journal.MaxPostingsPerEntry] postings. journal cannot produce one, and
24	// re-checking is what makes [MaxEntries]'s cost bound a proven ceiling
25	// rather than a hope.
26	ErrTooManyPostings = errors.New("cashflow: entry exceeds journal.MaxPostingsPerEntry")
27
28	// ErrInvalidPosting is an in-window posting with an invalid Side or a
29	// non-positive Amount. journal carries direction in Side and amounts are
30	// always positive, so a signed amount here is a posting from somewhere
31	// else.
32	ErrInvalidPosting = errors.New("cashflow: invalid posting")
33
34	// ErrUnknownAccount is an in-window posting naming a code absent from the
35	// chart. It is scoped to the window because no figure in the report
36	// depends on an entry outside it.
37	ErrUnknownAccount = errors.New("cashflow: posting names an account absent from the chart")
38
39	// ErrNoCashAccounts is an empty [Policy.Cash]. A statement of cash flows
40	// over a book with no declared cash is all zeroes and looks exactly like
41	// a quiet period, so the empty declaration is refused rather than
42	// reported.
43	ErrNoCashAccounts = errors.New("cashflow: policy declares no cash accounts")
44
45	// ErrCashNotSorted is a [Policy.Cash] not strictly ascending.
46	ErrCashNotSorted = errors.New("cashflow: policy cash codes not strictly ascending")
47
48	// ErrUnknownCashAccount is a declared cash code absent from the chart.
49	ErrUnknownCashAccount = errors.New("cashflow: policy declares a cash account absent from the chart")
50
51	// ErrCashAccountNotAsset is a declared cash code whose chart Kind is not
52	// [journal.Asset]. See the package doc on the sign convention: this is
53	// what keeps a debit to cash meaning an inflow.
54	ErrCashAccountNotAsset = errors.New("cashflow: policy declares a non-asset account as cash")
55
56	// ErrRulesNotSorted is a [Policy.Rules] not strictly ascending by Code.
57	ErrRulesNotSorted = errors.New("cashflow: policy rule codes not strictly ascending")
58
59	// ErrInvalidCategory is a category outside the declared three — in a
60	// policy rule, or passed to [Report.Line].
61	ErrInvalidCategory = errors.New("cashflow: unknown category")
62
63	// ErrUnknownRuleAccount is a policy rule naming a code absent from the
64	// chart.
65	ErrUnknownRuleAccount = errors.New("cashflow: policy rule names an account absent from the chart")
66
67	// ErrCashAccountClassified is a code declared both as cash and as a
68	// classified account. The two roles are exclusive: a cash account is what
69	// MOVES, and a classified account is what the movement is FOR. Accepting
70	// both would make the same code answer two different questions in one
71	// entry.
72	ErrCashAccountClassified = errors.New("cashflow: code is declared as cash and also classified")
73
74	// ErrOverflow is an int64 overflow in any accumulation, including the
75	// entry-level cash total and the closing balance.
76	ErrOverflow = errors.New("cashflow: int64 overflow")
77)

1func Derive(chart []journal.Account, entries []journal.Entry, w periods.Window, p Policy, opening int64) (Report, error)

1type Category uint8

1type Classification struct {
2	Code     string
3	Category Category
4}

 1type Line struct {
 2	Category Category
 3
 4	// Inflows is the gross cash received, non-negative.
 5	Inflows int64
 6
 7	// Outflows is the gross cash paid, non-negative.
 8	Outflows int64
 9
10	// Entries is how many in-window entries were attributed here.
11	Entries int
12}

 1type Policy struct {
 2	// Cash is the codes that hold cash, strictly ascending. Must be
 3	// non-empty, and every code must be a [journal.Asset] in the chart.
 4	Cash []string
 5
 6	// Rules is the activity category for non-cash codes, strictly ascending
 7	// by Code. A code absent from here is NOT defaulted; an entry touching it
 8	// is unresolved with [ReasonUndeclared].
 9	Rules []Classification
10}

1type Reason uint8

 1type Report struct {
 2	// Window is the window the figures are for, echoed back so a stored
 3	// report cannot be read without it.
 4	Window periods.Window
 5
 6	// Lines is the three categories, ascending by Category, always present
 7	// and always of length [NumCategories] — a category with no activity is a
 8	// zero line, not an absent one, because a statement of cash flows with a
 9	// missing section is not a statement of cash flows. Use [Report.Line] to
10	// reach one by category rather than indexing by arithmetic.
11	Lines []Line
12
13	// Opening is the caller-supplied opening cash position, echoed back
14	// unchanged. This package cannot verify it; see the package doc. A
15	// negative value is accepted — an overdrawn position is a real one — so
16	// the sign is not constrained here.
17	Opening int64
18
19	// NetChange is the window's total net cash movement, attributed and
20	// unattributed together. It is the book's figure, not the statement's, so
21	// it is true even when the split is not complete.
22	NetChange int64
23
24	// Unattributed is the net cash movement of the entries in Unresolved.
25	// Zero exactly when every entry that moved cash was classified.
26	Unattributed int64
27
28	// Closing is Opening plus NetChange.
29	Closing int64
30
31	// Entries is how many entries fell in the window, including the ones that
32	// moved no cash. Zero is a legitimate report of a quiet period, not an
33	// error.
34	Entries int
35
36	// CashEntries is how many in-window entries touched a declared cash
37	// account at all, including the ones in NetZero and Unresolved.
38	CashEntries int
39
40	// NetZero is the IDs of in-window entries that touched cash but moved
41	// none on net — a transfer between two declared cash accounts, possibly
42	// alongside non-cash legs. Classification is deliberately not attempted:
43	// there is nothing to attribute, so demanding determinacy of them would
44	// manufacture unresolved entries out of non-events.
45	NetZero []uint64
46
47	// Unresolved is the entries whose category was not determinate.
48	Unresolved []Unresolved
49}

 1type Unresolved struct {
 2	// EntryID is the entry's journal ID.
 3	EntryID uint64
 4
 5	// Reason is why it could not be classified.
 6	Reason Reason
 7
 8	// Net is the entry's net cash movement: positive for an inflow. Reported
 9	// so a reader can see the size of what is unattributed rather than only
10	// that something is.
11	Net int64
12
13	// Categories is the conflicting set, ascending and of length at least
14	// two, when Reason is [ReasonConflict]; empty otherwise. Freshly
15	// allocated and never nil.
16	//
17	// Ascending rather than in posting order, so that two records of the same
18	// conflict compare equal whichever leg was posted first.
19	Categories []Category
20
21	// Codes is the undeclared account codes, in posting order and
22	// deduplicated, when Reason is [ReasonUndeclared]; empty otherwise.
23	// Freshly allocated and never nil.
24	//
25	// Posting order rather than ascending, because these are a worklist for
26	// whoever extends the policy and the order a reader meets them in the
27	// entry is the more useful one. The two slices differ on this
28	// deliberately: a conflict set is compared, a code list is worked
29	// through.
30	Codes []string
31}