services.devDocs

Two clients, over the years

The running jobjob_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged

What a subject holds after the first year. Acme's states each keep their own date, it registers in Texas, a restated figure mints an amendment, a refund date bars one, and it leaves with its dates handed back. A partnership's three partners each get a K-1, and Beta Labs joins mid-year on a June year end.

tax's wordsreturn is a jobtaxpayer is a subjectreview is a taskpreparer is a member

The taxpayer is the subject, so a client is one record across every year. These are the cases the year doesn't reach:

CaseThe clientWhat holds it
Each state, its own dateAcme, July 2027clocks.file.each: one clock per jurisdiction, closed by its own receipt
A new stateAcme registers in Texassubscriptions update: the next mint reads the subscription as it stands
A restated figurethe 2025 return is amendedfact.restated on every job that read it, and on.event mints the amendment
Too late to amendApril 2029the refund clock's hard: { bars }, on refundCloses
Three partnersHarbor Partnersowners, lateFiling per partner, and k1.issued to each partner's own taxpayer
A fiscal year, joined lateBeta Labs, 30 Junesubject.period.ends, catch_up: 'open', and the June-year rule
A client who leavesAcme cancelsthe last cycle hands back every open date, clock.outlived

Each state, its own date

The day after the July filing, only New York's date is open, on its repair window:

captured/tax-cases.txt · magic values: owner.email = signs@example.test, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}
$ npx services.dev clocks list --on job_4Tx3 --test-clock tc_7Hq4
job_4Tx3 · annual-return · period 2026 · at 2027-07-12 09:00:00 · 7 clocks
  id              name        item   status     due         moved from  by
  clk_7Hq9#US     file        US     satisfied  2027-10-15  2027-04-15  file · accepted 2027-07-11
  clk_7Hq9#US-CA  file        US-CA  satisfied  2027-11-15  2027-04-15  file · accepted 2027-07-11

A client who changes

In March Acme registers in Texas. The next mint files five returns, and the 2026 return keeps its four:

Run
npx services.dev subscriptions update sbn_7Hq2 jurisdictions=US,US-CA,US-NY,US-NJ,US-TX --test-clock tc_7Hq4
magic values: owner.email = signs@example.test, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}
sbn_7Hq2 · tax-plan · active · updated 2027-03-08 · jurisdictions + US-TX
  next mint   annual 2028-02-01 · period 2027 · US, US-CA, US-NY, US-NJ, US-TX · Texas due 05-15, its own extension on 05-164
  keeps       job_4Tx3 · period 2026 · US, US-CA, US-NY, US-NJ, as minted 2027-02-01

The 2025 return is amended for a late credit. The 2026 return read it, so the plan mints a 2026 amendment:

captured/tax-cases.txt · magic values: owner.email = signs@example.test, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}
$ npx services.dev events --since 2027-11-30 --on sbj_7Hq2 --test-clock tc_7Hq4
evt_9Ts1  job.accepted         job_4Ty3  amended-return · period 2025 · the subject keeps carryforwards 2025 and tax 2025, newer values
evt_9Ts2  fact.restated        sbj_7Hq2  carryforwards 2025 · read by job_4Tx3 (period 2026, at compute 2027-07-13)
Run
npx services.dev jobs get job_4Tx3 --test-clock tc_7Hq4
magic values: owner.email = signs@example.test, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}
job_4Tx3 · accepted · annual-return · period 2026 · $0.00 on sbn_7Hq2
  read     carryforwards 2025 · fct_7Hq4 (job_4Tx2) · restated by fct_7Hr9 (job_4Ty3) 2027-11-30
  offered  amended-return · period 2026 · $900.00 · next POST /jobs { "service": "amended-return", "from": "job_4Tx3" }

Filed early, the 2025 return's refund date runs from its due date, three years on. After it, an amendment answers date_passed:

captured/tax-cases.txt · magic values: owner.email = signs@example.test, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}
$ npx services.dev jobs again job_4Tx2 --service amended-return change="a second credit" --test-clock tc_7Hq3
× 409 date_passed · amended-return.file is barred: refund on job_4Tx2 closed 2029-04-17, and the amendment claims a refund (claimsRefund) · nothing held
  why   3y after the date it was due, 2026-04-15, rolled past a weekend and Emancipation Day; it was filed early, 2026-02-01

