Skip to Content

Tax contributor guide

How to contribute tax rules: what to change, the source rule, two walkthroughs, the checks and review.

This guide is for people who know a country’s or a state’s tax rules and want the code to follow them. You do not need to know the rest of the codebase.

The package is @trajectonomics/tax. It reaches users inside the traj CLI, which bundles it through packages/core as @trajectonomics/core/tax, with the Thai and US entry points at @trajectonomics/core/tax/th and @trajectonomics/core/tax/us. Paths in this guide are relative to this folder, packages/core/tax, unless they start with packages/.

Who this is for

  • Accountants and tax practitioners who can read a statute, a rate schedule or a form instruction.
  • Developers who know one of the jurisdictions well enough to check a figure against its source.

The code is pure. It does no I/O, reads no clock and uses no randomness. A rule is data plus a few pure functions. You change the data and the functions that read it, and every change is tested against a figure you can point to.

What you can contribute

From the easiest to the hardest:

  1. Report a wrong figure. Open the Tax: wrong figure issue. It asks for the official source URL, and the issue gets the tax label.
  2. Update a figure for a new tax year. Read walkthrough A first. Today the Thai and US engines only accept 2026, so a new year also needs the year wiring.
  3. Add worked examples from official documents to the test corpus. A corpus case is a literal input, literal expected figures and a comment that names its source.
  4. Add a US state. See Adding a US state.
  5. Add a new country. Read walkthrough B.

The source rule

Every statutory figure cites an official document.

Thailand. references/th/SOURCES.md has one row for each parameter path in TH_2026_PARAMETERS. A row names the parameter path, the figure as the document prints it, the citation, the URL that was read, the date it was read and a result:

  • match: the document states the figure and the engine applies it.
  • derived: the figure is hand arithmetic over documented figures. The row shows the working.
  • reported: only a secondary source states the 2026 figure. Enough for a corpus case, never for a match.
  • unsourced: neither the instrument nor a secondary source was read. No corpus case asserts it.
  • fixed: the engine was corrected from the document. Written only when the owner has authorised the change.

bun run check:th-sources fails when a parameter path has no row, when a row names no parameter, when a row is malformed, or when a corpus file imports something other than bun:test, the corpus harness or the money module.

United States. references/SOURCES.md has one table per verification level. Each row names the state, the document, the date read and the result. A state’s level is official, partial, reported or unconfirmed. Nothing runs a script over this file. src/us/tests/state-parameters.test.ts fails when the tally of levels in the file drifts from the parameter tables, and the reviewer checks each row.

