Purpose
Tax preparation needs a computation you can audit. A model may help someone find and interpret a rule, but the number on the return has to come from deterministic code with the source it used attached.
PreviewPythonFastAPIPostgreSQLRetrieval
Filing Harbor
A deterministic Form 1040 workspace: typed taxpayer facts, cited IRS sources, reviewed calculations, and a NOT FOR FILING export.
Case summary
System
Filing Harbor keeps every taxpayer fact typed, provenance-tagged, and reviewed before deterministic services compute eligibility, tax, credits, and payments. Retrieval returns exact citations with hashes and page ranges, and the export is watermarked NOT FOR FILING.
Contribution
Deterministic tax-engine architecture, fact provenance and review model, retrieval citation contract, source-grounded acceptance criteria, and the deployment pipeline; implementation is directed and reviewed against those constraints.
Deterministic boundary
Models may help read a rule; the return arithmetic and its citations are deterministic.
typed facts
deterministic services
1040 lines
review gate
NOT FOR FILING export
Problem
- A plausible number is not an auditable number.
- Retrieval without exact citations invites fabricated tax rules.
- Filing readiness must be a visible gate, not an assumption.
Technical Highlights
- Typed canonical fact paths with entry provenance and review state
- Deterministic Form 1040 computation with no model or network dependence
- IRS source retrieval that returns citations, revisions, hashes, and page ranges
- Review state that blocks export until facts are confirmed
- NOT FOR FILING export with source and output hashes
- Browser-ephemeral authentication preview; the full hosted tax workflow is not yet available
System Design
- facts -> deterministic services -> 1040 lines -> review gate -> NOT FOR FILING export
- Retrieval attaches an exact source record to every rule it surfaces.
- The hosted demo profile keeps no uploads, downloads, or persistent returns.
Deterministic Authority
- Eligibility and filing-status rules
- 1040 line computation
- Review-state gating
- Export assembly and watermarks
Where Models Fit
- Optional retrieval and explanation assistance near cited sources; never the arithmetic on the return.
Trust, Failure & Recovery
- Migration-backed schema with documented rollback.
- Backlog tests are executable acceptance contracts.
- The demo profile is a single-process, non-persistent deployment.
Measured evidence
Current hosted demo verification
not yet publishedRecord the deployed revision, container health, and the reviewed demo-profile capability set for the current commit.
No synthetic accuracy or performance metric is published for this case.
n=not measured
evidence method/source