ENGINE 47

SFS-E47-IRN · INFORMATION RETURNS · REV 2026-07-24 · PRODUCTION

PRODUCTION = runnable end-to-end, CI-backed, full test suite passing. All data fictional and seeded.

Information Return Issuance

Was a form issued exactly where one was owed, and does every box foot?

Once a year the group rebuilds a population it never maintained: every payee it paid something reportable to, reassembled entity by entity -- interest to lenders and affiliates, non-employee compensation to vendors, card and third-party settlement. A box catalog carries a threshold per box. A ledger extract carries every payment line. A form register carries what was actually issued, with the payer's taxpayer number, the payee's, the box amount and any backup withholding. A transmittal per entity accompanies the forms and an annual rollup adds the transmittals together. This engine reads the eight artifacts that record emits -- the entity register, the payee register, the box catalog, the ledger extract, the form register, the transmittal register, the threshold watchlist and the issuance report -- and runs twenty-two deterministic controls over them. Is the reporting file complete and the year readable, are the payer entity ids unique and every payer identified, are the payee ids unique, is every payee type known and is every taxpayer number on file readable, is every catalogued box a known return series defined once with a usable threshold, is every payment line attributable, non-negative integer cents and inside the reporting year, is every form complete, correctly attributed to its payer, unduplicated and footed to the ledger beneath it, is a form issued exactly where one is owed and never where one is not, what sits just under a threshold, does backup withholding recompute at the statutory rate in both directions, and do the transmittals, the annual rollup and the watchlist foot the forms. Every box is compared with exact == in integer cents, withholding is applied with truncating basis-point arithmetic, every payment line is tested against the reporting year the file carries rather than the system clock, and no source artifact is ever written.

A payee who should have been reported and was not leaves nothing behind to notice. The payments posted, the invoices closed, and the omission exists only in a population nobody re-ran -- because the ledger was never organised around who has to receive a form. That is the failure the annual cycle is most exposed to, and its exact complement is the one usually left unbuilt: a form issued where none was owed is not harmless excess, it reports a payee who was not reportable and leaves that payee reconciling a statement against a return that should never have been filed. Between them sits the threshold, met at the cent, and a second obligation that overrides it entirely -- where a box attracts backup withholding and the payee has no taxpayer number on file, tax is withheld and withheld tax is reported however small the payment was. Then the arithmetic: a box amount re-keyed from a summary rather than footed from the entity's own payment lines, and a transmittal whose count or total is maintained beside the register rather than struck from it, so the one page the authority reads first disagrees with the forms behind it. The engine defines the issuance predicate exactly once and has both the generator and the controls import it, so a form cannot disagree with the logic that produced it. It foots every box to its payment lines, recomputes withholding in both directions, tests completeness and excess as complements, and ships a planted-defect file for every registered control -- with a real row sitting on the threshold to the cent and another owed a form only because withholding attached.

Run it Book a consultation

Architecture

functional block stack · static overview

Select a layer

Nine control families run in registry order over each reporting file. The first proves the others had something to read and that the reporting year is legible, because a control that passes on absent evidence reports assurance it never performed.

Key specifications

at a glance

10,382¹

Tests

the collected checks that pin this engine's behavior

22²

Controls

independent rules run over every reporting file

9³

Families

groups of controls, each answering one question

24⁴

Reporting files

one clean baseline plus twenty-three planted-defect files

8⁵

Artifacts read

entity register, payee register, box catalog, ledger extract, form register, transmittal register, threshold watchlist, issuance report

0⁶

Tolerance

a box amount a cent off its re-derivation is a break, not a rounding band

What it does for you

plain terms