Raw documents are not committed. references/* and references/th/* are git-ignored, except the two manifests. Download a document from the URL in its row, and keep it on your machine. A reviewer downloads the same URL to check the figure.

How the code is organised

Parameters are data; stages are logic. Statutory amounts, rates, allowances and brackets are typed constants. Thailand’s are in src/th/parameters.ts, with the brackets in src/th/parameters-brackets.ts and the special regimes in src/th/parameters-special.ts. The US federal constants are in src/us/parameters/, and each state’s table is in src/us/state/parameters/. The stages are in src/th/stages/, src/us/stages/ and src/us/state/. A stage reads its numbers from a parameter table. It never holds a statutory number of its own.

One rule per file. Each statutory rule is a pure function in its own file, under 100 lines. Each stage file has one test file of its own under 200 lines, so the test for a rule is easy to find.

Know each stage’s units before you change it. The public API takes major units, such as baht or dollars. Arithmetic that must not drift, such as the bracket slices in src/th/stages/bracket-eval.ts, converts to integer satang or cents with toMinorUnits and back with fromMinorUnits. Many Thai stages instead work in whole-baht major units. Every stage says which in a Units: line in its doc comment, for example “THB major units” or “inputs and outputs in THB major units; arithmetic in integer satang”. Read that line first, and keep it true when you change the stage. See ADR 0002.

Statutory rounding. Where a statute rounds down in whole baht, a stage that works in baht rounds down with Math.floor. The Section 40(1) and (2) expense is one example, in src/th/stages/expenses-40-1-2.ts.

No raw strings in stages. Diagnostic paths and breakdown keys are typed enums, such as ThTaxField and ThBracketField. Currency comes from the parameters, never from a literal. See ADR 0003.

Jurisdictions are subpaths. Each jurisdiction has its own entry point, so a caller imports only the rules it needs. See ADR 0001.

Money primitives come from the shared package. The conversions delegate to @trajectonomics/money. See ADR 0004.

The Thai pipeline is runThTaxPipeline in src/th/stages/pipeline.ts. It resolves the special regimes, then assessable income, expenses, allowances and brackets, then the minimum gross tax, and last the combined liability.

Walkthrough A: a new Thai tax year, end to end

Use this when a Thai figure changes for a new year. The example year is 2027.

  1. Find the instrument that moved the figure. Start from the Revenue Code section in the Revenue Department’s English publication, at https://www.rd.go.th/english/37749.html. The English text prints the Code as enacted, so find the Amendment Act, Royal Decree, Ministerial Regulation or Departmental Notification that changed the figure. The consolidated Code at https://www.rd.go.th/5937.html shows the current wording. Do not cite the personal income tax overview at https://www.rd.go.th/english/6045.html as a source of record. It prints 2013 and 2014 figures.
  2. Keep the document and write the row. Save the document in references/th/, which is git-ignored. Add a row to references/th/SOURCES.md for each changed parameter path, with the result word.
  3. Change the parameters, and the year wiring. This is the step the code does not yet support. TH_2026_PARAMETERS is the only parameter set. taxYear is typed as the literal 2026 in src/th/parameters-types.ts, and validateYear in src/th/stages/pipeline.ts rejects every other year. A 2027 set needs its own constant, a widened taxYear type, and a way to select the set by year. check:th-sources also compares the rows with TH_2026_PARAMETERS only, so it needs the new set wired in too. Review this step as a change to a stage, not as a data edit.
  4. Add a corpus case. Put it in the src/th/tests/corpus-*.test.ts file for the rule. Use literal expected baht figures and a comment that names the basis (documented, derived or reported) and the section. A corpus file imports only bun:test, ./corpus-harness and ../../core/money.
  5. Check it. Run bun run check:th-sources, then the full check in Checking your change.
  6. Review it. A reviewer re-reads each changed figure in its document. See Review.

Walkthrough B: a new country, from folder skeleton to export

Use this for a country that has no folder yet. The example code is xx, and the folder is src/xx/.

  1. Create the skeleton. Copy the shape of src/th/: parameters.ts with a taxYear and a currency, types.ts, calculate.ts for the entry function, system.ts for the TaxSystem value, index.ts for the public exports, and stages/ and tests/ folders. Keep index.ts to the public API.
  2. Add the currency if it is new. TaxSupportedCurrency in src/core/money/currency.ts is "THB" | "USD". A new currency means extending that type and the currency tables that go with it.
  3. Write the source manifest. Create references/xx/SOURCES.md in the Thai format: one row per parameter path, with a result word. No checker reads it yet. check-th-sources.ts is written for Thailand, so a new country needs its own check, or a reviewer checks every row by hand. Say which in the pull request.
  4. Write the first source-backed test. Put it in src/xx/tests/. Use literal expected figures from the document, and name the document in a comment.
  5. Cover your stages in the string check. scripts/check-no-hardcoded-strings.ts scans only src/th/stages, src/us/stages and src/us/state. Add your stage folder to STAGES_DIRS, or the check does not cover it.
  6. Export the subpath in the bundle. The bundle the CLI builds on is packages/core, not this folder. Add an entry such as "tax/xx/index": here("./tax/src/xx/index.ts") to packages/core/tsdown.config.ts. Add a ./tax/xx entry to packages/core/package.json, with the import and require types and default files, copied from the ./tax/th entry. In this folder, add src/xx/index.ts to the entry list in tsdown.config.ts, and a ./xx entry to exports in package.json, as ./th and ./us have.
  7. Check it. Run the tax checks and the core checks in Checking your change.

Adding a US state

  1. Put the state’s table in the file for its tax structure: src/us/state/parameters/progressive/ for a graduated schedule, or src/us/state/parameters/flat/ for a flat rate. A state with no income tax goes in src/us/state/parameters/none.ts.
  2. Set the table’s verification level, and add a row to the table for that level in references/SOURCES.md.
  3. Update the tally line in references/SOURCES.md, or src/us/tests/state-parameters.test.ts fails.
  4. Add a golden case in the matching src/us/tests/state-golden*.test.ts file.
  5. The README’s state paragraph is prose. No script checks it, so update it when a state’s treatment changes.

Checking your change

Run the tax checks from the repository root:

bunx turbo run check --filter=@trajectonomics/tax

Or run them inside packages/core/tax with bun run check. The check runs these steps in order: lint (Biome, then the hardcoded-string check check:strings), check:th-sources, typecheck, test (with the 100% line-coverage floor), build, check:readme and lint:package.

Run the core checks too when you change the bundle, its exports or the import rules:

bunx turbo run check --filter=@trajectonomics/core

What each failure means:

StepMessageWhat it meansWhat to do
lint (Biome)a formatting, import or style errorThe file does not match the shared styleRun bun run format.
lint (Biome)a file or function is too long or too complexA source file has over 100 lines, a test file over 200, or a function complexity over 10Split the file or the function.
lint (check:strings)Hardcoded diagnostic string, or Hardcoded ‘THB’A stage holds a raw field name or currencyUse the typed enum, or parameters.currency.
check:th-sourcesSOURCES ...: missing-rowA parameter path has no rowAdd the row with its document.
check:th-sourcesSOURCES ...: extra-rowA row names no parameterRemove the row, or add the parameter.
check:th-sourcesMANIFEST ... or duplicate-rowA row is malformed or repeatedFix the row.
check:th-sourcesCORPUS ...: forbidden importA corpus file imports something it may notImport only the three allowed modules.
typecheckan error on an exported valueThe build needs an explicit type on every exportAdd the type.
testcoverage below 100%A source file has a line no test runsAdd a test for the line.
testa corpus or stage test failsThe engine and the case disagreeRead the document again before you change either side.
buildtsdown errorThe bundle does not buildRead the error. It is usually an export or a type.
check:readmean example fails, or its output differsThe README example no longer runs as writtenUpdate the example and its output together.
check:readmea name is not exportedA backticked Th, Us, TH_, US_, calculate, emit or Tax name is not a public exportExport it, or stop naming it.
lint:packagepublint or attw errorThe exports or the types in package.json are wrongFix the entry you added.

Review

  • Write the title as a conventional commit with the tax scope: feat(tax): ... for a new year, state, country or rule, and fix(tax): ... for a corrected figure or a bug. Release versions are computed from commit messages, so the title matters.
  • Do not edit version in package.json. The release process sets it.
  • Name the official document in the pull request for each figure that changed: the URL, the page or section, and the date you read it.
  • A reviewer re-checks every changed figure against its cited source. The owner of this folder is @fromsukong, set in .github/CODEOWNERS.