us-tax-advantaged-params 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,8 +4,30 @@ All notable changes to this project will be documented in this file. The project
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-08-30
+
 ### Changed
 
+- **Renamed the remaining retirement-scoped public symbols.** The package models only retirement accounts today, so these names were accurate, but they become wrong the moment a non-retirement account type lands, and renaming them after adoption would be a breaking change for real consumers. Done now, while the consumer count is zero:
+
+  | Before | After |
+  | --- | --- |
+  | `RetirementAccountInput` | `AccountInput` |
+  | `RetirementScenarioInput` | `ScenarioInput` |
+  | `RetirementScenarioResult` | `ScenarioResult` |
+  | `RetirementAccountBuilder` | `AccountBuilder` |
+  | `RetirementScenario` | `Scenario` |
+  | `RetirementScenarioBuilder` | `ScenarioBuilder` |
+  | `RetirementParameterError` (TS) | `ParameterError` |
+  | `RetirementParameterException` (PHP) | `ParameterException` |
+  | `calculateRetirementScenario` (TS) | `calculateScenario` |
+
+  This makes the surface internally consistent: the prefix was already absent from `PersonBuilder`, `RothConversionBuilder`, `AccountType`, and `UnsupportedTaxYearError`/`Exception`, so the retirement-prefixed names were the minority, not the convention. `UnsupportedTaxYearError extends ParameterError` (and the PHP equivalent) is unchanged.
+
+  Genuinely retirement-specific *data* fields keep their names, because they describe retirement plans and will still be correct alongside other account types: `coveredByEmployerRetirementPlan` (the §219(g) active-participant test) and `selfEmployedRetirementDeduction`.
+
+  Breaking, with no compatibility aliases. Calculation behavior, the encoded 1975-2026 parameter range, the result shape, and the conformance vectors are unchanged — the 46-vector cross-language parity suite passes untouched.
+
 - **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`
@@ -23,6 +45,8 @@ All notable changes to this project will be documented in this file. The project
 
 ## [0.1.0] - 2026-08-28
 
+> **The `0.1.0` published to npm on 2026-08-30 does not match this entry.** It was built from a tree that already carried the package/symbol rename listed under 0.2.0 above, so its public API is `USTaxAdvantagedParams` with the `Retirement*`-prefixed member names — a combination no tagged release describes. It exists only because the rename was published before a release entry was cut. Use 0.2.0; `0.1.0` is superseded and should be treated as a bootstrap artifact.
+
 ### 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.

package/README.md

@@ -141,7 +141,7 @@ require_once __DIR__ . '/vendor/autoload.php';
 use USTaxAdvantagedParams\AccountType;
 use USTaxAdvantagedParams\FilingStatus;
 use USTaxAdvantagedParams\PersonBuilder;
-use USTaxAdvantagedParams\RetirementAccountBuilder;
+use USTaxAdvantagedParams\AccountBuilder;
 use USTaxAdvantagedParams\USTaxAdvantagedParams as TaxAdvantagedParams;
 
 $result = TaxAdvantagedParams::forTaxYear(2026)
@@ -168,7 +168,7 @@ $result = TaxAdvantagedParams::forTaxYear(2026)
         'taxpayer-401k',
         'taxpayer',
         AccountType::TRADITIONAL_401K,
-        static function (RetirementAccountBuilder $account): void {
+        static function (AccountBuilder $account): void {
             $account
                 ->employer('employer-a')
                 ->annualAdditionsGroup('employer-a')

package/dist/cjs/USTaxAdvantagedParams.js

@@ -13,10 +13,10 @@
  * determined defined-benefit/cash-balance contributions.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.USTaxAdvantagedParams = exports.RetirementScenarioBuilder = exports.RetirementScenario = exports.RothConversionBuilder = exports.RetirementAccountBuilder = exports.PersonBuilder = exports.UnsupportedTaxYearError = exports.RetirementParameterError = exports.DiagnosticSeverity = exports.CalculationStatus = exports.ConversionType = exports.AccountType = exports.FilingStatus = exports.ENGINE_VERSION = exports.PACKAGE_NAME = void 0;
-exports.calculateRetirementScenario = calculateRetirementScenario;
+exports.USTaxAdvantagedParams = exports.ScenarioBuilder = exports.Scenario = exports.RothConversionBuilder = exports.AccountBuilder = exports.PersonBuilder = exports.UnsupportedTaxYearError = exports.ParameterError = exports.DiagnosticSeverity = exports.CalculationStatus = exports.ConversionType = exports.AccountType = exports.FilingStatus = exports.ENGINE_VERSION = exports.PACKAGE_NAME = void 0;
+exports.calculateScenario = calculateScenario;
 exports.PACKAGE_NAME = "us-tax-advantaged-params";
-exports.ENGINE_VERSION = "0.1.0";
+exports.ENGINE_VERSION = "0.2.0";
 var FilingStatus;
 (function (FilingStatus) {
     FilingStatus["SINGLE"] = "single";
@@ -5325,16 +5325,16 @@ const RAW_PARAMETERS = {
     }
 };
 /* </generated-parameters> */
-class RetirementParameterError extends Error {
+class ParameterError extends Error {
     code;
     constructor(code, message) {
         super(message);
-        this.name = "RetirementParameterError";
+        this.name = "ParameterError";
         this.code = code;
     }
 }
-exports.RetirementParameterError = RetirementParameterError;
-class UnsupportedTaxYearError extends RetirementParameterError {
+exports.ParameterError = ParameterError;
+class UnsupportedTaxYearError extends ParameterError {
     constructor(year, minimum, maximum) {
         super("UNSUPPORTED_TAX_YEAR", `Tax year ${year} is not supported. Supported years are ${minimum}-${maximum}; future years are never extrapolated.`);
         this.name = "UnsupportedTaxYearError";
@@ -5597,7 +5597,7 @@ function parseFilingStatus(value, diagnostics) {
     const token = normalizeToken(String(value));
     const parsed = FILING_STATUS_ALIASES[token];
     if (!parsed) {
-        throw new RetirementParameterError("INVALID_FILING_STATUS", `Unsupported filing status: ${value}`);
+        throw new ParameterError("INVALID_FILING_STATUS", `Unsupported filing status: ${value}`);
     }
     if (token === "M") {
         diagnostics?.push(diagnostic("AMBIGUOUS_M_ALIAS_ASSUMED_MFJ", DiagnosticSeverity.WARNING, 'Filing-status alias "M" was interpreted as married filing jointly. Use MFJ or MFS to be explicit.', "filingStatus"));
@@ -5610,7 +5610,7 @@ function parseAccountType(value) {
     }
     const parsed = ACCOUNT_TYPE_ALIASES[normalizeToken(String(value))];
     if (!parsed) {
-        throw new RetirementParameterError("INVALID_ACCOUNT_TYPE", `Unsupported retirement account type: ${value}`);
+        throw new ParameterError("INVALID_ACCOUNT_TYPE", `Unsupported retirement account type: ${value}`);
     }
     return parsed;
 }
@@ -5620,7 +5620,7 @@ function parseConversionType(value) {
     }
     const parsed = CONVERSION_TYPE_ALIASES[normalizeToken(String(value))];
     if (!parsed) {
-        throw new RetirementParameterError("INVALID_CONVERSION_TYPE", `Unsupported Roth conversion type: ${value}`);
+        throw new ParameterError("INVALID_CONVERSION_TYPE", `Unsupported Roth conversion type: ${value}`);
     }
     return parsed;
 }
@@ -5631,7 +5631,7 @@ function money(value, path, defaultValue = 0) {
     if (value === undefined || value === null)
         return defaultValue;
     if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
-        throw new RetirementParameterError("INVALID_MONEY", `${path} must be a finite, nonnegative number.`);
+        throw new ParameterError("INVALID_MONEY", `${path} must be a finite, nonnegative number.`);
     }
     return roundMoney(value);
 }
@@ -5639,7 +5639,7 @@ function rate(value, path, defaultValue = 0) {
     if (value === undefined || value === null)
         return defaultValue;
     if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
-        throw new RetirementParameterError("INVALID_RATE", `${path} must be a number from 0 through 1.`);
+        throw new ParameterError("INVALID_RATE", `${path} must be a number from 0 through 1.`);
     }
     return value;
 }
@@ -5781,7 +5781,7 @@ function mergeTaxEffects(target, source) {
 }
 function getParametersForYear(year) {
     if (!Number.isInteger(year)) {
-        throw new RetirementParameterError("INVALID_TAX_YEAR", "taxYear must be an integer.");
+        throw new ParameterError("INVALID_TAX_YEAR", "taxYear must be an integer.");
     }
     const { minimum, maximum } = RAW_PARAMETERS.supportedTaxYears;
     if (year < minimum || year > maximum || !RAW_PARAMETERS.years[String(year)]) {
@@ -5794,18 +5794,18 @@ function deepClone(value) {
 }
 function normalizePersons(persons) {
     if (!Array.isArray(persons) || persons.length === 0) {
-        throw new RetirementParameterError("PERSON_REQUIRED", "At least one person is required.");
+        throw new ParameterError("PERSON_REQUIRED", "At least one person is required.");
     }
     const result = new Map();
     for (const [index, input] of persons.entries()) {
         if (!input.id?.trim()) {
-            throw new RetirementParameterError("PERSON_ID_REQUIRED", `persons[${index}].id is required.`);
+            throw new ParameterError("PERSON_ID_REQUIRED", `persons[${index}].id is required.`);
         }
         if (result.has(input.id)) {
-            throw new RetirementParameterError("DUPLICATE_PERSON_ID", `Duplicate person ID: ${input.id}`);
+            throw new ParameterError("DUPLICATE_PERSON_ID", `Duplicate person ID: ${input.id}`);
         }
         if (input.birthYear !== undefined && (!Number.isInteger(input.birthYear) || input.birthYear < 1800 || input.birthYear > 3000)) {
-            throw new RetirementParameterError("INVALID_BIRTH_YEAR", `persons[${index}].birthYear is invalid.`);
+            throw new ParameterError("INVALID_BIRTH_YEAR", `persons[${index}].birthYear is invalid.`);
         }
         if (input.birthDate !== undefined)
             validateIsoDate(input.birthDate, `persons[${index}].birthDate`);
@@ -5823,7 +5823,7 @@ function normalizePersons(persons) {
         }
         const role = input.role ?? (index === 0 ? "taxpayer" : index === 1 ? "spouse" : "other");
         if (role !== "taxpayer" && role !== "spouse" && role !== "other") {
-            throw new RetirementParameterError("INVALID_PERSON_ROLE", `persons[${index}].role must be taxpayer, spouse, or other.`);
+            throw new ParameterError("INVALID_PERSON_ROLE", `persons[${index}].role must be taxpayer, spouse, or other.`);
         }
         result.set(input.id, {
             ...input,
@@ -5845,7 +5845,7 @@ function normalizePersons(persons) {
     for (const role of ["taxpayer", "spouse"]) {
         const matching = [...result.values()].filter((person) => person.role === role);
         if (matching.length > 1) {
-            throw new RetirementParameterError("DUPLICATE_PERSON_ROLE", `Only one person may have the ${role} role; found ${matching.map((person) => person.id).join(", ")}.`);
+            throw new ParameterError("DUPLICATE_PERSON_ROLE", `Only one person may have the ${role} role; found ${matching.map((person) => person.id).join(", ")}.`);
         }
     }
     return result;
@@ -5854,14 +5854,14 @@ function normalizeAccounts(accounts, persons) {
     const ids = new Set();
     return accounts.map((input, index) => {
         if (!input.id?.trim()) {
-            throw new RetirementParameterError("ACCOUNT_ID_REQUIRED", `accounts[${index}].id is required.`);
+            throw new ParameterError("ACCOUNT_ID_REQUIRED", `accounts[${index}].id is required.`);
         }
         if (ids.has(input.id)) {
-            throw new RetirementParameterError("DUPLICATE_ACCOUNT_ID", `Duplicate account ID: ${input.id}`);
+            throw new ParameterError("DUPLICATE_ACCOUNT_ID", `Duplicate account ID: ${input.id}`);
         }
         ids.add(input.id);
         if (!persons.has(input.ownerId)) {
-            throw new RetirementParameterError("UNKNOWN_ACCOUNT_OWNER", `Account ${input.id} references unknown owner ${input.ownerId}.`);
+            throw new ParameterError("UNKNOWN_ACCOUNT_OWNER", `Account ${input.id} references unknown owner ${input.ownerId}.`);
         }
         const planRules = input.planRules ?? {};
         validatePlanRules(planRules, `accounts[${index}].planRules`);
@@ -5890,7 +5890,7 @@ function validatePlanRules(rules, path) {
     if (rules.special403bCatchUp) {
         const special = rules.special403bCatchUp;
         if (!Number.isFinite(special.yearsOfService) || special.yearsOfService < 0) {
-            throw new RetirementParameterError("INVALID_YEARS_OF_SERVICE", `${path}.special403bCatchUp.yearsOfService is invalid.`);
+            throw new ParameterError("INVALID_YEARS_OF_SERVICE", `${path}.special403bCatchUp.yearsOfService is invalid.`);
         }
         money(special.priorElectiveDeferrals, `${path}.special403bCatchUp.priorElectiveDeferrals`);
         money(special.priorSpecialCatchUpUsed, `${path}.special403bCatchUp.priorSpecialCatchUpUsed`);
@@ -5901,12 +5901,12 @@ function validatePlanRules(rules, path) {
 }
 function validateIsoDate(value, path) {
     if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
-        throw new RetirementParameterError("INVALID_DATE", `${path} must use YYYY-MM-DD.`);
+        throw new ParameterError("INVALID_DATE", `${path} must use YYYY-MM-DD.`);
     }
     const [year, month, day] = value.split("-").map(Number);
     const date = new Date(Date.UTC(year, month - 1, day));
     if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
-        throw new RetirementParameterError("INVALID_DATE", `${path} is not a valid calendar date.`);
+        throw new ParameterError("INVALID_DATE", `${path} is not a valid calendar date.`);
     }
 }
 function ageAtEndOfTaxYear(person, taxYear) {
@@ -7244,17 +7244,17 @@ function normalizeConversions(conversions, persons, accountsById) {
     const ids = new Set();
     return conversions.map((input, index) => {
         if (!input.id?.trim()) {
-            throw new RetirementParameterError("CONVERSION_ID_REQUIRED", `conversions[${index}].id is required.`);
+            throw new ParameterError("CONVERSION_ID_REQUIRED", `conversions[${index}].id is required.`);
         }
         if (ids.has(input.id)) {
-            throw new RetirementParameterError("DUPLICATE_CONVERSION_ID", `Duplicate conversion ID: ${input.id}`);
+            throw new ParameterError("DUPLICATE_CONVERSION_ID", `Duplicate conversion ID: ${input.id}`);
         }
         ids.add(input.id);
         if (!persons.has(input.ownerId)) {
-            throw new RetirementParameterError("UNKNOWN_CONVERSION_OWNER", `Conversion ${input.id} references unknown owner ${input.ownerId}.`);
+            throw new ParameterError("UNKNOWN_CONVERSION_OWNER", `Conversion ${input.id} references unknown owner ${input.ownerId}.`);
         }
         if (input.sourceAccountId && !accountsById.has(input.sourceAccountId)) {
-            throw new RetirementParameterError("UNKNOWN_CONVERSION_SOURCE_ACCOUNT", `Conversion ${input.id} references unknown source account ${input.sourceAccountId}.`);
+            throw new ParameterError("UNKNOWN_CONVERSION_SOURCE_ACCOUNT", `Conversion ${input.id} references unknown source account ${input.sourceAccountId}.`);
         }
         return {
             ...input,
@@ -7471,7 +7471,7 @@ function calculateIraConversionGroup(context, ownerId, conversions, accountResul
         };
     });
 }
-function calculateRetirementScenario(input) {
+function calculateScenario(input) {
     const scenarioDiagnostics = [];
     const taxYear = input.taxYear;
     const parameters = getParametersForYear(taxYear);
@@ -7669,7 +7669,7 @@ class PersonBuilder {
     }
 }
 exports.PersonBuilder = PersonBuilder;
-class RetirementAccountBuilder {
+class AccountBuilder {
     value;
     constructor(id, ownerId, type) {
         this.value = {
@@ -7794,7 +7794,7 @@ class RetirementAccountBuilder {
         return deepClone(this.value);
     }
 }
-exports.RetirementAccountBuilder = RetirementAccountBuilder;
+exports.AccountBuilder = AccountBuilder;
 class RothConversionBuilder {
     value;
     constructor(id, ownerId, type, amount) {
@@ -7825,23 +7825,23 @@ class RothConversionBuilder {
     }
 }
 exports.RothConversionBuilder = RothConversionBuilder;
-class RetirementScenario {
+class Scenario {
     input;
     constructor(input) {
         this.input = input;
     }
     calculate() {
-        return calculateRetirementScenario(deepClone(this.input));
+        return calculateScenario(deepClone(this.input));
     }
     toInput() {
         return deepClone(this.input);
     }
 }
-exports.RetirementScenario = RetirementScenario;
-class RetirementScenarioBuilder {
+exports.Scenario = Scenario;
+class ScenarioBuilder {
     value;
     static forTaxYear(taxYear) {
-        return new RetirementScenarioBuilder(taxYear);
+        return new ScenarioBuilder(taxYear);
     }
     constructor(taxYear) {
         this.value = {
@@ -7871,11 +7871,11 @@ class RetirementScenarioBuilder {
         return this.addPerson(builder);
     }
     addAccount(account) {
-        this.value.accounts.push(account instanceof RetirementAccountBuilder ? account.build() : deepClone(account));
+        this.value.accounts.push(account instanceof AccountBuilder ? account.build() : deepClone(account));
         return this;
     }
     account(id, ownerId, type, configure) {
-        const builder = new RetirementAccountBuilder(id, ownerId, type);
+        const builder = new AccountBuilder(id, ownerId, type);
         configure?.(builder);
         return this.addAccount(builder);
     }
@@ -7889,7 +7889,7 @@ class RetirementScenarioBuilder {
         return this.addConversion(builder);
     }
     build() {
-        return new RetirementScenario(deepClone(this.value));
+        return new Scenario(deepClone(this.value));
     }
     calculate() {
         return this.build().calculate();
@@ -7898,13 +7898,13 @@ class RetirementScenarioBuilder {
         return deepClone(this.value);
     }
 }
-exports.RetirementScenarioBuilder = RetirementScenarioBuilder;
+exports.ScenarioBuilder = ScenarioBuilder;
 class USTaxAdvantagedParams {
     static forTaxYear(taxYear) {
-        return RetirementScenarioBuilder.forTaxYear(taxYear);
+        return ScenarioBuilder.forTaxYear(taxYear);
     }
     static calculate(input) {
-        return calculateRetirementScenario(input);
+        return calculateScenario(input);
     }
     static parametersForYear(taxYear) {
         return getParametersForYear(taxYear);