receivables package

BucketAt returns one line item of a frozen report, youngest band first.

`lo` and `hi` are the band's age range in BLOCKS, half-open [lo, hi); when `unbounded` is true the band has no upper edge and `hi` is meaningless. An age equal to an edge belongs to the OLDER band. `rate` is in RateScale units, `unpaid` is the outstanding total that landed in the band, and `provision` is `floor(unpaid × rate / RateScale)`.

BucketCount is how many age bands a frozen report has, which is the bucket count of the schedule that priced it and may differ from the issuer's current schedule.

Buckets is how many age bands an issuer's current schedule has.

Count is how many reports an issuer has published. Zero for an address that never has, which is not an error.

Coverage is the part of a report a reader must not skip.

This realm cannot enumerate an issuer's invoices (see the package doc), so a report covers exactly the ids the issuer named. These eight numbers are what let a reader judge whether that was everything:

• `listed` — distinct ids in the call, after deduplication.
• `aged` — ids that became obligations in the report. The provision covers these and nothing else.
• `notOpen` — settled or voided, so nothing owed.
• `zeroOut` — open with nothing outstanding.
• `notDue` — open and owed, but not yet due at `PublishedAt`.
• `dupes` — repeated ids dropped before aging.
• `openAt` — `invoices.OpenOf(issuer)` at publication: how many open invoices the issuer actually held.
• `recordsAt` — `invoices.RecordsOf(issuer)` at publication: records of any status, which is the figure r/invoices' per-issuer cap applies to.

The arithmetic to do: `aged + zeroOut + notDue` is how many OPEN invoices the report accounted for, so `openAt` minus that is **how many open invoices were left out**. A non-zero remainder means the provision is understated by an unknown amount, and no part of this realm can say by how much.

`listed = aged + notOpen + zeroOut + notDue` always holds; `dupes` is outside it, having been dropped before the filter.

ACCOUNTED FOR IS NOT THE SAME AS AT RISK

`notDue` counts toward "accounted for" and carries NO provision. That is right on its own terms — the invoice was examined, and p/aging deliberately refuses to bucket something that is not yet due — but it makes one reading wrong in a way the arithmetic above will not catch. A reader who takes `aged` (or the provision) as "the receivables at risk" while `notDue` is non-zero has measured a STRICT SUBSET of the open book: the omitted part is not omitted by mistake, it is merely not due yet, and it becomes due later with no further call to this realm.

So `OmittedOpen == 0` means "every open invoice was examined", never "every open invoice is provisioned". The second question is answered by reading `notDue` beside the provision, and the render pages print both for exactly this reason.

Has reports whether a report exists, so a reader can distinguish it from the panics the accessors below raise for an unknown one.

HasSchedule reports whether an issuer has registered a schedule, so a reader can distinguish that from the panic ScheduleOf raises.

Height is the current chain height, which is the `now` a report published in this transaction would be aged against.

Latest is an issuer's highest sequence number, and whether they have published at all. The second result matters: sequence numbers start at 1, so a zero first result means "never published" and never "report 0".

OmittedOpen is the coverage arithmetic as one number: how many of the issuer's open invoices the report did not account for, at the height it was published.

Zero is the answer a complete report gives. A positive answer means the provision is understated. A NEGATIVE answer is possible and is not a bug here: `openAt` is read after the loop, so an invoice settled or voided by a transaction between — impossible within one transaction, but the figure is a snapshot either way — would make the accounted set larger than the open count. It is returned signed rather than clamped, because a clamp would turn an inconsistency into a clean zero.

ProposedEntry returns the double entry that records a report's provision, in the `code:side:amount` form r/books' PostMulti accepts — and this realm does NOT post it.

It cannot. r/books derives a book's owner structurally from its caller, so a posting made from here would land in this realm's own book rather than the issuer's, and there is no owner parameter and no delegation path. The issuer posts this string themselves, from their own account, into their own book. That keeps this realm keyless with respect to every ledger: it cannot write a wrong entry because it cannot write.

The entry debits `expenseCode` and credits `allowanceCode` for the whole provision:

1ProposedEntry(issuer, seq, "E-BADDEBT", "A-ALLOW")
2  → "E-BADDEBT:D:1250,A-ALLOW:C:1250"

Both codes go through [validCode], an ASCII whitelist, and the reason is the format itself: a code containing `:` or `,` would inject extra legs into a string this realm presents as its own arithmetic. Whether a code EXISTS, or is the right kind, in any ledger is not checked and cannot be — this realm reads no ledger.

A zero provision is refused rather than returned as a balanced pair of zeros, which would be a storage deposit spent to post nothing.

