Federal tax / Library

The federal tax engine as a library

The engine behind POST /api/federal-tax is also a library you run inside your own application (libfedtax 1.0.0, engine 1.3.0, tax year 2026): the same C code, the same rules, the same citations and the same output, byte for byte. No network call, no per-request latency, and no household data leaving your system. It is the sibling of the state tax engine library.

One engine, two doors

The JSON entry point (qcft_compute_json) is the API's own request parser, field table, engine call and response builder, compiled unchanged: for any request it returns the bytes the API returns, including the 400 body of a refusal. The schema and rules documents (GET /api/federal-tax/schema and /rules) are there too, byte for byte. The typed entry point (qcft_compute) takes a C struct and returns the result's figures; it runs the API's own parser and evaluator on the request, so a refused typed request carries the API's message.

What you get

Thin bindings for Go, Rust, Java, .NET and Swift call the JSON entry point of the same shared library. Sizes measured on the 1.0.0 release build (engine 1.3.0) of 2026-09-28; every artefact is rebuilt byte for byte from the same sources, with SHA-256 checksums and a manifest of the pinned toolchains.

Without the citations

Each full response carries the official sources of every step on the return, with their checked quotes. A build without them answers every request as the full library does, minus rules.sources and rules.unsourced (the blocks includeSources: false leaves out); every figure is the same. The sources stay published on the sources page.

Size budgets are enforced on every release build (bytes, measured and budget):

The typed request

The typed request is generated from the API's field table, so it has one member per request field and nothing else. When the API gains a field, a regeneration and a rebuild add it at the end of the struct, and the build fails until that is done. The offsets below are the library's binary interface: they never move within a major version.

With the state engine

The state tax library (libstatetax 1.6.0) carries this engine: its JSON entry point answers computeFederal: true as POST /api/state-tax does, with the federal engine supplying the federal figures the state rules read. It is one binary, so the two engines are always the same version.

The same answer, checked on every build

A parity gate runs on every build. On 2026-09-28 (engine 1.3.0) it sent a generated corpus of 16,551 requests (13,478 computed, 3,073 refused: every filing status and age gate, every one of the 56 request fields at and past its limits, extended returns, every refusal the API makes, malformed bodies) through four surfaces: the C library, the WebAssembly package, the Python package and the API's own request handler. All four must produce the same bytes for every request, and the 11,300 requests the typed entry point can express must give the same document through it. The build also runs the whole test suite under address, undefined-behaviour and thread sanitizers, fuzzes both entry points, and checks that the binary exports only its own functions.

Performance

Measured 2026-09-28 (engine 1.3.0) on Intel Core i7-12800H, one core; 1,547,861 typed calls a second on 8 threads.

Most of a JSON call is building and printing the document, and the sources are most of the document: send includeSources: false, or use the typed entry point, when a response does not need them.

Versions and updates

The library version follows semantic versioning (additions are minor versions; a break is a new major version with a new shared-library name); the engine version, reported as engineVersion, moves whenever a rule, rate or threshold moves; the tax year is the law the build encodes.

Licence

The library is licensed commercially. Ask at [email protected].