---
title: "Porting apis.tax"
url: https://services.dev/docs/examples/tax/port
captured: [tax-flows.txt, tax-suite.txt]
---
# Porting apis.tax

URL: https://services.dev/docs/examples/tax/port

> Every flow the live apis.tax door states, matched to the generated tax brand's behavior, adapted to a new shape, or decided. Then the tests behind them, and the brand's own suite, passing.

*tax's words: return is a job, taxpayer is a subject, review is a task, preparer is a member (examples/tax/brand.ts).*

apis.tax states what it sells in two files, its `llms.txt` and the sample records in `data.js`: lender records, typed, with a boundary that prepares, represents and signs nothing. The tax example generates that door, and a preparation business beside it, from one folder. This page holds the two side by side, the acceptance test for Time's lender line.

| Measure | Of | Result | Read it |
|---|---|---|---|
| apis.tax's flows: its `llms.txt` and `data.js`, at `17a25d0` | 16 flows | 9 matched · 6 adapted · 1 not ported | [Route by route](https://services.dev/docs/examples/tax/port.md#route-by-route) |
| The tests behind them | 4 tests | 4 passed | [Its behavior tests](https://services.dev/docs/examples/tax/port.md#its-behavior-tests) |
| The brand's own suite, generated from its contract | 258 cases from 84 rows | 258 passed · 0 failed · 89 skipped | [The suite](https://services.dev/docs/examples/tax/port.md#the-suite) |

## The suite

The door ships no suite of its own, so the brand's generated suite is the contract: every row by its credentials, over HTTP and MCP, the Pool, the clocks, the taxpayers and the Tax Plan included:

```bash
npx services.dev verify --surface all
```

```txt title="magic values: metadata.sandbox.review = pass, metadata.sandbox.review = flag_once, party.email = signs@example.test, party.email = declines@example.test, party.email = silent@example.test, metadata.sandbox.talk = open, watch.url = https://fails-once.example.test/suite, watch.url = https://down.example.test/suite, watch.url = https://hooks.example.test/suite, member = mbr_eligible, member = mbr_lapsed_credential"
tax · 229 HTTP cases and 29 MCP cases from 84 rows: each row by its live credentials and magic values, with its auth, audience, replay and next cases · http://localhost:8787/verify/suite.json
258 passed · 0 failed · 89 skipped
not in tax's contract: job.policy and job.signal, which no tax Service names
```

## Route by route

`flows.ts` reads each flow the door states and names the test that proves the generated brand does the same. Each is marked one of three ways:

| Mark | Means |
|---|---|
| matched | The brand behaves as the door states |
| adapted | It behaves the same with another shape, and the row says what a caller changes |
| not ported | The door's own, with no behavior a buyer, member or agent meets here |

```bash
node -e "import('./flows.ts')"   # the apis.tax door at 17a25d0: 16 flows in holdings/public/apis.tax/llms.txt and holdings/public/apis.tax/data.js
```

```txt title="captured/tax-flows.txt · magic values: none"

## matched · 9
  llms.txt#status: ROADMAP. The three surfaces are typed; none takes calls yet
    → tax-example › answers not_live with its waitlist as next, and holds nothing · status: 'roadmap' publishes the Service with its price and types; an order answers not_live, holds nothing, and names the waitlist
  llms.txt#boundary: apis.tax prepares no returns, represents no taxpayer and signs nothing for one
    → tax-example › refuses the three acts that belong to people, naming whose each is, and meters nothing · kept as the Transcript's three refused rows; the brand prepares, signs and represents only through its credentialed steps on other Services
  llms.txt#income.analysis: Schedule C income added back the Fannie Mae Form 1084 way, by year, with the trend and the 24-month average when income is stable or rising
    → tax-example › figures the sample borrower's income the Form 1084 way · lib/tax.ts figures it, and the transcript's income step runs it on the fields it reads
  llms.txt#PREPARE_RETURN: BLOCKED, RESERVED_ACT, tier LICENSED, naming a paid preparer with a PTIN
    → tax-example › refuses the three acts that belong to people, naming whose each is, and meters nothing · act_refused cites the row, names the paid preparer with a PTIN, and routes to the annual return
  llms.txt#REPRESENT_TAXPAYER: BLOCKED, RESERVED_ACT, tier LICENSED, naming an attorney, CPA or enrolled agent, under Circular 230
    → tax-example › refuses the three acts that belong to people, naming whose each is, and meters nothing · act_refused cites the row, names the CPA, enrolled agent or attorney, and routes to the notice response
  llms.txt#SIGN_CONSENT: BLOCKED, CONSENT_REQUIRED: the taxpayer signs; nothing here signs for them
    → tax-example › refuses the three acts that belong to people, naming whose each is, and meters nothing · act_refused names the taxpayer; the consent ask itself answers anyone but the taxpayer needs_the_party, with their link to hand over
  llms.txt#Refusals meter nothing
    → tax-example › refuses the three acts that belong to people, naming whose each is, and meters nothing · no job.ordered and no charge on the feed, and the key has spent $0
  data.js#the sample borrower's income: 2024 $105,300 and 2025 $113,600 added back, increasing 7.88%, $9,120.83 a month on the 24-month average
    → tax-example › figures the sample borrower's income the Form 1084 way
  data.js#each reserved act's refusal: permanent, with its cure, and charge null
    → tax-example › refuses the three acts that belong to people, naming whose each is, and meters nothing · act_refused is never performed here: each names its row, its cure route or none, and charges nothing

## adapted · 6
  llms.txt#access: POST https://apis.finance/request-key with first_name, last_name, email and property=apis.tax
    → tax-example › answers not_live with its waitlist as next, and holds nothing · the generated waitlist takes an email and gives a place in line, and a key comes from POST /keys; the family form stays on the hub
  llms.txt#tax.transcript: ordered on the taxpayer's signed Form 4506-C through an IVES participant
    → tax-example › orders on the taxpayer's signed consent under the brand's participant status, or reads the return it filed · source: 'ives' asks the taxpayer for the 4506-C and orders under the brand's ives credential; source: 'filed' reads a return the brand filed, on its §7216 consent
  llms.txt#tax.transcript: the IRS must receive a 4506-C within 120 days of signing
    → tax-example › orders on the taxpayer's signed consent under the brand's participant status, or reads the return it filed · the clock named for the order falls due 120 days after the consent, and its receipt satisfies it; a filed return needs no 4506-C
  llms.txt#return.fields: lines from the return, each with its form, tax year and line number
    → tax-example › orders on the taxpayer's signed consent under the brand's participant status, or reads the return it filed · the fields step cites each field by form, tax year and line, and on a filed return by the filing's receipt as well
  data.js#the sample borrower's transcript: return transcripts for 2024 and 2025, consent signed 2026-09-28, receive_by 2027-01-26
    → tax-example › orders on the taxpayer's signed consent under the brand's participant status, or reads the return it filed · ordered for 2024 and 2025 on a consent signed 2026-09-28; the order's clock falls due 2027-01-26
  data.js#the sample borrower's 2025 Schedule C fields: lines 1, 13, 30 and 31, each with its form and tax year
    → tax-example › orders on the taxpayer's signed consent under the brand's participant status, or reads the return it filed · the same lines, each cited by form, tax year and line, read by the fields step

## not ported · 1
  llms.txt#In the family: apis.finance, the hub, and seven sibling doors
    each sibling is another brand with its own door; this example is one brand, and the family stays on the hub
```

## What was decided

Three rows needed a decision:

| Flow | Decision | Why |
|---|---|---|
| `boundary`: no return prepared, no taxpayer represented, nothing signed for one | kept, as the Transcript's three refused rows | The lender door still refuses all three. The brand prepares, signs and represents on other Services, each through a credentialed step: [the rules table](https://services.dev/docs/examples/tax/rules.md) |
| `access`: a key requested on the family hub's form | the generated waitlist and key | An order answers `not_live` with the waitlist as `next`, and a key comes from `POST /keys`; the family's form stays on the hub |
| `In the family`: the hub and seven sibling doors | stays on the hub | Each sibling is another brand with its own door; this example is one brand |

The adapted transcript rows take one new key: `source: 'filed' | 'ives'`. A lender the §7216 consent names reads the return the brand filed, cited to its receipt, with no 4506-C and no wait.

## Its behavior tests

Each flow names the test that proves it. Four tests carry all sixteen:

| Test | Proves |
|---|---|
| answers not_live with its waitlist as next, and holds nothing | the door's status and its access |
| refuses the three acts that belong to people, naming whose each is, and meters nothing | the boundary, each reserved act's refusal and its cure, and that refusals meter nothing |
| orders on the taxpayer's signed consent under the brand's participant status, or reads the return it filed | the transcript, its 120-day clock, its fields and the sample borrower |
| figures the sample borrower's income the Form 1084 way | the income analysis and the sample's figures |

`test/apis-tax-flows.test.ts` holds the list to the door, flow for flow:

```bash
npx vitest run test/apis-tax-flows.test.ts
```

```txt title="magic values: none"
 Test Files  1 passed (1)
      Tests  3 passed (3)
```

## Port your own

`flows.ts` is a list: each flow the door states, the test that proves it, and its mark. `test/apis-tax-flows.test.ts` fails a source flow with no row, a row with no source, and a test that names no test. Its type, and one row of each mark:

```ts title="tax · flows.ts"
export type FlowMark = 'matched' | 'adapted' | 'not ported'
export interface Flow {
  source: string
  mark: FlowMark
  test?: string
  why?: string
}
export default [
  { source: 'llms.txt#Refusals meter nothing', mark: 'matched', test: refused, why: 'no job.ordered and no charge on the feed, and the key has spent $0' },
  { source: 'llms.txt#tax.transcript: the IRS must receive a 4506-C within 120 days of signing', mark: 'adapted', test: transcript, why: 'the clock named for the order falls due 120 days after the consent, and its receipt satisfies it; a filed return needs no 4506-C' },
  { source: 'llms.txt#In the family: apis.finance, the hub, and seven sibling doors', mark: 'not ported', why: 'each sibling is another brand with its own door; this example is one brand, and the family stays on the hub' },
] satisfies Flow[]
```

[What the brand gets](https://services.dev/docs/examples/tax/surfaces.md) shows the same operations on every surface.

---

- Up: [The tax example](https://services.dev/docs/examples/tax.md)
- Previous: [When a date is missed](https://services.dev/docs/examples/tax/missed.md)
- Next: [Take your first real return](https://services.dev/docs/examples/tax/launch.md)