// us-federal-income-tax-2026-brackets.cjs -- METHOD DECK (X063).
// Per the Founder rule via W001/PQ021, a time-varying table is an input with a source and a
// date, never baked into the method. The bracket table itself does not fit cleanly into a form
// field (it is seven rows per filing status, three filing statuses), so instead of a raw JSON
// array input this method takes tax_year as an enum input (only "2026" published so far) plus
// tax_year_source and tax_year_date as companion inputs citing where that year's table came from
// and when it was retrieved. A stranger filling out a form picks a year from a short list rather
// than pasting a bracket table by hand; adding a future year means adding a new enum value, a new
// table branch below, and a new citation, exactly like adding a new dated rate to the currency
// cards. The numeric bracket values for each published tax_year stay in code, tied to that year's
// citation, the same way the ECB currency card documents its rate table in `constants` without
// letting run() read it directly.
module.exports = {
  slug: "us-federal-income-tax-2026-brackets",
  title: "US federal income tax, by tax year",
  deck_category: "tax",
  description: "Computes US federal income tax owed on taxable income using the published IRS tax rate table for a chosen tax year and filing status.",
  inputs: [
    { name: "filing_status", type: "string", required: true, description: "Filing status", enum: ["single", "married_filing_jointly", "head_of_household"] },
    { name: "taxable_income", type: "number", unit: "currency units", required: true, description: "Taxable income for the chosen tax year (after deductions)", min: 0 },
    { name: "tax_year", type: "string", required: true, description: "Which year's published IRS bracket table to use. Only 2026 is built into this method today; a later year requires adding its table.", enum: ["2026"] },
    { name: "tax_year_source", type: "string", required: true, description: "Citation for the tax_year bracket table (for example the IRS revenue procedure); change it together with tax_year when a newer year is added." },
    { name: "tax_year_date", type: "string", unit: "ISO date", required: true, description: "The date the cited tax_year table was retrieved or published." }
  ],
  outputs: [
    { name: "tax_owed", unit: "currency units", description: "Total federal income tax owed for the chosen tax year" }
  ],
  steps: [
    "The visitor supplies tax_year (which published IRS bracket table to use) plus tax_year_source and tax_year_date, the citation for that table; this method never looks up or fetches a table itself.",
    "Select the bracket table for tax_year and filing_status.",
    "Find the bracket row where taxable_income falls between the row's lower and upper bounds. Boundaries are inclusive of the upper bound: income exactly at a bracket's upper threshold is taxed in that (lower) bracket, matching the IRS table's 'not over' wording; the next bracket applies only to income strictly greater than the threshold.",
    "tax_owed = the row's base amount plus its marginal rate times (taxable_income minus the row's lower bound).",
    "Round tax_owed to 2 decimals (money to cents)."
  ],
  constants: [
    { name: "single_2026_brackets", value: "10% to $12,400; 12% to $50,400; 22% to $105,700; 24% to $201,775; 32% to $256,225; 35% to $640,600; 37% above", unit: "rate schedule", source: 0 },
    { name: "married_filing_jointly_2026_brackets", value: "10% to $24,800; 12% to $100,800; 22% to $211,400; 24% to $403,550; 32% to $512,450; 35% to $768,700; 37% above", unit: "rate schedule", source: 0 },
    { name: "head_of_household_2026_brackets", value: "10% to $17,700; 12% to $67,450; 22% to $105,700; 24% to $201,750; 32% to $256,200; 35% to $640,600; 37% above", unit: "rate schedule", source: 0 }
  ],
  sources: [
    { kind: "url", value: "https://www.irs.gov/pub/irs-drop/rp-25-32.pdf", title: "Rev. Proc. 2025-32, Section 4.01 (2026 Tax Rate Tables, Tables 1-3)", publisher: "Internal Revenue Service", retrieved_utc: "2026-09-30T19:31:29Z", note: "Official 2026 tax year inflation-adjusted tax rate tables for Married Filing Jointly, Head of Household, and Unmarried Individuals (Single); documented source of the tax_year_source/tax_year_date default values prefilled below." }
  ],
  disclaimer: "General federal tax formula only, using the officially published IRS brackets for the chosen tax year. Not tax advice. State tax, credits, alternative minimum tax, and other adjustments are not included. Consult a licensed tax professional or the IRS for your actual return.",
  questionText(inputs) {
    const statusText = { single: "single", married_filing_jointly: "married filing jointly", head_of_household: "head of household" }[inputs.filing_status];
    return `Using the ${inputs.tax_year} IRS tax brackets (${inputs.tax_year_source}, dated ${inputs.tax_year_date}), what is the federal income tax owed on $${inputs.taxable_income} of taxable income for a ${statusText} filer?`;
  },
  run(inputs) {
    const { filing_status, taxable_income, tax_year, tax_year_source, tax_year_date } = inputs;
    const tablesByYear = {
      "2026": {
        single: [
          [0, 12400, 0.10, 0],
          [12400, 50400, 0.12, 1240],
          [50400, 105700, 0.22, 5800],
          [105700, 201775, 0.24, 17966],
          [201775, 256225, 0.32, 41024],
          [256225, 640600, 0.35, 58448],
          [640600, Infinity, 0.37, 192979.25]
        ],
        married_filing_jointly: [
          [0, 24800, 0.10, 0],
          [24800, 100800, 0.12, 2480],
          [100800, 211400, 0.22, 11600],
          [211400, 403550, 0.24, 35932],
          [403550, 512450, 0.32, 82048],
          [512450, 768700, 0.35, 116896],
          [768700, Infinity, 0.37, 206583.50]
        ],
        head_of_household: [
          [0, 17700, 0.10, 0],
          [17700, 67450, 0.12, 1770],
          [67450, 105700, 0.22, 7740],
          [105700, 201750, 0.24, 16155],
          [201750, 256200, 0.32, 39207],
          [256200, 640600, 0.35, 56631],
          [640600, Infinity, 0.37, 191171]
        ]
      }
    };
    if (!tablesByYear[tax_year]) throw new Error("tax_year must be one of: " + Object.keys(tablesByYear).join(", "));
    const tables = tablesByYear[tax_year];
    if (!tables[filing_status]) throw new Error("filing_status must be one of: single, married_filing_jointly, head_of_household");
    if (typeof taxable_income !== "number" || taxable_income < 0) throw new Error("taxable_income must be a non-negative number");
    if (typeof tax_year_source !== "string" || !tax_year_source.trim()) throw new Error("tax_year_source must be a non-empty string");
    if (typeof tax_year_date !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(tax_year_date)) throw new Error("tax_year_date must be a string in YYYY-MM-DD format");
    const brackets = tables[filing_status];
    // Boundaries are inclusive of the upper bound (IRS "not over" wording): income exactly at a
    // bracket's upper threshold stays in that row; only income strictly greater moves to the next.
    const row = brackets.find(([lo, hi]) => lo === 0 ? taxable_income <= hi : (taxable_income > lo && taxable_income <= hi))
      || brackets[brackets.length - 1];
    const [lo, , rate, base] = row;
    const tax_owed = Math.round((base + rate * (taxable_income - lo)) * 100) / 100;
    const fmt = (n) => n.toFixed(2).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
    return {
      answer: `$${fmt(tax_owed)}`,
      values: { tax_owed }
    };
  },
  examples: [
    {
      name: "worked example",
      inputs: { filing_status: "single", taxable_income: 75000, tax_year: "2026", tax_year_source: "IRS Rev. Proc. 2025-32, Section 4.01", tax_year_date: "2026-09-30" },
      expected: { answer: "$11,212.00" },
      check: "hand computation using IRS Table 3 (single): 75000 falls in the 22% bracket over 50400; tax = 5800 + 0.22*(75000-50400) = 5800 + 0.22*24600 = 5800+5412 = 11212.00"
    },
    {
      name: "test vector: married filing jointly top bracket",
      inputs: { filing_status: "married_filing_jointly", taxable_income: 900000, tax_year: "2026", tax_year_source: "IRS Rev. Proc. 2025-32, Section 4.01", tax_year_date: "2026-09-30" },
      expected: { answer: "$255,164.50" },
      check: "hand computation using IRS Table 1 (MFJ): 900000 is over 768700 at 37%; tax = 206583.50 + 0.37*(900000-768700) = 206583.50 + 0.37*131300 = 206583.50+48581.00 = 255164.50"
    },
    {
      name: "test vector: single filer exactly at a bracket boundary",
      inputs: { filing_status: "single", taxable_income: 50400, tax_year: "2026", tax_year_source: "IRS Rev. Proc. 2025-32, Section 4.01", tax_year_date: "2026-09-30" },
      expected: { answer: "$5,800.00" },
      check: "hand computation using IRS Table 3 (single): 50400 is exactly the upper bound of the 12% bracket (10% to 12400, 12% to 50400); the IRS 'not over 50400' wording keeps it in that row, so tax = 1240 + 0.12*(50400-12400) = 1240+4560 = 5800.00, not the 22% row's base"
    }
  ]
};