@trajectonomics/tax 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 excited.live
+
+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

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# @trajectonomics/tax
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pure, deterministic statutory tax calculation engine with subpaths for Thailand (`@trajectonomics/tax/th`) and the United States (`@trajectonomics/tax/us`), covering 2026 federal tax plus all 50 state income tax systems and the District of Columbia.
+
+## United States State Tax
+
+`calculateUsTax` accepts an optional `state` code (`AL` through `WY` plus `DC`). When present, the result includes `breakdown.state` with state taxable income, bracket slices, personal/dependent credits, state withholding, and net state tax, and the state liability is folded into the top-level `totalTax` and `netTaxPayable`.
+
+- Nine no-income-tax states (`AK`, `FL`, `NV`, `NH`, `SD`, `TN`, `TX`, `WA`, `WY`) return zero state tax and zero state rates.
+- Sixteen flat-rate states (including `LA` and `OH`, which are single-rate in 2026) and twenty-five graduated-rate states plus `DC` use their 2026 standard deductions, personal/dependent exemptions, and statutory bracket tables.
+- `MA` includes the 4% millionaire surtax and `CA` includes the 1% mental health services surtax.
+- State inputs also include `stateDependents`, `stateWithholding`, and `stateCredits` (`nonRefundable` / `refundable`).
+- State calculations start from federal AGI and apply the state standard deduction, personal/dependent exemptions or credits, and the state bracket table. Top-level `marginalRate` is the federal ordinary rate plus the state marginal rate. Head-of-household uses the state's joint schedule in `NJ`, `OR`, and `OK` and the single schedule elsewhere unless a dedicated table is encoded (`CA`, `MN`, `NY`, `ME`); head-of-household and separate-filer standard deductions outside the federal-conforming states are derived (1.5x single, joint/2). Top-level `withholding` is federal-only: `breakdown.state.withholding` carries state withholding, and `netTaxPayable` subtracts both. `stateDependents`, `stateWithholding`, and `stateCredits` require a `state` code and throw otherwise. Separate filers use half the joint thresholds in `MN` and `WI`; `MO` joint returns use doubled single thresholds (each spouse taxed on half). Known gaps: Utah's credit phase-out, Connecticut/Illinois/Maryland/Oregon/Rhode Island/Wisconsin income-tested phase-outs, the Maryland capital-gains and Minnesota net-investment-income surtaxes, and Maine's 2026 high-income surcharge are not modeled; New York uses the 2025 return rate schedule; Nebraska head-of-household uses the single schedule; head-of-household brackets outside the states listed in the parameter tables fall back to the single schedule. Local/city income taxes, state itemized deductions, and income-tested phase-outs not encoded in the parameter tables are out of scope.
+
+## Commands
+
+- `bun run check`: Complete verification suite (`lint`, `typecheck`, `test` with 100% coverage, `build`, `lint:package`).
+- `bun run build`: Build ESM and CJS bundles via `tsdown`.
+- `bun test`: Run test suite with 100% coverage enforcement.
+- `bun run typecheck`: Run strict TypeScript compiler checks.
+- `bun run lint`: Lint with Biome (zero warnings allowed).
+- `bun run format`: Auto-format and organize imports with Biome.
+- `bun run lint:package`: Validate package manifests and type exports with `publint` and `@arethetypeswrong/cli`.
+
+## Releasing
+
+Versions are computed, never edited by hand (`package.json` says `0.0.0-development` on purpose). `scripts/version.ts` reads the last `vX.Y.Z` git tag and the conventional commit messages since then:
+
+| Commits since last release | Bump |
+| --- | --- |
+| any `feat!:` / `fix!:` / `BREAKING CHANGE:` | major (minor while on 0.x) |
+| any `feat:` | minor |
+| anything else | patch |
+
+- **Alpha, automatic:** Every merge to `main` that touches code publishes `<next>-alpha.<n>` under the npm dist-tag `alpha` (`bun add @trajectonomics/tax@alpha`). `n` counts up per upcoming version.
+- **Stable, on demand:** Actions → Release → Run workflow (on `main`). It publishes `<next>` under `latest`, tags `vX.Y.Z`, and creates a GitHub release with generated notes. The bump input overrides the computed one; pick `major` to cut 1.0.0.
+
+PR titles must be conventional commits (enforced by the `PR title` check) because squash-merge commit subjects become the basis for version calculation.
+
+Preview the next version locally:
+
+```bash
+bun scripts/version.ts --channel alpha
+bun scripts/version.ts --channel stable
+```
+
+## License
+
+MIT

package/dist/clamp-BKG7kjVf.cjs

