services.devDocs

A year, and the next

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

The tax example's gate. A company's 2025 return, then a Tax Plan run for a year on a test clock with tick 1y. The plan mints each 1099 filing, return and estimate, a rung deposits the tax and files each state's extension by its own rule, a state is repaired in time, a CP161 is answered, and the plan renews into the next year.

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

Acme Robotics files federally and in three states, with twelve simulated preparers. The magic values script the year: the books come 160 days late, New York rejects once, a W-9 comes late, and a notice arrives in November.

The year before

The 2025 return runs on a clock of its own, its balance paid with the return:

captured/tax-years.txt · magic values: owner.email = signs@example.test, metadata.sandbox.asks = {"organizer.books":"after 160d","organizer.assets":"waive","organizer #2":"after 2d","w9":"after 19d"}, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}, metadata.sandbox.events = { notice.received: { at: 2027-11-14T15:00:00Z, data: { notice, reply_by, tax_years } } }
$ npx services.dev annual-return "business=Acme Robotics <books@acme.example>" "owner=Ada Lovelace <signs@example.test>" ein=12-3456789 "entity=C corp" jurisdictions=US,US-CA,US-NY,US-NJ books=https://books.example/acme tax_year=2025 --max 1800 --test-clock tc_7Hq3
job_4Tx2 · working · $1,800.00 held
job_4Tx2 · delivered · workpapers-2025.txt · return.txt · $1,800.00 charged
  record  consent · owner · §7216 · use: prepare · disclose: none, so members located in the US | 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 | expiring clock · rolled 2045-12-31 → 2046-01-02 · weekend, holiday | draft · ai | check · ai · adversarial · 3 lenses · pass | sign · person · ptin and enrolled agent · * · mbr_8Ea1 · paid-preparer block for apis.tax | authorize · owner · Form 8879-CORP · id-verified | file · IRS and states · efin simulated · 4 accepted · tax with the return
  clocks  file · due 2026-04-15 · mbr_8Ea1 · satisfied
          pay · due 2026-04-15 · buyer · satisfied
          assessment · due 2029-04-17 (rolled from 2029-04-15) · the brand · open · on the subject
Run
npx services.dev clocks get clk_7Hq3
magic values: owner.email = signs@example.test, metadata.sandbox.asks = {"organizer.books":"after 160d","organizer.assets":"waive","organizer #2":"after 2d","w9":"after 19d"}, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}, metadata.sandbox.events = { notice.received: { at: 2027-11-14T15:00:00Z, data: { notice, reply_by, tax_years } } }
clk_7Hq3 · pay · due 2026-04-15 · buyer · satisfied

The plan

On a second clock, on 20 January 2027, the business buys the plan:

captured/tax-years.txt · magic values: owner.email = signs@example.test, metadata.sandbox.asks = {"organizer.books":"after 160d","organizer.assets":"waive","organizer #2":"after 2d","w9":"after 19d"}, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}, metadata.sandbox.events = { notice.received: { at: 2027-11-14T15:00:00Z, data: { notice, reply_by, tax_years } } }
$ npx services.dev tax-plan "business=Acme Robotics <books@acme.example>" "owner=Ada Lovelace <signs@example.test>" ein=12-3456789 "entity=C corp" jurisdictions=US,US-CA,US-NY,US-NJ books=https://books.example/acme --max 2400 --test-clock tc_7Hq4 --metadata 'sandbox.asks={"organizer.books":"after 160d","organizer.assets":"waive","organizer #2":"after 2d","w9":"after 19d"}' --metadata 'sandbox.outside={"reject":{"file.US-NY":["ein_mismatch"]}}' --metadata 'sandbox.events={"notice.received":{"at":"2027-11-14T15:00:00Z","data":{"notice":{"url":"data:text/plain,CP161%3A%20balance%20due%202026.","name":"cp161.pdf"},"reply_by":"2027-12-14","tax_years":["2026","2027"]}}}'
sbn_7Hq2 · tax-plan · active · cycle 1 · 2027-01-20 → 2028-01-20 · $2,400.00 per year
  allowances  annual-return 0 of 1 · information-returns 0 of 25 · estimate 0 of 4 · question 0 of 12 · notice-response 0 of 2
  minted      2027-01-20  catch_up open → job_4Tx1 information-returns · period 2026 · due 2027-02-01, rolled from 2027-01-31 · weekend
  schedule    information → information-returns · next 2028-01-05 (5d after end 2027-12-31)
  schedule    annual → annual-return · next 2027-02-01 (1mo after end 2026-12-31)
  schedule    estimate → estimate · next 2027-04-05 (10d before pay 2027-04-15)
  event       question.asked → question