Once a year the group reassembles, entity by entity, the payees it paid something reportable to -- interest to lenders and affiliates, non-employee compensation to vendors, card and third-party settlement -- applies the box threshold, issues a form, and reconciles each box back to the payment lines it came from. Three failures hide inside that, and none of them look wrong in a ledger that was never organised around who has to receive a form. First, the population has a hole in it: a payee clears a threshold in one entity and is never cut a form, and nothing in the ledger notices, because the payments posted and the invoices closed and the omission exists only in a population nobody re-ran; the same hole appears in reverse when a payee has no taxpayer number on file and nothing is withheld against it. Second, a box amount stops being footed: the figure on the form is re-keyed from a summary rather than added from the entity's own payment lines, so the form goes out reporting an amount the ledger does not support and the payee reconciles against it. Third, the transmittal stops tying the forms: the count or the total is maintained beside the register rather than struck from it, so the one page the authority reads first disagrees with the forms behind it. Approving and releasing a disbursement is a separate engine's question, and that engine explicitly declines to ask whether what it released was reportable. This is that question, asked once a year over the whole population, and none of it is a judgment call. It is a threshold met at the cent, a shape test on an identifier, a sum against its line items, a rate applied at the statutory figure, and a count against a recount -- which a deterministic control settles better than a spreadsheet rebuilt each January.

The seeded demo runs every control over every reporting file⁷. The CLI generates twenty-four fictional reporting files -- one clean baseline and one carrying each of the twenty-three planted defects -- then runs all twenty-two 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 threshold is met at the cent, and a cent under it is not⁸. The clean corpus has one entity paying a payee exactly the non-employee threshold, and a form is issued for it -- met at the cent is met. A boundary test takes one cent off that payment and the form on the register stops being owed, so thr_no_unrequired_form reports it by form id. The two controls are exact complements resolved through one predicate, so completeness and excess cannot disagree about the same row.

Withheld tax obliges a form the threshold would not have⁹. One payee with no taxpayer number on file is paid far under the box threshold, and a form is still owed, because the box attracts backup withholding and withheld tax is reported however small the payment was. A boundary test puts a number on file for that payee and the same form stops being owed, which is what proves the override is doing the work rather than the threshold.

Functional block diagram

engineering · each block links to its source

Plain terms

Seeded Reporting Files. fictional annual information-return files enter the control registry
Structural Precondition. is the reporting file complete and the year legible
Payer Entity Register. is every filing entity unique and identified
Payee Population. is every payee unique, typed and readable
Box Catalog. is every box a known series with one usable threshold
Ledger Extract. is every payment line attributable, valid and in year
Form Register. is every form well-formed, attributed, unique and footed
Threshold and Issuance. is a form issued exactly where one is owed
Backup Withholding. does the statutory rate recompute in both directions
Transmittals and Rollup. do the transmittals and the annual rollup foot the forms
Catalog, Ledger & Registers. the artifacts and thresholds every rule resolves against
Verdict and Findings. every finding, with the reason it exists, ends at a person

Engineering

