Add a rule

Use this guide when you need a source-backed calculation rule, threshold, coefficient formula, parameter table or derived fact.

Before you start

The rule package owns the rule layer, parameter service, descriptor, source references, graph metadata, rule-pack composition and golden tests.

Proposal

Before implementation, write down:

  • the official source and section, table, schedule or page range
  • the effective period and tax year
  • the input facts and parameter services the rule requires
  • the facts, traces or ledger components the rule provides
  • the rounding mode and edge cases
  • whether the change needs API compatibility tests or SDK compatibility tests

Implementation

Rules are Effect Layers. Parameter tables are services, not imported globals. The existing Schedule 1 parameter file uses this definition:

ts
export const AtoSchedule1_2025_26_Live =
  Layer.succeed(AtoSchedule1Table)(table2025_26);

This is an excerpt from the owning parameter source. That file imports Layer, defines AtoSchedule1Table and checks table2025_26 with its owning schema. The excerpt needs those definitions; it is not a complete application example.

Keep algorithm code separate from yearly data. Most tax-year updates should add schema-validated parameter data and golden tests without rewriting the rule algorithm.

Tests

Your evidence should include:

  • source reference validation for each official source
  • effective-date overlap checks for parameter descriptors
  • graph cycle and duplicate-provider checks
  • golden tests from official examples or known scenarios
  • date-boundary tests when thresholds change across periods
  • trace snapshot tests when rule IDs, source references or ledgers change
  • package export or type tests when public exports change

Pull request evidence

Use Source citation standards and PR evidence checklist. Explain whether the rule changes public API or SDK behaviour, even when endpoint shapes do not change.

Read this page as Markdown