cashflow state

RealmPath

RealmPath is this realm's own path, used to build Render links.

BooksPath

BooksPath is the ledger realm every entry here is read from. Taken BY VALUE from that realm's own exported constant rather than typed out again, so this is the compile-time pin itself and not a second copy that could drift. A reader checking which ledger a statement describes is reading the import.

MaxWindowEntries

MaxWindowEntries bounds how many entries one [Publish](#Publish) may read. This is the §7.4 refusal bound and the number has a derivation rather than a feel. Reading one entry costs TWO cross-realm reads — [books.EntryInfo](/gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/books#EntryInfo) for the header and [books.EntryLegs](/gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/books#EntryLegs) for the postings — because r/books returns them separately. Add the chart reconstruction, which is one [books.Accounts](/gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/books#Accounts), one [books.Codes](/gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/books#Codes) at the chart cap and one [books.AccountInfo](/gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/books#AccountInfo) per account, and the live precedent [r/statements](/r/statements) pays about 130 reads per report. Add the search: 2\*ceil(log2(N+1)) + 4 header reads to locate and prove the range. At 256 the whole publish is about 666 plain reads, roughly five times a report [r/statements](/r/statements) performs on this chain today. At r/books' own entry cap of 4096 it would be about 8,350, which is the figure the discovery gate for r/receivables used to defer this product. It is a REFUSAL and not a truncation: a window holding more entries than this panics and names the count, and the caller narrows the window. Publishing a statement over a silently-truncated entry set is the one failure this product is least able to detect, because a short statement still balances.

PolicyIsReplaceable

PolicyIsReplaceable records a decision a reader will look for. [DeclarePolicy](#DeclarePolicy) overwrites an owner's previous declaration and keeps no history of it. That is safe only because every [Publish](#Publish) FREEZES a copy of the policy it used into the record: a published statement is readable with the classification that produced it forever, via [PolicyOf](#PolicyOf), and changing the live policy cannot restate a published figure. The alternative — versioned policies with reports pointing at a version — is the same information with an extra indirection and one more place for the two to disagree.

PublicationsAreUncapped

PublicationsAreUncapped mirrors [r/statements](/r/statements)' decision for the same three reasons, which hold here unchanged: keys are per owner so an owner can only fill their own history; no accessor and no [Render](#Render) path walks a publisher's whole history; and there is no engine cap above this realm to mirror.

RenderPublicationLimit

RenderPublicationLimit caps how many of a publisher's statements one [Render](#Render) call lists.

RenderCensusLimit

RenderCensusLimit caps how many unresolved or net-zero rows one [Render](#Render) call emits. A window may hold [MaxWindowEntries](#MaxWindowEntries) entries and in a book with no policy rules every one of them is unresolved.

policy

policy is one owner's frozen declaration. The slices are allocated here from the caller's parsed strings and never handed out: [PolicyCash](#PolicyCash) and [PolicyRules](#PolicyRules) re-encode them into a fresh string.

record

record is one frozen statement. It stores the [cf.Report](/gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/cashflow#Report) whole rather than copying its fields into a parallel struct — a second field set is a second place for the two to disagree — plus the three things the report cannot carry: the policy that produced it, the entry-ID range that was read, and the cumulative cross-check result. There is deliberately no seq field. Every read path reaches a record by constructing pubKey from a seq it already holds, so a stored copy would only ever be checked against its own source. [r/statements](/r/statements) records the same decision and the reason it was found: a sabotage harness could not make dropping the assignment fail any test.

policies

policies maps an owner's address string to \*policy.

published

published maps "\<owner>|\<padded seq>" to \*record. The pointer never leaves this file. Every accessor copies scalars out, so no caller receives a handle onto stored state.

counts

counts maps an owner's address string to how many statements they have published. It is the sequence allocator as well as the count.

pubCount

pubCount is the global total, maintained alongside the tree so the index page never iterates.

refuseCoins

refuseCoins panics if a direct caller attached coins. This realm has no banker, no withdrawal path and nothing that can spend what arrives, so a silently-accepted send would be stranded permanently and "we hold no funds" would be true of the design and false of the balance. The residual is stated rather than guarded: coins can still reach this realm's address through an intermediary's explicit banker send, which no predicate here can see. What makes that survivable is the absence of any consumption path, not this guard. The IsCurrent check is a no-op at both of today's call sites — a crossing function's first \`cur\` is runtime-current by construction and stays current when forwarded through a non-crossing call. It is here because this realm is IMMUTABLE after addpkg, so a future third caller cannot be made safe later, and a helper that reads Previous() off an unchecked realm parameter is a designation-forgery shape whether or not it is reachable today.

parseKind

parseKind turns one of [r/books](/r/books)' five kind words back into a [journal.Kind](/gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/journal#Kind) and PANICS on anything else. This is the same seam [r/statements](/r/statements) names in its own copy, and the reason it panics is the same and is specific: the zero [journal.Kind](/gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/journal#Kind) is reported CREDIT-NORMAL by IsDebitNormal, so a silently-unparsed word would not drop the row — it would misfile it and produce a statement that balances and misstates. The five words are that type's own String output, and the suite pins the round trip over all five rather than trusting it to stay true.

chartOf

chartOf reads the owner's whole chart of accounts in one pass. ONE call for the codes, at r/books' own account cap. That iterator has no seek and honours \`from\` by skipping, so one call walks the whole chart however small the limit is — paging it would cost ceil(n/limit) full walks, and [books.Codes](/gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/books#Codes)' \`from\` is INCLUSIVE so every paging caller also owes itself a boundary dedup. A missed one double-counts an account, and a double-counted balance is a defect this product cannot see: the statement would still balance. The agreement check is not decoration. [books.Accounts](/gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/books#Accounts) and [books.Codes](/gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/books#Codes) are two reads through different code paths; if they disagree this refuses rather than deriving over a truncated chart, because [cf.Derive](/gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/cashflow#Derive) rejects a posting naming an account absent from the chart and a truncated chart turns an ordinary entry into ErrUnknownAccount pointing at the wrong layer. TAINT: the \[]string [books.Codes](/gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/books#Codes) returns was allocated under that realm and arrives readonly-tainted. Nothing here mutates it or stores it — codes are read out by value and the rows are allocated here. This is a second copy of [r/statements](/r/statements)' unexported chartOf, forced: that realm is live and §6 forbids modifying it to promote the helper.

lowerBound

lowerBound is the smallest entry ID in 1..n whose At is >= target, or n+1 if there is none. Correct only under the non-decreasing-At premise in the package doc. A violation makes this land somewhere arbitrary rather than wrong-by-one, which is why \[scan] probes the located boundaries rather than trusting the result.

scan

scan locates and reads every entry in w, and returns them with the inclusive ID range and whether the window extends past every entry the book holds. The last return value is what makes the cumulative cross-check sound; see [OpeningReconciled](#OpeningReconciled). It is true for an empty book as well, where every balance is necessarily zero because balances come only from postings. Every check here is a panic rather than a return, because this is reached from a mutating path and in Gno only a panic reverts a transaction.

parseLegs

parseLegs decodes the "code:side:amount,..." form [books.EntryLegs](/gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/books#EntryLegs) returns. That form is [books.PostMulti](/gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/books#PostMulti)'s input format, so this is the inverse of a parser living in the realm the string came from. It is duplicated rather than shared for the same reason chartOf is: r/books is live. It is STRICTER than r/books' own parser in one direction and deliberately so. r/books accepts "D", "DR" and "DEBIT" for a side because a human types its input; [books.EntryLegs](/gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/books#EntryLegs) emits only "D" or "C", so anything else here means the format changed underneath this realm and the right outcome is a refusal rather than a tolerant read. It is not stricter about leg count: r/books refuses fewer than two on the way IN, and re-asserting that on the way out would duplicate another realm's invariant in a place that cannot enforce it.

liveCash

liveCash sums the declared cash accounts' balances now. Every cash code is a [journal.Asset](/gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/journal#Asset) — [cf.Derive](/gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/cashflow#Derive) refuses a policy that declares a non-asset as cash — so each balance is debit-normal and the sum is the book's cumulative net cash movement since its first posting. That is the figure [OpeningReconciled](#OpeningReconciled) compares against.

DeclarePolicy

DeclarePolicy records the caller's own classification policy for their own book, replacing any previous one. \`cash\` is a comma-separated list of account codes that hold cash, strictly ascending — for example \`1010,1020\`. It must be non-empty and every code must be an asset in the caller's chart. \`rules\` is a comma-separated list of \`code:category\` pairs, strictly ascending by code, where category is \`operating\`, \`investing\` or \`financing\` — for example \`4000:operating,1500:investing,3000:financing\`. A code absent from \`rules\` is NOT defaulted to anything: an entry touching it is reported unresolved, by name, because a default bucket turns a missing declaration into a figure nobody questions. \`rules\` may be empty. The owner is \`cur.Previous().Address()\` and there is NO owner parameter. [r/books](/r/books) derives a book's owner the same way and no mutating function there takes one either, so the only party who can declare a policy for a book is the only party who can write to it. An owner parameter would move the trust boundary to whoever called this. The declaration is validated against the caller's LIVE chart by deriving over an empty entry set: [cf.Derive](/gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/cashflow#Derive) validates the window, the chart and the policy before it reads an entry, so a nil entry slice exercises exactly the declaration's validity and nothing else. A policy that is valid now stays valid, because [r/books](/r/books) has no way to remove an account from a chart.

parseCash

parseCash decodes the cash-code list. Order and duplication are NOT checked here: [cf.Derive](/gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/cashflow#Derive)'s validatePolicy requires strictly ascending codes and says so with its own error, and a second copy of that rule here would be a second place for the two to disagree.

parseRules

parseRules decodes the code:category list. An empty string is a legitimate empty policy — every entry touching a non-cash account is then unresolved, which is a true report of a book whose owner has declared nothing.

parseCategory

parseCategory turns a category word into a [cf.Category](/gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/cashflow#Category) and panics on anything else. The three words are that type's own String output; the suite pins the round trip over all three rather than trusting another package's method to stay put. It panics rather than returning the zero Category because the zero value is deliberately invalid in [p/cashflow](/p/cashflow) and a silently-zero rule would reach validatePolicy as ErrInvalidCategory, pointing a reader at the wrong layer.

Publish

Publish freezes a statement of cash flows over \[from, until) and returns its sequence number, which counts from 1 per publisher. The window is half-open: \`from\` is included and \`until\` is not. The unit is whatever [r/books](/r/books) dates with, which is block height. \`opening\` is the caller's declared opening cash position. It cannot be derived from a windowed entry set and is echoed into the report unchanged; see [OpeningReconciled](#OpeningReconciled) for the one window shape where this realm can and does check it. The owner is \`cur.Previous().Address()\`. There is NO owner parameter and no way to publish over someone else's book, for the reason given at [DeclarePolicy](#DeclarePolicy). It PANICS, rather than returning an error, on: no book, no declared policy, an invalid window, a window holding more than [MaxWindowEntries](#MaxWindowEntries) entries, a violation of the entry-dating premise at either window edge, a disagreement between the chart's two reads or an entry's two reads, any [cf.Derive](/gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/cashflow#Derive) error, and a failed cumulative cross-check. An error return would not revert a Gno transaction; only a panic does.

Count

Count is how many statements an owner has published.

Latest

Latest is the newest sequence number for an owner, and false if they have published none.

Total

Total is how many statements every publisher has published together. There is deliberately no way to enumerate the publishers; see the package doc.

Has

Has reports whether a statement exists.

PublishedAt

PublishedAt is the block height a statement was frozen at.

Window

Window is the period a statement covers, half-open: \`from\` is in, \`until\` is out.

Totals

Totals is the four cumulative figures. \`closing\` is \`opening + netChange\`, and \`opening\` was supplied by the publisher — see [OpeningReconciled](#OpeningReconciled) for whether this realm was able to check it. \`unattributed\` is the net movement of the entries in the unresolved census and is part of \`netChange\`, not additional to it.

LineOf

LineOf is one category's gross flows. \`category\` is \`operating\`, \`investing\` or \`financing\`; anything else panics. Inflows and outflows are GROSS and both non-negative. A category with 1,000 in and 1,000 out is not the same business as one with nothing happening, and a net of zero is all a netted figure could say about either.

Scope

Scope is the statement's own coverage line, and it is the thing to read before quoting any figure above. - \`entries\` is how many entries fell in the window, including the ones that moved no cash. Zero is a quiet period, not an error. - \`cashEntries\` is how many touched a declared cash account at all. - \`netZero\` is how many touched cash and moved none on net — a transfer between two cash accounts. Classification is not attempted for them: there is nothing to attribute. - \`unresolved\` is how many could not be classified. A statement with unresolved entries is still arithmetically whole — the residual is in \`unattributed\` — but its SPLIT is incomplete.

EntryRange

EntryRange is the inclusive [r/books](/r/books) entry-ID range this statement was derived from. \`ok\` is false when the window held no entries. It is stored because it is the evidence for the statement's scope: a reader can take the two IDs to [r/books](/r/books) and read the entries themselves. A statement is the only artifact here, and this is what makes it checkable against its source.

Complete

Complete reports whether every in-window entry that moved cash was attributed to a category. A complete statement is not a correct one. Completeness is a property of the POLICY's coverage, and a policy that classifies every account wrongly is complete. [p/cashflow](/p/cashflow) says this of its own accessor and it is worth repeating at the realm boundary, where the word will be quoted.

Reconciles

Reconciles reports whether the attributed lines plus the unattributed residual equal the net change. On a statement published here it is ALWAYS TRUE, because [cf.Derive](/gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/cashflow#Derive) produces it that way and nothing between there and storage touches the figures. It is exposed anyway, and the reason is narrow: it is the one check a reader can run against a stored report without re-reading the ledger, and an exposed constant-true that is DOCUMENTED as one is better than a reader assuming the invariant holds without ever being told where it comes from. It must not be quoted as evidence that a statement is right.

OpeningReconciled

OpeningReconciled reports whether this realm was able to check the publisher's declared opening position against the ledger — and, because a failed check REFUSES to publish, it being true means the check passed. ### When it applies {#hdr-When_it_applies} Only when the window extended past every entry the book held at publication. Then the window's net change covers all movement from \`from\` onward, the declared cash accounts' summed balance covers all movement ever, and the difference between them is exactly the movement before \`from\` — which is what a correct opening is. An empty book qualifies too: with no postings every balance is zero, so the check requires an opening of zero. It does NOT apply to a window that closed before later entries were posted. There the balances carry post-window movement the statement rightly excludes, and comparing them would be comparing two different periods. ### What it proves, and the second thing it proves {#hdr-What_it_proves__and_the_second_thing_it_proves} First, that the declared opening is consistent with the ledger. Second — and this is why it is worth its cost — that THE ENTRY SCAN WAS COMPLETE. A scan that silently missed entries produces a short net change, and a short net change fails this comparison. That is the one mechanical control this realm has against the silent-under-reporting failure mode the package doc names, and it covers exactly the window shape where it is available. ### What it does not prove {#hdr-What_it_does_not_prove} Nothing about whether the codes called cash hold cash. Both sides of the comparison are the same owner's self-report, read through the same realm. It is an internal consistency check, not a custody attestation.

ReconciledCash

ReconciledCash is the declared cash accounts' summed balance at publication, and false if [OpeningReconciled](#OpeningReconciled) does not apply to this statement. The figure is meaningless when ok is false and is returned as zero.

UnresolvedCount

UnresolvedCount is how many entries could not be classified.

UnresolvedAt

UnresolvedAt is one unresolved entry, by index into the census. - \`reason\` is \`conflict\` (the non-cash legs classify to more than one category), \`undeclared\` (a non-cash leg's account has no policy rule) or \`unbalanced\`. - \`net\` is the entry's net cash movement, which is real movement the statement could not attribute. - \`categories\` is the conflicting categories, comma-separated, for a conflict. - \`codes\` is the undeclared account codes, comma-separated, for an undeclared entry. Declaring them may resolve the entry, which is why \`undeclared\` takes precedence over \`conflict\` when both apply.

NetZeroCount

NetZeroCount is how many in-window entries touched cash and moved none on net.

NetZeroAt

NetZeroAt is one net-zero entry's ID, by index.

PolicyOf

PolicyOf is the classification policy that produced a published statement, re-encoded in [DeclarePolicy](#DeclarePolicy)'s own input format. It is the statement's policy, frozen with it, NOT the owner's current one. [PolicyIsReplaceable](#PolicyIsReplaceable) explains why both exist: a reader of a published figure needs the declaration that produced it, and an owner needs to be able to correct a declaration without restating history.

HasPolicy

HasPolicy reports whether an owner has declared a policy.

PolicyCash

PolicyCash is the owner's CURRENT declared cash codes, comma-separated.

PolicyRules

PolicyRules is the owner's CURRENT declared rules, comma-separated \`code:category\` pairs.

PolicyDeclaredAt

PolicyDeclaredAt is the height the owner's current policy was declared at.

LiveCash

LiveCash is the declared cash accounts' summed balance right now. This is the book's cumulative net cash movement since its first posting, and it is a LIVE figure — it moves with every posting. It is not a published statement and must not be quoted as one.

Rescan

Rescan re-locates a published statement's window in the ledger NOW and reports whether the entry count and the net change still agree with what was frozen. ### Why this exists and the re-derivation accessor does not {#hdr-Why_this_exists_and_the_re_derivation_accessor_does_not} The package doc says there is no \`Verify\` here, because re-deriving a statement over a window that has closed is a CONSTANT TRUE: entries are dated at the chain height and the journal is append-only, so nothing can later fall into a closed window. This is the part of that comparison which is NOT constant. Window selection is a binary search resting on a premise owned by [r/books](/r/books) — that entry dates are non-decreasing in entry ID — and nothing freezes that premise. A future change there could break it silently. Re-locating the range and comparing is therefore a real test of the selection, and it is the only check here whose answer can change for a reason that matters. ### What it costs and what it does not cover {#hdr-What_it_costs_and_what_it_does_not_cover} It is a plain read, so the caller pays. It re-reads the window's entries, which is up to 2\*[MaxWindowEntries](#MaxWindowEntries) cross-realm reads plus the search. It compares the entry COUNT and the NET CHANGE, not every line. The net change is the figure that moves if the entry set changed, and it is derived from the postings rather than from the policy, so a disagreement points at the ledger or the selection rather than at a reclassification. A false return means do not trust the statement and does not say which of the two it is.

Height

Height is the current block height, so a reader can tell how old a statement is without a second query.

Ledger

Ledger is the realm every entry here is read from.

pubKey

pubKey is owner|paddedSeq. The sequence is left-padded to 19 digits — the width of MaxInt64 — so lexicographic order over an owner's prefix is numeric order over their statements. An unpadded decimal would sort "10" before "9". The convention is r/invoices' invKey, adopted rather than re-derived.

ownerCount

ownerCount reads a publisher's count, treating an absent key as zero. avl.Tree.Get returns ONE value and cannot distinguish an absent key from a nil-valued one, so the two-value type assertion carries the existence answer in one traversal. Only this file ever Sets, and it only ever Sets an int.

mustRecord

mustPolicy

copyCodes

copyRules

encodeCash

encodeRules

checkedAdd

checkedAdd is int64 addition that reports overflow instead of wrapping. Local because a /p/ import for one function would be a dependency this realm's closure does not need, and the same four lines appear in p/journal, p/periods and p/cashflow.

Render

Render serves the index at "", a publisher's page at "\<address>", and one statement at "\<address>/\<seq>". Every caller-supplied string reaching this page — an account code, an entry memo — is an owner's free text in [r/books](/r/books) and arrives unsanitized, because that realm does not sanitize what it stores. Free text reaching a page unescaped is the one injection-shaped surface a realm with no custody still has, and the bytes coming from a THIRD realm's state does not make them safer. Everything goes through \[cell].

renderIndex

renderPublisher

renderStatement

renderCensus

censusDetail

censusDetail is the actionable half of an unresolved row: the undeclared codes for an undeclared entry, the conflicting categories for a conflict.

cell

cell truncates and escapes a string for a markdown table cell. The truncation is first and is not cosmetic: an account name may be books.MaxNameLen bytes and a memo books.MaxMemoLen, and a table row carrying either whole is unreadable. The escape is sanitize.TableCell, which is what keeps an owner's free text from breaking out of the cell.

yesNo