inventory state

RealmPath

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

InventoryCode

The fixed chart. The codes follow r/books' convention, where an account's LEADING DIGIT fixes its kind: 1 asset, 2 liability, 3 equity, 4 revenue, 5 expense. A six-series code would be an invalid account under that convention, which is why cost of goods sold is 5000 and not the 6000 some charts use.

InventoryName

The fixed chart. The codes follow r/books' convention, where an account's LEADING DIGIT fixes its kind: 1 asset, 2 liability, 3 equity, 4 revenue, 5 expense. A six-series code would be an invalid account under that convention, which is why cost of goods sold is 5000 and not the 6000 some charts use.

COGSCode

The fixed chart. The codes follow r/books' convention, where an account's LEADING DIGIT fixes its kind: 1 asset, 2 liability, 3 equity, 4 revenue, 5 expense. A six-series code would be an invalid account under that convention, which is why cost of goods sold is 5000 and not the 6000 some charts use.

COGSName

The fixed chart. The codes follow r/books' convention, where an account's LEADING DIGIT fixes its kind: 1 asset, 2 liability, 3 equity, 4 revenue, 5 expense. A six-series code would be an invalid account under that convention, which is why cost of goods sold is 5000 and not the 6000 some charts use.

ContribCode

The fixed chart. The codes follow r/books' convention, where an account's LEADING DIGIT fixes its kind: 1 asset, 2 liability, 3 equity, 4 revenue, 5 expense. A six-series code would be an invalid account under that convention, which is why cost of goods sold is 5000 and not the 6000 some charts use.

ContribName

The fixed chart. The codes follow r/books' convention, where an account's LEADING DIGIT fixes its kind: 1 asset, 2 liability, 3 equity, 4 revenue, 5 expense. A six-series code would be an invalid account under that convention, which is why cost of goods sold is 5000 and not the 6000 some charts use.

MaxItemsPerRegister

MaxItemsPerRegister caps one owner's SKU count. Every register-wide cross-foot walks every item's lots, and this bound is half of what keeps those reads affordable for everyone.

MaxLotsPerItem

MaxLotsPerItem caps one item's LIVE lots, well below p/lots' MaxLotsLimit of 1024. It is the other half of the read bound: the worst case a register-wide walk must visit is MaxItemsPerRegister\*MaxLotsPerItem lots. Exhausted lots are dropped by p/lots, so this bounds concurrent lots and not the number of receipts an item may ever take. A WAVG item merges every receipt into one lot and so can never reach it — which means this is NOT the binding constraint for a WAVG item, and that item has a merge-overflow refusal of its own instead. See the package doc.

MaxEntriesPerRegister

MaxEntriesPerRegister caps one owner's journal, far below journal's MaxEntriesLimit of 1000000 because Rederive is linear in the posting count and is a free read here. A register that fills refuses further receipts and shipments rather than dropping history. There is deliberately no Archive — it would destroy the record the invariants are checked against — so the remedy is a second register under a second address, which is a real limitation and not a hidden one.

MaxSKULen

MaxSKULen bounds a SKU, which is an avl key, a Render table cell and a Render path component all at once.

MaxItemNameLen

MaxItemNameLen bounds an item's human name. Every name is a candidate for Render output.

RenderItemLimit

RenderItemLimit caps how many items one register page tabulates.

RenderLotLimit

RenderLotLimit caps how many lots one item page tabulates.

maxInt64

maxInt64 is the largest int64. It is a precondition of the counter guards below, so it is pinned BY BEHAVIOUR in the suite rather than by a test that restates the literal: TestMaxInt64IsTheInt64Maximum proves it wraps when incremented.

register

register is one owner's inventory sub-ledger and the book its postings go to. The book and every pool are POINTERS and none is ever returned by any exported function — p/journal consumer obligation 4 and the identical rule for p/lots: a \*Book is a mutable handle and a \*Pool is a mutable handle, and handing either across a realm boundary would hand out the right to post or to consume.

item

item is one stock-keeping unit and its cost pool.

regs

regs maps an owner's address string to that owner's \*register.

regCount

regCount is maintained alongside the tree so the index page never has to iterate it.

refuseCoins

