Crate btctax_forms 

btctax-forms — fill the OFFICIAL IRS fillable PDFs (Form 8949 + Schedule D) from btctax’s already-computed tax data. Offline, deterministic, and geometry-verified: every fill is read back from its own serialized bytes and each value’s widget /Rect is checked against a map-independent column/row band re-derived from the PDF itself. A mis-mapped cell fails closed.

Sub-project 1 (TY2025)

• Form 8949 — Bitcoin under Box I (short-term) / Box L (long-term), the 1099-DA revision (NOT Box C/F, which read “other than digital asset transactions”). 11 rows per part per page.
• Schedule D — lines 3 & 7 (ST), 10 & 15 (LT), 16 (total), QOF = No. Lines 17-22 are scoped out (the caller prints a notice).
• These are static XFA-hybrid PDFs: the fill removes the /AcroForm /XFA layer (else Acrobat shows blank), sets /NeedAppearances, and pins determinism (drops /Info dates + the trailer /ID).

The tax data is REUSED verbatim from the projection (btctax_core::form_8949 / btctax_core::schedule_d) — this crate never recomputes gains.

Modules

testonly

Structs

Form1040Fill

The result of a Form 1040 cap-gains fill: the bytes + what was actually written (drives the CLI’s partial-scope + loss notices).

Form1040Inputs

The btctax-evidenced signals that drive the two Form 1040 cells.

Form1040Map

Form8275Map

The Form 8275 (Disclosure Statement, Rev. 10-2024) field map. One revision, aliased to every SUPPORTED_YEAR — see F8275_MAP_2024.

Form8283Map

The Form 8283 (Rev. 12-2025) field map for one tax year.

Form8949Map

The full Form 8949 field map for one tax year.

Form8959Map

The Form 8959 (Additional Medicare Tax) field map for one tax year.

Form8960Map

The Form 8960 (Net Investment Income Tax) field map for one tax year.

Form8995Map

The Form 8995 (QBI deduction, simplified) field map for one tax year.

PartIiOverflow

Detail for a narrative that will not fit — everything a caller needs to build a helpful refusal (see btctax-forms::part_ii_capacity_check, used by btctax-cli’s export pre-flight).

Schedule1Map

The Schedule 1 (Additional Income and Adjustments to Income) field map for one tax year.

Schedule2Map

The Schedule 2 (Additional Taxes) field map for one tax year.

Schedule3Map

The Schedule 3 (Additional Credits and Payments) field map for one tax year.

ScheduleAMap

The Schedule A (Itemized Deductions) field map for one tax year.

ScheduleBMap

The Schedule B (Interest and Ordinary Dividends) field map for one tax year.

ScheduleCMap

The Schedule C (Profit or Loss From Business) field map — the crypto trade or business.

ScheduleDMap

The Schedule D field map for one tax year.

ScheduleSeMap

The Schedule SE (Form 1040) field map for one tax year — the filled §1401 line chain.

Enums

FormsError

Anything that can go wrong filling an official IRS PDF.

PartIiCapacity

The verdict [part_ii_capacity_check] returns.

Constants

SE_FLOOR

The §1401 net-earnings STOP floor: Schedule SE is not owed when line 4c (base) is below $400.

SUPPORTED_YEARS

The tax years this build bundles forms + maps for. Each fill dispatches to the year’s committed map + bundled PDF via the Map::for_year constructors; an unlisted year fails closed with FormsError::UnsupportedYear.

Functions

fill_8949_full

Fill the full-return Form 8949 for year from the core-derived printed chain (btctax_core::tax::printed::form_8949_printed). Whole dollars, and column (h) is DERIVED from the printed (d) − (e). Schedule D lines 3/10 ARE this form’s printed column totals.

fill_form_8275

Fill Form 8275 (Disclosure Statement) for year from the T13 printed disclosure (btctax_core::tax::printed::printed_8275) + the FILER’s identity. Ok(None) when there is no Part I content to disclose.

fill_form_8283

Fill Form 8283 (Noncash Charitable Contributions, Rev. 12-2025) for year from the projected donation rows + DonationDetails. Returns Ok(None) when there are no donations in the year. Fills the donee/appraiser IDENTITY + per-row property data (and, for Section B, checks the “k Digital assets” property-type box); leaves BLANK every OTHER party’s declaration/signature (a LOUD partial-scope notice is the caller’s). More rows than a section holds (4 in Section A / 3 in Section B) overflow onto additional form copies via [overflow::merge_copies].

fill_form_8949

Fill Form 8949 (Part I + Part II) for year from the projection rows and return the PDF bytes. The box is year-aware: Bitcoin is filed under the digital-asset Box I/L from TY2025, and the securities Box C/F on the pre-2025 revisions. Parts that overflow the revision’s grid (11 rows per part on the 2025 form, 14 on 2024/2017) paginate: ⌈rows/grid⌉ page copies per part, each with its own totals; the copies are merged with per-copy field renaming so no two share a value. Every copy is geometry-verified before merge.

fill_form_8959

Fill Form 8959 (Additional Medicare Tax) for year from the core-derived line chain (btctax_core::tax::other_taxes::form_8959_lines). Returns Ok(None) when the form is not required — line 18 (the tax) AND line 24 (the withholding reconciliation) are both zero.

fill_form_8960