It is a PROPOSAL in the full sense: nothing here records that it was posted, posting it twice double-counts, and the allowance it credits is a contra asset whose previous balance this realm cannot see. An issuer provisioning monthly posts the DELTA, not this figure, and working that out is theirs.

Provision is the allowance for credit losses a report concluded: the sum of the per-bucket column, each bucket floored.

Publish freezes an aging report over the named invoices at the current height and returns its sequence number, which starts at 1 for each issuer.

`ids` is a comma-separated list of the caller's own invoice ids in r/invoices, at most MaxIDsPerCall of them. The caller must have registered a schedule first.

What each id is checked for

An id with no record for this issuer PANICS and fails the whole call. That is deliberate: a silently-dropped id is an under-report, and under-reporting is the one error this product cannot detect after the fact. The existence probe is a separate `HasInvoice` call rather than letting the next read panic, because r/invoices' own message is `"unknown invoice"` and does not say WHICH — unhelpful in a list of sixty-four.

An id that exists but is not ageable is filtered, counted, and reported:

• not `open` — settled or voided, so nothing is owed. Counted `notOpen`.
• open with nothing outstanding. Counted `zeroOut`.
• open, owed, but `dueHeight > now`. Counted `notDue`.

The third one is not an optimisation. `aging.ReportAt` requires `DueAt <= now` for EVERY obligation and fails the whole call on the first that is not, so a report over a list containing one current invoice would produce nothing at all. Pre-filtering here is what makes "age everything I have" a usable call, and the count is what stops the filter being invisible.

The outstanding cross-check

`amount - paid` is computed here and compared against r/invoices' `Outstanding`. State its reach exactly, because the flattering reading is available: both sides are that realm's own two numbers, so this is a CONSTANT TRUE against any disagreement in ITS arithmetic and must never be quoted as cross-checking it. What it catches is a transcription error in THIS realm — reading `paid` where `amount` belongs in a six-value return, or subtracting the wrong way round — which is the one place in this path such an error could happen, and an inflated outstanding is an over-provision that still cross-foots.

The id list is not stored

A report keeps the figures and the coverage counts, not the ids. Storing 64 ids per report would roughly double the record for the sake of a `Verify` that could not mean much anyway: the invoices keep moving, so re-deriving would answer "do the figures still hold at today's height" and not "was this report right when made". r/statements documents the same distinction about its own Verify. The honest artifact is the frozen figure plus the coverage line.

PublishedAt is the chain height a report was frozen at. It is also the `now` every age in it was measured against.

Render serves the index at "", an issuer's page at "<address>", and one report at "<address>/<seq>".

Every caller-supplied string reaching the output goes through the sanitizer. The surface is narrower here than in the sibling realms — this realm stores no free text, so the only untrusted bytes are the path itself — and it is still the one injection-shaped surface a realm with no custody has.

ScheduleOf returns an issuer's CURRENT schedule in the comma-separated form SetSchedule accepts, so the round trip is exact.

This is the schedule that would price the issuer's NEXT report, not necessarily the one that priced their last. ScheduleUsed answers that.

ScheduleUsed returns the schedule that PRICED a frozen report, in the comma-separated form SetSchedule accepts.

This exists because p/aging warns that a report carries no reference to its schedule and two schedules of the same bucket count will silently accept each other's reports. Here the reference is stored, so a reader can see the rates that produced the figure rather than inferring them from whatever the issuer has registered today.

SetSchedule registers or replaces the caller's own aging schedule and returns its bucket count.

`edges` is a comma-separated list of block ages, positive and strictly increasing; `rates` is one more number than there are edges, each in [0, RateScale] and non-decreasing. So

1SetSchedule("216000,432000,648000", "0,1000,2500,5000")

reads as: nothing provisioned under 216,000 blocks past due, 10% from there to 432,000, 25% to 648,000, 50% beyond. Every constraint is p/aging's and is validated by `aging.New` rather than re-checked here; a second copy of somebody else's validation is a second place for it to drift.

The owner is `cur.Previous().Address()` and there is no owner parameter, so authorization is structural rather than a check: there is no address to forge and no way to set a schedule for somebody else.

REPLACEMENT IS SAFE and that is a property of [report], not of this function: every published report snapshots the schedule that priced it, so a new schedule applies only to reports published after it. Nothing already frozen is re-priced.

Source is the realm every figure here is read from, by value from its own exported constant.

Total is how many reports exist across every issuer. It is a count and nothing more; see the package doc on why there is no cross-issuer provision.

Totals returns a report's headline figures together, which is the shape a reader wants and the shape that cannot be assembled from two reads at different heights.

Unpaid is the total outstanding the report aged. It is the denominator the provision is a fraction of, and it covers ONLY the aged invoices — not the issuer's whole receivable book. See Coverage.