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:
- Report a wrong figure. Open the Tax: wrong figure issue. It asks for the official source
URL, and the issue gets the
taxlabel. - 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.
- 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.
- Add a US state. See Adding a US state.
- 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 amatch.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.
- 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 athttps://www.rd.go.th/5937.htmlshows the current wording. Do not cite the personal income tax overview athttps://www.rd.go.th/english/6045.htmlas a source of record. It prints 2013 and 2014 figures. - Keep the document and write the row. Save the document in
references/th/, which is git-ignored. Add a row toreferences/th/SOURCES.mdfor each changed parameter path, with the result word. - Change the parameters, and the year wiring. This is the step the code does not yet support.
TH_2026_PARAMETERSis the only parameter set.taxYearis typed as the literal2026insrc/th/parameters-types.ts, andvalidateYearinsrc/th/stages/pipeline.tsrejects every other year. A 2027 set needs its own constant, a widenedtaxYeartype, and a way to select the set by year.check:th-sourcesalso compares the rows withTH_2026_PARAMETERSonly, so it needs the new set wired in too. Review this step as a change to a stage, not as a data edit. - Add a corpus case. Put it in the
src/th/tests/corpus-*.test.tsfile for the rule. Use literal expected baht figures and a comment that names the basis (documented,derivedorreported) and the section. A corpus file imports onlybun:test,./corpus-harnessand../../core/money. - Check it. Run
bun run check:th-sources, then the full check in Checking your change. - 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/.
- Create the skeleton. Copy the shape of
src/th/:parameters.tswith ataxYearand acurrency,types.ts,calculate.tsfor the entry function,system.tsfor theTaxSystemvalue,index.tsfor the public exports, andstages/andtests/folders. Keepindex.tsto the public API. - Add the currency if it is new.
TaxSupportedCurrencyinsrc/core/money/currency.tsis"THB" | "USD". A new currency means extending that type and the currency tables that go with it. - Write the source manifest. Create
references/xx/SOURCES.mdin the Thai format: one row per parameter path, with a result word. No checker reads it yet.check-th-sources.tsis 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. - 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. - Cover your stages in the string check.
scripts/check-no-hardcoded-strings.tsscans onlysrc/th/stages,src/us/stagesandsrc/us/state. Add your stage folder toSTAGES_DIRS, or the check does not cover it. - 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")topackages/core/tsdown.config.ts. Add a./tax/xxentry topackages/core/package.json, with theimportandrequiretypes and default files, copied from the./tax/thentry. In this folder, addsrc/xx/index.tsto theentrylist intsdown.config.ts, and a./xxentry toexportsinpackage.json, as./thand./ushave. - Check it. Run the tax checks and the core checks in Checking your change.
Adding a US state
- Put the state’s table in the file for its tax structure:
src/us/state/parameters/progressive/for a graduated schedule, orsrc/us/state/parameters/flat/for a flat rate. A state with no income tax goes insrc/us/state/parameters/none.ts. - Set the table’s
verificationlevel, and add a row to the table for that level inreferences/SOURCES.md. - Update the tally line in
references/SOURCES.md, orsrc/us/tests/state-parameters.test.tsfails. - Add a golden case in the matching
src/us/tests/state-golden*.test.tsfile. - 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:
| Step | Message | What it means | What to do |
|---|---|---|---|
lint (Biome) | a formatting, import or style error | The file does not match the shared style | Run bun run format. |
lint (Biome) | a file or function is too long or too complex | A source file has over 100 lines, a test file over 200, or a function complexity over 10 | Split the file or the function. |
lint (check:strings) | Hardcoded diagnostic string, or Hardcoded ‘THB’ | A stage holds a raw field name or currency | Use the typed enum, or parameters.currency. |
check:th-sources | SOURCES ...: missing-row | A parameter path has no row | Add the row with its document. |
check:th-sources | SOURCES ...: extra-row | A row names no parameter | Remove the row, or add the parameter. |
check:th-sources | MANIFEST ... or duplicate-row | A row is malformed or repeated | Fix the row. |
check:th-sources | CORPUS ...: forbidden import | A corpus file imports something it may not | Import only the three allowed modules. |
typecheck | an error on an exported value | The build needs an explicit type on every export | Add the type. |
test | coverage below 100% | A source file has a line no test runs | Add a test for the line. |
test | a corpus or stage test fails | The engine and the case disagree | Read the document again before you change either side. |
build | tsdown error | The bundle does not build | Read the error. It is usually an export or a type. |
check:readme | an example fails, or its output differs | The README example no longer runs as written | Update the example and its output together. |
check:readme | a name is not exported | A backticked Th, Us, TH_, US_, calculate, emit or Tax name is not a public export | Export it, or stop naming it. |
lint:package | publint or attw error | The exports or the types in package.json are wrong | Fix the entry you added. |
Review
- Write the title as a conventional commit with the
taxscope:feat(tax): ...for a new year, state, country or rule, andfix(tax): ...for a corrected figure or a bug. Release versions are computed from commit messages, so the title matters. - Do not edit
versioninpackage.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.