us-tax-advantaged-params 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The project follows Semantic Versioning.
+
+## [Unreleased]
+
+### Changed
+
+- **Renamed the package and its public symbol.** The scope is broadening from federal retirement accounts to U.S. tax-advantaged accounts generally, so the identities were changed before the package acquired consumers:
+  - npm: `usa-retirement-account-parameters` → `us-tax-advantaged-params`
+  - Composer: `bherila/usa-retirement-account-parameters` → `bherila/us-tax-advantaged-params`
+  - TypeScript class / default export and PHP class and namespace: `USARetirementAccountParameters` → `USTaxAdvantagedParams`
+  - Engine, test, and built artifact filenames follow the symbol (`src/USTaxAdvantagedParams.ts`, `php/src/USTaxAdvantagedParams.php`, `dist/{esm,cjs}/USTaxAdvantagedParams.js`, `dist/types/USTaxAdvantagedParams.d.{ts,cts}`).
+  - The GitHub repository moved to `bherila/us-tax-advantaged-params`; GitHub redirects the previous path.
+
+  This is a breaking rename with no compatibility alias. Calculation behavior, the encoded 1975-2026 parameter range, the result shape, and the conformance vectors are unchanged.
+
+- `data/retirement-parameters.json` keeps its filename and its `./data/retirement-parameters.json` subpath export; only its `package` field was updated to the new npm name. Renaming the data file is a separate module-layout decision.
+
+### Fixed
+
+- `npm pack --dry-run` no longer fails through `prepack`. npm exported `npm_config_dry_run=true` into the nested `npm pack` that `check:types` runs, so no tarball was written and `attw` failed with `ENOENT`. The inner pack now passes `--no-dry-run`.
+
+## [0.1.0] - 2026-08-28
+
+### Fixed
+
+- Designated Roth governmental 457(b) contributions are now gated on their statutory 2011 start date (Small Business Jobs Act of 2010, IRC §402A(e)(1)); earlier years return `unavailable` instead of a determinate Roth deferral.
+- The SIMPLE 401(k) 3% matching contribution is now computed on §401(a)(17)-capped compensation; the SIMPLE IRA match correctly remains exempt from the compensation cap.
+
+### Changed
+
+- Composer autoloading switched from `files` to lazy `classmap` (the engine no longer defines namespace-level constants; `PACKAGE_NAME` and `ENGINE_VERSION` are class constants).
+- The PHP requirement was lowered from 8.5 to 8.2, with PHP 8.2-8.5 tested in CI.
+- The npm package now ships a CommonJS-flavored `.d.cts` declaration for `require` consumers and exports `./data/retirement-parameters.json` and `./package.json` through the exports map.
+
+### Added
+
+- Error-expectation conformance vectors (`expectError`) exercised by both native suites and the cross-language parity check, plus new vectors covering MFS phase-outs, modern spousal IRAs, ordinary age-50 catch-up, age-64 reversion, and effective-year boundaries (1975, 2010, 2020, 2023).
+- `@arethetypeswrong/cli` package-resolution gate, tag-triggered npm publish workflow with provenance, and Dependabot configuration.
+- Native single-file TypeScript and PHP retirement-account calculation engines.
+- Builder and direct-input interfaces for taxpayers, spouses, accounts, existing contributions, plan rules, and Roth conversions.
+- Historical parameter coverage from 1975 through 2026 without future-year extrapolation.
+- Traditional/Roth IRA sharing, IRA deduction and Roth phase-outs, spousal IRA compensation, historical restrictions, and nondeductible IRA treatment.
+- Qualified-plan §402(g), §414(v), and §415(c) shared-pool allocation.
+- Governmental and nongovernmental 457(b), 403(b) 15-year catch-up, 457(b) special catch-up, SIMPLE, SEP, SARSEP, TSP, employer-only plans, and explicit actuarial indeterminacy for pensions.
+- Enhanced age-60-to-63 catch-up and high-wage Roth catch-up classification.
+- IRA-to-Roth, qualified-plan-to-Roth-IRA, and in-plan Roth conversion calculations with aggregate pro-rata IRA basis.
+- Canonical annual data, generation tooling, native tests, shared conformance vectors, and complete cross-runtime parity checking.
+- ESM, CommonJS, TypeScript declarations, Composer manifest, CI, release validation, documentation, and MIT license.
+
+#### Pre-release corrections
+
+- Apply the applicable §401(a)(17) recognized-compensation ceiling before multiplying compensation by employer nonelective, employer matching, and common-law SEP contribution rates.
+- For self-employed percentage contributions, compare the reduced-rate net-earnings amount with recognized compensation multiplied by the unreduced plan rate before applying other annual limits.
+- Preserve actual-compensation treatment for employee elective deferrals rather than imposing the §401(a)(17) ceiling as an additional §402(g) cutoff.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Herila
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,413 @@
+# us-tax-advantaged-params
+
+[![CI](https://github.com/bherila/us-tax-advantaged-params/actions/workflows/ci.yml/badge.svg)](https://github.com/bherila/us-tax-advantaged-params/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+`us-tax-advantaged-params` is a dependency-free calculation engine for historical and current U.S. tax-advantaged account parameters. Retirement accounts are the coverage today: it calculates account-level and household-level contribution capacity, IRA phase-outs, shared statutory limits, federal income effects, and Roth-conversion taxability.
+
+The repository contains two native implementations with the same behavior:
+
+- **TypeScript** for npm, exported as `USTaxAdvantagedParams`.
+- **PHP 8.2+** for Packagist, in the `USTaxAdvantagedParams` namespace.
+
+Annual legal parameters are maintained once in `data/retirement-parameters.json` and generated into each single-file runtime. Shared conformance vectors and a full-output parity check keep the TypeScript and PHP engines synchronized.
+
+> **Tax-software scope, not tax advice.** This package calculates statutory parameters from caller-supplied facts. It does not determine whether a plan document permits a contribution, perform ERISA nondiscrimination testing, calculate self-employment tax, replace Form 8606, provide an actuarial valuation, or prepare a tax return. Review material results against the governing plan document and current primary authority.
+
+## Supported tax years
+
+The encoded range is **1975 through 2026**. The package does not extrapolate a future year. Calling a year outside the range throws `UnsupportedTaxYearError` in TypeScript or `UnsupportedTaxYearException` in PHP.
+
+The 1975 starting point corresponds to the first generally available IRA contribution year. Some early employer-plan years cannot be reduced to a universal modern dollar ceiling from tax year alone. In those cases the engine returns an explicit `indeterminate` status and diagnostic rather than inventing a value.
+
+```ts
+USTaxAdvantagedParams.supportedTaxYears();
+// { minimum: 1975, maximum: 2026 }
+```
+
+## Installation
+
+### npm
+
+```bash
+npm install us-tax-advantaged-params
+```
+
+The npm package provides ESM, CommonJS, and TypeScript declarations and supports Node.js 20 or later.
+
+```js
+// ESM
+import USTaxAdvantagedParams from "us-tax-advantaged-params";
+
+// CommonJS — the class is the module's default export
+const USTaxAdvantagedParams = require("us-tax-advantaged-params").default;
+```
+
+### Composer / Packagist
+
+```bash
+composer require bherila/us-tax-advantaged-params
+```
+
+The PHP package requires PHP 8.2 or later and loads the native single-file implementation through Composer.
+
+## TypeScript builder example
+
+```ts
+import USTaxAdvantagedParams, {
+  AccountType,
+  ConversionType,
+  FilingStatus,
+} from "us-tax-advantaged-params";
+
+const result = USTaxAdvantagedParams.forTaxYear(2026)
+  .filingStatus(FilingStatus.MARRIED_FILING_JOINTLY)
+  .taxpayer("taxpayer", (person) => {
+    person
+      .bornIn(1963)
+      .iraCompensation(180_000)
+      .w2Compensation(180_000)
+      .rothIraMagi(240_000)
+      .traditionalIraDeductionMagi(240_000)
+      .coveredByEmployerPlan(true)
+      .priorYearFicaWages("employer-a", 180_000)
+      .aggregateTraditionalSepSimpleIraBasis(20_000)
+      .yearEndTraditionalSepSimpleIraValue(80_000);
+  })
+  .spouse("spouse", (person) => {
+    person
+      .bornIn(1970)
+      .iraCompensation(0)
+      .rothIraMagi(240_000)
+      .traditionalIraDeductionMagi(240_000)
+      .coveredByEmployerPlan(false);
+  })
+  .account(
+    "taxpayer-401k",
+    "taxpayer",
+    AccountType.TRADITIONAL_401K,
+    (account) => {
+      account
+        .employer("employer-a")
+        .annualAdditionsGroup("employer-a")
+        .planCompensation(180_000)
+        .permitsRothContributions()
+        .permitsRothCatchUp()
+        .permitsAfterTaxContributions()
+        .expectedEmployerContribution(9_000)
+        .priority(10);
+    },
+  )
+  .account("taxpayer-roth-ira", "taxpayer", AccountType.ROTH_IRA, (account) => {
+    account.priority(20);
+  })
+  .account("spouse-traditional-ira", "spouse", AccountType.TRADITIONAL_IRA, (account) => {
+    account.priority(30);
+  })
+  .conversion(
+    "ira-conversion",
+    "taxpayer",
+    ConversionType.IRA_TO_ROTH_IRA,
+    10_000,
+  )
+  .calculate();
+
+console.log(result.accounts[0].maximumAnnualContributionBasedOnInputs);
+console.log(result.totals.federalAgiReduction);
+console.log(result.conversions[0].taxableAmount);
+```
+
+A built scenario can be inspected and calculated repeatedly:
+
+```ts
+const scenario = USTaxAdvantagedParams.forTaxYear(2026)
+  .filingStatus("MFJ")
+  .taxpayer("taxpayer", (person) => person.bornIn(1980).w2Compensation(200_000))
+  .build();
+
+const input = scenario.toInput();
+const result = scenario.calculate();
+```
+
+## PHP builder example
+
+```php
+<?php
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+use USTaxAdvantagedParams\AccountType;
+use USTaxAdvantagedParams\FilingStatus;
+use USTaxAdvantagedParams\PersonBuilder;
+use USTaxAdvantagedParams\RetirementAccountBuilder;
+use USTaxAdvantagedParams\USTaxAdvantagedParams as TaxAdvantagedParams;
+
+$result = TaxAdvantagedParams::forTaxYear(2026)
+    ->filingStatus(FilingStatus::MARRIED_FILING_JOINTLY)
+    ->taxpayer('taxpayer', static function (PersonBuilder $person): void {
+        $person
+            ->bornIn(1963)
+            ->iraCompensation(180_000)
+            ->w2Compensation(180_000)
+            ->rothIraMagi(240_000)
+            ->traditionalIraDeductionMagi(240_000)
+            ->coveredByEmployerPlan(true)
+            ->priorYearFicaWages('employer-a', 180_000);
+    })
+    ->spouse('spouse', static function (PersonBuilder $person): void {
+        $person
+            ->bornIn(1970)
+            ->iraCompensation(0)
+            ->rothIraMagi(240_000)
+            ->traditionalIraDeductionMagi(240_000)
+            ->coveredByEmployerPlan(false);
+    })
+    ->account(
+        'taxpayer-401k',
+        'taxpayer',
+        AccountType::TRADITIONAL_401K,
+        static function (RetirementAccountBuilder $account): void {
+            $account
+                ->employer('employer-a')
+                ->annualAdditionsGroup('employer-a')
+                ->planCompensation(180_000)
+                ->permitsRothContributions()
+                ->permitsRothCatchUp()
+                ->permitsAfterTaxContributions()
+                ->expectedEmployerContribution(9_000)
+                ->priority(10);
+        },
+    )
+    ->account('spouse-ira', 'spouse', AccountType::TRADITIONAL_IRA)
+    ->calculate();
+
+var_dump($result['totals']);
+```
+
+The PHP result is an associative-array equivalent of the TypeScript result. Enum values serialize to the same snake-case strings.
+
+## Direct unified interface
+
+Builders are optional. Both engines accept the same language-neutral scenario shape, which is useful for services, fixtures, database records, and cross-runtime integrations.
+
+```ts
+const result = USTaxAdvantagedParams.calculate({
+  taxYear: 2026,
+  filingStatus: "HOH",
+  persons: [
+    {
+      id: "taxpayer",
+      role: "taxpayer",
+      birthYear: 1975,
+      compensation: { iraCompensation: 140_000, w2Compensation: 140_000 },
+      magi: { rothIra: 158_000, traditionalIraDeduction: 158_000 },
+      coveredByEmployerRetirementPlan: true,
+    },
+  ],
+  accounts: [
+    {
+      id: "401k",
+      ownerId: "taxpayer",
+      type: "traditional_401k",
+      employerId: "employer-a",
+      planRules: {
+        planCompensation: 140_000,
+        annualAdditionsGroupId: "employer-a",
+        expectedEmployerContribution: 7_000,
+      },
+    },
+    { id: "roth-ira", ownerId: "taxpayer", type: "roth_ira", priority: 20 },
+  ],
+});
+```
+
+Filing-status aliases include `S`, `SINGLE`, `MFJ`, `MFS`, `HOH`, `QSS`, and `QW`. The alias `M` is accepted as MFJ but emits an ambiguity diagnostic. Canonical values are preferred in persisted data.
+
+## Account coverage
+
+| Family | Account types |
+|---|---|
+| Individual retirement arrangements | Traditional IRA, Roth IRA, rollover IRA, payroll-deduction IRA, deemed traditional/Roth IRA, inherited traditional/Roth IRA |
+| Small-employer arrangements | SEP IRA, Roth SEP IRA, SIMPLE IRA, Roth SIMPLE IRA, grandfathered SARSEP |
+| Qualified elective plans | Traditional/Roth 401(k), Solo/Roth Solo 401(k), SIMPLE/Roth SIMPLE 401(k), starter 401(k) |
+| Tax-sheltered annuities | Traditional/Roth 403(b), safe-harbor deferral-only 403(b) |
+| Deferred compensation | Governmental/Roth governmental 457(b), nongovernmental eligible 457(b), 457(f) |
+| Federal plan | Traditional and Roth TSP |
+| Employer-only defined-contribution plans | 401(a), profit-sharing, money-purchase, Keogh, ESOP |
+| Pension arrangements | Defined-benefit and cash-balance plans |
+
+Defined-benefit and cash-balance contributions are deliberately returned as `indeterminate`; their funding requires the plan formula, census, assets, actuarial assumptions, and funding rules.
+
+## Result semantics
+
+| Field | Meaning |
+|---|---|
+| `statutoryMaximumAnnualContribution` | Overall monetary legal ceiling when determinable from encoded law and supplied facts |
+| `maximumAnnualContributionBasedOnInputs` | Maximum supported by law and supplied plan capabilities/formulas |
+| `maximumAdditionalContributionBasedOnInputs` | Remaining supported amount after existing contributions |
+| `existingAnnualContribution` | Existing contribution components supplied by the caller |
+| `planTermDependentCapacity` | Potential space that cannot be allocated without additional plan/employer facts |
+| `contributionComponents` | Pretax, Roth, after-tax, employer, IRA, and catch-up components |
+| `federalTaxEffects` | Federal AGI, taxable-income, W-2 box 1, nondeductible, after-tax/Roth, and conversion effects |
+| `sharedLimits` | Audit trail showing each statutory pool used by the account |
+| `diagnostics` | Assumptions, warnings, unavailable rules, and legal references |
+
+`maximumAnnualContributionBasedOnInputs` is a mechanical result, not a contribution recommendation.
+
+## Shared-limit allocation
+
+Accounts are allocated in ascending `priority` and then input order. This makes overlapping limits deterministic.
+
+The engine tracks, among other pools:
+
+- Traditional and Roth IRA contributions per owner.
+- Joint-return compensation available for spousal IRAs.
+- The owner-level §402(g) elective-deferral limit across applicable 401(k), 403(b), TSP, SARSEP, and SIMPLE sources.
+- The owner-level §414(v) age-based catch-up pool.
+- A separate §457(b) limit.
+- §415(c) annual additions per participant and controlled-employer group.
+- The owner-level 403(b) 15-years-of-service catch-up pool.
+- The 457(b) last-three-years special catch-up.
+
+Use the same `annualAdditionsGroupId` for plans that share one §415(c) controlled-employer limit. Unrelated employers should normally use different group IDs.
+
+## Recognized compensation under §401(a)(17)
+
+When a caller supplies an employer contribution **rate**, the engine first limits plan compensation to the applicable annual recognized-compensation ceiling and then applies the rate. This applies to:
+
+- Employer nonelective formulas.
+- Employer matching formulas whose matchable compensation is expressed as a fraction of compensation.
+- Common-law employee SEP formulas.
+- The plan-rate side of self-employed SEP and qualified-plan formulas.
+
+For a self-employed owner, the maximum percentage contribution is the lesser of:
+
+1. net earnings after the deductible half of self-employment tax multiplied by the reduced self-employed rate; and
+2. recognized compensation multiplied by the unreduced plan contribution rate.
+
+The result remains subject to §415(c), plan-document limits, and existing annual additions.
+
+The compensation ceiling is **not** imposed as an extra dollar cap that prematurely stops an employee’s otherwise valid §402(g) elective deferral. Employee deferrals remain subject to actual compensation, §402(g), catch-up rules, shared pools, and plan terms.
+
+SIMPLE formulas preserve their distinct treatment: the ordinary 3% matching method is based on compensation and deferrals, while the 2% nonelective method and applicable additional nonelective contribution use recognized compensation.
+
+Supplying `expectedEmployerContribution` bypasses formula inference because it represents a known caller-provided employer amount. The amount is still constrained by applicable annual-additions and plan-document ceilings.
+
+## IRA phase-outs and spousal IRAs
+
+The package models:
+
+- The combined traditional/Roth IRA annual contribution limit.
+- Age-50 IRA catch-up amounts.
+- Roth IRA MAGI phase-outs.
+- Traditional IRA active-participant deduction phase-outs.
+- The separate phase-out for a noncovered spouse married to a covered participant.
+- Married-filing-separately rules, including whether spouses lived together during the year.
+- MFJ spousal-IRA compensation sharing.
+- Historical one-earner spousal limits.
+- The pre-2020 traditional-IRA age-70½ contribution restriction.
+- Nondeductible traditional IRA capacity when a deduction is unavailable.
+- IRS worksheet-style phase-out rounding and the positive reduced minimum.
+
+Supply the MAGI value applicable to each calculation. The engine does not derive tax-return MAGI from raw income items.
+
+## Catch-up contributions and birth data
+
+Age is generally determined at the end of the tax year. `bornIn(year)` is sufficient for ordinary age-50 and age-60-to-63 catch-up rules; `bornOn(YYYY-MM-DD)` is preferred for legacy age-70½ edge cases.
+
+There is no general pre-1960/post-1960 retirement-account contribution-limit split. The 1960 boundary is primarily associated with Social Security full retirement age, not these contribution limits.
+
+Supported catch-up logic includes:
+
+- Ordinary age-50 catch-up.
+- Enhanced age-60-to-63 catch-up beginning in 2025.
+- 403(b) 15-years-of-service catch-up, including annual and lifetime residuals.
+- Governmental 457(b) age catch-up.
+- The 457(b) special last-three-years catch-up, selecting the larger applicable method rather than combining incompatible methods.
+- High-wage Roth catch-up classification using prior-year FICA wages for the sponsoring employer when applicable.
+
+## Roth conversions and in-plan Roth rollovers
+
+Conversions are separate from contributions and do not consume the annual IRA or elective-deferral limit.
+
+Supported conversion categories are:
+
+- Traditional/SEP/SIMPLE IRA to Roth IRA.
+- Qualified plan to Roth IRA.
+- In-plan Roth rollover.
+
+For IRA conversions, the engine can allocate aggregate traditional/SEP/SIMPLE IRA basis using Form 8606-style pro-rata treatment. Supply aggregate basis, year-end aggregate IRA value, and other current-year distributions when relevant. Multiple same-year conversion inputs share basis without penny over-allocation.
+
+The package reports gross converted amount, taxable amount, nontaxable basis, AGI increase, and diagnostics. It does not calculate withholding, estimated-tax penalties, five-year holding periods, early-distribution recapture, state tax, or full plan distribution eligibility.
+
+## Calculation status and diagnostics
+
+Possible statuses are:
+
+- `determinate`
+- `determinate_with_assumptions`
+- `indeterminate`
+- `unavailable`
+- `ineligible`
+
+Do not discard diagnostics. They are part of the calculation contract. A non-error status may still contain warnings about missing plan terms, historical uncertainty, employer aggregation, Roth catch-up classification, or caller assumptions.
+
+## Native TypeScript/PHP parity
+
+The DRY boundary is the statutory data and behavioral specification, not a cross-language runtime dependency:
+
+```text
+data/retirement-parameters.json
+           │
+           ├── generated TypeScript parameter block
+           ├── generated PHP parameter block
+           └── shared conformance vectors
+                         │
+                         └── complete serialized-output parity test
+```
+
+This gives npm consumers an idiomatic TypeScript package and Packagist consumers an idiomatic PHP package without duplicating annual parameter maintenance.
+
+## Development
+
+```bash
+npm ci
+npm run validate:data
+npm run generate:check
+npm run typecheck
+npm run test:ts
+npm run test:php
+npm run test:parity
+npm run verify
+```
+
+After changing `data/retirement-parameters.json`:
+
+```bash
+npm run generate
+npm run verify
+```
+
+`npm run generate:check` fails if either native embedded data block differs from canonical JSON. `npm run test:parity` compares the complete TypeScript and PHP result for every shared vector, not merely selected assertions.
+
+See [DESIGN.md](DESIGN.md), [SOURCES.md](SOURCES.md), and [CONTRIBUTING.md](CONTRIBUTING.md) before changing legal parameters or calculation semantics.
+
+## Deliberate exclusions
+
+The package does not calculate:
+
+- State income-tax treatment.
+- The retirement savings contributions credit.
+- Required minimum distributions or distribution penalties.
+- Plan eligibility, vesting, loans, or distributions generally.
+- ADP, ACP, coverage, top-heavy, or other nondiscrimination testing.
+- Employer controlled-group ownership from raw entity records.
+- Full payroll, self-employment tax, or tax-return MAGI.
+- Defined-benefit or cash-balance actuarial funding.
+- Investment returns, retirement sufficiency, or withdrawal planning.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/SOURCES.md

@@ -0,0 +1,68 @@
+# Primary Authorities and Data Provenance
+
+## Source policy
+
+Retirement parameters are maintained from primary federal sources whenever available. The canonical machine-readable source list is embedded in `data/retirement-parameters.json` and exposed at runtime through `USTaxAdvantagedParams.sourceMetadata()`.
+
+Source metadata documents provenance; it is not fetched at runtime. Calculations are deterministic and network-free.
+
+## Core annual-limit sources
+
+- **IRS Notice 2025-67 / Internal Revenue Bulletin 2025-49** — 2026 retirement-plan and IRA cost-of-living adjustments, including §402(g), IRA, SIMPLE, catch-up, §415(c), §401(a)(17), SEP eligibility, and phase-out figures.  
+  `https://www.irs.gov/pub/irs-irbs/irb25-49.pdf`
+
+- **IRS Notice 2024-80 / Internal Revenue Bulletin 2024-47** — 2025 retirement-plan and IRA cost-of-living adjustments.  
+  `https://www.irs.gov/pub/irs-irbs/irb24-47.pdf`
+
+- **IRS Cash or Deferred Arrangements manual** — historical elective-deferral and related qualified-plan limitation tables and mechanics.  
+  `https://www.irs.gov/pub/irs-tege/codas.pdf`
+
+- **IRS SEP/SARSEP Audit Techniques** — SEP/SARSEP historical and operational limits.  
+  `https://www.irs.gov/pub/irs-tege/epche1303.pdf`
+
+- **IRS Statistics of Income Bulletin describing early IRA law** — historical 1981-and-earlier and 1982 IRA limits.  
+  `https://www.irs.gov/pub/irs-soi/83rpsumbul.pdf`
+
+- **U.S. Department of Labor 401(k) history** — contextual history of 401(k) plans and their development.  
+  `https://www.dol.gov/agencies/ebsa/about-ebsa/our-activities/resource-center/faqs/401k-plans`
+
+## Section 401(a)(17) employer-formula authorities
+
+- **IRS Notice 2001-56** states that §401(a)(17) limits annual compensation used to determine allocations under a defined-contribution plan and discusses the effective date of the EGTRRA compensation-limit increase.  
+  `https://www.irs.gov/pub/irs-drop/n-01-56.pdf`
+
+- **IRS Employee Plans News, Fall 2009, “When Limits Collide, Which One Wins?”** distinguishes §401(a)(17), §415(c), and §402(g). It describes the compensation cap for plan contributions while explaining why the cap should not be applied as an extra cutoff preventing an employee from completing the annual elective-deferral amount.  
+  `https://www.irs.gov/pub/irs-tege/fall09.pdf`
+
+- **IRS Publication 535 (2001), self-employed qualified-plan worksheet** demonstrates that self-employed contribution calculations compare the reduced-rate net-earnings amount with the annual compensation ceiling multiplied by the unreduced plan rate.  
+  `https://www.irs.gov/pub/irs-prior/p535--2001.pdf`
+
+- **IRS SARSEP Fix-it Guide** describes SEP/SARSEP total contribution limits as the lesser of the annual dollar limit and the applicable percentage of compensation, with compensation considered subject to the annual limit.  
+  `https://www.irs.gov/retirement-plans/sarsep-fix-it-guide-total-contributions-employee-elective-deferrals-and-nonelective-employer-contributions-exceeded-the-maximum-legal-limits`
+
+## IRA phase-outs and rounding
+
+Annual IRA contribution and phase-out values are encoded from the applicable IRS annual adjustment notices and IRA publications. The calculation follows the IRS reduced-contribution worksheet pattern: determine the reduction fraction, subtract it from the otherwise available contribution, round the result upward to the specified increment, apply the positive reduced minimum when applicable, and subtract other IRA contributions sharing the annual limit.
+
+## Historical confidence policy
+
+Historical tax law is not uniform across the full 1975–2026 range. Early salary-reduction arrangements, legacy 403(b) exclusion allowances, plan-document-specific limits, and actuarial pension funding cannot always be represented by one universal amount. The engines return diagnostics and an indeterminate result where the data does not support a precise answer.
+
+A historical row must not be added solely from a secondary summary when an IRS bulletin, publication, notice, regulation, statute, or Department of Labor source is reasonably available.
+
+## Annual update checklist
+
+For each new tax year:
+
+1. Obtain the final IRS cost-of-living adjustment notice or revenue procedure.
+2. Update all relevant limit, catch-up, compensation, SEP/SIMPLE, 457(b), starter-plan, and IRA phase-out fields.
+3. Add the primary source to the canonical source list.
+4. Run `npm run generate`.
+5. Add conformance vectors for changed rules and boundary values.
+6. Run `npm run verify` under supported Node and PHP versions.
+7. Review the generated diff in both runtime files; only generated data blocks should change for a data-only annual update.
+8. Record the update in `CHANGELOG.md` and update the package version as appropriate.
+
+## Legal-change policy
+
+A statutory or regulatory change that affects algorithmic behavior requires more than a data-row update. It should include a primary authority, a design note covering aggregation/effective date/transition relief/plan dependencies, native tests in both languages, shared conformance vectors, full-output parity, and migration notes when serialized contracts change.