A partnership's partners

A late partnership return costs $245 a partner a month even at $0 tax. On acceptance, each partner's K-1 lands on their own taxpayer:

captured/tax-cases.txt · magic values: owner.email = signs@example.test, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}
$ npx services.dev annual-return "business=Harbor Partners <books@harbor.example>" "owner=Rosa Diaz <rosa@harbor.example>" ein=98-7654340 entity=partnership jurisdictions=US,US-NJ books=https://books.example/harbor tax_year=2026 "owners=Rosa Diaz 40%,Sam Okoro 35%,Ines Varga 25%" --max 2000 --test-clock tc_7Hq6
job_4Ty5 · working · $2,000.00 held
  clocks  file · US due 2027-03-15 · US-NJ due 2027-04-15 · about $735 a month late: 3 partners × $245, owed at $0 tax
job_4Ty5 · accepted · $1,950.00 charged · state fees $150.00 at cost

Its amendment is an AAR: Amended return.

A second client, on its own year

Beta Labs' year ends 30 June, and it buys the plan on 10 August, already extended. Its 2026 year began before 2026, so its return was due 15 September 2026, and had passed:

captured/tax-cases.txt · magic values: owner.email = signs@example.test, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}
$ npx services.dev plan --at 2027-08-10 ein=98-7654321 "entity=C corp" jurisdictions=US,US-CA year_end=06-30 extended_to=2028-04-15
tax-plan for 98-7654321 · tax year ends 06-30 · from 2027-08-10
  annual    would mint now: period 2027 (2026-07-01 → 2027-06-30), its file date still open · catch_up 'open'
  annual    next 2028-08-01 (1mo after end 2028-06-30) · period 2028
captured/tax-cases.txt · magic values: owner.email = signs@example.test, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}
$ npx services.dev tax-plan "business=Beta Labs <books@beta.example>" "owner=Lin Okafor <lin@beta.example>" ein=98-7654321 "entity=C corp" jurisdictions=US,US-CA books=https://books.example/beta year_end=06-30 extended_to=2028-04-15 --max 2400 --test-clock tc_7Hq5
sbn_7Hr1 · tax-plan · active · cycle 1 · 2027-08-10 → 2028-08-10 · $2,400.00 per year
  minted    2027-08-10  catch_up open → job_4Ty1 annual-return · period 2027 · $0.00 · allowance 1 of 1
  clocks    job_4Ty1 file · due 2028-04-15, the client's extension (extended_to) · US, US-CA

A client who leaves

Acme cancels. The plan runs to the end of its cycle, then hands back each date it held:

Run
npx services.dev subscriptions cancel sbn_7Hq2 --test-clock tc_7Hq4
magic values: owner.email = signs@example.test, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}
sbn_7Hq2 · tax-plan · canceling · runs to 2029-01-20, the end of cycle 2 · nothing after it mints or charges
captured/tax-cases.txt · magic values: owner.email = signs@example.test, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}
$ npx services.dev events --since 2029-01-20 --on sbn_7Hq2,sbj_7Hq2 --test-clock tc_7Hq4
evt_9Tw1  subscription.canceled  sbn_7Hq2  cycle 2 ended 2029-01-20 · minting stops · owed 14:00:00, fired 14:00:00
evt_9Tw2  clock.outlived         sbj_7Hq2  assessment and refund 2025 2029-04-17 · 2026 2030-07-11 · 2027 2031-04-18 · expiring 2046-12-31 · handed back to the client
captured/tax-cases.txt · 200 · the disengagement letter · Acme Robotics · 2029-01-20 · magic values: owner.email = signs@example.test, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}
→ GET /portal/subjects/sbj_7Hq2/letter
  Your Tax Plan ended on 20 January 2029. These dates are still running, and from today they are yours to keep:
    2029-04-17  refund claims on your 2025 return close, and so does the IRS's time to assess it
    2030-07-11  the same, for your 2026 return

Subjects covers what a subject keeps, and Periods a fiscal year.