@@ -0,0 +1,509 @@
+// src/core/money/errors.ts
+/**
+* Error thrown when input values violate mathematical boundaries or statutory constraints.
+* Exposes field, raw value, and validation reason for transparency and structured error reporting.
+*/
+var TaxValidationError = class TaxValidationError extends Error {
+	field;
+	value;
+	reason;
+	constructor(field, value, reason) {
+		super(`Tax validation error on field '${field}': ${reason} (received: ${String(value)})`);
+		this.name = "TaxValidationError";
+		this.field = field;
+		this.value = value;
+		this.reason = reason;
+		Object.setPrototypeOf(this, TaxValidationError.prototype);
+	}
+};
+// src/core/money/currency.ts
+/**
+* Minor-unit precision (fractional decimal digits) per supported currency.
+*
+* Units: THB 2 (1 baht = 100 satang), USD 2 (1 dollar = 100 cents).
+* Internal to the money module; not part of the public package API.
+*/
+const CURRENCY_PRECISION = {
+	THB: 2,
+	USD: 2
+};
+// src/core/money/validate.ts
+/**
+* Validates a monetary input against numerical boundaries (NaN, Infinity, negative).
+*
+* @param value Number to validate.
+* @param field Diagnostic field name for error reporting.
+* @param options Validation options.
+* @throws {TaxValidationError} if value is NaN, non-finite, or negative without allowNegative.
+*/
+function validateMonetaryAmount(value, field, options) {
+	if (Number.isNaN(value)) throw new TaxValidationError(field, value, "Value cannot be NaN");
+	if (!Number.isFinite(value)) throw new TaxValidationError(field, value, "Value must be a finite number");
+	if (!options?.allowNegative && value < 0) throw new TaxValidationError(field, value, "Value cannot be negative");
+}
+/**
+* Validates a statutory percentage rate (e.g. 0.05 for 5%).
+*
+* @param rate Rate ratio between 0 and 1.
+* @param field Diagnostic field name.
+* @throws {TaxValidationError} if rate is NaN, non-finite, or outside [0, 1].
+*/
+function validateRate(rate, field) {
+	if (Number.isNaN(rate) || !Number.isFinite(rate)) throw new TaxValidationError(field, rate, "Rate must be a finite number");
+	if (rate < 0 || rate > 1) throw new TaxValidationError(field, rate, "Statutory rate ratio must be between 0 and 1 (inclusive)");
+}
+/**
+* Validates that an amount is an exact integer minor unit.
+*
+* @param minorUnits Integer minor units.
+* @param field Diagnostic field name.
+* @param options Validation options.
+* @throws {TaxValidationError} if not a safe integer.
+*/
+function validateIntegerMinorUnits(minorUnits, field, options) {
+	validateMonetaryAmount(minorUnits, field, options);
+	if (!Number.isSafeInteger(minorUnits)) throw new TaxValidationError(field, minorUnits, "Minor units amount must be a safe integer");
+}
+/**
+* Validates a statutory count (children, years of service, holding years).
+*
+* Purpose: Guards integer counts that later multiply money, rejecting fractions and unsafe values.
+* Math: Requires `Number.isSafeInteger(value)` and `value >= min`.
+* Units: Dimensionless count (not currency).
+* Throws: TaxValidationError if value is not a safe integer or is below `min`.
+*
+* @param value Count to validate.
+* @param field Diagnostic field name.
+* @param min Inclusive lower bound (defaults to 0).
+* @statute Jurisdiction-neutral input bound (AGENTS rule 8); no statutory citation.
+*/
+function validateSafeIntegerCount(value, field, min = 0) {
+	if (!Number.isSafeInteger(value)) throw new TaxValidationError(field, value, "Count must be a safe integer");
+	if (value < min) throw new TaxValidationError(field, value, `Count must be at least ${min}`);
+}
+/**
+* Multiplies two integers and fails loudly if the product leaves the safe integer range.
+*
+* Purpose: Prevents silent precision loss when scaling minor units by a count (years, days).
+* Math: `a * b`, requiring `Number.isSafeInteger(a * b)`.
+* Units: Typically integer minor units times a dimensionless count; result in minor units.
+* Throws: TaxValidationError (reported against `field`) if the product is not a safe integer.
+*
+* @param a Integer factor (e.g. minor units).
+* @param b Integer factor (e.g. a validated count).
+* @param field Diagnostic field name of the count or amount being scaled.
+* @statute Jurisdiction-neutral input bound (AGENTS rule 8); no statutory citation.
+*/
+function multiplySafeInteger(a, b, field) {
+	const product = a * b;
+	if (!Number.isSafeInteger(product)) throw new TaxValidationError(field, b, "Scaled amount exceeds the safe integer range");
+	return product + 0;
+}
+// src/core/money/minor-units.ts
+function scaleDecimalString(abs, precision) {
+	const factor = 10 ** precision;
+	if (String(abs).includes("e")) return abs * factor;
+	const parts = String(abs).split(".");
+	const intPart = parts[0] ?? "0";
+	const decPart = (parts[1] ?? "").padEnd(precision, "0");
+	const whole = intPart + decPart.slice(0, precision);
+	const fraction = decPart.slice(precision);
+	return Number(whole + (fraction.length > 0 ? `.${fraction}` : ""));
+}
+/**
+* Converts a major-unit monetary amount to integer minor units (satang/cent).
+*
+* Math: Decimal string expansion and half-away-from-zero rounding to eliminate IEEE 754 float drift.
+* Units: Input is major currency unit (e.g. THB, USD); output is integer minor units (e.g. Satang, Cents).
+*
+* @param amount Amount in major units.
+* @param currency Supported statutory currency (THB or USD).
+* @param field Diagnostic field name.
+* @param options Validation options (e.g. allowNegative for refund balances).
+* @returns Integer minor units.
+* @throws {TaxValidationError} if amount is NaN, infinite, or results in a non-safe integer.
+* @example toMinorUnits(1.14, "USD") // 114 (114 cents)
+*/
+function toMinorUnits(amount, currency, field = "amount", options) {
+	validateMonetaryAmount(amount, field, options);
+	const precision = CURRENCY_PRECISION[currency];
+	const sign = amount < 0 ? -1 : 1;
+	const scaled = scaleDecimalString(Math.abs(amount), precision);
+	const result = sign * Math.round(scaled) + 0;
+	if (!Number.isSafeInteger(result)) throw new TaxValidationError(field, amount, "Conversion to minor units failed or exceeded safe integer bounds");
+	return result;
+}
+/**
+* Converts an integer minor unit amount back to major currency units.
+*
+* @param minorUnits Integer minor units.
+* @param currency Supported statutory currency (THB or USD).
+* @param field Diagnostic field name.
+* @param options Validation options (e.g. allowNegative for refund balances).
+* @returns Amount in major units.
+* @throws {TaxValidationError} if minorUnits is not a safe integer.
+* @example fromMinorUnits(1055, "THB") // 10.55
+*/
+function fromMinorUnits(minorUnits, currency, field = "minorUnits", options) {
+	validateIntegerMinorUnits(minorUnits, field, options);
+	const precision = CURRENCY_PRECISION[currency];
+	const factor = 10 ** precision;
+	return (minorUnits < 0 ? -1 : 1) * Number((Math.abs(minorUnits) / factor).toFixed(precision)) + 0;
+}
+// src/core/money/rounding.ts
+/**
+* Rounds a number to the nearest integer, breaking ties away from zero (standard half-up).
+*
+* Math: Rounds fractional halves away from zero (e.g. 1.5 -> 2, -1.5 -> -2).
+*
+* @param value Floating-point value.
+* @returns Rounded integer.
+*/
+function roundHalfUp(value) {
+	if (value < 0) return -Math.round(Math.abs(value)) + 0;
+	return Math.round(value) + 0;
+}
+function parseRateRational(rate) {
+	const parts = (rate.toString().includes("e") ? rate.toFixed(10).replace(/\.?0+$/, "") : rate.toString()).split(".");
+	const decimals = parts[1] ? parts[1].length : 0;
+	return {
+		num: BigInt(parts.join("")),
+		den: 10n ** BigInt(decimals)
+	};
+}
+/**
+* Applies a statutory percentage rate to an integer minor unit amount using exact rational arithmetic.
+*
+* Math: Exact rational scaling via BigInt `(minorUnits * num + modeAdjust) / den`
+* to eliminate IEEE 754 binary floating-point drift on exact statutory tax rates.
+* Units: Input and output are integer minor units (satang/cents).
+*
+* @param minorUnits Integer minor units amount.
+* @param rate Statutory rate ratio (e.g. 0.05 for 5%, 0.35 for 35%).
+* @param rounding Rounding mode (`half-up`, `floor`, or `ceil`).
+* @param options Validation options (e.g. allowNegative).
+* @returns Computed tax in integer minor units.
+* @throws {TaxValidationError} if minorUnits is not a safe integer or rate is outside [0, 1].
+* @example applyPercentage(90, 0.35) // 32 (exact statutory satang calculation)
+*/
+function applyPercentage(minorUnits, rate, rounding = "half-up", options) {
+	validateIntegerMinorUnits(minorUnits, "minorUnits", options);
+	validateRate(rate, "rate");
+	const { num, den } = parseRateRational(rate);
+	const prod = BigInt(minorUnits) * num;
+	let result;
+	if (rounding === "floor") result = prod >= 0n ? prod / den : (prod - (den - 1n)) / den;
+	else if (rounding === "ceil") result = prod >= 0n ? (prod + (den - 1n)) / den : prod / den;
+	else result = prod >= 0n ? (prod * 2n + den) / (den * 2n) : (prod * 2n - den) / (den * 2n);
+	return Number(result) + 0;
+}
+/**
+* Applies the statutory gross-up ratio `rate / (1 - rate)` to an integer minor unit amount.
+*
+* Purpose: Recovers the underlying tax from a net amount (e.g. a dividend tax credit).
+* Math: Exact BigInt rational `(minorUnits * num) / (den - num)` where `rate = num / den`,
+* rounded half-up (away from zero) so ties such as 0.5 satang never suffer binary float drift.
+* Units: Input and output are integer minor units (satang/cents).
+*
+* @param minorUnits Non-negative integer minor units amount (the net amount).
+* @param rate Underlying rate ratio in [0, 1) (e.g. 0.2 for a 20% corporate tax rate).
+* @param field Diagnostic field name reported on failure (defaults to `"minorUnits"`).
+* @returns Gross-up amount (`minorUnits * rate / (1 - rate)`) in integer minor units.
+* @throws {TaxValidationError} if minorUnits is not a non-negative safe integer, rate is outside
+* [0, 1), or the result is not a safe integer.
+* @statute Jurisdiction-neutral; Thailand Revenue Code Section 47 bis is the first consumer.
+* @example applyGrossUp(100_000, 0.2) // 25_000 (1,000.00 -> 250.00 credit at 20%)
+*/
+function applyGrossUp(minorUnits, rate, field = "minorUnits") {
+	validateIntegerMinorUnits(minorUnits, field);
+	validateRate(rate, "rate");
+	if (rate >= 1) throw new TaxValidationError("rate", rate, "Gross-up rate must be strictly less than 1");
+	const { num, den } = parseRateRational(rate);
+	const divisor = den - num;
+	const result = Number((BigInt(minorUnits) * num * 2n + divisor) / (divisor * 2n)) + 0;
+	if (!Number.isSafeInteger(result)) throw new TaxValidationError(field, minorUnits, "Gross-up result exceeds the safe integer range");
+	return result;
+}
+// src/core/money/types.ts
+/**
+* Constructs a branded Money value with immediate input boundary validation.
+*
+* @param amount Numerical amount in major units.
+* @param _currency Currency code tag.
+* @param field Diagnostic field name.
+* @param options Validation options (e.g. allowNegative for refund balances).
+* @returns Branded Money value.
+* @throws {TaxValidationError} if amount is NaN, infinite, or negative without allowNegative.
+*/
+function money(amount, _currency, field = "amount", options) {
+	validateMonetaryAmount(amount, field, options);
+	return amount;
+}
+/**
+* Constructs a branded Thai Baht (THB) money value with input boundary validation.
+*
+* @param amount Amount in Baht.
+* @param field Diagnostic field name.
+* @param options Validation options (e.g. allowNegative for refund balances).
+* @returns Branded Money<"THB"> value.
+* @throws {TaxValidationError} if amount is NaN, infinite, or negative without allowNegative.
+*/
+function thb(amount, field = "amount", options) {
+	validateMonetaryAmount(amount, field, options);
+	return amount;
+}
+/**
+* Constructs a branded US Dollar (USD) money value with input boundary validation.
+*
+* @param amount Amount in Dollars.
+* @param field Diagnostic field name.
+* @param options Validation options (e.g. allowNegative for refund balances).
+* @returns Branded Money<"USD"> value.
+* @throws {TaxValidationError} if amount is NaN, infinite, or negative without allowNegative.
+*/
+function usd(amount, field = "amount", options) {
+	validateMonetaryAmount(amount, field, options);
+	return amount;
+}
+// src/core/brackets/marginal.ts
+/**
+* Determines the marginal tax rate that applies to the next unit of ordinary income.
+*
+* @param brackets Ordered progressive tax brackets.
+* @param nextUnit Amount of income on the boundary transition (taxableAmount + 1).
+* @returns Marginal statutory rate ratio.
+*/
+function marginalRateAt(brackets, nextUnit) {
+	let lower = 0;
+	for (const bracket of brackets) {
+		const upper = bracket.upTo;
+		if (nextUnit > lower && (upper === null || !Number.isFinite(upper) || nextUnit <= upper)) return bracket.rate;
+		if (upper === null || !Number.isFinite(upper)) break;
+		lower = upper;
+	}
+	return brackets[0]?.rate ?? 0;
+}
+// src/core/brackets/slice.ts
+/**
+* Computes progressive tax and slice boundaries for a single bracket tier.
+*
+* @param lowerBound Lower threshold in minor units.
+* @param bracket Current bracket specification.
+* @param taxableAmount Total taxable income in minor units.
+* @param index Bracket index.
+* @returns Computed BracketSlice.
+*/
+function computeBracketSlice(lowerBound, bracket, taxableAmount, index) {
+	const upperBound = bracket.upTo;
+	let sliceTaxable = 0;
+	if (taxableAmount > lowerBound) {
+		if (upperBound === null || !Number.isFinite(upperBound)) sliceTaxable = taxableAmount - lowerBound;
+		else sliceTaxable = Math.min(taxableAmount, upperBound) - lowerBound;
+	}
+	const sliceTax = applyPercentage(sliceTaxable, bracket.rate);
+	return {
+		bracketIndex: index,
+		lowerBound,
+		upperBound,
+		rate: bracket.rate,
+		taxableAmount: sliceTaxable,
+		tax: sliceTax
+	};
+}
+// src/core/brackets/evaluate.ts
+function validateSingleBracket(bracket, index, isLast, prevBound) {
+	validateRate(bracket.rate, `bracket[${index}].rate`);
+	if (bracket.upTo === null) {
+		if (!isLast) throw new TaxValidationError(`bracket[${index}].upTo`, bracket.upTo, "Only the final bracket tier may have upTo: null (unbounded)");
+		return prevBound;
+	}
+	validateMonetaryAmount(bracket.upTo, `bracket[${index}].upTo`);
+	if (!Number.isSafeInteger(bracket.upTo) || bracket.upTo <= prevBound) throw new TaxValidationError(`bracket[${index}].upTo`, bracket.upTo, `Bracket bound must be a safe integer greater than ${prevBound}`);
+	return bracket.upTo;
+}
+function validateBrackets(brackets) {
+	if (brackets.length === 0) throw new TaxValidationError("brackets", brackets, "Bracket list cannot be empty");
+	let prevBound = 0;
+	for (let i = 0; i < brackets.length; i++) {
+		const bracket = brackets[i];
+		if (!bracket) continue;
+		prevBound = validateSingleBracket(bracket, i, i === brackets.length - 1, prevBound);
+	}
+	const last = brackets[brackets.length - 1];
+	if (last && last.upTo !== null) throw new TaxValidationError("brackets", brackets, "Final bracket tier must have upTo: null");
+}
+/**
+* Evaluates progressive tax brackets slice-by-slice across multiple tiers.
+*
+* Math: Slices taxable income across progressive tiers and sums integer tax per slice.
+* Units: All inputs and outputs must be integer minor units (satang/cents).
+*
+* @param taxableAmount Taxable income in integer minor units.
+* @param brackets Ordered progressive statutory tax brackets.
+* @param grossIncome Optional gross income in minor units for statutory effective rate calculation.
+* @param field Diagnostic field name.
+* @returns Evaluated bracket result including total tax, slices, effective rate, and marginal rate.
+* @throws {TaxValidationError} if inputs are invalid.
+*/
+function evaluateBrackets(taxableAmount, brackets, grossIncome, field = "taxableAmount") {
+	validateMonetaryAmount(taxableAmount, field);
+	if (grossIncome !== void 0) validateMonetaryAmount(grossIncome, "grossIncome");
+	validateBrackets(brackets);
+	let totalTax = 0;
+	let lowerBound = 0;
+	const slices = [];
+	for (let i = 0; i < brackets.length; i++) {
+		const bracket = brackets[i];
+		if (!bracket) continue;
+		const slice = computeBracketSlice(lowerBound, bracket, taxableAmount, i);
+		slices.push(slice);
+		totalTax += slice.tax;
+		if (bracket.upTo === null || !Number.isFinite(bracket.upTo)) break;
+		lowerBound = bracket.upTo;
+	}
+	const baseForEffective = grossIncome ?? taxableAmount;
+	const effectiveRate = baseForEffective > 0 ? totalTax / baseForEffective : 0;
+	const marginalRate = marginalRateAt(brackets, taxableAmount + 1);
+	return {
+		totalTax,
+		slices,
+		effectiveRate,
+		marginalRate
+	};
+}
+// src/core/caps/resolve.ts
+/**
+* Resolves a statutory cap limit from a formula configuration (percentage, ceiling, or min of both).
+*
+* @param options Statutory cap options specifying base, rate, and/or ceiling.
+* @param defaultField Default diagnostic field name.
+* @returns Resolved cap numerical ceiling.
+* @throws {TaxValidationError} if inputs are invalid.
+*/
+function resolveCap(options, defaultField = "cap") {
+	const fieldName = options.field ?? defaultField;
+	const { base, rate, ceiling, currency } = options;
+	let computedCap = Number.POSITIVE_INFINITY;
+	if (base !== void 0 && rate !== void 0) {
+		validateMonetaryAmount(base, `${fieldName}Base`);
+		validateRate(rate, `${fieldName}Rate`);
+		if (currency) computedCap = fromMinorUnits(applyPercentage(toMinorUnits(base, currency, `${fieldName}Base`), rate), currency);
+		else if (Number.isSafeInteger(base)) computedCap = applyPercentage(base, rate);
+		else computedCap = roundHalfUp(base * rate);
+	}
+	if (ceiling !== void 0) {
+		validateMonetaryAmount(ceiling, `${fieldName}Ceiling`);
+		computedCap = Math.min(computedCap, ceiling);
+	}
+	validateMonetaryAmount(computedCap, `${fieldName}Cap`);
+	return computedCap;
+}
+// src/core/caps/clamp.ts
+/**
+* Clamps a requested deduction, allowance, or expense against a statutory cap.
+*
+* @param requested Original requested amount.
+* @param capOrOptions Numeric cap or StatutoryCapOptions specification.
+* @param field Diagnostic field name.
+* @returns Breakdown-ready ClampedAmount structure.
+* @throws {TaxValidationError} if inputs are negative, NaN, or non-finite.
+* @example clampCap(150_000, 100_000, "allowance") // { requested: 150000, allowed: 100000, cap: 100000, wasClamped: true }
+*/
+function clampCap(requested, capOrOptions, field = "amount") {
+	validateMonetaryAmount(requested, field);
+	const cap = typeof capOrOptions === "number" ? capOrOptions : resolveCap(capOrOptions, field);
+	validateMonetaryAmount(cap, `${field}Cap`);
+	const wasClamped = requested > cap;
+	return {
+		requested,
+		allowed: wasClamped ? cap : requested,
+		cap,
+		wasClamped
+	};
+}
+Object.defineProperty(exports, "TaxValidationError", {
+	enumerable: true,
+	get: function() {
+		return TaxValidationError;
+	}
+});
+Object.defineProperty(exports, "applyGrossUp", {
+	enumerable: true,
+	get: function() {
+		return applyGrossUp;
+	}
+});
+Object.defineProperty(exports, "applyPercentage", {
+	enumerable: true,
+	get: function() {
+		return applyPercentage;
+	}
+});
+Object.defineProperty(exports, "clampCap", {
+	enumerable: true,
+	get: function() {
+		return clampCap;
+	}
+});
+Object.defineProperty(exports, "evaluateBrackets", {
+	enumerable: true,
+	get: function() {
+		return evaluateBrackets;
+	}
+});
+Object.defineProperty(exports, "fromMinorUnits", {
+	enumerable: true,
+	get: function() {
+		return fromMinorUnits;
+	}
+});
+Object.defineProperty(exports, "money", {
+	enumerable: true,
+	get: function() {
+		return money;
+	}
+});
+Object.defineProperty(exports, "multiplySafeInteger", {
+	enumerable: true,
+	get: function() {
+		return multiplySafeInteger;
+	}
+});
+Object.defineProperty(exports, "roundHalfUp", {
+	enumerable: true,
+	get: function() {
+		return roundHalfUp;
+	}
+});
+Object.defineProperty(exports, "thb", {
+	enumerable: true,
+	get: function() {
+		return thb;
+	}
+});
+Object.defineProperty(exports, "toMinorUnits", {
+	enumerable: true,
+	get: function() {
+		return toMinorUnits;
+	}
+});
+Object.defineProperty(exports, "usd", {
+	enumerable: true,
+	get: function() {
+		return usd;
+	}
+});
+Object.defineProperty(exports, "validateMonetaryAmount", {
+	enumerable: true,
+	get: function() {
+		return validateMonetaryAmount;
+	}
+});
+Object.defineProperty(exports, "validateSafeIntegerCount", {
+	enumerable: true,
+	get: function() {
+		return validateSafeIntegerCount;
+	}
+});
+
+//# sourceMappingURL=clamp-BKG7kjVf.cjs.map

