The reference
Each surface, with the names you can go and look up.
Gross-to-net arithmetic
Gross-to-net arithmetic — exact integer cents, and a paycheck that cannot go negative
Earnings in, deductions in, net out — every field an exact integer number of cents, never a float. Net floors at zero: a paycheck cannot be negative. And when deductions exceed gross, the over-deduction is flagged for review as its own signal rather than silently zeroed and forgotten — the floor being hit is exactly the case a human has to look at. A negative earning or deduction line is treated as zero rather than allowed to corrupt a sum.
grossPayCents · totalDeductionsCents · netPayCents · isOverDeducted · disburseStatus
What it guarantees. Net floors at zero, so a paycheck can never be negative — and the floor being hit is raised as its own signal rather than silently absorbed. A negative earning or deduction line arriving as input is treated as zero rather than allowed to corrupt a sum.
What it refuses. disburseStatus returns honest_off_no_partner whenever no licensed partner is wired, and nothing in any wired route sets that flag true. It is the shape of the code path, not a configuration value somebody could flip by mistake.
back-office-payroll-engine.ts
disburseStatus returns honest_off_no_partner. Nothing moves.
Per-authority taxable basis
Per-authority taxable basis — the number one real-money hazard, computed one authority at a time
Different pre-tax deductions reduce different tax bases, and a single wrong mask produces the wrong Social Security and Medicare withholding and the wrong W-2 Boxes 3 and 5 and the wrong 941 — one mistake, three wrong documents. So there is no single “taxable wages” number here. Each authority gets its own basis, computed from a signed per-deduction-class exemption mask, and each carries its own reconcile identity: basis equals gross minus what reduced it, and never falls below zero. An unsigned mask computes no basis at all — it does not guess “reduce everything” and it does not guess “reduce nothing.”
What it guarantees. Each authority gets its own basis from a signed per-deduction-class exemption mask, and each carries the same reconcile identity: the basis equals gross minus what reduced it, and never falls below zero.
What it refuses. An unsigned mask computes NO basis at all and returns needs_sme. It does not fall back to “reduce everything” and it does not fall back to “reduce nothing” — both of those are wrong in a way that produces a number.
back-office-payroll-taxable-basis.ts
No money. A basis is an input to a calculation, not a payment.
Federal withholding
Federal income-tax withholding — IRS Pub 15-T Worksheet 1A, step by readable step
The percentage method for automated payroll systems, written as the worksheet actually reads: annualize the wage, apply the Step 4a and 4b adjustments and the filing-status standard adjustment, look up the tentative annual tax in the supplied bracket table, de-annualize, subtract the Step 3 tax credit, add the 4c extra per-period amount. The per-period division floors down and the dropped sub-cent fraction is returned rather than rounded away. Every constant — the standard adjustment, the bracket table — is supplied and signed. This module invents no IRS figure.
computeFederalWithholding
What it guarantees. The IRS Publication 15-T Worksheet 1A percentage method for automated payroll systems, written in the order the worksheet reads: annualize, apply the Step 4a and 4b adjustments and the filing-status standard adjustment, look up the tentative annual tax in the SUPPLIED bracket table, de-annualize, subtract the Step 3 credit, add the 4c extra amount. The per-period division floors down and returns the dropped sub-cent fraction.
What it refuses. An unsigned bracket table returns needs_sme_unsigned_table and withholds ZERO. This module invents no IRS figure — not a rate, not a bracket, not a wage base.
back-office-payroll-federal-withholding.ts
No money. An unsigned table withholds zero and names the reason.
FICA, employee and employer
FICA and Medicare — rates as exact rationals, because 1.45% is not an integer per-mille
Medicare is 1.45 percent. Expressed as an integer per-mille that is 14.5, which is not an integer — so a per-mille engine has to round the rate itself, and a rounded rate is wrong on every paycheck forever. This module takes the rate as an exact integer rational (145/10000, 62/1000, 9/1000) and floors the product, surfacing the dropped fraction. No rate is ever rounded. Social Security is capped against year-to-date wages; Medicare is uncapped; Additional Medicare is employee-only with no employer match, because that is the law and a symmetric implementation would have quietly over-charged the employer.
computeFicaEmployee · computeFicaEmployer
What it guarantees. Rates are held as exact integer RATIONALS — 145/10000, 62/1000, 9/1000 — and the product is floored with the dropped fraction surfaced. No rate is ever rounded, because 1.45 percent is 14.5 per mille, which is not an integer, and a rounded rate is wrong on every paycheck forever. Social Security is capped against year-to-date wages; Medicare is uncapped; Additional Medicare is employee-only with NO employer match, because that is the law and a symmetric implementation would quietly over-charge the employer.
What it refuses. Unsigned configuration withholds zero and names the reason.
back-office-payroll-fica.ts
No money. Unsigned config withholds zero.
Gross-to-net pay stub
The pay stub — one composed statement over the same primitives
The stub composition endpoint assembles the earning lines, the per-authority bases, the withholding lines and the net into a single statement, using the same primitives the individual endpoints expose. There is no second arithmetic path for “the stub version” of a number: if the FICA endpoint and the stub ever disagreed, one of them would be calling something that does not exist.
the gross-to-net stub composition endpoint
What it guarantees. The stub is assembled over the SAME primitives the individual endpoints expose — the earning lines, the per-authority bases, the withholding lines, the net. There is no second arithmetic path for “the stub version” of a number.
What it refuses. If the FICA endpoint and the stub ever disagreed, one of them would be calling something that does not exist. They cannot disagree, because there is only one implementation.
back-office-payroll-gross-to-net.ts
No money. A statement is not a payment.
NACHA structural proof
NACHA PPD — the batch is built and proven, and the file is withheld
The direct-deposit builder assembles a balanced NACHA PPD batch as fixed 94-character records and proves the structural invariants a receiving bank checks: every record exactly 94 ASCII characters; each routing number passing ABA mod-10 with the 3-7-1 weights, and a bad routing withheld and flagged rather than sent; the entry hash agreeing between batch control and file control; block-fill padded to a multiple of ten; a single balancing debit whose amount equals the sum of the credits exactly; a zero-dollar prenote that holds instead of settling. Then the endpoint withholds the raw file and returns the proof, with transmitted and railLive both false. No socket is opened. There is no originating bank.
buildBalancedPpdBatch · validateNachaRecords
What it guarantees. Fixed 94-character ASCII records; every routing number checked by ABA mod-10 with the three-seven-one weights; the entry hash taken modulo ten to the tenth and agreeing between batch control and file control; block-fill padded to a multiple of ten; a single balancing debit whose amount equals the sum of the credits exactly.
What it refuses. A failing routing number is WITHHELD from the batch and flagged rather than sent. A zero-dollar prenote HOLDS instead of settling. Then the endpoint withholds the raw file entirely and returns the structural proof with transmitted false and railLive false. No socket is opened anywhere in the module.
back-office-payroll-nacha.ts
Structural proof only. No file leaves. No money moves.
W-2 / W-3 / 941 reconcile
The three-way filing reconcile — the year has to agree, or it blocks
Before anything could be filed, one identity has to hold: the sum of every employee W-2 equals the W-3 transmittal equals the sum of the four quarterly 941s. If it does not, the reconcile blocks and shows the leg that disagrees. On top of that the per-W-2 box invariants: Box 3 never exceeds the annual Social Security wage base, Box 5 is uncapped, Box 1 excludes pre-tax deferrals while Boxes 3 and 5 include them (so Box 1 is at most Box 5 by construction), and the 941 fractions-of-cents drift is carried as an explicit adjustment line, never hidden and never force-balanced to make a total look tidy. This proves a filing set. It emits no form and transmits nothing.
What it guarantees. One identity has to hold: the sum of every employee W-2 equals the W-3 transmittal equals the sum of the four quarterly 941s. Per W-2: Box 3 never exceeds the annual Social Security wage base, Box 5 is uncapped, and Box 1 is at most Box 5 by construction because Box 1 excludes the pre-tax deferrals that Boxes 3 and 5 include.
What it refuses. If the three legs disagree the reconcile BLOCKS and shows which leg is out. The 941 fractions-of-cents drift is carried as an explicit adjustment line, never hidden inside another figure and never used to force a total to balance. It proves a filing set; it emits no form and transmits nothing.
back-office-payroll-filing-reconcile.ts
No money. Nothing is transmitted to the IRS or the SSA.
Four-eyes approval
Segregation of duties — four-eyes in the engine, not in the org chart
The approval decision refuses when the approver is the same person who assembled the run. Above a configurable total-gross threshold it requires a second, distinct approver who differs from both. And the approval binds to the register content hash: change a single line after sign-off and the hash changes, which invalidates the approval and forces a re-approve. Four-eyes written into a policy document is a hope. Four-eyes that fails closed in the function that returns the verdict is a control.
What it guarantees. The approver must differ from the person who assembled the run, and above a configurable total-gross threshold a second, DISTINCT approver is required who differs from both. The approval binds to the register CONTENT HASH.
What it refuses. Change one line after sign-off and the hash changes, which invalidates the approval and forces a re-approve. That closes the gap that makes most approval workflows theatre: approving a run and then editing it is the whole attack, and a status flag on a record cannot detect it.
back-office-payroll-sod-approval.ts
A decision, not a payment. This module commits nothing.
Employee self-service
Employee self-service — built end to end, and honestly inert
The self-service lane is built the whole way through: the decision module, thirteen registered endpoints, a web route, and a row-level isolation test. It is deny by default — a user may touch only the row whose employee reference equals their own server-resolved reference, a blank viewer authorizes nothing, and there is no widen path and no privileged branch anywhere in the lane. A direct-deposit submission is validated and returned, not stored: the routing number is checked against ABA mod-10, the account comes back masked to its last four digits, the full account is never echoed in any response, and the disbursement status is always honest-off. A W-4, direct-deposit or address submission computes a SHA-256 hash-chained audit event and returns it to the caller, with a one-way digest standing in for the sensitive value. Leave balances are counted in days, never money. Now the honest part, and it matters. Two things are missing, and they are the same kind of thing. The stub, W-2 and total-compensation views read pay tables that nothing in production writes, so they return an honest empty result until a run writer exists. And the change endpoints persist nothing at all — the repository behind this lane has five read methods and no write method, so a submitted election or address is validated, audited, returned, and then gone when the response ends. Built, wired, walled, and not switched on.
listOwnPayStubs · viewOwnPayStub · downloadOwnPayStub · viewOwnW2 · viewOwnTotalComp
What it guarantees. Deny by default: a user may touch only the row whose employee reference equals their own server-resolved reference. A blank viewer authorizes nothing, there is no widen path, no privileged branch and no employee picker anywhere in the lane. A direct-deposit submission is VALIDATED and RETURNED: the routing number is checked against ABA mod-10, the account comes back masked to its last four digits, and the full account is never echoed in any response.
What it refuses. Those five are the WHOLE repository interface, and that is the point of listing them: there is no write method at all. So a W-4, a direct-deposit election or an address change is validated, masked, audited and returned — and then gone when the response ends. The five read methods themselves read pay tables that nothing in production writes, so they return an honest empty result.
back-office-payroll-ess.ts
No account is ever debited or credited, and no election is stored.
Quarterly 941 read
The employer quarterly 941 — assembled from movements, filed nowhere
The quarterly return is built by reading recorded payroll movements out of the database and assembling the employer figures. It files nothing and transmits nothing, and it returns a clean service-unavailable when no database is provisioned rather than a plausible-looking zero. Same honest caveat as self-service: it reads a table that has no production writer today.
the quarterly 941 build and its feeder
What it guarantees. The employer quarterly figures are assembled by reading recorded payroll movements rather than by re-deriving them, so the return and the ledger cannot drift apart.
What it refuses. It returns a clean service-unavailable when no database is provisioned, rather than a plausible-looking zero. Same honest caveat as self-service: the table it reads has no production writer today.
back-office-payroll-941-940.ts / -941-feeder.ts
No money. No transmission.
Hiring and HR records
Hiring and HR records — the one lane in this whole category that actually persists
Job requisitions, the application funnel, stage advancement, the hiring-approval and hire decision, the pipeline board, and the HR dashboard are all reachable — and unlike every payroll surface above, this lane writes to the database. Employee records, staff credentials, professional development activity, job postings, applications, leave balances and leave requests all have real persistence behind them. If you are looking for the part of this product that is finished rather than proven, it is this one. Leave is tracked in days; nothing in it touches money.
saveEmployeeRecord · saveJobPosting · recordJobApplication
What it guarantees. These three are real writes through the canonical repository, not a second store invented for this lane. Employee records, staff credentials, professional-development activity, job postings, applications, leave balances and leave requests all have persistence behind them.
What it refuses. Nothing in this lane touches money, and leave is tracked in DAYS rather than converted to a dollar figure. One bound carried in the route module’s own header: the HR-officer capability is not yet plumbed into the session, so the gate that runs in practice today is the administrator tier rather than a distinct HR-officer role.
back-office-applicant-tracking.ts, hr-recruiting-funnel-ats.ts, hr-job-postings-catalog.ts
No money anywhere in the hiring or records lane.