@trajectonomics/tax 0.2.0-alpha.0 → 0.2.0-alpha.1

package/dist/th/index.d.cts

@@ -464,6 +464,420 @@ interface ThTaxInput {
  * @statute Thailand Revenue Code Sections 40, 42 bis, 47, 48(1)–(2).
  */
 export declare function calculateThTax(input?: ThTaxInput): TaxResult<"THB", ThBreakdown>;
+/**
+ * Tally bases sim-core's `tally` Measure reads.
+ *
+ * Purpose: Distinguishes income Flows from contribution Flows at the tally.
+ * Math: No arithmetic; a discriminator only.
+ * Units: Dimensionless.
+ * Throws: Nothing.
+ * @statute Thailand Revenue Code Sections 40(1)–(8) (gross) and 47 (funded).
+ */
+export declare const ThLevyTallyBasis: {
+  /** Sums income Flows. */
+  readonly Gross: "gross";
+  /** Sums contribution Flows. */
+  readonly Funded: "funded";
+};
+/**
+ * Union of {@link ThLevyTallyBasis} values.
+ *
+ * Purpose: Narrow type for the tally basis of an emitted Measure.
+ * Math: No arithmetic; a discriminator only.
+ * Units: Dimensionless.
+ * Throws: Nothing.
+ * @statute Thailand Revenue Code Sections 40(1)–(8) (gross) and 47 (funded).
+ */
+export type ThLevyTallyBasis = (typeof ThLevyTallyBasis)[keyof typeof ThLevyTallyBasis];
+/**
+ * Rounding modes sim-core's `scale` Measure accepts.
+ *
+ * Purpose: Names the three rounding policies embedded in emitted Measures.
+ * Math: `Floor` rounds down, `Ceil` up, and `HalfUp` sends ties away from zero.
+ * Units: Dimensionless.
+ * Throws: Nothing.
+ * @statute Thailand Revenue Code Sections 47 bis, 48(1), 48(2).
+ */
+export declare const ThLevyRounding: {
+  readonly Floor: "floor";
+  readonly HalfUp: "halfUp";
+  readonly Ceil: "ceil";
+};
+/**
+ * Union of {@link ThLevyRounding} values.
+ *
+ * Purpose: Narrow type for a `scale` Measure's rounding policy.
+ * Math: No arithmetic; names `floor`, `ceil`, or ties-away-from-zero `halfUp`.
+ * Units: Dimensionless.
+ * Throws: Nothing.
+ * @statute Thailand Revenue Code Sections 47 bis, 48(1), 48(2).
+ */
+export type ThLevyRounding = (typeof ThLevyRounding)[keyof typeof ThLevyRounding];
+/**
+ * Recurring calendar date without a year, as sim-core's `MonthDay`.
+ *
+ * Purpose: Fixes the Levy period and settlement dates at emit time.
+ * Math: No arithmetic; the date recurs every year and is never February 29.
+ * Units: Month number 1–12 and day number; not a timestamp.
+ * Throws: Nothing; sim-core's `check()` validates the pair.
+ * @statute Thailand Revenue Code Section 56 (annual return filing period).
+ */
+interface ThLevyMonthDay {
+  /** Month number, 1 to 12. */
+  readonly month: number;
+  /** Day number within the month. */
+  readonly day: number;
+}
+/**
+ * One node of the emitted rule graph, restricted to the operation set sim-core evaluates.
+ *
+ * Purpose: Closed union that makes any operation outside sim-core's set a type error.
+ * Math: `const`, `tally`, binary arithmetic, exact `scale`, and `pick` — nothing else.
+ * Units: `value` and Measure totals are integer satang; `num`/`den` are dimensionless.
+ * Throws: Nothing at construction; {@link ThLevyGraph.build} checks operands.
+ * @statute Thailand Revenue Code Sections 40, 42 bis, 47, 47 bis, 48(1)–(2).
+ */
+type ThLevyMeasure = {
+  readonly id: string;
+  readonly op: "const";
+  readonly value: number;
+} | {
+  readonly id: string;
+  readonly op: "tally";
+  readonly label: string;
+  readonly basis: ThLevyTallyBasis;
+} | {
+  readonly id: string;
+  readonly op: "add" | "sub" | "min" | "max";
+  readonly a: string;
+  readonly b: string;
+} | {
+  readonly id: string;
+  readonly op: "scale";
+  readonly of: string;
+  readonly num: number;
+  readonly den: number;
+  readonly rounding: ThLevyRounding;
+} | {
+  readonly id: string;
+  readonly op: "pick";
+  readonly a: string;
+  readonly b: string;
+  readonly then: string;
+  readonly else: string;
+};
+/**
+ * A Thailand Personal Income Tax rule set in sim-core's published `Levy` shape.
+ *
+ * Purpose: The caller hands this to sim-core, which evaluates it from Flow tallies without
+ * importing this package. The taxpayer profile, elections, and 2026 statutory parameters are
+ * frozen at emit time, so one Levy describes one taxpayer.
+ * Math: Every Measure is exact integer satang arithmetic over the closed sim-core operation set.
+ * Units: All monetary Measure values are integer satang (THB minor units).
+ * Throws: Nothing at construction; {@link ThLevyGraph.build} validates the graph.
+ * @statute Thailand Revenue Code Sections 40, 42 bis, 47, 47 bis, 48(1)–(2).
+ */
+interface ThLevy {
+  /** Stable Levy id echoed by sim-core's projection report. */
+  readonly id: string;
+  /** Calendar date on which each Settlement period starts. */
+  readonly period: ThLevyMonthDay;
+  /** First such date strictly after the period's last day. */
+  readonly settlement: ThLevyMonthDay;
+  /** Rule graph, in dependency-friendly emit order. */
+  readonly measures: readonly ThLevyMeasure[];
+  /** Id of the Measure holding the amount owed before Prepayment. */
+  readonly due: string;
+}
+/**
+ * Fixed allowance amounts frozen into a TH 2026 Levy at emit time.
+ *
+ * Purpose: These allowances depend only on the taxpayer profile, so the emitter bakes them as
+ * fixed Measures. Contribution-driven allowances (RMF, SSF, PVD, GPF, NSF, pension life insurance,
+ * ThaiESG) are excluded on purpose: they arrive as `funded` Flow tallies instead.
+ * Math: Sums the calculator's family and insurance stages into one fixed Measure.
+ * Units: THB major units, except counts (children, parents, disabled persons).
+ * Throws: TaxValidationError at emit time for a negative or non-finite amount or an invalid count.
+ * @statute Thailand Revenue Code Section 47.
+ */
+type ThLevyAllowances = Pick<ThAllowancesInput, "personal" | "spouse" | "children" | "parents" | "disabledCareCount" | "socialSecurity" | "lifeInsurance" | "healthInsurance" | "parentHealthInsurance" | "spouseLifeInsurance" | "mortgageInterest" | "donation2x" | "donation1x">;
+/**
+ * Expense election fixed for one electable income item at emit time.
+ *
+ * Purpose: Chooses the standard statutory percentage or an actual substantiated expense.
+ * Math: No arithmetic; selects which expense Measure graph is emitted.
+ * Units: `actualExpense` is THB major units.
+ * Throws: TaxValidationError at emit time if the actual expense is invalid.
+ * @statute Thailand Revenue Code Sections 42 bis, 42 ter, 43–46.
+ */
+interface ThLevyExpenseChoice {
+  /** Defaults to `"standard"`. */
+  readonly election?: ThExpenseElection | undefined;
+  /** Actual substantiated expense in THB; used only when `election` is `"actual"`. */
+  readonly actualExpense?: number | undefined;
+}
+/**
+ * Expense elections frozen into the Levy, per Section 40 income item with a standard/actual choice.
+ *
+ * Purpose: Records which items use the standard statutory percentage and which use actuals.
+ * Math: No arithmetic; each choice selects an emitted Measure branch.
+ * Units: Actual expense amounts are THB major units.
+ * Throws: TaxValidationError at emit time if an actual expense is invalid.
+ * @statute Thailand Revenue Code Sections 42 bis, 42 ter, 43–46; Royal Decree No. 11.
+ */
+interface ThLevyExpenseElections {
+  /** Section 40(3) royalties and goodwill. */
+  readonly section40_3?: ThLevyExpenseChoice | undefined;
+  /** Section 40(5) rental income, per property class. */
+  readonly section40_5?: {
+    readonly building?: ThLevyExpenseChoice | undefined;
+    readonly agriculturalLand?: ThLevyExpenseChoice | undefined;
+    readonly nonAgriculturalLand?: ThLevyExpenseChoice | undefined;
+    readonly vehicles?: ThLevyExpenseChoice | undefined;
+    readonly other?: ThLevyExpenseChoice | undefined;
+  };
+  /** Section 40(6) liberal professions, per profession class. */
+  readonly section40_6?: {
+    readonly medical?: ThLevyExpenseChoice | undefined;
+    readonly law?: ThLevyExpenseChoice | undefined;
+    readonly engineering?: ThLevyExpenseChoice | undefined;
+    readonly architecture?: ThLevyExpenseChoice | undefined;
+    readonly accounting?: ThLevyExpenseChoice | undefined;
+    readonly fineArts?: ThLevyExpenseChoice | undefined;
+    readonly other?: ThLevyExpenseChoice | undefined;
+  };
+  /** Section 40(7) contracting with materials. */
+  readonly section40_7?: ThLevyExpenseChoice | undefined;
+  /** Section 40(8) business income, split by expense schedule. */
+  readonly section40_8?: {
+    readonly general?: ThLevyExpenseChoice | undefined;
+    readonly entertainer?: ThLevyExpenseChoice | undefined;
+  };
+}
+/**
+ * Section 40(4) elections frozen into the Levy. All sources default to `"include"`.
+ *
+ * Purpose: Fixes final withholding versus regular-bracket inclusion per source.
+ * Math: No arithmetic; each election selects the withholding a Measure applies.
+ * Units: `dividendCorpTaxRate` is a dimensionless ratio in [0, 1).
+ * Throws: TaxValidationError at emit time if the corporate rate is outside [0, 1).
+ * @statute Thailand Revenue Code Sections 40(4), 47 bis, 50(2)(g), 57 ter.
+ */
+interface ThLevySection40_4Elections {
+  /** Interest: final withholding versus regular brackets. */
+  readonly interest?: ThFinalWithholdingElection | undefined;
+  /** Dividends: final withholding versus regular brackets. */
+  readonly dividends?: ThFinalWithholdingElection | undefined;
+  /** Digital asset income: final withholding versus regular brackets. */
+  readonly digitalAssets?: ThFinalWithholdingElection | undefined;
+  /** Section 47 bis corporate rate for included dividends in [0, 1); omit for no credit. */
+  readonly dividendCorpTaxRate?: number | undefined;
+}
+/**
+ * Levy identity and Settlement period frozen at emit time.
+ *
+ * Purpose: Lets a caller name the Levy and override the default filing window.
+ * Math: No arithmetic; identity and calendar dates only.
+ * Units: Not monetary; the dates are month/day pairs.
+ * Throws: Nothing; sim-core's `check()` validates the dates.
+ * @statute Thailand Revenue Code Section 56 (annual return filing period).
+ */
+interface ThLevyIdentity {
+  /** Levy id, defaulting to `"th-2026-pit"`. */
+  readonly id?: string | undefined;
+  /** Period start, defaulting to 1 January (the calendar tax year). */
+  readonly period?: ThLevyMonthDay | undefined;
+  /** Settlement date, defaulting to 31 March after the tax year. */
+  readonly settlement?: ThLevyMonthDay | undefined;
+}
+/**
+ * The taxpayer profile an emitted TH 2026 Levy is specialised to.
+ *
+ * Purpose: Holds everything that must be fixed at emit time: filing status, fixed allowances,
+ * expense elections, Section 40(4) elections, and the Levy identity. Income and contribution
+ * amounts are not part of the profile; they arrive as Flow tallies at evaluation time.
+ * Math: No arithmetic; every monetary amount is an emit-time constant.
+ * Units: Monetary profile amounts are THB major units.
+ * Throws: TaxValidationError at emit time for any invalid allowance, donation, expense, or rate.
+ * @statute Thailand Revenue Code Sections 40, 42 bis, 47, 47 bis, 48(1)–(2), 56.
+ */
+interface ThLevyProfile {
+  /** Filing status governing family allowances; defaults to `"single"`. */
+  readonly filingStatus?: ThFilingStatus | undefined;
+  /** Fixed allowances and donation requests; contribution allowances come from tallies. */
+  readonly allowances?: ThLevyAllowances | undefined;
+  /** Standard-versus-actual expense elections; omitted items use the standard deduction. */
+  readonly expenses?: ThLevyExpenseElections | undefined;
+  /** Section 40(4) final-withholding and Section 47 bis elections. */
+  readonly section40_4?: ThLevySection40_4Elections | undefined;
+  /** Levy id, period, and settlement; each has a statutory default. */
+  readonly levy?: ThLevyIdentity | undefined;
+}
+/**
+ * Emits a Thailand 2026 Personal Income Tax rule set as sim-core Levy data.
+ *
+ * Purpose: Lets sim-core charge the annual PIT assessment from Flow tallies without importing
+ * this package. The profile, elections, and 2026 statutory parameters are frozen at emit time;
+ * income and contribution amounts arrive as Flow tallies under the exported labels.
+ * Math: `due = max(progressive, minimum gross tax) + final withholding tax
+ * - final withholding tax - Section 47 bis credit`, which is the calculator's `netTaxPayable`
+ * when no separate sheet, real estate, or other withholding is supplied.
+ * Units: Every monetary Measure is integer satang.
+ * Throws: TaxValidationError for an invalid profile allowance, donation, actual expense, or rate.
+ *
+ * @param profile Taxpayer profile and elections fixed at emit time.
+ * @statute Thailand Revenue Code Sections 40, 42 bis, 47, 47 bis, 48(1)–(2), 50(2)(g), 56.
+ */
+export declare function emitThLevy(profile?: ThLevyProfile): ThLevy;
+/**
+ * Tally labels a TH 2026 Levy reads from income Flows (`gross` basis).
+ *
+ * Purpose: One label per assessable income class under Section 40(1)–(8), with Section 40(4)
+ * split per source because each source carries its own final-withholding election at emit time.
+ * Math: No arithmetic; the label selects which tally a Measure reads.
+ * Units: Dimensionless label string; the tallied amount is integer satang.
+ * Throws: Nothing.
+ * @statute Thailand Revenue Code Sections 40(1)–(8), 40(4), 50(2)(g).
+ */
+export declare const ThLevyIncomeLabel: {
+  /** Section 40(1) employment income. */
+  readonly Section40_1: "income.section40_1";
+  /** Section 40(2) service and hire-of-work income. */
+  readonly Section40_2: "income.section40_2";
+  /** Section 40(3) royalties, goodwill, and copyright income. */
+  readonly Section40_3: "income.section40_3";
+  /** Section 40(4) income with no source-specific election. */
+  readonly Section40_4Other: "income.section40_4";
+  /** Section 40(4) interest, elected final or included at emit time. */
+  readonly Section40_4Interest: "income.section40_4.interest";
+  /** Section 40(4) dividends, elected final or included at emit time. */
+  readonly Section40_4Dividends: "income.section40_4.dividends";
+  /** Section 40(4) digital asset income, elected final or included at emit time. */
+  readonly Section40_4DigitalAssets: "income.section40_4.digitalAssets";
+  /** Section 40(5) building rental income. */
+  readonly Section40_5Building: "income.section40_5.building";
+  /** Section 40(5) agricultural land rental income. */
+  readonly Section40_5AgriculturalLand: "income.section40_5.agriculturalLand";
+  /** Section 40(5) non-agricultural land rental income. */
+  readonly Section40_5NonAgriculturalLand: "income.section40_5.nonAgriculturalLand";
+  /** Section 40(5) vehicle rental income. */
+  readonly Section40_5Vehicles: "income.section40_5.vehicles";
+  /** Section 40(5) other rental income. */
+  readonly Section40_5Other: "income.section40_5.other";
+  /** Section 40(6) medical profession income. */
+  readonly Section40_6Medical: "income.section40_6.medical";
+  /** Section 40(6) law profession income. */
+  readonly Section40_6Law: "income.section40_6.law";
+  /** Section 40(6) engineering profession income. */
+  readonly Section40_6Engineering: "income.section40_6.engineering";
+  /** Section 40(6) architecture profession income. */
+  readonly Section40_6Architecture: "income.section40_6.architecture";
+  /** Section 40(6) accounting profession income. */
+  readonly Section40_6Accounting: "income.section40_6.accounting";
+  /** Section 40(6) fine arts profession income. */
+  readonly Section40_6FineArts: "income.section40_6.fineArts";
+  /** Section 40(6) other liberal profession income. */
+  readonly Section40_6Other: "income.section40_6.other";
+  /** Section 40(7) contracting income. */
+  readonly Section40_7: "income.section40_7";
+  /** Section 40(8) general business and commerce income. */
+  readonly Section40_8General: "income.section40_8.general";
+  /** Section 40(8) entertainer income (tiered expense rate). */
+  readonly Section40_8Entertainer: "income.section40_8.entertainer";
+};
+/**
+ * Union of {@link ThLevyIncomeLabel} values.
+ *
+ * Purpose: Narrow type for the labels a caller may put on an income Flow.
+ * Math: No arithmetic.
+ * Units: Dimensionless label string.
+ * Throws: Nothing.
+ * @statute Thailand Revenue Code Sections 40(1)–(8), 40(4).
+ */
+export type ThLevyIncomeLabel = (typeof ThLevyIncomeLabel)[keyof typeof ThLevyIncomeLabel];
+/**
+ * Tally labels a TH 2026 Levy reads from contribution Flows (`funded` basis).
+ *
+ * Purpose: One label per contribution-driven retirement allowance.
+ * Math: No arithmetic; the label selects which tally a Measure reads.
+ * Units: Dimensionless label string; the tallied amount is integer satang.
+ * Throws: Nothing.
+ * @statute Thailand Revenue Code Section 47; Ministerial Regulations No. 126, 390.
+ */
+export declare const ThLevyContributionLabel: {
+  /** RMF contribution. */
+  readonly Rmf: "allowance.retirement.rmf";
+  /** SSF contribution. */
+  readonly Ssf: "allowance.retirement.ssf";
+  /** PVD contribution. */
+  readonly Pvd: "allowance.retirement.pvd";
+  /** GPF contribution. */
+  readonly Gpf: "allowance.retirement.gpf";
+  /** National Savings Fund contribution. */
+  readonly Nsf: "allowance.retirement.nsf";
+  /** Pension life insurance premium. */
+  readonly PensionLifeInsurance: "allowance.retirement.pension_life";
+  /** ThaiESG fund contribution. */
+  readonly ThaiEsg: "allowance.thai_esg";
+};
+/**
+ * Union of {@link ThLevyContributionLabel} values.
+ *
+ * Purpose: Narrow type for the labels a caller may put on a contribution Flow.
+ * Math: No arithmetic.
+ * Units: Dimensionless label string.
+ * Throws: Nothing.
+ * @statute Thailand Revenue Code Section 47; Ministerial Regulations No. 126, 390.
+ */
+export type ThLevyContributionLabel = (typeof ThLevyContributionLabel)[keyof typeof ThLevyContributionLabel];
+/**
+ * Every income tally label the emitter reads, in Section 40 order.
+ *
+ * Purpose: Ordered contract a caller can iterate to label or audit income Flows.
+ * Math: No arithmetic.
+ * Units: Dimensionless label strings.
+ * Throws: Nothing.
+ * @statute Thailand Revenue Code Sections 40(1)–(8), 40(4).
+ */
+export declare const TH_LEVY_INCOME_LABELS: readonly ThLevyIncomeLabel[];
+/**
+ * Every contribution tally label the emitter reads, in retirement-cluster order.
+ *
+ * Purpose: Ordered contract a caller can iterate to label or audit contribution Flows.
+ * Math: No arithmetic.
+ * Units: Dimensionless label strings.
+ * Throws: Nothing.
+ * @statute Thailand Revenue Code Section 47; Ministerial Regulations No. 126, 390.
+ */
+export declare const TH_LEVY_CONTRIBUTION_LABELS: readonly ThLevyContributionLabel[];
+/**
+ * Audited Measure ids a TH 2026 Levy exposes by name.
+ *
+ * Purpose: Lets callers and tests compare each intermediate statutory figure without knowing
+ * the emit order.
+ * Math: No arithmetic; Measure ids only.
+ * Units: The referenced Measures are integer satang.
+ * Throws: Nothing.
+ * @statute Thailand Revenue Code Sections 40, 42 bis, 47, 47 bis, 48(1)–(2).
+ */
+export declare enum ThLevyMeasureId {
+  AssessableTotal = "assessable.total",
+  GrossNonEmployment = "assessable.non_employment",
+  ExpensesTotal = "expenses.total",
+  AllowancesFixed = "allowances.fixed",
+  RetirementCluster = "allowances.retirement_cluster",
+  ThaiEsg = "allowances.thai_esg",
+  Donations = "allowances.donations",
+  AllowancesTotal = "allowances.total",
+  NetTaxableIncome = "taxable.income",
+  ProgressiveTax = "tax.progressive",
+  MinimumGrossTax = "tax.minimum",
+  RegularTax = "tax.regular",
+  FinalWithholdingTax = "tax.final_withholding",
+  DividendCredit = "credit.dividend",
+  TotalTax = "tax.total",
+  NetTaxPayable = "tax.net_payable"
+}
 interface ThParameters {
   readonly taxYear: 2026;
   readonly currency: "THB";
@@ -632,5 +1046,5 @@ export declare const TH_2026_PARAMETERS: ThParameters;
  * Implements TaxSystem contract for `@trajectonomics/tax/th`.
  */
 export declare const th: TaxSystem<ThTaxInput, "THB", ThBreakdown>;
-export type { ThAllowancesBreakdown, ThAllowancesInput, ThAssessableIncomeBreakdown, ThAssessableIncomeInput, ThBreakdown, ThChild, ThChildrenInput, ThCombinedTaxBreakdown, ThDividendTaxCreditBreakdown, ThDonationsBreakdown, ThExpenseDeductionsBreakdown, ThExpenseElectableIncome, ThExpenseElection, ThFilingStatus, ThFinalWithholdingBreakdown, ThFinalWithholdingSourceBreakdown, ThMinimumGrossTaxBreakdown, ThParentsInput, ThRealEstateBreakdown, ThRealEstateTransferInput, ThRetirementClusterBreakdown, ThSection40_4Dividend, ThSection40_4Input, ThSection40_4Source, ThSection40_5Input, ThSection40_6Input, ThSection40_8Input, ThSeparateSheetBreakdown, ThSeparateSheetInput, ThTaxInput };
+export type { ThAllowancesBreakdown, ThAllowancesInput, ThAssessableIncomeBreakdown, ThAssessableIncomeInput, ThBreakdown, ThChild, ThChildrenInput, ThCombinedTaxBreakdown, ThDividendTaxCreditBreakdown, ThDonationsBreakdown, ThExpenseDeductionsBreakdown, ThExpenseElectableIncome, ThExpenseElection, ThFilingStatus, ThFinalWithholdingBreakdown, ThFinalWithholdingSourceBreakdown, ThLevy, ThLevyAllowances, ThLevyExpenseChoice, ThLevyExpenseElections, ThLevyIdentity, ThLevyMeasure, ThLevyMonthDay, ThLevyProfile, ThLevySection40_4Elections, ThMinimumGrossTaxBreakdown, ThParentsInput, ThRealEstateBreakdown, ThRealEstateTransferInput, ThRetirementClusterBreakdown, ThSection40_4Dividend, ThSection40_4Input, ThSection40_4Source, ThSection40_5Input, ThSection40_6Input, ThSection40_8Input, ThSeparateSheetBreakdown, ThSeparateSheetInput, ThTaxInput };
 //# sourceMappingURL=index.d.cts.map