PFIC Catch-Up — local workpaper prototype

What you can test here

The public demo lets you inspect the synthetic workflow and the safety gates. The real calculator is deliberately a local command-line application: it stores its SQLite workspace and source documents on your machine and makes no network requests.

Import

Preserve evidence

Normalized CSV rows retain a source hash and source-row link. PDFs and spreadsheets can be kept locally as evidence without sharing them.

Calculate

Trace every number

FIFO lots, per-share excess-distribution tests, day allocations, supplied rates, and interest factors are exported to inspectable workpapers.

Review

Block assumptions

PFIC status, treatment, ownership, FX, and filing-policy choices require explicit confirmation. An unresolved input blocks a filing-ready bundle.

Run the synthetic example on your Mac

The example uses invented taxpayers, invented funds, and synthetic amounts. It creates a private workspace under /tmp so you can see every generated artifact before using any real records.

cd /Users/yosemite/githubs/claude_code_misc_work/pfic-catchup && python3 pfic.py demo /tmp/my-pfic-demo

open /tmp/my-pfic-demo/exports/2024/audit_bundle.html

This calculator currently needs Python 3.12+ and no package installation for its deterministic core.

Browse the source Read the full setup guide

Safety-gate simulation

This browser control is an explanatory simulation only. It does not calculate tax or store any input.

All tax-relevant transactions are explicitly classified.
For example, a reinvestment is confirmed as a distribution plus purchase only after source review. PFIC and section 1291 treatment are explicitly confirmed.
The tool never infers PFIC status merely because a fund was in a UK ISA. USD conversion and historical rate/interest inputs are documented.
The calculator refuses to guess a missing rate or cumulative interest factor. I have separately reviewed any accumulation-unit issue.
This remains a professional-review warning, not an automatic legal conclusion.

REVIEW REQUIREDArithmetic may run, but every draft form and policy choice still needs human review. The unchecked accumulation item is recorded as a warning.

Synthetic run at a glance

10imported transactions

4reconstructed lots

2dispositions

5section 1291 events

These are test-fixture results, not an estimate of anyone’s tax liability.

Bundle item	Purpose	Status in the synthetic run
Lot and basis ledger	Shows purchases/reinvestments, remaining shares, basis, and FIFO disposals.	Generated
Section 1291 allocations	Links each event and holding-period allocation to evidence and entered rate inputs.	Generated
Form 8621 field packet	Provides transfer-ready draft fields and allocation statements.	Draft only
Accumulation-unit treatment	Requires an explicit factual/legal review; it cannot be solved by a checkbox.	Review required

Use it with your own records

Keep real records offline. Copy the synthetic project configuration, replace only the local facts, preserve statements as evidence, import a normalized CSV, resolve the review queue, and calculate one correction year at a time.

python3 pfic.py init /path/to/private-pfic-workspace --config /path/to/project.json

python3 pfic.py calculate /path/to/private-pfic-workspace 2024 --fail-on-blockers --redacted-out /path/to/redacted-review

Current prototype boundaries

Normalized CSV import is implemented. PDF/XLSX extraction and an AJ Bell-specific parser are not yet automated.
The PDF output is a draft field packet, not a filled official IRS PDF.
QEF, mark-to-market, purging elections, foreign-tax-credit allocation, and notional accumulation-unit determinations are not implemented.
Streamlined and green-card outputs are review workpapers, never eligibility conclusions.