Trial-Balance Roll-Forward

Architecture

Key specifications

What it does for you

Once a fiscal year the group rebuilds a workpaper it does not maintain in between: one column per entity, carried forward from last year's structure and repopulated from the year-end trial-balance extract. Entities dissolve and lose their columns, entities are renamed and must be carried exactly once, entities are formed and arrive with a registration date that starts their first period. Five failures hide inside that, and they share the property that makes them dangerous: the workpaper still balances. First, a column is populated from the wrong source column -- some books carry a monthly-activity figure beside the balance, and a harvest that reads by position takes movement instead of balances; activity foots to zero exactly the way balances do, so the column self-balances and the reviewer's whole defence passes. Second, a balance rides an equivalent chart code and disappears: two charts share one workpaper row, and dropping the equivalence strands a retained-earnings balance on a code the sheet displays but the sum ignores, while every column still foots. Third, the eliminations range excludes this year's columns, because a range written over last year's structure keeps evaluating without error after columns are inserted beyond its end. Fourth, the backup tab quotes the source's category column instead of its title column, so the evidence a reviewer lands on reads plausibly and reconciles to nothing. Fifth, the two rendered formats drift, and a repair applied to one leaves the other in circulation. Which return each entity owes is a separate engine's question. This is the workpaper underneath that filing, and none of it is a judgment call: it is a column located by its declared role, a sum against its constituent codes, a set compared in both directions, a range against a column list, and a figure against the row it links to -- which a deterministic control settles better than a sheet rebuilt each July.

The seeded demo runs every control over every workpaper file⁷. The CLI generates twenty-seven fictional workpaper files -- one clean baseline and one carrying each of the twenty-six planted defects -- then runs all twenty-four 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.

A column populated from the activity column still foots, and is caught anyway⁸. One planted defect repopulates the parent column from the book's monthly-activity column instead of its balance column, then rebuilds the combined column and the twin from those same wrong figures, exactly as a real workpaper would. The column still sums to zero, so the footing control stays silent -- a test asserts that silence, because if the footing check could catch this the basis control would be redundant. src_balance_basis catches it by re-deriving what the column would carry if populated from activity and finding that every differing row matches.

A dropped chart equivalence strands a balance while everything still balances⁹. The workpaper carries retained earnings on a legacy code that the chart map equates to the book's current code. One planted defect empties the equivalence list. The balance is then collected by no row at all -- and both the book and the column still foot, because the balance simply never arrives. Only the forward completeness sweep, which enumerates every nonzero book balance and asks which row collected it, reports the loss.

Functional block diagram

Instruction set

Benchmarks

Control characteristics

• Read-only: workpaper 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 cell, and a penny off the re-derivation is reported as a break.
• Every column is located by its declared role rather than its position -- the balance column by its role and the title column by its role -- because reading by position is the single error that produces all of the failures that still foot.
• One derivation kernel: the controls and the generator share rollforward_engine.workpaper, so a populated cell cannot disagree with the logic that produced it, and forward and reverse completeness cannot disagree about the same balance.
• A column populated from a monthly-activity column self-balances, and the suite asserts that the footing control stays silent on it -- so the basis control is proved to be doing work the footing check cannot.
• Completeness is swept in both directions: every nonzero book balance must land in a row, and every nonzero cell must trace back to a book.
• A dual-chart row carries the sum of every code it collects through the equivalence map, and each book code is consumed by exactly one row, so a balance can neither be stranded nor counted twice.
• A figure that should be integer cents but is not produces an AMOUNT_INVALID finding contained to the one cell it was read on, rather than being coerced into the number the engine is meant to audit.
• Every registration date is tested against the fiscal window the file carries, never against the system clock, so a run in a later year returns the same findings.
• 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 populates a workpaper, files a return, pays a fee or writes to a source artifact. It reads the workpaper file and stops.¹⁴
• It reads the seven artifacts the annual roll-forward emits. It does not connect to a general ledger, a spreadsheet, an entity-management system or any tax authority's filing channel.¹⁵
• It does not decide which return an entity owes or when it is due. That is a filing-calendar question and a separate engine's; this engine is the workpaper the filing is prepared from and nothing more.¹⁶
• It audits the extract it is given. If a book is missing from the extract entirely, the register control reports the column that names it, but the engine cannot know that a book which is present is complete -- only that it foots and that the workpaper ties to it.¹⁷
• It applies the statuses, the fixed fee and the review band the file itself carries; it does not decide whether an entity's status is correct in law or whether the fee is the figure the jurisdiction currently charges. All shipped data is fictional -- the groups, entities, books, chart codes, balances and dates are invented, and the fiscal year is set in a fictional future.¹⁸

See it run

Integration

Distribution: public repository, MIT license.