// marginal-vs-effective-tax-rate.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. As in us-federal-income-tax-2026-brackets.cjs, the bracket
// table itself does not fit a form field cleanly, so tax_year is an enum input (only "2026"
// published so far) with companion tax_year_source and tax_year_date inputs citing where that
// year's table came from. Adding a future year means adding a new enum value, a new table branch,
// and a new citation.
module.exports = {
  slug: "marginal-vs-effective-tax-rate",
  title: "Marginal vs. effective tax rate, by tax year",
  deck_category: "tax",
  description: "Computes both the marginal tax rate (the rate on the last dollar earned) and the effective tax rate (total tax divided by taxable income) using the published IRS brackets for a chosen tax year.",
  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.01 },
    { 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" },
    { name: "marginal_rate_percent", unit: "%", description: "Tax rate applied to the last dollar of taxable income" },
    { name: "effective_rate_percent", unit: "%", description: "tax_owed divided by taxable_income, as a percent" }
  ],
  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; that row's rate is the marginal_rate_percent. Boundaries are inclusive of the upper bound: income exactly at a bracket's upper threshold is taxed and rated 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), rounded to 2 decimals.",
    "effective_rate_percent = tax_owed / taxable_income * 100, rounded to 2 decimals."
  ],
  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 used for both the marginal rate lookup and the tax computation; 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. 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 `For a ${statusText} filer with $${inputs.taxable_income} of taxable income in tax year ${inputs.tax_year} (${inputs.tax_year_source}, dated ${inputs.tax_year_date}), what is the marginal tax rate and the effective tax rate?`;
  },
  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 positive 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 marginal_rate_percent = Math.round(rate * 100 * 100) / 100;
    const effective_rate_percent = Math.round((tax_owed / taxable_income) * 100 * 100) / 100;
    return {
      answer: `Marginal rate ${marginal_rate_percent.toFixed(2)}%, effective rate ${effective_rate_percent.toFixed(2)}%`,
      values: { tax_owed, marginal_rate_percent, effective_rate_percent }
    };
  },
  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: "Marginal rate 22.00%, effective rate 14.95%" },
      check: "hand computation: tax_owed = 11212.00 (see us-federal-income-tax-2026-brackets); marginal = 22.00% (bracket rate); effective = 11212.00/75000*100 = 14.9493..., rounds to 14.95%"
    },
    {
      name: "test vector: head of household lower income",
      inputs: { filing_status: "head_of_household", taxable_income: 30000, tax_year: "2026", tax_year_source: "IRS Rev. Proc. 2025-32, Section 4.01", tax_year_date: "2026-09-30" },
      expected: { answer: "Marginal rate 12.00%, effective rate 10.82%" },
      check: "hand computation: 30000 falls in the 12% bracket over 17700; tax = 1770 + 0.12*(30000-17700) = 1770+1476 = 3246.00; effective = 3246.00/30000*100 = 10.82%"
    },
    {
      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: "Marginal rate 12.00%, effective rate 11.51%" },
      check: "hand computation: 50400 is exactly the upper bound of the 12% bracket; the IRS 'not over 50400' wording keeps it there, so marginal = 12.00% and tax = 1240+0.12*(50400-12400) = 5800.00; effective = 5800.00/50400*100 = 11.5079...%, rounds to 11.51%"
    }
  ]
};