Unit Sales & Commission Tie-Out

Architecture

Key specifications

What it does for you

A residential for-sale project -- condo or townhome -- is administered out of one workbook, instantiated from the same template on every project, and the same three failures recur in each instantiation. The Matrix tab carries every unit: plan, plan square footage, list price, sales price, concession, revenue per square foot, closing costs and total selling commission. The Sold/Close tab logs the offer date, the actual date sold, the closing date and whether proof of closing came back. The Commission Log splits each unit's total commission across the named selling agents who earned it. First, a derived column stops deriving: revenue per square foot, net proceeds and total commission are formulas until somebody types over one of them for a single unit, and from then on the column is a mixture of computed and typed figures that no longer follows from the prices beside it -- and the mixture is invisible on a printed tab. Second, the commission splits stop adding up: the log pays named agents, the sum of the splits on a unit is meant to be the total the Matrix authorised, and a split edited after the fact or an agent added without reducing another leaves the log paying an amount no row ever approved. Third, the tabs stop reconciling: a unit is marked sold and never reaches the Sold/Close tab, a closing is logged with the sale date before the offer date, or the rollup that leaves the sales office states a count and a revenue total the Matrix does not support. None of these are judgment calls. They are equalities and comparisons -- a stated figure against its re-derivation with exact == in integer cents, a set of splits against the total it divides, a set of sold ids against a set of closing ids in both directions, three dates against each other with <= -- which a deterministic control settles better than a workbook inherited by whoever administers sales this quarter.

The seeded demo runs every control over every sales file⁷. The CLI generates twenty-three fictional sales files -- one clean baseline and one carrying each of the twenty-two planted defects -- then runs all twenty-one controls over each. The clean file returns PASS with no flags; every defect file returns REVIEW or FAIL and names the control it tripped along with the reason that control exists.

The splits are compared against the row that authorised them⁸. A defect file shortens one agent's split on UNIT-105 by a hundred dollars and leaves every other figure untouched, so the Commission Log still looks internally orderly and the Matrix still foots. comm_splits_tie sums the three logged splits on the unit, compares them in integer cents with exact == to the total commission the Matrix row authorised, and reports the shortfall against the row that approved it.

The Sold/Close reconciliation runs both ways⁹. One defect file deletes the closing row for UNIT-104 while the Matrix still marks it sold, and close_sold_reconciles reports revenue the Matrix claims that the tab cannot evidence. The same control tests the other direction on every file -- a closing row for a unit the Matrix does not call sold -- which is the harder break to notice and the one that leaves a settled sale out of the period.

Functional block diagram

Instruction set

Benchmarks

Control characteristics

• Read-only: sales files are parsed and never written back, so the engine cannot introduce the break it reports.
• Integer cents throughout, compared with exact ==; there is no tolerance band on a derived figure, and a cent off the re-derivation is reported as a break.
• One tie-out kernel: the controls and the generator share the arithmetic in sales_engine.tieout, so a derived column cannot disagree with the data that produced it.
• Truncation is the contract in both directions -- revenue per square foot floors and the commission rate is applied with truncating basis-point arithmetic -- so a derived figure can be compared to the stated figure with exact ==.
• A figure that should be integer cents but is not produces an AMOUNT_INVALID finding contained to the one row it was read on, rather than being coerced into the number the engine is meant to audit.
• Every closing and proof test is measured to the review date the file carries, never to the system clock, so a run in a later month returns the same findings.
• Commission splits are allocated by the largest-remainder method, so the residual cent lands on one named agent rather than disappearing into the rounding.
• Deterministic and byte-stable: same inputs produce the same findings in the same order, with no timestamps or absolute paths in any output.
• Absent evidence is never a passing control; a missing artifact fails completeness rather than letting the controls that read it pass unread.

Operating limits

• The engine never posts a journal entry, releases a commission payment, files a closing statement or writes to a source artifact. It reads the sales file and stops.¹⁴
• It reads the seven artifacts the sales-administration record emits. It does not connect to a general ledger, an escrow or title system, a payroll or commission-payment run, or the underlying purchase contracts.¹⁵
• It proves the Matrix is internally true, not that a price was the right price or that a discount past the approved band should have been granted. Whether a struck price is commercially sound is a judgment the flag routes to a person.¹⁶
• It re-derives every commission at the basis-point rate the file's own commission schedule carries for the unit's sale channel; it does not decide whether that rate, that channel or that split weight is the one the agent's agreement provides for.¹⁷
• It takes the Sold/Close records at face value: it confirms the tabs reconcile and the dates run forward, not that a sale or a settlement actually occurred. All shipped data is fictional -- the developers, projects, plans, unit numbers, selling agents, prices and closing dates are invented, and the sales period is set in a fictional future.¹⁸

See it run

Integration

Distribution: public repository, MIT license.