Federal first, then the states
The annual return's file step. One filing per jurisdiction, the federal return leading and each state linked to it, a rejection routed by its code to the step that repairs it, and a repair inside the perfection window that keeps its first filing time.
tax's wordsreturn is a jobtaxpayer is a subjectreview is a taskpreparer is a member
One submit step files the return everywhere it's owed: the federal return first, then each state, linked to it. A rejection is a transition to the step its code names, state by state, and the states that accepted stay filed.
grep -A3 "file: {$" services/annual-return.ts file: {
submit: efile, to: 'IRS and states', receipt: 'receipts', each: { of: 'jurisdictions', lead: j => j === 'US' },
rejected: { ein_mismatch: { to: 'organizer', items: reask.ein_mismatch }, schedule_missing: { to: 'organizer', items: reask.schedule_missing }, math: 'draft', '*': 'prepare' }, perfect: '10d',
},| Key | Here | What it does |
|---|---|---|
submit | efile, your function in lib/tax.ts | Files one jurisdiction's return. A live brand calls its transmitter here |
receipt | 'receipts' | The output each receipt's id fills, one per jurisdiction |
each.of | 'jurisdictions' | One submission, and one receipt, per element of the input list |
each.lead | j => j === 'US' | The federal return goes first; each state waits for its acceptance |
rejected | a map of codes | Each code to the step that repairs it, in the order written; '*' takes the rest |
perfect | '10d' | A repair resubmitted within 10 days of the first submission keeps that submission's time |
Each code, where it goes, and the test EIN that produces it:
| Code | Goes to | Then | Test EIN |
|---|---|---|---|
ein_mismatch | organizer | Re-asks only that state's tax account number | 98-7654321, New York |
schedule_missing | organizer | Re-asks only the schedule that state named | 98-7654323, New Jersey |
math | draft | The AI drafts again, and the signer signs the new version | 98-7654322, California |
| any other | prepare | A preparer repairs it, and a different member signs | 98-7654325, New Jersey, and 98-7654326, California, business_rule |
The simulated e-file system in lib/tax.ts, your code, rejects New York once for test EIN 98-7654321. Ada signs the §7216 consent and answers the organizer through her own links, and Katherine Johnson signs:
→ POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada Lovelace","email":"ada@example.com"},"ein":"98-7654321","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"acme-ny"}
# Ada signs the §7216 consent and answers the organizer through her own links
# mbr_8Ea1, in her own session: GET /tasks/tsk_7Hq2/sheet · POST /tasks/tsk_7Hq2/claim · POST /tasks/tsk_7Hq2/clear
→ POST /practitioners/returns/job_4Tx2/approve {"checklist":["every line traces to a source","due diligence answered","the officer's e-file authorization shows this return's figures"]}
← 200Ada signs Form 8879-CORP. The federal return, California and New Jersey are accepted, and New York is rejected with ein_mismatch:
→ POST /practitioners/returns/job_4Tx2/approve {"checklist":["every line traces to a source","due diligence answered","the officer's e-file authorization shows this return's figures"]}← job_4Tx2 · waiting · on claim · $1,800.00 held · sign
rcp_7Hq2 US accepted · filed 2027-02-01 · US 1120 2026 accepted
rcp_7Hq3 US-CA accepted · filed 2027-02-01 · after rcp_7Hq2 · US-CA 100 2026 accepted
rcp_7Hq4 US-NY rejected · ein_mismatch · filed 2027-02-01 · after rcp_7Hq2
rcp_7Hq5 US-NJ accepted · filed 2027-02-01 · after rcp_7Hq2 · US-NJ CBT-100 2026 acceptedThree days later Ada answers New York's one item. The workpapers changed, so the signature no longer covers them: Katherine signs the new version, a new act paid again, and Ada signs a new Form 8879-CORP. Only New York is refiled:
→ POST /test_clocks/default/advance {"to":"3d"}
← job_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged
rcp_7Hq2 US accepted · filed 2027-02-01 · US 1120 2026 accepted
rcp_7Hq3 US-CA accepted · filed 2027-02-01 · after rcp_7Hq2 · US-CA 100 2026 accepted
rcp_7Hq4 US-NY rejected · ein_mismatch · filed 2027-02-01 · after rcp_7Hq2
rcp_7Hq5 US-NJ accepted · filed 2027-02-01 · after rcp_7Hq2 · US-NJ CBT-100 2026 accepted
rcp_7Hq6 US-NY accepted · filed 2027-02-01 · sent 2027-02-04 · after rcp_7Hq2 · US-NY CT-3 2026 acceptedNew York's two receipts. The refiled one went out inside perfect: '10d', so it keeps the rejected filing's at; sent_at is when it actually left:
curl -s http://localhost:8787/returns/job_4Tx2 | jq '[.receipts[] | select(.element == 2)]' # New York, rejected then filed on time[
{
"id": "rcp_7Hq4",
"object": "receipt",
"job": "job_4Tx2",
"step": "file",
"to": "IRS and states",
"at": "2027-02-01T09:00:00.000Z",
"status": "rejected",
"element": 2,
"for": "US-NY",
"lead": "rcp_7Hq2",
"livemode": false,
"codes": [
"ein_mismatch"
],
"simulated": true
},
{
"id": "rcp_7Hq6",
The charge released when the last filing was accepted. The owner's record shows each step, including the signature the gate refused for the changed workpapers:
→ GET /owner/returns/job_4Tx2 # the owner console record consent · owner · §7216 | organizer.books · answered | organizer.bank · answered | organizer.payroll · answered | organizer.assets · answered | organizer.ca_account · answered | organizer.ny_account · answered | organizer.nj_account · answered | organizer · owner · upload | compute · code | draft · ai | check · ai · adversarial · 3 lenses · pass | sign · person · ptin and cpa · * · mbr_8Ea1 | authorize · owner · Form 8879-CORP · id-verified | file · IRS and states · rejected · ein_mismatch · repairing at organizer | organizer.ny_account · answered | organizer · owner · upload | compute · code | sign · signer · refused · unattested · workpapers changed after the signer signed it; they sign the new version before it is filed. | authorize · signature void | draft · ai | check · ai · adversarial · 3 lenses · pass | sign · person · ptin and cpa · * · mbr_8Ea1 | authorize · signature void | authorize · owner · Form 8879-CORP · id-verified · clock paused 3d | file · IRS and states · efin simulated · 4 accepted
ledger +$1,800.00 · AI $3.36 · signer $210.00 · you $1,586.64Each test EIN, run on its own. After any repair the return changed, so the signer signs again before it's filed:
→ POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada","email":"signs@example.test"},"ein":"98-7654321","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"98-7654321"} # ein = 98-7654321
← job_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged
→ POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada","email":"signs@example.test"},"ein":"98-7654322","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"98-7654322"} # ein = 98-7654322
← job_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged
→ POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada","email":"signs@example.test"},"ein":"98-7654323","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"98-7654323"} # ein = 98-7654323
← job_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged
→ POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada","email":"signs@example.test"},"ein":"98-7654325","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"98-7654325"} # ein = 98-7654325
← job_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged
→ POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada","email":"signs@example.test"},"ein":"98-7654326","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"98-7654326"} # ein = 98-7654326
← job_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged
Two states, each with its own code and item, and the states that accepted stay filed:
→ POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada","email":"signs@example.test"},"ein":"98-7654324","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"two-states"} # ein = 98-7654324
← job_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged
record … organizer.books · answered | organizer.bank · answered | organizer.payroll · answered | organizer.assets · answered | organizer.ca_account · answered | organizer.ny_account · answered | organizer.nj_account · answered | file · IRS and states · rejected · ein_mismatch · repairing at organizer | file · IRS and states · rejected · schedule_missing | organizer.ny_account · answered | organizer.nj_schedule · answered | file · IRS and states · efin simulated · 4 accepted
re-asked ny_account: Your NY tax account number · nj_schedule: The NJ schedule the state found missing
One submission per element and Sending to outside systems cover the keys.