package/dist/clamp-BKG7kjVf.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"clamp-BKG7kjVf.cjs","names":[],"sources":["../src/core/money/errors.ts","../src/core/money/currency.ts","../src/core/money/validate.ts","../src/core/money/minor-units.ts","../src/core/money/rounding.ts","../src/core/money/types.ts","../src/core/brackets/marginal.ts","../src/core/brackets/slice.ts","../src/core/brackets/evaluate.ts","../src/core/caps/resolve.ts","../src/core/caps/clamp.ts"],"sourcesContent":["/**\n * Error thrown when input values violate mathematical boundaries or statutory constraints.\n * Exposes field, raw value, and validation reason for transparency and structured error reporting.\n */\nexport class TaxValidationError extends Error {\n\treadonly field: string\n\treadonly value: unknown\n\treadonly reason: string\n\n\tconstructor(field: string, value: unknown, reason: string) {\n\t\tsuper(`Tax validation error on field '${field}': ${reason} (received: ${String(value)})`)\n\t\tthis.name = \"TaxValidationError\"\n\t\tthis.field = field\n\t\tthis.value = value\n\t\tthis.reason = reason\n\t\tObject.setPrototypeOf(this, TaxValidationError.prototype)\n\t}\n}\n","/**\n * Currencies the tax engine accounts in: one statutory currency per supported jurisdiction.\n *\n * Purpose: Compile-time gate for every monetary API. Callers map their own currency codes\n * onto this union; there is no runtime validation or fallback.\n * @statute Thai Revenue Code (THB) and US Internal Revenue Code (USD) both require\n * amounts to be stated in the domestic currency.\n */\nexport type TaxSupportedCurrency = \"THB\" | \"USD\"\n\n/**\n * Minor-unit precision (fractional decimal digits) per supported currency.\n *\n * Units: THB 2 (1 baht = 100 satang), USD 2 (1 dollar = 100 cents).\n * Internal to the money module; not part of the public package API.\n */\nexport const CURRENCY_PRECISION: Readonly<Record<TaxSupportedCurrency, number>> = {\n\tTHB: 2,\n\tUSD: 2,\n}\n","import { TaxValidationError } from \"./errors\"\n\n/**\n * Options controlling monetary validation.\n */\nexport interface ValidateAmountOptions {\n\t/** If true, negative values will not throw an error (e.g. net payable after refundable credits). */\n\treadonly allowNegative?: boolean\n}\n\n/**\n * Validates a monetary input against numerical boundaries (NaN, Infinity, negative).\n *\n * @param value Number to validate.\n * @param field Diagnostic field name for error reporting.\n * @param options Validation options.\n * @throws {TaxValidationError} if value is NaN, non-finite, or negative without allowNegative.\n */\nexport function validateMonetaryAmount(\n\tvalue: number,\n\tfield: string,\n\toptions?: ValidateAmountOptions,\n): void {\n\tif (Number.isNaN(value)) {\n\t\tthrow new TaxValidationError(field, value, \"Value cannot be NaN\")\n\t}\n\tif (!Number.isFinite(value)) {\n\t\tthrow new TaxValidationError(field, value, \"Value must be a finite number\")\n\t}\n\tif (!options?.allowNegative && value < 0) {\n\t\tthrow new TaxValidationError(field, value, \"Value cannot be negative\")\n\t}\n}\n\n/**\n * Validates a statutory percentage rate (e.g. 0.05 for 5%).\n *\n * @param rate Rate ratio between 0 and 1.\n * @param field Diagnostic field name.\n * @throws {TaxValidationError} if rate is NaN, non-finite, or outside [0, 1].\n */\nexport function validateRate(rate: number, field: string): void {\n\tif (Number.isNaN(rate) || !Number.isFinite(rate)) {\n\t\tthrow new TaxValidationError(field, rate, \"Rate must be a finite number\")\n\t}\n\tif (rate < 0 || rate > 1) {\n\t\tthrow new TaxValidationError(\n\t\t\tfield,\n\t\t\trate,\n\t\t\t\"Statutory rate ratio must be between 0 and 1 (inclusive)\",\n\t\t)\n\t}\n}\n\n/**\n * Validates that an amount is an exact integer minor unit.\n *\n * @param minorUnits Integer minor units.\n * @param field Diagnostic field name.\n * @param options Validation options.\n * @throws {TaxValidationError} if not a safe integer.\n */\nexport function validateIntegerMinorUnits(\n\tminorUnits: number,\n\tfield: string,\n\toptions?: ValidateAmountOptions,\n): void {\n\tvalidateMonetaryAmount(minorUnits, field, options)\n\tif (!Number.isSafeInteger(minorUnits)) {\n\t\tthrow new TaxValidationError(field, minorUnits, \"Minor units amount must be a safe integer\")\n\t}\n}\n\n/**\n * Validates a statutory count (children, years of service, holding years).\n *\n * Purpose: Guards integer counts that later multiply money, rejecting fractions and unsafe values.\n * Math: Requires `Number.isSafeInteger(value)` and `value >= min`.\n * Units: Dimensionless count (not currency).\n * Throws: TaxValidationError if value is not a safe integer or is below `min`.\n *\n * @param value Count to validate.\n * @param field Diagnostic field name.\n * @param min Inclusive lower bound (defaults to 0).\n * @statute Jurisdiction-neutral input bound (AGENTS rule 8); no statutory citation.\n */\nexport function validateSafeIntegerCount(value: number, field: string, min = 0): void {\n\tif (!Number.isSafeInteger(value)) {\n\t\tthrow new TaxValidationError(field, value, \"Count must be a safe integer\")\n\t}\n\tif (value < min) {\n\t\tthrow new TaxValidationError(field, value, `Count must be at least ${min}`)\n\t}\n}\n\n/**\n * Multiplies two integers and fails loudly if the product leaves the safe integer range.\n *\n * Purpose: Prevents silent precision loss when scaling minor units by a count (years, days).\n * Math: `a * b`, requiring `Number.isSafeInteger(a * b)`.\n * Units: Typically integer minor units times a dimensionless count; result in minor units.\n * Throws: TaxValidationError (reported against `field`) if the product is not a safe integer.\n *\n * @param a Integer factor (e.g. minor units).\n * @param b Integer factor (e.g. a validated count).\n * @param field Diagnostic field name of the count or amount being scaled.\n * @statute Jurisdiction-neutral input bound (AGENTS rule 8); no statutory citation.\n */\nexport function multiplySafeInteger(a: number, b: number, field: string): number {\n\tconst product = a * b\n\tif (!Number.isSafeInteger(product)) {\n\t\tthrow new TaxValidationError(field, b, \"Scaled amount exceeds the safe integer range\")\n\t}\n\treturn product + 0\n}\n","import { CURRENCY_PRECISION, type TaxSupportedCurrency } from \"./currency\"\nimport { TaxValidationError } from \"./errors\"\nimport {\n\ttype ValidateAmountOptions,\n\tvalidateIntegerMinorUnits,\n\tvalidateMonetaryAmount,\n} from \"./validate\"\n\nfunction scaleDecimalString(abs: number, precision: number): number {\n\tconst factor = 10 ** precision\n\tif (String(abs).includes(\"e\")) {\n\t\treturn abs * factor\n\t}\n\tconst parts = String(abs).split(\".\")\n\tconst intPart = parts[0] ?? \"0\"\n\tconst decPart = (parts[1] ?? \"\").padEnd(precision, \"0\")\n\tconst whole = intPart + decPart.slice(0, precision)\n\tconst fraction = decPart.slice(precision)\n\treturn Number(whole + (fraction.length > 0 ? `.${fraction}` : \"\"))\n}\n\n/**\n * Converts a major-unit monetary amount to integer minor units (satang/cent).\n *\n * Math: Decimal string expansion and half-away-from-zero rounding to eliminate IEEE 754 float drift.\n * Units: Input is major currency unit (e.g. THB, USD); output is integer minor units (e.g. Satang, Cents).\n *\n * @param amount Amount in major units.\n * @param currency Supported statutory currency (THB or USD).\n * @param field Diagnostic field name.\n * @param options Validation options (e.g. allowNegative for refund balances).\n * @returns Integer minor units.\n * @throws {TaxValidationError} if amount is NaN, infinite, or results in a non-safe integer.\n * @example toMinorUnits(1.14, \"USD\") // 114 (114 cents)\n */\nexport function toMinorUnits(\n\tamount: number,\n\tcurrency: TaxSupportedCurrency,\n\tfield = \"amount\",\n\toptions?: ValidateAmountOptions,\n): number {\n\tvalidateMonetaryAmount(amount, field, options)\n\tconst precision = CURRENCY_PRECISION[currency]\n\tconst sign = amount < 0 ? -1 : 1\n\tconst abs = Math.abs(amount)\n\tconst scaled = scaleDecimalString(abs, precision)\n\tconst result = sign * Math.round(scaled) + 0\n\tif (!Number.isSafeInteger(result)) {\n\t\tthrow new TaxValidationError(\n\t\t\tfield,\n\t\t\tamount,\n\t\t\t\"Conversion to minor units failed or exceeded safe integer bounds\",\n\t\t)\n\t}\n\treturn result\n}\n\n/**\n * Converts an integer minor unit amount back to major currency units.\n *\n * @param minorUnits Integer minor units.\n * @param currency Supported statutory currency (THB or USD).\n * @param field Diagnostic field name.\n * @param options Validation options (e.g. allowNegative for refund balances).\n * @returns Amount in major units.\n * @throws {TaxValidationError} if minorUnits is not a safe integer.\n * @example fromMinorUnits(1055, \"THB\") // 10.55\n */\nexport function fromMinorUnits(\n\tminorUnits: number,\n\tcurrency: TaxSupportedCurrency,\n\tfield = \"minorUnits\",\n\toptions?: ValidateAmountOptions,\n): number {\n\tvalidateIntegerMinorUnits(minorUnits, field, options)\n\tconst precision = CURRENCY_PRECISION[currency]\n\tconst factor = 10 ** precision\n\tconst sign = minorUnits < 0 ? -1 : 1\n\tconst absUnits = Math.abs(minorUnits)\n\treturn sign * Number((absUnits / factor).toFixed(precision)) + 0\n}\n","import { TaxValidationError } from \"./errors\"\nimport { type ValidateAmountOptions, validateIntegerMinorUnits, validateRate } from \"./validate\"\n\n/**\n * Supported rounding modes for statutory tax computations.\n */\nexport type RoundingMode = \"half-up\" | \"floor\" | \"ceil\"\n\n/**\n * Rounds a number to the nearest integer, breaking ties away from zero (standard half-up).\n *\n * Math: Rounds fractional halves away from zero (e.g. 1.5 -> 2, -1.5 -> -2).\n *\n * @param value Floating-point value.\n * @returns Rounded integer.\n */\nexport function roundHalfUp(value: number): number {\n\tif (value < 0) {\n\t\tconst res = -Math.round(Math.abs(value))\n\t\treturn res + 0\n\t}\n\treturn Math.round(value) + 0\n}\n\nfunction parseRateRational(rate: number): { num: bigint; den: bigint } {\n\tconst rateStr = rate.toString().includes(\"e\")\n\t\t? rate.toFixed(10).replace(/\\.?0+$/, \"\")\n\t\t: rate.toString()\n\tconst parts = rateStr.split(\".\")\n\tconst decimals = parts[1] ? parts[1].length : 0\n\treturn {\n\t\tnum: BigInt(parts.join(\"\")),\n\t\tden: 10n ** BigInt(decimals),\n\t}\n}\n\n/**\n * Applies a statutory percentage rate to an integer minor unit amount using exact rational arithmetic.\n *\n * Math: Exact rational scaling via BigInt `(minorUnits * num + modeAdjust) / den`\n * to eliminate IEEE 754 binary floating-point drift on exact statutory tax rates.\n * Units: Input and output are integer minor units (satang/cents).\n *\n * @param minorUnits Integer minor units amount.\n * @param rate Statutory rate ratio (e.g. 0.05 for 5%, 0.35 for 35%).\n * @param rounding Rounding mode (`half-up`, `floor`, or `ceil`).\n * @param options Validation options (e.g. allowNegative).\n * @returns Computed tax in integer minor units.\n * @throws {TaxValidationError} if minorUnits is not a safe integer or rate is outside [0, 1].\n * @example applyPercentage(90, 0.35) // 32 (exact statutory satang calculation)\n */\nexport function applyPercentage(\n\tminorUnits: number,\n\trate: number,\n\trounding: RoundingMode = \"half-up\",\n\toptions?: ValidateAmountOptions,\n): number {\n\tvalidateIntegerMinorUnits(minorUnits, \"minorUnits\", options)\n\tvalidateRate(rate, \"rate\")\n\n\tconst { num, den } = parseRateRational(rate)\n\tconst m = BigInt(minorUnits)\n\tconst prod = m * num\n\n\tlet result: bigint\n\tif (rounding === \"floor\") {\n\t\tresult = prod >= 0n ? prod / den : (prod - (den - 1n)) / den\n\t} else if (rounding === \"ceil\") {\n\t\tresult = prod >= 0n ? (prod + (den - 1n)) / den : prod / den\n\t} else {\n\t\t// half-up: away from zero\n\t\tresult = prod >= 0n ? (prod * 2n + den) / (den * 2n) : (prod * 2n - den) / (den * 2n)\n\t}\n\n\treturn Number(result) + 0\n}\n\n/**\n * Applies the statutory gross-up ratio `rate / (1 - rate)` to an integer minor unit amount.\n *\n * Purpose: Recovers the underlying tax from a net amount (e.g. a dividend tax credit).\n * Math: Exact BigInt rational `(minorUnits * num) / (den - num)` where `rate = num / den`,\n * rounded half-up (away from zero) so ties such as 0.5 satang never suffer binary float drift.\n * Units: Input and output are integer minor units (satang/cents).\n *\n * @param minorUnits Non-negative integer minor units amount (the net amount).\n * @param rate Underlying rate ratio in [0, 1) (e.g. 0.2 for a 20% corporate tax rate).\n * @param field Diagnostic field name reported on failure (defaults to `\"minorUnits\"`).\n * @returns Gross-up amount (`minorUnits * rate / (1 - rate)`) in integer minor units.\n * @throws {TaxValidationError} if minorUnits is not a non-negative safe integer, rate is outside\n * [0, 1), or the result is not a safe integer.\n * @statute Jurisdiction-neutral; Thailand Revenue Code Section 47 bis is the first consumer.\n * @example applyGrossUp(100_000, 0.2) // 25_000 (1,000.00 -> 250.00 credit at 20%)\n */\nexport function applyGrossUp(minorUnits: number, rate: number, field = \"minorUnits\"): number {\n\tvalidateIntegerMinorUnits(minorUnits, field)\n\tvalidateRate(rate, \"rate\")\n\tif (rate >= 1) {\n\t\tthrow new TaxValidationError(\"rate\", rate, \"Gross-up rate must be strictly less than 1\")\n\t}\n\tconst { num, den } = parseRateRational(rate)\n\tconst divisor = den - num\n\tconst result = Number((BigInt(minorUnits) * num * 2n + divisor) / (divisor * 2n)) + 0\n\tif (!Number.isSafeInteger(result)) {\n\t\tthrow new TaxValidationError(\n\t\t\tfield,\n\t\t\tminorUnits,\n\t\t\t\"Gross-up result exceeds the safe integer range\",\n\t\t)\n\t}\n\treturn result\n}\n","import type { TaxSupportedCurrency } from \"./currency\"\nimport { type ValidateAmountOptions, validateMonetaryAmount } from \"./validate\"\n\n/**\n * Branded nominal type representing a monetary value in a specific currency.\n * Enforces compile-time type safety preventing accidental cross-currency mixing.\n */\nexport type Money<C extends TaxSupportedCurrency = TaxSupportedCurrency> = number & {\n\treadonly __currencyBrand: C\n}\n\n/**\n * Constructs a branded Money value with immediate input boundary validation.\n *\n * @param amount Numerical amount in major units.\n * @param _currency Currency code tag.\n * @param field Diagnostic field name.\n * @param options Validation options (e.g. allowNegative for refund balances).\n * @returns Branded Money value.\n * @throws {TaxValidationError} if amount is NaN, infinite, or negative without allowNegative.\n */\nexport function money<C extends TaxSupportedCurrency>(\n\tamount: number,\n\t_currency?: C,\n\tfield = \"amount\",\n\toptions?: ValidateAmountOptions,\n): Money<C> {\n\tvalidateMonetaryAmount(amount, field, options)\n\treturn amount as Money<C>\n}\n\n/**\n * Constructs a branded Thai Baht (THB) money value with input boundary validation.\n *\n * @param amount Amount in Baht.\n * @param field Diagnostic field name.\n * @param options Validation options (e.g. allowNegative for refund balances).\n * @returns Branded Money<\"THB\"> value.\n * @throws {TaxValidationError} if amount is NaN, infinite, or negative without allowNegative.\n */\nexport function thb(\n\tamount: number,\n\tfield = \"amount\",\n\toptions?: ValidateAmountOptions,\n): Money<\"THB\"> {\n\tvalidateMonetaryAmount(amount, field, options)\n\treturn amount as Money<\"THB\">\n}\n\n/**\n * Constructs a branded US Dollar (USD) money value with input boundary validation.\n *\n * @param amount Amount in Dollars.\n * @param field Diagnostic field name.\n * @param options Validation options (e.g. allowNegative for refund balances).\n * @returns Branded Money<\"USD\"> value.\n * @throws {TaxValidationError} if amount is NaN, infinite, or negative without allowNegative.\n */\nexport function usd(\n\tamount: number,\n\tfield = \"amount\",\n\toptions?: ValidateAmountOptions,\n): Money<\"USD\"> {\n\tvalidateMonetaryAmount(amount, field, options)\n\treturn amount as Money<\"USD\">\n}\n","import type { TaxBracket } from \"./types\"\n\n/**\n * Determines the marginal tax rate that applies to the next unit of ordinary income.\n *\n * @param brackets Ordered progressive tax brackets.\n * @param nextUnit Amount of income on the boundary transition (taxableAmount + 1).\n * @returns Marginal statutory rate ratio.\n */\nexport function marginalRateAt(brackets: readonly TaxBracket[], nextUnit: number): number {\n\tlet lower = 0\n\tfor (const bracket of brackets) {\n\t\tconst upper = bracket.upTo\n\t\tif (nextUnit > lower && (upper === null || !Number.isFinite(upper) || nextUnit <= upper)) {\n\t\t\treturn bracket.rate\n\t\t}\n\t\tif (upper === null || !Number.isFinite(upper)) {\n\t\t\tbreak\n\t\t}\n\t\tlower = upper\n\t}\n\treturn brackets[0]?.rate ?? 0\n}\n","import { applyPercentage } from \"../money\"\nimport type { BracketSlice, TaxBracket } from \"./types\"\n\n/**\n * Computes progressive tax and slice boundaries for a single bracket tier.\n *\n * @param lowerBound Lower threshold in minor units.\n * @param bracket Current bracket specification.\n * @param taxableAmount Total taxable income in minor units.\n * @param index Bracket index.\n * @returns Computed BracketSlice.\n */\nexport function computeBracketSlice(\n\tlowerBound: number,\n\tbracket: TaxBracket,\n\ttaxableAmount: number,\n\tindex: number,\n): BracketSlice {\n\tconst upperBound = bracket.upTo\n\tlet sliceTaxable = 0\n\n\tif (taxableAmount > lowerBound) {\n\t\tif (upperBound === null || !Number.isFinite(upperBound)) {\n\t\t\tsliceTaxable = taxableAmount - lowerBound\n\t\t} else {\n\t\t\tsliceTaxable = Math.min(taxableAmount, upperBound) - lowerBound\n\t\t}\n\t}\n\n\tconst sliceTax = applyPercentage(sliceTaxable, bracket.rate)\n\n\treturn {\n\t\tbracketIndex: index,\n\t\tlowerBound,\n\t\tupperBound,\n\t\trate: bracket.rate,\n\t\ttaxableAmount: sliceTaxable,\n\t\ttax: sliceTax,\n\t}\n}\n","import { TaxValidationError, validateMonetaryAmount, validateRate } from \"../money\"\nimport { marginalRateAt } from \"./marginal\"\nimport { computeBracketSlice } from \"./slice\"\nimport type { BracketEvaluationResult, BracketSlice, TaxBracket } from \"./types\"\n\nfunction validateSingleBracket(\n\tbracket: TaxBracket,\n\tindex: number,\n\tisLast: boolean,\n\tprevBound: number,\n): number {\n\tvalidateRate(bracket.rate, `bracket[${index}].rate`)\n\tif (bracket.upTo === null) {\n\t\tif (!isLast) {\n\t\t\tthrow new TaxValidationError(\n\t\t\t\t`bracket[${index}].upTo`,\n\t\t\t\tbracket.upTo,\n\t\t\t\t\"Only the final bracket tier may have upTo: null (unbounded)\",\n\t\t\t)\n\t\t}\n\t\treturn prevBound\n\t}\n\tvalidateMonetaryAmount(bracket.upTo, `bracket[${index}].upTo`)\n\tif (!Number.isSafeInteger(bracket.upTo) || bracket.upTo <= prevBound) {\n\t\tthrow new TaxValidationError(\n\t\t\t`bracket[${index}].upTo`,\n\t\t\tbracket.upTo,\n\t\t\t`Bracket bound must be a safe integer greater than ${prevBound}`,\n\t\t)\n\t}\n\treturn bracket.upTo\n}\n\nfunction validateBrackets(brackets: readonly TaxBracket[]): void {\n\tif (brackets.length === 0) {\n\t\tthrow new TaxValidationError(\"brackets\", brackets, \"Bracket list cannot be empty\")\n\t}\n\tlet prevBound = 0\n\tfor (let i = 0; i < brackets.length; i++) {\n\t\tconst bracket = brackets[i]\n\t\tif (!bracket) continue\n\t\tprevBound = validateSingleBracket(bracket, i, i === brackets.length - 1, prevBound)\n\t}\n\tconst last = brackets[brackets.length - 1]\n\tif (last && last.upTo !== null) {\n\t\tthrow new TaxValidationError(\"brackets\", brackets, \"Final bracket tier must have upTo: null\")\n\t}\n}\n\n/**\n * Evaluates progressive tax brackets slice-by-slice across multiple tiers.\n *\n * Math: Slices taxable income across progressive tiers and sums integer tax per slice.\n * Units: All inputs and outputs must be integer minor units (satang/cents).\n *\n * @param taxableAmount Taxable income in integer minor units.\n * @param brackets Ordered progressive statutory tax brackets.\n * @param grossIncome Optional gross income in minor units for statutory effective rate calculation.\n * @param field Diagnostic field name.\n * @returns Evaluated bracket result including total tax, slices, effective rate, and marginal rate.\n * @throws {TaxValidationError} if inputs are invalid.\n */\nexport function evaluateBrackets(\n\ttaxableAmount: number,\n\tbrackets: readonly TaxBracket[],\n\tgrossIncome?: number,\n\tfield = \"taxableAmount\",\n): BracketEvaluationResult {\n\tvalidateMonetaryAmount(taxableAmount, field)\n\tif (grossIncome !== undefined) {\n\t\tvalidateMonetaryAmount(grossIncome, \"grossIncome\")\n\t}\n\tvalidateBrackets(brackets)\n\n\tlet totalTax = 0\n\tlet lowerBound = 0\n\tconst slices: BracketSlice[] = []\n\n\tfor (let i = 0; i < brackets.length; i++) {\n\t\tconst bracket = brackets[i]\n\t\tif (!bracket) continue\n\n\t\tconst slice = computeBracketSlice(lowerBound, bracket, taxableAmount, i)\n\t\tslices.push(slice)\n\t\ttotalTax += slice.tax\n\n\t\tif (bracket.upTo === null || !Number.isFinite(bracket.upTo)) {\n\t\t\tbreak\n\t\t}\n\t\tlowerBound = bracket.upTo\n\t}\n\n\tconst baseForEffective = grossIncome ?? taxableAmount\n\tconst effectiveRate = baseForEffective > 0 ? totalTax / baseForEffective : 0\n\tconst marginalRate = marginalRateAt(brackets, taxableAmount + 1)\n\n\treturn {\n\t\ttotalTax,\n\t\tslices,\n\t\teffectiveRate,\n\t\tmarginalRate,\n\t}\n}\n","import {\n\tapplyPercentage,\n\tfromMinorUnits,\n\troundHalfUp,\n\ttoMinorUnits,\n\tvalidateMonetaryAmount,\n\tvalidateRate,\n} from \"../money\"\nimport type { StatutoryCapOptions } from \"./types\"\n\n/**\n * Resolves a statutory cap limit from a formula configuration (percentage, ceiling, or min of both).\n *\n * @param options Statutory cap options specifying base, rate, and/or ceiling.\n * @param defaultField Default diagnostic field name.\n * @returns Resolved cap numerical ceiling.\n * @throws {TaxValidationError} if inputs are invalid.\n */\nexport function resolveCap(options: StatutoryCapOptions, defaultField = \"cap\"): number {\n\tconst fieldName = options.field ?? defaultField\n\tconst { base, rate, ceiling, currency } = options\n\n\tlet computedCap = Number.POSITIVE_INFINITY\n\n\tif (base !== undefined && rate !== undefined) {\n\t\tvalidateMonetaryAmount(base, `${fieldName}Base`)\n\t\tvalidateRate(rate, `${fieldName}Rate`)\n\t\tif (currency) {\n\t\t\tconst minorBase = toMinorUnits(base, currency, `${fieldName}Base`)\n\t\t\tconst minorCap = applyPercentage(minorBase, rate)\n\t\t\tcomputedCap = fromMinorUnits(minorCap, currency)\n\t\t} else if (Number.isSafeInteger(base)) {\n\t\t\tcomputedCap = applyPercentage(base, rate)\n\t\t} else {\n\t\t\tcomputedCap = roundHalfUp(base * rate)\n\t\t}\n\t}\n\n\tif (ceiling !== undefined) {\n\t\tvalidateMonetaryAmount(ceiling, `${fieldName}Ceiling`)\n\t\tcomputedCap = Math.min(computedCap, ceiling)\n\t}\n\n\tvalidateMonetaryAmount(computedCap, `${fieldName}Cap`)\n\treturn computedCap\n}\n","import { validateMonetaryAmount } from \"../money\"\nimport { resolveCap } from \"./resolve\"\nimport type { ClampedAmount, StatutoryCapOptions } from \"./types\"\n\n/**\n * Clamps a requested deduction, allowance, or expense against a statutory cap.\n *\n * @param requested Original requested amount.\n * @param capOrOptions Numeric cap or StatutoryCapOptions specification.\n * @param field Diagnostic field name.\n * @returns Breakdown-ready ClampedAmount structure.\n * @throws {TaxValidationError} if inputs are negative, NaN, or non-finite.\n * @example clampCap(150_000, 100_000, \"allowance\") // { requested: 150000, allowed: 100000, cap: 100000, wasClamped: true }\n */\nexport function clampCap(\n\trequested: number,\n\tcapOrOptions: number | StatutoryCapOptions,\n\tfield = \"amount\",\n): ClampedAmount {\n\tvalidateMonetaryAmount(requested, field)\n\n\tconst cap = typeof capOrOptions === \"number\" ? capOrOptions : resolveCap(capOrOptions, field)\n\n\tvalidateMonetaryAmount(cap, `${field}Cap`)\n\n\tconst wasClamped = requested > cap\n\tconst allowed = wasClamped ? cap : requested\n\n\treturn {\n\t\trequested,\n\t\tallowed,\n\t\tcap,\n\t\twasClamped,\n\t}\n}\n"],"mappings":";;;;;AAIA,IAAa,qBAAb,MAAa,2BAA2B,MAAM;CAC7C;CACA;CACA;CAEA,YAAY,OAAe,OAAgB,QAAgB;EAC1D,MAAM,kCAAkC,MAAM,KAAK,OAAO,cAAc,OAAO,KAAK,EAAE,EAAE;EACxF,KAAK,OAAO;EACZ,KAAK,QAAQ;EACb,KAAK,QAAQ;EACb,KAAK,SAAS;EACd,OAAO,eAAe,MAAM,mBAAmB,SAAS;CACzD;AACD;;;;;;;;ACDA,MAAa,qBAAqE;CACjF,KAAK;CACL,KAAK;AACN;;;;;;;;;;ACDA,SAAgB,uBACf,OACA,OACA,SACO;CACP,IAAI,OAAO,MAAM,KAAK,GACrB,MAAM,IAAI,mBAAmB,OAAO,OAAO,qBAAqB;CAEjE,IAAI,CAAC,OAAO,SAAS,KAAK,GACzB,MAAM,IAAI,mBAAmB,OAAO,OAAO,+BAA+B;CAE3E,IAAI,CAAC,SAAS,iBAAiB,QAAQ,GACtC,MAAM,IAAI,mBAAmB,OAAO,OAAO,0BAA0B;AAEvE;;;;;;;;AASA,SAAgB,aAAa,MAAc,OAAqB;CAC/D,IAAI,OAAO,MAAM,IAAI,KAAK,CAAC,OAAO,SAAS,IAAI,GAC9C,MAAM,IAAI,mBAAmB,OAAO,MAAM,8BAA8B;CAEzE,IAAI,OAAO,KAAK,OAAO,GACtB,MAAM,IAAI,mBACT,OACA,MACA,0DACD;AAEF;;;;;;;;;AAUA,SAAgB,0BACf,YACA,OACA,SACO;CACP,uBAAuB,YAAY,OAAO,OAAO;CACjD,IAAI,CAAC,OAAO,cAAc,UAAU,GACnC,MAAM,IAAI,mBAAmB,OAAO,YAAY,2CAA2C;AAE7F;;;;;;;;;;;;;;AAeA,SAAgB,yBAAyB,OAAe,OAAe,MAAM,GAAS;CACrF,IAAI,CAAC,OAAO,cAAc,KAAK,GAC9B,MAAM,IAAI,mBAAmB,OAAO,OAAO,8BAA8B;CAE1E,IAAI,QAAQ,KACX,MAAM,IAAI,mBAAmB,OAAO,OAAO,0BAA0B,KAAK;AAE5E;;;;;;;;;;;;;;AAeA,SAAgB,oBAAoB,GAAW,GAAW,OAAuB;CAChF,MAAM,UAAU,IAAI;CACpB,IAAI,CAAC,OAAO,cAAc,OAAO,GAChC,MAAM,IAAI,mBAAmB,OAAO,GAAG,8CAA8C;CAEtF,OAAO,UAAU;AAClB;;AC1GA,SAAS,mBAAmB,KAAa,WAA2B;CACnE,MAAM,SAAS,MAAM;CACrB,IAAI,OAAO,GAAG,CAAC,CAAC,SAAS,GAAG,GAC3B,OAAO,MAAM;CAEd,MAAM,QAAQ,OAAO,GAAG,CAAC,CAAC,MAAM,GAAG;CACnC,MAAM,UAAU,MAAM,MAAM;CAC5B,MAAM,WAAW,MAAM,MAAM,GAAA,CAAI,OAAO,WAAW,GAAG;CACtD,MAAM,QAAQ,UAAU,QAAQ,MAAM,GAAG,SAAS;CAClD,MAAM,WAAW,QAAQ,MAAM,SAAS;CACxC,OAAO,OAAO,SAAS,SAAS,SAAS,IAAI,IAAI,aAAa,GAAG;AAClE;;;;;;;;;;;;;;;AAgBA,SAAgB,aACf,QACA,UACA,QAAQ,UACR,SACS;CACT,uBAAuB,QAAQ,OAAO,OAAO;CAC7C,MAAM,YAAY,mBAAmB;CACrC,MAAM,OAAO,SAAS,IAAI,KAAK;CAE/B,MAAM,SAAS,mBADH,KAAK,IAAI,MACe,GAAG,SAAS;CAChD,MAAM,SAAS,OAAO,KAAK,MAAM,MAAM,IAAI;CAC3C,IAAI,CAAC,OAAO,cAAc,MAAM,GAC/B,MAAM,IAAI,mBACT,OACA,QACA,kEACD;CAED,OAAO;AACR;;;;;;;;;;;;AAaA,SAAgB,eACf,YACA,UACA,QAAQ,cACR,SACS;CACT,0BAA0B,YAAY,OAAO,OAAO;CACpD,MAAM,YAAY,mBAAmB;CACrC,MAAM,SAAS,MAAM;CAGrB,QAFa,aAAa,IAAI,KAAK,KAErB,QADG,KAAK,IAAI,UACG,IAAI,OAAA,CAAQ,QAAQ,SAAS,CAAC,IAAI;AAChE;;;;;;;;;;AChEA,SAAgB,YAAY,OAAuB;CAClD,IAAI,QAAQ,GAEX,OAAO,CADM,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,IAC1B;CAEd,OAAO,KAAK,MAAM,KAAK,IAAI;AAC5B;AAEA,SAAS,kBAAkB,MAA4C;CAItE,MAAM,SAHU,KAAK,SAAS,CAAC,CAAC,SAAS,GAAG,IACzC,KAAK,QAAQ,EAAE,CAAC,CAAC,QAAQ,UAAU,EAAE,IACrC,KAAK,SAAS,EAAA,CACK,MAAM,GAAG;CAC/B,MAAM,WAAW,MAAM,KAAK,MAAM,EAAE,CAAC,SAAS;CAC9C,OAAO;EACN,KAAK,OAAO,MAAM,KAAK,EAAE,CAAC;EAC1B,KAAK,OAAO,OAAO,QAAQ;CAC5B;AACD;;;;;;;;;;;;;;;;AAiBA,SAAgB,gBACf,YACA,MACA,WAAyB,WACzB,SACS;CACT,0BAA0B,YAAY,cAAc,OAAO;CAC3D,aAAa,MAAM,MAAM;CAEzB,MAAM,EAAE,KAAK,QAAQ,kBAAkB,IAAI;CAE3C,MAAM,OADI,OAAO,UACJ,IAAI;CAEjB,IAAI;CACJ,IAAI,aAAa,SAChB,SAAS,QAAQ,KAAK,OAAO,OAAO,QAAQ,MAAM,OAAO;MACnD,IAAI,aAAa,QACvB,SAAS,QAAQ,MAAM,QAAQ,MAAM,OAAO,MAAM,OAAO;MAGzD,SAAS,QAAQ,MAAM,OAAO,KAAK,QAAQ,MAAM,OAAO,OAAO,KAAK,QAAQ,MAAM;CAGnF,OAAO,OAAO,MAAM,IAAI;AACzB;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,aAAa,YAAoB,MAAc,QAAQ,cAAsB;CAC5F,0BAA0B,YAAY,KAAK;CAC3C,aAAa,MAAM,MAAM;CACzB,IAAI,QAAQ,GACX,MAAM,IAAI,mBAAmB,QAAQ,MAAM,4CAA4C;CAExF,MAAM,EAAE,KAAK,QAAQ,kBAAkB,IAAI;CAC3C,MAAM,UAAU,MAAM;CACtB,MAAM,SAAS,QAAQ,OAAO,UAAU,IAAI,MAAM,KAAK,YAAY,UAAU,GAAG,IAAI;CACpF,IAAI,CAAC,OAAO,cAAc,MAAM,GAC/B,MAAM,IAAI,mBACT,OACA,YACA,gDACD;CAED,OAAO;AACR;;;;;;;;;;;;AC1FA,SAAgB,MACf,QACA,WACA,QAAQ,UACR,SACW;CACX,uBAAuB,QAAQ,OAAO,OAAO;CAC7C,OAAO;AACR;;;;;;;;;;AAWA,SAAgB,IACf,QACA,QAAQ,UACR,SACe;CACf,uBAAuB,QAAQ,OAAO,OAAO;CAC7C,OAAO;AACR;;;;;;;;;;AAWA,SAAgB,IACf,QACA,QAAQ,UACR,SACe;CACf,uBAAuB,QAAQ,OAAO,OAAO;CAC7C,OAAO;AACR;;;;;;;;;ACxDA,SAAgB,eAAe,UAAiC,UAA0B;CACzF,IAAI,QAAQ;CACZ,KAAK,MAAM,WAAW,UAAU;EAC/B,MAAM,QAAQ,QAAQ;EACtB,IAAI,WAAW,UAAU,UAAU,QAAQ,CAAC,OAAO,SAAS,KAAK,KAAK,YAAY,QACjF,OAAO,QAAQ;EAEhB,IAAI,UAAU,QAAQ,CAAC,OAAO,SAAS,KAAK,GAC3C;EAED,QAAQ;CACT;CACA,OAAO,SAAS,EAAE,EAAE,QAAQ;AAC7B;;;;;;;;;;;ACVA,SAAgB,oBACf,YACA,SACA,eACA,OACe;CACf,MAAM,aAAa,QAAQ;CAC3B,IAAI,eAAe;CAEnB,IAAI,gBAAgB,YAAY;EAC/B,IAAI,eAAe,QAAQ,CAAC,OAAO,SAAS,UAAU,GACrD,eAAe,gBAAgB;OAE/B,eAAe,KAAK,IAAI,eAAe,UAAU,IAAI;CAEvD;CAEA,MAAM,WAAW,gBAAgB,cAAc,QAAQ,IAAI;CAE3D,OAAO;EACN,cAAc;EACd;EACA;EACA,MAAM,QAAQ;EACd,eAAe;EACf,KAAK;CACN;AACD;;AClCA,SAAS,sBACR,SACA,OACA,QACA,WACS;CACT,aAAa,QAAQ,MAAM,WAAW,MAAM,OAAO;CACnD,IAAI,QAAQ,SAAS,MAAM;EAC1B,IAAI,CAAC,QACJ,MAAM,IAAI,mBACT,WAAW,MAAM,SACjB,QAAQ,MACR,6DACD;EAED,OAAO;CACR;CACA,uBAAuB,QAAQ,MAAM,WAAW,MAAM,OAAO;CAC7D,IAAI,CAAC,OAAO,cAAc,QAAQ,IAAI,KAAK,QAAQ,QAAQ,WAC1D,MAAM,IAAI,mBACT,WAAW,MAAM,SACjB,QAAQ,MACR,qDAAqD,WACtD;CAED,OAAO,QAAQ;AAChB;AAEA,SAAS,iBAAiB,UAAuC;CAChE,IAAI,SAAS,WAAW,GACvB,MAAM,IAAI,mBAAmB,YAAY,UAAU,8BAA8B;CAElF,IAAI,YAAY;CAChB,KAAK,IAAI,IAAI,GAAG,IAAI,SAAS,QAAQ,KAAK;EACzC,MAAM,UAAU,SAAS;EACzB,IAAI,CAAC,SAAS;EACd,YAAY,sBAAsB,SAAS,GAAG,MAAM,SAAS,SAAS,GAAG,SAAS;CACnF;CACA,MAAM,OAAO,SAAS,SAAS,SAAS;CACxC,IAAI,QAAQ,KAAK,SAAS,MACzB,MAAM,IAAI,mBAAmB,YAAY,UAAU,yCAAyC;AAE9F;;;;;;;;;;;;;;AAeA,SAAgB,iBACf,eACA,UACA,aACA,QAAQ,iBACkB;CAC1B,uBAAuB,eAAe,KAAK;CAC3C,IAAI,gBAAgB,KAAA,GACnB,uBAAuB,aAAa,aAAa;CAElD,iBAAiB,QAAQ;CAEzB,IAAI,WAAW;CACf,IAAI,aAAa;CACjB,MAAM,SAAyB,CAAC;CAEhC,KAAK,IAAI,IAAI,GAAG,IAAI,SAAS,QAAQ,KAAK;EACzC,MAAM,UAAU,SAAS;EACzB,IAAI,CAAC,SAAS;EAEd,MAAM,QAAQ,oBAAoB,YAAY,SAAS,eAAe,CAAC;EACvE,OAAO,KAAK,KAAK;EACjB,YAAY,MAAM;EAElB,IAAI,QAAQ,SAAS,QAAQ,CAAC,OAAO,SAAS,QAAQ,IAAI,GACzD;EAED,aAAa,QAAQ;CACtB;CAEA,MAAM,mBAAmB,eAAe;CACxC,MAAM,gBAAgB,mBAAmB,IAAI,WAAW,mBAAmB;CAC3E,MAAM,eAAe,eAAe,UAAU,gBAAgB,CAAC;CAE/D,OAAO;EACN;EACA;EACA;EACA;CACD;AACD;;;;;;;;;;ACpFA,SAAgB,WAAW,SAA8B,eAAe,OAAe;CACtF,MAAM,YAAY,QAAQ,SAAS;CACnC,MAAM,EAAE,MAAM,MAAM,SAAS,aAAa;CAE1C,IAAI,cAAc,OAAO;CAEzB,IAAI,SAAS,KAAA,KAAa,SAAS,KAAA,GAAW;EAC7C,uBAAuB,MAAM,GAAG,UAAU,KAAK;EAC/C,aAAa,MAAM,GAAG,UAAU,KAAK;EACrC,IAAI,UAGH,cAAc,eADG,gBADC,aAAa,MAAM,UAAU,GAAG,UAAU,KAC3B,GAAW,IACf,GAAU,QAAQ;OACzC,IAAI,OAAO,cAAc,IAAI,GACnC,cAAc,gBAAgB,MAAM,IAAI;OAExC,cAAc,YAAY,OAAO,IAAI;CAEvC;CAEA,IAAI,YAAY,KAAA,GAAW;EAC1B,uBAAuB,SAAS,GAAG,UAAU,QAAQ;EACrD,cAAc,KAAK,IAAI,aAAa,OAAO;CAC5C;CAEA,uBAAuB,aAAa,GAAG,UAAU,IAAI;CACrD,OAAO;AACR;;;;;;;;;;;;AC/BA,SAAgB,SACf,WACA,cACA,QAAQ,UACQ;CAChB,uBAAuB,WAAW,KAAK;CAEvC,MAAM,MAAM,OAAO,iBAAiB,WAAW,eAAe,WAAW,cAAc,KAAK;CAE5F,uBAAuB,KAAK,GAAG,MAAM,IAAI;CAEzC,MAAM,aAAa,YAAY;CAG/B,OAAO;EACN;EACA,SAJe,aAAa,MAAM;EAKlC;EACA;CACD;AACD"}