Seeded Reporting Files. generate_corpus writes one clean baseline plus one planted-defect file for every registered control, twenty-four files in total. Only the entities, the payees, the box catalog and the individual payment lines are stated; every box amount, every issuance decision, all backup withholding, both transmittal totals and the annual rollup are re-derived through the same issuance kernel the engine later recomputes with, so the relationships the engine tests are the relationships that produced the data. The corpus deliberately puts real rows on the edges that matter: one entity pays a payee exactly the non-employee threshold to the cent, one payee with no taxpayer number is paid far under a threshold and is owed a form only because withholding attached, and one payee is paid well under its threshold and owes nothing and raises no flag.
Structural Precondition. One control. FAILs a file missing any of the eight artifact types or carrying a duplicate of one, and FAILs an unreadable reporting year, so no downstream rule holds vacuously on absent evidence.
Payer Entity Register. Two controls: entity ids are unique, and every entity carries a well-formed taxpayer number, since a return filed in the name of an unidentifiable entity cannot be matched.
Payee Population. Three controls: payee ids are unique, every type is one of lender, affiliate, vendor or settlement entity, and every taxpayer number on file is well-formed -- a payee with no number at all belongs to the withholding control instead.
Box Catalog. Two controls: every catalogued row names a known return series and a non-negative integer-cent threshold, and no box is defined twice -- a duplicate makes the threshold every issuance decision turns on ambiguous.
Ledger Extract. Three controls: every line names a declared entity, payee and box, every amount is non-negative integer cents, and every date falls inside the reporting year inclusive of both endpoints.
Form Register. Four controls: the required fields are present, the payer on the form is the payer on the register, no payee is issued the same box twice, and every box amount re-sums the entity's own payment lines for that payee and box with exact ==.
Threshold and Issuance. Three controls: a payee/box total that obliges a return has a form, no form is issued where none is owed, and a payee inside the file's own review band below a threshold is flagged. All three resolve through the single issuance predicate, so completeness and excess cannot disagree.
Backup Withholding. One control: where the box withholds and no taxpayer number is on file, the statutory rate applied to the reported amount with truncating basis-point arithmetic; where a number is on file, exactly zero. Both failures surface from the same re-derivation.
Transmittals and Rollup. Three controls: each entity's transmittal count and totals are re-struck from the forms it accompanies, the annual issuance report is re-struck across every form, and the threshold watchlist is rebuilt and reported in both directions.
Catalog, Ledger & Registers. The entity register carries each filing entity's id, name and payer taxpayer number; the payee register carries each payee's id, name, type and taxpayer number where one is on file; the box catalog carries each box's return series, label, threshold in cents and whether it attracts backup withholding; the ledger extract carries every payment line with its entity, payee, series, box, amount and paid date; the form register carries every issued form with both taxpayer numbers, the box amount and the withholding; the transmittal register carries each entity's form count and totals; and the file itself carries the reporting year, the statutory withholding rate in basis points and the review band in cents. Every issuance, withholding and tie-out control resolves against these through the shared issuance kernel.
Verdict and Findings. Findings roll up per reporting file: any FAIL is FAIL, FLAGs without FAILs are REVIEW, clean is PASS. The CLI exit code is the verdict, so a pipeline can gate on it. Reports carry no timestamps or absolute paths, which is what makes the committed report diffable -- a change in the diff is a change in the controls, not a change in when the report was run.

Instruction set

every public command

Command	Operation	Output	Exit	Artifacts
`python run.py`	regenerate the seeded fictional corpus, run all twenty-two controls, write both reports	per-file verdicts and every actionable finding, then the overall verdict	2 for the bundled corpus, which carries a planted defect for every control by design	inforeturn_report.json, inforeturn_report.md, samples/
`python -m inforeturn_engine samples`	analyze an existing folder of reporting files without regenerating it	per-file verdicts and findings	0 PASS / 1 REVIEW / 2 FAIL / 3 usage	none unless --json or --md is passed
`python -m inforeturn_engine samples --generate --quiet`	regenerate the corpus and print only the overall verdict	a single verdict line	0 PASS / 1 REVIEW / 2 FAIL / 3 usage	samples/
`python -m pytest inforeturn_engine/tests -q`	run the full test suite for this engine	10382 passed	0 when every test passes	none

Benchmarks

measured demo results

Measure	Result
Engine tests¹⁰	10,382 tests collected live collection from the engine directory
Registered controls¹¹	22 controls counted from the registry, not from documentation
Planted defects¹²	23 defect files every registered control has at least one file that trips it
Control coverage¹³	100 percent of controls with a planted defect no control ships without a file demonstrating it firing

Control characteristics

engineering

Plain terms

The engine has no write path and therefore no autonomy to gate. It produces findings; a person decides whether a form is issued, a transmittal is filed and withholding is remitted.

Engineering

Deterministic envelope. seeded fictional inputs, read-only operation, offline default mode.

Demo gate. FAIL on the bundled corpus, by design -- it carries a planted defect for every registered control

Severity	Verdict	Action
No findings above PASS	PASS	carry the mechanically clean population into the documented information-return review and sign-off before the forms go out
One or more FLAG, no FAIL	REVIEW	a human resolves each flag; a payee sitting inside the review band below a threshold and a watchlist that disagrees with the population both land here
One or more FAIL	FAIL	no form is issued and no transmittal filed until the failing control is cleared -- a payee owed a form who has none, a form owed to nobody, a box that does not foot to its payment lines, withholding that does not recompute, or a transmittal that does not tie