Fill Form 8960 (Net Investment Income Tax, §1411) for year from the core-derived line chain (btctax_core::tax::other_taxes::form_8960_lines, which returns None when no NIIT is owed — there is then no form to file).

fill_form_8995

Fill Form 8995 (QBI deduction, simplified) for year from the core-derived line chain (btctax_core::tax::qbi::form_8995_lines, which returns None when there is no QBI).

fill_form_1040_capgains

Fill the capital-gains cells of Form 1040 for year: line 7a (only when Schedule D is ACTIVE and line 16 ≥ 0; active-and-zero → “-0-”) and the Digital-Asset Yes/No question (YES iff there is btctax-evidenced qualifying activity). Returns Ok(None) — skip the whole 1040 — when there is no reportable activity (the DA answer would be blank and there is no 7a value). 7b checkboxes are left untouched; a NET LOSS leaves 7a blank (the §1211 line-21 cap is the filer’s). A partial-scope notice enumerating exactly what was filled is the caller’s.

fill_form_1040_full

Fill the FULL-RETURN Form 1040 for year from the core-derived printed chain (btctax_core::tax::printed::form_1040_lines) — every line, not just the capital-gain cluster.

fill_form_8275_slice

Fill Form 8275 for year on the crypto-slice export-irs-pdf path (Task 16) — NO filer identity (mirrors fill_form_8283, whose crypto-slice fill also writes no identity block): the disclosure still rides the export even when there is no ReturnInputs on file. Ok(None) when there is no Part I content to disclose.

fill_form_8283_full

Fill the full-return Form 8283 for year — whole-dollar rows plus the FILER’s identity block (which the crypto slice never writes). Ok(None) when there are no donation rows.

fill_schedule_1

Fill Schedule 1 (Additional Income and Adjustments to Income) for year from the core-derived printed chain (btctax_core::tax::printed::schedule_1_lines, which returns None when there is neither additional income nor an adjustment — the schedule is then not filed).

fill_schedule_2

Fill Schedule 2 (Additional Taxes) for year from the core-derived printed chain (btctax_core::tax::printed::schedule_2_lines, which returns None when there are no other taxes to report — the schedule is then not filed).

fill_schedule_3

Fill Schedule 3 (Additional Credits and Payments) for year from the core-derived printed chain (btctax_core::tax::printed::schedule_3_lines, which returns None when there is neither a foreign tax credit nor an excess-Social-Security credit).

fill_schedule_a

Fill Schedule A (Itemized Deductions) for year from the core-derived printed chain (btctax_core::tax::printed::schedule_a_lines, which returns None unless the return actually itemizes — Schedule A is computed even when the standard deduction wins, but only FILED when it is the deduction claimed).

fill_schedule_b

Fill Schedule B (Interest and Ordinary Dividends) for year from the core-derived printed chain (btctax_core::tax::printed::schedule_b_lines, which returns None when Schedule B is not required — interest and dividends both at or under $1,500 and no declared foreign account).

fill_schedule_c

Fill Schedule C (Profit or Loss From Business) for year from the core-derived printed chain (btctax_core::tax::printed::schedule_c_lines, which returns None when there is no crypto trade or business).

fill_schedule_d

Fill Schedule D for year from the part totals and return the PDF bytes.

fill_schedule_d_full

Fill the FULL-RETURN Schedule D for year from the core-derived printed chain (btctax_core::tax::printed::schedule_d_lines), including Part III’s SPEC §7.2 routing.

fill_schedule_se

Fill Schedule SE (Form 1040) for year from the computed §1401 SeTaxResult, the filer’s Form W-2 Social Security wages (line 8a), and the year’s Social Security wage base (line 7). Returns Ok(None) when net SE earnings are below the $400 floor (no SE tax owed — the form is not written). Line 12 = SS + regular Medicare only (the 0.9% Additional Medicare Tax is a Form 8959 item, not on Schedule SE); when se.addl > 0 the caller prints a Form 8959 advisory.

fill_schedule_se_full

Fill the full-return Schedule SE for year from the core-derived printed chain (btctax_core::tax::printed::schedule_se_lines). Whole dollars — the crypto slice’s fill_schedule_se keeps its exact-cents rendering and is untouched.

part_ii_capacity_check

Whether a Form 8275 Part II narrative fits year’s bundled revision, WITHOUT filling anything — runs the identical wrap the real fill does, so a caller can pre-flight BEFORE writing any packet file (T-f8275-part-ii-overflow round 2 finding 2). See [form8275::part_ii_capacity_check]’s doc comment for the full rationale.

rows_possibly_broker_reported

[I5] How many rows might belong on a SEPARATE broker-reported Form 8949 — i.e. disposals on an exchange that may have issued broker basis reporting. The separate boxes and this export’s filed boxes are year-aware (see btctax-cli’s broker_reporting_advisory): a 1099-B / Box A/B/D/E, filed under C/F pre-TY2025; a 1099-DA / Box G/H/J/K, filed under I/L from TY2025. A non-zero count is a loud advisory, not a refusal.

stamp_draft_watermark

Stamp a diagonal DRAFT — ESTIMATE, NOT FOR FILING watermark on every page of a filled form. Applied by the CLI when the ledger is pseudo-reconciled (an estimate). The overlay carries its own embedded standard font resource, orthogonal to /NeedAppearances.