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

  • Read Calculators.
  • Read the public boundary in API and SDK.
  • 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

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

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

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

Attach source citations, test output, compatibility notes and a Changeset or no-Changeset rationale in PR evidence checklist.

Read this page as Markdown