payslips package

ChargeOn quotes an employer's current schedule against an arbitrary gross without publishing anything. The quote a caller needs before choosing a schedule, and the one view here that is not about a record.

Count is how many payslips an employer has published. Sequence numbers run 1..Count with no gaps: a payslip is never removed.

Coverage is the payslip's coverage line, and it is the number to read before any total.

1listed     employees the caller named, duplicates included
2priced     lines in the record
3zeroGross  priced lines whose settled gross is zero
4withDue    priced lines with gross due and not accrued
5ended      priced lines whose position's clock had stopped
6dupes      duplicate names dropped
7rosterAt   open positions the employer held at this height
8openAt     open positions across every employer at this height

listed == priced + dupes always, by construction: nothing else is dropped. rosterAt - priced is OmittedRoster.

Employers is how many addresses have set a schedule here. Note the tense: a schedule survives, so this is not a count of employers with payslips.

FeeBpsAt is the platform fee rate this payslip was priced against.

GrossOf is a payslip's total SETTLED gross. Read it beside UnsettledGrossOf and OmittedRoster: neither is an error, and both change what this number means.

Has reports whether a payslip exists, so the record accessors can be pre-checked rather than recovered from. Every one of them panics on an absent record, which is deliberate — returning a zero figure for a payslip that was never published is the exact silent under-report this realm exists to refuse — but a panic is only a usable contract when the caller has a way not to hit it.

It is here before the first deploy rather than in a successor because a realm's bytes are frozen by addpkg: an accessor a consumer needs cannot be added afterwards.

HasSchedule reports whether an employer has set a schedule, without panicking on absence — every other schedule accessor panics, which makes them unusable as an existence probe.

Height is the current chain height, exposed so a caller can see the clock this realm reads payroll against.

LineEnded reports whether this line's position had been terminated or had passed its end height when the payslip was published. An ended position can still carry unsettled gross: payroll keeps the obligation alive past Terminate on purpose.

LineNetRange bounds what this employee kept. Same interval as NetRange, one line.

Lines is how many employees a payslip prices.

MarginalRateOf is the rate an employer's current schedule would charge on the next ugnot of gross past the given amount, of RateScale.

NetRange bounds what the employee kept: gross, less the schedule's withholding, less payroll's fee. The interval is inherited whole from PlatformFeeRange — the withholding itself is exact.

IT CAN BE NEGATIVE, and that is a finding rather than a bug. A schedule may legally charge up to 100%, and payroll's fee is taken on top of whatever this realm withholds, so a schedule at or near the ceiling withholds more than the employee actually received. OverWithheld names that case.

NumTiersOf is how many brackets an employer's current schedule has.

OmittedRoster is how many of the employer's open positions this payslip did not price. It is the one number that says whether a payslip is complete, and a total read without it is being read wrongly.

It cannot be negative: every priced line has an open position under this employer at the payslip's height, duplicates are dropped before pricing, so priced is a count of distinct open positions and rosterAt is their total.

OverWithheld reports whether this payslip's withholding plus payroll's largest possible fee exceeds the gross. True is almost always a transposed or mis-scaled rate array, which p/tiers cannot detect, so this realm surfaces it instead of refusing to publish it — a refusal would lose the evidence.

Payslips is how many payslips exist across every employer.

PlatformFeeRange bounds the accrual fee r/payroll already took on this gross. It is an interval because the fee depends on accrual batching, which payroll does not expose — see the package doc. lo == hi is common and means the batching could not have mattered.

Publish prices the named employees under the caller's own roster and records a payslip. It returns the payslip's sequence number, which is per-employer and starts at 1.

employees is a comma-separated list of addresses, at most MaxEmployeesPerCall of them. Order is the caller's and is preserved in the record, so a payslip reads in the order it was requested.

THREE REFUSAL RULES, AND THE ASYMMETRY BETWEEN THEM IS THE POINT:

• An employee with NO OPEN POSITION under the caller PANICS and fails the whole call. A silently-dropped line is an under-report, and under- reporting is the one error this product cannot detect after the fact. A caller that wants to skip an absent position must leave it out, which is a decision in the transaction rather than a silence in the record.
• A DUPLICATE is dropped, counted in the coverage line, and does not fail the call. Dropping it cannot under-report: the employee is still priced once, and double-counting them would be worse.
• An employee with ZERO SETTLED GROSS is PRICED, not filtered. A payslip for a position that has settled nothing yet is a correct payslip with a gross of zero, and filtering it would turn a true statement into a missing line.

An empty list is refused. Nothing here filters a list down to nothing, so after deduplication a call always prices at least one employee.

PublishedAt is the height a payslip was published at, which is the height every figure in it was read at.

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

Every caller-supplied string reaching the output goes through the sanitizer. This realm stores no free text, so the untrusted bytes are the path itself and the addresses in a record — and that is still the one injection-shaped surface a realm with no custody has.

ScheduleAt is the schedule that priced this payslip, as comma-separated lists that round-trip exactly through SetSchedule. The snapshot, not the employer's current schedule — see ScheduleOf for that.

ScheduleOf is an employer's CURRENT schedule, as lists that round-trip through SetSchedule. It is not what priced any published payslip — see ScheduleAt.

SetSchedule installs the caller's own withholding schedule and returns its tier count.

edges and rates are comma-separated int64 lists in p/tiers's units: rates are of RateScale, edges are gross amounts in ugnot. There is one more rate than there are edges, because the last tier is unbounded. An EMPTY edges string is legal and means a one-tier schedule — a flat rate — which is the shape to use for a flat withholding and the shape this realm uses internally for the platform fee.

1SetSchedule(cross(cur), "1000000,5000000", "500,1500,2500")

is 5% on the first 1,000,000 ugnot of gross, 15% on the next 4,000,000, and 25% above 5,000,000.

REPLACING A SCHEDULE DOES NOT RE-PRICE ANYTHING. Every published payslip carries the schedule that priced it, so this only affects payslips published after it. That is a design requirement rather than a convenience: a published statement whose numbers change under it is not a record.

A FALLING RATE ARRAY IS ACCEPTED, because p/tiers accepts one — it is a volume discount, which is a real schedule. The consequence is that a transposed array is a silent authoring error here, and neither this realm nor tiers can detect it. Read back ScheduleOf after setting one.

TierBreakdown is the withholding on one line split by bracket, as a comma-separated list in tier order — the column a payslip reader actually wants, because it shows which brackets the gross reached.

It is recomputed from the payslip's own schedule snapshot rather than stored, so it is exact for the schedule that priced the line and costs no storage. It cross-foots the column against the stored total before returning it: p/tiers DOCUMENTS that Charge is defined as the sum of ChargeByTier, and a documented identity across a package boundary is worth one loop to assert.

UnsettledGrossOf is gross that had completed and not been accrued at the payslip's height, and is therefore EXCLUDED from GrossOf. Non-zero is normal: payroll accrues on demand.

WithheldOf is the schedule's total charge on the gross.