# Add a calculator [#add-a-calculator]

Use this guide when you need a new public calculation goal or report, such as
a new withholding, annual tax or repayment calculation.

## Before you start [#before-you-start]

* Read [Calculators](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/docs/architecture/calculators.md).
* Read the public boundary in
  [API and SDK](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/docs/architecture/api-and-sdk.md).
* Inspect the calculator catalogue in `@taxkit/calculators`.

The rule package owns the calculator program, report schema and rule-pack
layer. `@taxkit/calculators` owns reusable catalogue entries,
`CalculatorRunRequest`, `CalculatorRunResponse`, `CalculatorServiceError`,
metadata projections, graph construction and service execution.

## Proposal [#proposal]

Describe:

* the calculation goal and report fields
* the accepted input facts and scenario context
* the rule packs and parameter services required for each supported tax year
* the canonical calculator ID, jurisdiction and tax-year literals
* expected errors and validation help
* API and SDK compatibility impact

## Implementation [#implementation]

Keep the calculator small. It should require facts and return a schema-backed
report. Rule layers should derive tax facts.

```txt
accepted input facts
  -> scenario layer
  -> official rule pack layer
  -> calculator program
  -> schema-backed report
```

Do not place calculator business logic in `@taxkit/api-http` handlers, SDK
helpers or docs-only examples. HTTP and SDK layers must call the canonical
calculator boundary and preserve `CalculatorRun*` contracts.

## Tests [#tests]

Your evidence should include:

* golden tests for the calculator output
* graph validation for every required and provided fact
* schema decode tests for calculator input and report schemas
* type tests for SDK descriptor inference
* API compatibility tests for `POST /api/v1/calculators/:calculatorId/calculate`
* SDK compatibility tests for `TaxKit.calculate`, `TaxKit.safe.calculate`
  and any jurisdiction helper such as `au.incomeTax.annual`

## Pull request evidence [#pull-request-evidence]

Attach source citations, test output, compatibility notes and a Changeset or
no-Changeset rationale in [PR evidence checklist](/contributing/pr-evidence-checklist).