A year, on the clock

tick 1y moves the clock a year. January and February: the 1099s are filed, and the 2026 return is minted, its organizer started from 2025:

captured/tax-years.txt · magic values: owner.email = signs@example.test, metadata.sandbox.asks = {"organizer.books":"after 160d","organizer.assets":"waive","organizer #2":"after 2d","w9":"after 19d"}, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}, metadata.sandbox.events = { notice.received: { at: 2027-11-14T15:00:00Z, data: { notice, reply_by, tax_years } } }
$ npx services.dev tick 1y --test-clock tc_7Hq4 --market normal
tc_7Hq4 · 2027-01-20 09:00:00 → 2028-01-20 09:00:00 · 214 fired
  2027-01-20 09:00:00  job_4Tx1  read → list · 5 payees, each W-9 on file
  2027-01-20 09:00:00  job_4Tx1  match · TIN matching · 5 matched
  2027-01-20 09:00:00  job_4Tx1  ask confirm · signs@example.test · decided "file them"
  2027-01-20 09:00:00  job_4Tx1  file · IRS, through IRIS · 5 1099-NECs accepted · due 2027-02-01
  2027-01-20 09:00:00  job_4Tx1  send · 5 payee copies · delivered · collected $0.00 · allowance 5 of 25

Spring: the first estimate is paid in each state. Three days before the date to file, a rung deposits the tax the ledger expects and files each extension its state needs. Each date to file moves by its own rule; the date to pay doesn't. The return keeps the rungs of 2027-01, the version it opened under:

captured/tax-years.txt · magic values: owner.email = signs@example.test, metadata.sandbox.asks = {"organizer.books":"after 160d","organizer.assets":"waive","organizer #2":"after 2d","w9":"after 19d"}, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}, metadata.sandbox.events = { notice.received: { at: 2027-11-14T15:00:00Z, data: { notice, reply_by, tax_years } } }
$ npx services.dev tick 1y --test-clock tc_7Hq4 --market normal
  2027-03-16 13:00:00  job_4Tx3  clock file · rung notice 30d · due 2027-04-15 · US, US-CA, US-NY · owner of_record
  2027-04-01 13:00:00  job_4Tx3  clock pay · rung notice 14d · due 2027-04-15 · owner buyer · about $324 a month if it's late
  2027-04-05 13:00:00  sbn_7Hq2  schedule estimate → job_4Tx4 estimate · period 2027-Q1 · $0.00 · allowance 1 of 4
  2027-04-05 13:00:00  job_4Tx4  clock pay · rung notice 10d · due 2027-04-15 · owner buyer · about $284 a quarter if it's left unpaid
  2027-04-05 13:00:00  job_4Tx4  compute · 2026 isn't filed yet: 2025's tax (job_4Tx2) · US $16,223 · US-CA $1,639 · US-NJ $1,391 · US-NY's first installment goes with its CT-5
  2027-04-05 13:00:00  job_4Tx4  ask approve · signs@example.test · decided "pay it"
  2027-04-05 13:00:00  job_4Tx4  review
  2027-04-05 13:00:00  job_4Tx4  pay · Treasury and states · 3 accepted, US first · rcp_7Hq6
  2027-04-05 13:00:00  job_4Tx4  clock pay · satisfied · pay committed
  2027-04-05 13:00:00  job_4Tx4  record
  2027-04-05 13:00:00  job_4Tx4  delivered · collected $0.00
  2027-04-09 13:00:00  job_4Tx3  clock file · rung ack daily 7d · acknowledged, simulated · the acknowledgement due 7 days out

July: the books arrive. The return is drafted with the deposit credited, signed with last year's beside it, and filed with $0 due. New York rejects it once, and the refiling keeps its first time:

captured/tax-years.txt · magic values: owner.email = signs@example.test, metadata.sandbox.asks = {"organizer.books":"after 160d","organizer.assets":"waive","organizer #2":"after 2d","w9":"after 19d"}, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}, metadata.sandbox.events = { notice.received: { at: 2027-11-14T15:00:00Z, data: { notice, reply_by, tax_years } } }
$ npx services.dev tick 1y --test-clock tc_7Hq4 --market normal
  2027-07-11 14:00:00  job_4Tx3  ask organizer · books answered · done
  2027-07-11 14:00:00  job_4Tx3  compute · carryforwards read off 2025 (job_4Tx2) · $95,739.00 deposited with the extension, credited · balance due $0.00 → draft → check · waits on claim at sign
  2027-07-11 14:00:00  job_4Tx3  sign · offered first to mbr_8Ea1, of record · claimed · 2025 beside it (job_4Tx2)
  2027-07-11 14:00:00  job_4Tx3  ask authorize · signs@example.test · Form 8879-CORP signed id-verified as officer · sha256:69d3…
  2027-07-11 14:00:00  job_4Tx3  file · US 1120 accepted → US-CA 100 accepted, US-NJ CBT-100 accepted, US-NY CT-3 rejected ein_mismatch → organizer
  2027-07-11 14:00:00  job_4Tx3  clock file · US, US-CA, US-NJ satisfied · US-NY open until its own receipt
  2027-07-11 14:00:00  job_4Tx3  ask organizer · signs@example.test · 1 item · 1 open (ny_account)
  2027-07-11 14:00:00  job_4Tx3  waits on party at organizer
  2027-07-13 14:00:00  job_4Tx3  ask organizer · ny_account answered · done
  2027-07-13 14:00:00  job_4Tx3  compute · carryforwards read off 2025 (job_4Tx2)

Then three more estimates, September's catching up, a CP161 answered, the next 1099s, and the renewal:

captured/tax-years.txt · magic values: owner.email = signs@example.test, metadata.sandbox.asks = {"organizer.books":"after 160d","organizer.assets":"waive","organizer #2":"after 2d","w9":"after 19d"}, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}, metadata.sandbox.events = { notice.received: { at: 2027-11-14T15:00:00Z, data: { notice, reply_by, tax_years } } }
$ npx services.dev tick 1y --test-clock tc_7Hq4 --market normal
tc_7Hq4 · 2027-01-20 09:00:00 → 2028-01-20 09:00:00 · 214 fired
  2027-04-12 13:00:00  job_4Tx3  clock file · moved 2027-04-15 → 2027-10-15 · US, US-NY · US-NJ 2027-05-17 → 2027-11-15 · US-CA → 2027-11-15, automatic · each by its own rule · clock pay unmoved, still 2027-04-15
  2027-06-05 13:00:00  sbn_7Hq2  schedule estimate → job_4Tx5 estimate · period 2027-Q2 · $0.00 · allowance 2 of 4
  2027-06-05 13:00:00  job_4Tx5  clock pay · rung notice 10d · due 2027-06-15 · owner buyer · about $284 a quarter if it's left unpaid
  2027-06-05 13:00:00  job_4Tx5  compute · 2026 isn't filed yet: 2025's tax (job_4Tx2) · US $16,222 · US-CA $2,185 · US-NY $1,447 · US-NJ $1,390
  2027-06-05 13:00:00  job_4Tx5  ask approve · signs@example.test · decided "pay it"
  2027-06-05 13:00:00  job_4Tx5  review
  2027-06-05 13:00:00  job_4Tx5  pay · Treasury and states · 4 accepted, US first · rcp_7HqC

And the next

Thirteen days on, the 1099s go in, and the 2027 return is minted, its dates rolled past a weekend and a holiday:

Run
npx services.dev tick 13d --test-clock tc_7Hq4 --market normal
magic values: owner.email = signs@example.test, metadata.sandbox.asks = {"organizer.books":"after 160d","organizer.assets":"waive","organizer #2":"after 2d","w9":"after 19d"}, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}, metadata.sandbox.events = { notice.received: { at: 2027-11-14T15:00:00Z, data: { notice, reply_by, tax_years } } }
tc_7Hq4 · 2028-01-20 09:00:00 → 2028-02-02 09:00:00 · 19 fired
  2028-01-24 14:00:00  job_4TxA  ask w9 · Lumen Design LLC · uploaded
  2028-01-24 14:00:00  job_4TxA  match · TIN matching · 6 matched
  2028-01-24 14:00:00  job_4TxA  ask confirm · signs@example.test · decided "file them"
  2028-01-27 14:00:00  job_4TxA  file · IRS, through IRIS · 6 1099-NECs accepted · due 2028-01-31
  2028-01-27 14:00:00  job_4TxA  send · 6 payee copies · delivered · collected $0.00 · allowance 11 of 25, cycle 1
  2028-02-01 14:00:00  sbn_7Hq2  schedule annual → job_4Tx9 annual-return · period 2027 · $0.00 · allowance 1 of 1
  2028-02-01 14:00:00  job_4Tx9  clock pay · due 2028-04-18, rolled from 2028-04-15 · weekend, holiday
  2028-02-01 14:00:00  job_4Tx9  clock file · due 2028-04-18, rolled from 2028-04-15 · weekend, holiday · US, US-CA, US-NY · US-NJ and US-TX due 2028-05-15
  2028-02-01 14:00:00  job_4Tx9  clock file · rung notice 90d · owed 2028-01-19, armed by the mint: fires in place · US, US-CA, US-NY
  2028-02-01 14:00:00  job_4Tx9  ask consent · signs@example.test · §7216 consented as officer · use: prepare · disclose: none
  2028-02-01 14:00:00  job_4Tx9  ask organizer · signs@example.test · 10 items from 2026 (job_4Tx3) · 8 answered · 1 waived · 1 open (books)
  2028-02-01 14:00:00  job_4Tx9  affinity · mbr_8Ea1, of record, is offered its review first until 2028-02-15
  2028-02-01 14:00:00  job_4Tx9  waits on party at organizer

The plan and the taxpayer, read back:

captured/tax-years.txt · magic values: owner.email = signs@example.test, metadata.sandbox.asks = {"organizer.books":"after 160d","organizer.assets":"waive","organizer #2":"after 2d","w9":"after 19d"}, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}, metadata.sandbox.events = { notice.received: { at: 2027-11-14T15:00:00Z, data: { notice, reply_by, tax_years } } }
$ npx services.dev subscriptions get sbn_7Hq2
sbn_7Hq2 · tax-plan · active · cycle 2 · 2028-01-20 → 2029-01-20 · $2,400.00 per year
  allowances  annual-return 1 of 1 · information-returns 0 of 25 · estimate 0 of 4 · question 0 of 12 · notice-response 0 of 2
  schedule    information → information-returns · next 2029-01-05 (5d after end 2028-12-31)
  schedule    annual → annual-return · next 2029-02-01 (1mo after end 2028-12-31)
  schedule    estimate → estimate · next 2028-04-05 (10d before pay 2028-04-15)
  event       question.asked → question
  event       notice.received → notice-response