Read-only: reporting 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 box amount, and a cent off the re-derivation is reported as a break.
One issuance predicate: the controls and the generator share the kernel in inforeturn_engine.issuance, so a form cannot disagree with the logic that produced it, and completeness and excess cannot disagree about the same row.
The box threshold is met at the cent -- a year total of exactly the threshold is reportable and a cent under it is not -- and the corpus puts a real row on that edge.
Withheld tax obliges a form the threshold would not have: where a box attracts backup withholding and no taxpayer number is on file, a form is owed however small the payment was.
Backup withholding is applied with truncating basis-point arithmetic, so the reported figure can be compared to the derived one with exact ==; a negative amount withholds nothing.
A payee with no taxpayer number is a withholding case, not a data-quality exception; an unreadable number is the exception, because it counts as on file and suppresses the withholding that should have been taken.
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 payment line is tested against the reporting year 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

what it refuses to do

The engine never issues a form, files a transmittal, remits withholding or writes to a source artifact. It reads the reporting file and stops.¹⁴
It reads the eight artifacts the annual issuance record emits. It does not connect to a general ledger, an accounts-payable system, a payment rail, or any tax authority's filing channel.¹⁵
It does not ask whether a payment should have been made or approved. Releasing a disbursement is a separate engine's question, and that engine explicitly declines to ask whether what it released was reportable; this engine is that second question and nothing more.¹⁶
It tests a taxpayer number for shape only. A well-formed number is not a verified one and the engine makes no claim that it is -- but a number that cannot be parsed is one that was never captured, and every downstream treatment turns on whether it is there.¹⁷
It applies the thresholds and the withholding rate the file's own box catalog carries; it does not decide whether those are the figures the statute provides for, nor whether a payee's type is the correct classification in law. All shipped data is fictional -- the groups, entities, payees, taxpayer numbers, box catalog, payments and issue dates are invented, the taxpayer-number format is deliberately unlike any real identifier, and the reporting year is set in a fictional future.¹⁸

See it run

control architecture

Corporate obligation-matrix architecture for Information Return Issuance: entity and document records pass through jurisdiction and policy controls to verified reporting evidence. — The Information Return Issuance engine tile states the question the annual cycle turns on: every box footed back to the payment lines it came from, a form issued exactly where one is owed and nowhere else, withheld tax reported however small the payment was, and every transmittal recounted from the forms behind it.

Integration

how to run it

Distribution: public repository, MIT license.

python run.py

python -m pytest inforeturn_engine/tests -q

Source on GitHub Engine README All tests, by engine Run in Codespaces

Substantiation

1python -m pytest --collect-only -q -o addopts= (info-return-automation/)
2len(inforeturn_engine.engine.REGISTRY)
3distinct rule-id prefixes in inforeturn_engine.engine.REGISTRY
4samples/*.json after python run.py
5len(inforeturn_engine.model.DOC_TYPES)
6inforeturn_engine/tests boundary tests on the cent, the day and the taxpayer-number digit
7python run.py (info-return-automation/); inforeturn_engine/tests planted-defect suite
8inforeturn_engine/tests test_a_total_exactly_on_the_threshold_owes_a_form and test_a_cent_under_the_threshold_owes_nothing
9inforeturn_engine/tests test_withholding_attaches_below_the_threshold and test_giving_the_withheld_payee_a_number_makes_its_form_unrequired
10python -m pytest --collect-only -q -o addopts= (info-return-automation/)
11len(inforeturn_engine.engine.REGISTRY)
12len(inforeturn_engine.generate.DEFECTS)
13inforeturn_engine/tests: every registered rule has a planted defect
14info-return-automation/README.md and inforeturn_engine read-only / determinism tests
15inforeturn_engine/model.py DOC_TYPES
16info-return-automation/README.md scope statement
17inforeturn_engine/issuance.py tin_well_formed
18inforeturn_engine/generate.py

Show us where the hours go.

One conversation: you describe the work that consumes your team's month; we tell you plainly what this engine can take over, what it can't, and what a scoped first phase would cost. Your people keep approval authority.

Book a free consultation