refuseCoins panics if a user call arrives carrying coins. This realm has no withdrawal path, so accepted coins would be stranded permanently. The guard is on IsUserCall rather than IsUser deliberately: OriginSend is only meaningful for a direct MsgCall, and the MsgRun ephemeral can consume the envelope before forwarding control, so IsUser would be the wrong predicate. The IsCurrent() check is a separate concern and is not about coins: this is a non-crossing helper reading identity off a realm PARAMETER, which is the designation-forgery shape (security.md Class 2) whether or not a caller exercising it exists today. It is a no-op at every call site here, and that claim has one more hop in this realm than in its siblings: addItem is itself non-crossing and forwards the cur it was given, so the chain is AddFIFO/AddLIFO/AddWAVG -> addItem -> here. Every link forwards a crossing entrypoint's OWN first cur, which is runtime-current by construction and stays current through any number of non-crossing calls — so the guard still never fires, and the extra hop is exactly why having it at the point of USE rather than at the entrypoints is the right placement. It is kept because this realm is IMMUTABLE after addpkg. p/coinio guards the same shape in Receive, Payout and Sweep; this is that house precedent applied. No count of the call sites is written down, per CLAUDE.md § 4a.

mustOwnRegister

mustOwnRegister returns the CALLER'S register, and there is no variant that returns anyone else's. Every mutating entrypoint goes through this, so ownership is implicit in the call. "Ownership is never a parameter" is what this comment used to conclude, and it is true of the SIGNATURE and was never true of the realm VALUE: the owner is derived from cur, so an uncurrent cur IS an ownership parameter. That is the same Class 2 shape refuseCoins carries above and the more consequential half of it, because this is the function that decides who owns the register rather than one that only refuses coins. The addItem hop described above applies here too. The guard is a no-op today for the same reason, kept for the same reason, and its call sites are likewise not counted here. See AUDIT.md.

reg