Call
→ GET /taxpayers/sbj_7Hq2
magic values: owner.email = signs@example.test, metadata.sandbox.asks = {"organizer.books":"after 160d","organizer.assets":"waive","organizer #2":"after 2d","w9":"after 19d"}, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}, metadata.sandbox.events = { notice.received: { at: 2027-11-14T15:00:00Z, data: { notice, reply_by, tax_years } } }
← sbj_7Hq2 · taxpayer 12-3456789 · of record mbr_8Ea1, Katherine Johnson, until 2030-07-11
  period  2025     annual-return        job_4Tx2 · accepted
  period  2026     information-returns  job_4Tx1 · accepted
  period  2026     annual-return        job_4Tx3 · accepted
  period  2027-Q1  estimate             job_4Tx4 · accepted
  period  2027-Q2  estimate             job_4Tx5 · accepted
  period  2027-Q3  estimate             job_4Tx6 · accepted
  period  2027-Q4  estimate             job_4Tx8 · accepted
  period  2027     information-returns  job_4TxA · delivered
  period  2027     annual-return        job_4Tx9 · waiting
  keeps   carryforwards 2025    US credit 2025 $8,370, US-CA credit 2025 $6,537 · job_4Tx2 at compute · 2026-02-01
  keeps   carryforwards 2026    US credit 2026 $13,800, US-CA credit 2025 $331, US-CA credit 2026 $12,000 · job_4Tx3 at compute · 2027-07-20
  keeps   tax           2025    US $64,890 · US-CA $5,463 · US-NY $6,695 · US-NJ $5,562 · job_4Tx2 at compute · 2026-02-01
  keeps   tax           2026    US $73,710 · US-CA $6,205 · US-NY $7,605 · US-NJ $6,318 · job_4Tx3 at compute · 2027-07-20
  keeps   paid          2026    US $73,710 · US-CA $6,205 · US-NY $7,605 · US-NJ $6,318, with the extension · job_4Tx3 at pay · 2027-07-20
  keeps   first_installment 2026  US-NY $1,901, toward 2027 · job_4Tx3 at tentative · 2027-07-20
  keeps   paid          2027-Q1 US $16,223 · US-CA $1,639 · US-NJ $1,391 · job_4Tx4 at record · 2027-04-12
  keeps   paid          2027-Q2 US $16,222 · US-CA $2,185 · US-NY $1,447 · US-NJ $1,390 · job_4Tx5 at record · 2027-06-12
  keeps   paid          2027-Q3 US $22,838 · US-NY $2,356 · US-NJ $1,958 · job_4Tx6 at record · 2027-09-12
  keeps   paid          2027-Q4 US $18,427 · US-CA $2,381 · US-NY $1,901 · US-NJ $1,579 · job_4Tx8 at record · 2027-12-12

The gate

Call
→ GET /taxpayers/sbj_7Hq2
magic values: owner.email = signs@example.test, metadata.sandbox.asks = {"organizer.books":"after 160d","organizer.assets":"waive","organizer #2":"after 2d","w9":"after 19d"}, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}, metadata.sandbox.events = { notice.received: { at: 2027-11-14T15:00:00Z, data: { notice, reply_by, tax_years } } }
  keeps   paid          2026    US $73,710 · US-CA $6,205 · US-NY $7,605 · US-NJ $6,318, with the extension · job_4Tx3 at pay · 2027-07-20
  keeps   paid          2027-Q1 US $16,223 · US-CA $1,639 · US-NJ $1,391 · job_4Tx4 at record · 2027-04-12
  keeps   paid          2027-Q2 US $16,222 · US-CA $2,185 · US-NY $1,447 · US-NJ $1,390 · job_4Tx5 at record · 2027-06-12
  keeps   paid          2027-Q3 US $22,838 · US-NY $2,356 · US-NJ $1,958 · job_4Tx6 at record · 2027-09-12
  keeps   paid          2027-Q4 US $18,427 · US-CA $2,381 · US-NY $1,901 · US-NJ $1,579 · job_4Tx8 at record · 2027-12-12
# the gate, read off the run: the tax brand holds each line
  periods     2026, 2027 minted, each free · their 1099s too, 11 payees of 25
  read        carryforwards off 2025 (job_4Tx2), by value: 2 in, $14,907; 3 out, $26,131
  filed       1 federal and 3 linked state returns · the tentative tax deposited, then each extension its state's rule needs, proposed by a rung (by: clock, owed 2027-04-12 13:00)
  extended    US, US-NY to 2027-10-15 · US-NJ to 2027-11-15 · US-CA to 2027-11-15, automatic, no filing
  paid        2026: $95,739 with the extension, credited on the return · balance due $0.00
  repaired    US-NY ein_mismatch · refiled 2027-07-13, keeps 2027-07-11 · US-NJ filed 2027-07-11, on time
  estimates   4 kept by quarter, each state its own · Q3 catches up the $4,410 Q1 and Q2 were short · the 2027 organizer asks: Confirm the 4 federal payments for 2027, $73,710 in all
  notice      CP161 for 2026: rcp_7HqB found posted to 2027 · a transfer request under a Form 2848 naming mbr_8Ea1
  2027        file due 2028-04-18, rolled from 2028-04-15 (weekend, holiday) · US-NJ and US-TX 2028-05-15 · America/New_York
  renewed     cycle 2 · allowances reset
  folded      15 clocks, each rebuilt from its events alone: every one the same

Two clients, over the years runs what comes after. Keeping time covers every kind of time it uses.