reg looks an owner's register up. avl's Get returns a bare \`any\` and signals absence with nil, so the nil test IS the lookup result and not a defensive extra — every value this realm stores is a non-nil pointer.

mustReg

mustItem

checkSKU

checkSKU validates a SKU against a deliberately narrow charset: A-Z, a-z, 0-9, '.', '\_' and '-'. The restriction buys three things at once, which is why it is worth imposing on a caller. A SKU is an avl KEY, so its byte order is the Render table's row order. It is a Render PATH COMPONENT, so a '/' would forge a route and a '?' or '#' would truncate one. And it is a markdown TABLE CELL, so a '|' would forge a column. Escaping at each use site would be three chances to miss one; a charset is checked once, here, on the way in. Case is significant and "sku-1" and "SKU-1" are different items. That is a real sharp edge for a human operator and is the honest reading of a key: folding case would mean this realm, not the owner, decides which SKUs collide.

checkItemName

OpenRegister

OpenRegister creates the caller's register and opens its three accounts. It panics if the caller already has one. The chart is opened HERE rather than on demand, and the book is created with a cap of exactly three accounts. Both facts are load-bearing: they are why this realm is its book's only writer and why the cross-foot identities are exact rather than approximate.

AddFIFO

AddFIFO adds an item whose shipments are costed oldest-lot-first.

AddLIFO

AddLIFO adds an item whose shipments are costed newest-lot-first.

AddWAVG

AddWAVG adds an item whose receipts are merged into a single re-anchored lot and whose shipments are costed at the blended unit cost. A WAVG item holds exactly one lot however many receipts it takes, so it can never reach MaxLotsPerItem. It can still refuse a receipt: the MERGE has an overflow precondition the other two methods never evaluate, and it is a property of the pool's accumulated history rather than of the receipt. See the package doc; the practical consequence is that [LotCapacity](#LotCapacity) is not the figure to watch for a WAVG item.

addItem

Receive

Receive takes qty units costing cost in total into the item's pool and posts debit 1300 / credit 3900, returning the entry id. A cost of ZERO is accepted — free goods — and posts nothing; the returned id is then 0, which is not a valid entry id and is the signal that no entry was made. See the package doc. Panics if the item does not exist, if qty is not positive, if cost is negative, if the pool's lot cap is reached, if a WAVG merge would breach the per-lot overflow precondition — a refusal that depends on the item's history and not on this receipt, see [AddWAVG](#AddWAVG) — or if the book is full. Every one of those aborts the whole transaction, which is what makes the pool-then-post order safe: an error return would NOT revert the pool update, a panic does.

Ship

Ship consumes qty units from the item's pool and posts debit 5000 / credit 1300 for the cost it DERIVED, returning that cost. The cost is never a parameter. It is whatever the item's costing method charges against the lots on hand, which is the whole product. A derived cost of ZERO posts nothing — goods that cost nothing to acquire cost nothing to ship. The return value is then 0 and so is indistinguishable from "no entry made", deliberately: both facts are the same fact here. Panics if the item does not exist, if qty is not positive, if qty exceeds the quantity on hand (p/lots fails closed with ErrInsufficient and consumes nothing), or if the book is full.

Rename

Rename changes an item's human name. The SKU, the costing method and every lot are immutable; a name is presentation only and nothing derives from it.

HasRegister

HasRegister reports whether an address has opened a register.

Registers

Registers is how many registers exist across the realm.

OpenedAt

OpenedAt is the height an owner's register was opened at.

ItemCount

ItemCount is how many items an owner's register holds.

Height

Height is the current chain height, so a reader can date every other figure on this page without a second query.

SKUs

SKUs lists an owner's SKUs in key order, starting at or after from and returning at most limit of them. An empty from starts at the beginning. This enumerator exists because its absence is a known defect elsewhere in this portfolio: r/books exposes no account enumerator, so a third party cannot discover what to ask it about without already knowing. A sub-ledger whose invariants are per-item is useless to a verifier who cannot list the items, so the list is part of the product rather than an afterthought. A non-positive limit returns nothing rather than everything. The cap is the item cap, so a caller may always page the whole register.

HasItem

HasItem reports whether an owner's register holds a SKU.

ItemName

ItemName is an item's human name.

Method

Method is an item's costing method, as "fifo", "lifo" or "weighted-average".

AddedAt

AddedAt is the height an item was added at.

OnHand

OnHand is the quantity of an item on hand, DERIVED by walking its live lots rather than read from a counter — which is what makes [ItemCrossFootQty](#ItemCrossFootQty) a comparison rather than a tautology.

CostOnHand

CostOnHand is the carrying value of an item's live lots: the figure this item contributes to the 1300 balance. Derived, for the same reason as [OnHand](#OnHand).

Received

Received is an item's cumulative received quantity and cost.

Charged

Charged is an item's cumulative shipped quantity and the cost charged out for it. The cost figure is derived: no caller has ever supplied it.

Receipts

Receipts is how many receipts an item has taken, including those whose lots are exhausted and dropped. It is NOT the live lot count — see [LotCount](#LotCount).

LotCount

LotCount is how many LIVE lots an item holds. Exhausted lots are dropped.

LotAt

LotAt reports the i'th live lot of an item in receipt order, and whether i was in range. It returns primitives rather than a p/lots.Lot so that the figures are readable from vm/qeval without the caller knowing that type.

Capacity

Capacity reports how much room an owner's register has left.

LotCapacity

LotCapacity reports how many further live lots one item can hold. A WAVG item merges into one lot, so its figure is a bound it will never approach — and reading headroom off it for a WAVG item is therefore reading the wrong limit, because the refusal that CAN bind there is a merge overflow this figure knows nothing about. See [AddWAVG](#AddWAVG).

Balance

Balance returns an account's balance in its NORMAL direction and whether the code exists. All three of this realm's accounts are normal, so all three read non-negative.

RawBalance

RawBalance returns debits minus credits regardless of kind. Summed over the three accounts it is exactly zero in a balanced book, which is what makes it the useful figure for a consistency check and the wrong one for a report.

AccountKind

AccountKind returns an account's kind as a word, and whether it exists.

InventoryDebit

InventoryDebit is the 1300 balance: the value of goods on hand per the ledger.

COGSDebit

COGSDebit is the 5000 balance: everything ever charged out as cost of goods sold.

ContributedCredit

ContributedCredit is the 3900 balance. Read it as "goods arrived from somewhere this ledger does not model" — see the package doc on why 3900 is a plug this realm is forced to pick.

EntryCount

EntryCount is how many entries an owner's book holds.

Totals

Totals are the book's total debits and credits.

IsBalanced

IsBalanced reports whether total debits equal total credits.

Equation

Equation reports the accounting equation: debit-normal against credit-normal, and whether they offset. For this realm that is 1300 + 5000 against 3900, which offsets at 0 = 0 on an empty register and after every posting. READ THE SIGN BEFORE PRESENTING EITHER FIGURE. journal partitions RAW DELTAS — debits minus credits — so creditNormal is NEGATIVE whenever 3900 carries a credit balance, and \`offsets\` means debitNormal + creditNormal == 0, not debitNormal == creditNormal. The textbook "assets = equity" has both sides positive; this does not. A caller rendering a balance sheet wants -creditNormal. The first test written against this function asserted the right magnitude with the wrong sign and was red for it, which is why this paragraph exists rather than a reader discovering it. What \`offsets\` does NOT prove is journal's obligation 7, inherited here verbatim: the two subtotals are a partition of the same addends, so reclassifying every account in the chart changes both and leaves \`offsets\` true. A Kind set wrongly at Open time is invisible to it. What pins this realm's chart is the PAIR — debitNormal == InventoryDebit + COGSDebit and creditNormal == -ContributedCredit — and the suite asserts exactly that. Sharper than that, because the partition is arithmetically inert: the two subtotals are added back together, so \`offsets\` reduces to Σ debits == Σ credits over the whole chart, which is the FIRST of the three conjuncts [IsBalanced](#IsBalanced) checks. A balanced book therefore always offsets, and \`offsets\` carries no fact [IsBalanced](#IsBalanced) has not already carried more strongly. The informative half of this function is the PAIR OF FIGURES, not the boolean — the figures move when a Kind changes and the boolean does not. (The two walks accumulate in different orders, so a mid-sum overflow could in principle separate them. At 8192 entries it would take amounts no register can reach, and it is not a second independent check.)

Rederive

Rederive re-walks every posting in the book and reports whether the account totals agree with the journal. It is a FREE read, unlike r/books' owner-only equivalent, for the reason given in the package doc. The cost is linear in the posting count, which is what MaxEntriesPerRegister bounds.

Invariant

Invariant is the per-item derivation check, and it is this realm's central claim: postedCOGS == pool.ChargedCost() The left figure is what this realm posted to 5000 for the item; the right is what the pool says it charged. They are maintained by different code in different packages, so a false here means the realm posted an amount its own lots do not imply — which no code path in this realm can produce, and which is exactly why it is worth exporting. A claim is worth more checkable by a stranger than asserted in a comment. The receipt side is checked the same way by [InvariantReceipts](#InvariantReceipts).

InvariantReceipts

InvariantReceipts is [Invariant](#Invariant) for the receipt side: postedRecv == pool.ReceivedCost()

ItemCrossFoot

ItemCrossFoot is p/lots' own cost identity for one item: receivedCost == chargedCost + costOnHand Received and charged are counters; on-hand is a walk of the live lots. The identity therefore compares two independently maintained things, which is why p/lots keeps them apart.

ItemCrossFootQty

ItemCrossFootQty is the quantity identity for one item: receivedQty == consumedQty + qtyOnHand It is not implied by [ItemCrossFoot](#ItemCrossFoot): costs and quantities can disagree independently, and a bug that moved cost without moving quantity would be invisible to the cost identity alone.

CrossFootInventory

CrossFootInventory is the register-wide check on 1300: the sum of every item's carrying value against the ledger balance. The identity is EXACT, not approximate, and the reason is structural: this realm exposes no general posting entrypoint, so it is its book's only writer. Adding a general Post would destroy this check, which is the cost of adding one.

CrossFootCOGS

CrossFootCOGS is the register-wide check on 5000: the sum of every item's charged cost against the ledger balance.

CrossFootContributed

CrossFootContributed is the register-wide check on 3900: the sum of every item's received cost against the ledger balance.

CrossFoot

CrossFoot reports all four register-wide agreements as separate bools. They are returned SEPARATELY and there is deliberately no single aggregate bool: a one-word verdict over four checks is the shape that gets quoted without its coverage, and a reader who wants the figures behind any one of these has [CrossFootInventory](#CrossFootInventory), [CrossFootCOGS](#CrossFootCOGS), [CrossFootContributed](#CrossFootContributed) and [Equation](#Equation).

Render

Render shows the realm index at "/", one owner's register at "/\<address>", and one item at "/\<address>/\<sku>".

renderIndex

renderRegister

renderItem

cell

cell renders a caller-supplied string into a table cell. A blank value would collapse the column, so it is shown as a dash.

yesno