invest.capital-gains-tax Unreviewed

export function capitalGainsTax(taxYearDate: string, disposals: readonly CgtDisposal[], taxableIncome: Money, lossesBroughtForward: Money): CgtResult

export type AssetKind = "residential" | "other";

/** One chargeable gain or allowable loss. */
export interface CgtDisposal {
  /** the date of disposal, which decides the rate */
  readonly date: string;
  /** residential property, or anything else */
  readonly kind: AssetKind;
  /** the gain; negative for a loss */
  readonly gain: Money;
}

/** Taxable gains charged at one rate. */
export interface CgtLine {
  /** 1800 = 18% */
  readonly rateBasisPoints: number;
  readonly gains: Money;
  readonly tax: Money;
}

/** The computation, step by step, and the tax. */
export interface CgtResult {
  /** HMRC's label, 2024/25 */
  readonly taxYear: string;
  /** the year's gains added together */
  readonly gains: Money;
  /** the year's losses added together, as a positive amount */
  readonly losses: Money;
  readonly lossesBroughtForwardUsed: Money;
  readonly annualExemptAmount: Money;
  readonly annualExemptAmountUsed: Money;
  readonly taxableGains: Money;
  /** what taxable income leaves of the basic rate band */
  readonly basicRateBandAvailable: Money;
  /** lowest rate first */
  readonly lines: readonly CgtLine[];
  readonly tax: Money;
  /** losses still unused, to carry to next year */
  readonly lossesCarriedForward: Money;
}

import { capitalGainsTax } from "#fune/invest.capital-gains-tax@^1";

import { ukTaxYear } from "./dates_uk_tax_year.ts";  ← from dates.uk-tax-year ^1.0.0 · built alongside by fune
import { type Money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { applyRate } from "./money_apply_rate.ts";  ← from money.apply-rate ^1.0.0 · built alongside by fune
import { CGT_RATES, CGT_RATES_HISTORY, CGT_RATES_HORIZON, CGT_YEARS, CGT_YEARS_HISTORY, CGT_YEARS_HORIZON } from "./invest_capital_gains_tax_data.ts";  ← this capability’s own data, compiled from data/cgt-years.json into the same file by fune build
import { type CgtDisposal, type CgtLine, type CgtResult } from "./invest_capital_gains_tax_types.ts";

/** Gains that share a pair of rates; they are interchangeable for every step below. */
interface Bucket {
  lower: number;
  higher: number;
  amount: number;
}

function gbp(minor: number): Money {
  return { minor, currency: "GBP" };
}

function checkMoney(value: Money, name: string): void {
  if (value.currency !== "GBP") throw new RangeError(`${name} must be in GBP, received ${value.currency}`);
  if (!Number.isInteger(value.minor)) throw new RangeError(`${name} must be a whole number of pence, received ${value.minor}`);
}

function pruned(history: string, horizon: string | null, date: string): string {
  return horizon !== null && date < horizon
    ? `: this build was installed with history=${history}, so it only carries rules from ${horizon}. Reinstall with history=full for earlier years.`
    : "";
}

function rateFor(disposal: CgtDisposal): Bucket {
  for (const rule of CGT_RATES) {
    if (rule.kind !== disposal.kind || disposal.date < rule.validFrom) continue;
    if (rule.validTo !== null && disposal.date > rule.validTo) continue;
    return { lower: rule.lowerBasisPoints, higher: rule.higherBasisPoints, amount: 0 };
  }
  throw new RangeError(
    `no CGT rate for ${disposal.kind} gains on ${disposal.date}` + pruned(CGT_RATES_HISTORY, CGT_RATES_HORIZON, disposal.date)
  );
}

/**
 * Capital Gains Tax for an individual for one UK tax year.
 *
 * The year's losses come off its gains in full, even when that wastes the
 * annual exempt amount; losses brought forward only bring the net gains down
 * to the annual exempt amount. Losses and the exempt amount go against the
 * gains charged at the highest rate first, and what taxable income leaves of
 * the basic rate band goes to the gains whose two rates are furthest apart:
 * that is the "most beneficial" order TCGA 1992 s1F and s1K allow.
 */
export function capitalGainsTax(
  taxYearDate: string,
  disposals: readonly CgtDisposal[],
  taxableIncome: Money,
  lossesBroughtForward: Money
): CgtResult {
  const year = ukTaxYear(taxYearDate);
  const rules = CGT_YEARS.find((row) => row.validFrom <= year.start && (row.validTo === null || year.start <= row.validTo));
  if (rules === undefined) {
    throw new RangeError(`no CGT rules for the ${year.label} tax year` + pruned(CGT_YEARS_HISTORY, CGT_YEARS_HORIZON, year.start));
  }
  checkMoney(taxableIncome, "taxableIncome");
  checkMoney(lossesBroughtForward, "lossesBroughtForward");
  if (taxableIncome.minor < 0) throw new RangeError(`taxableIncome must not be negative, received ${taxableIncome.minor}`);
  if (lossesBroughtForward.minor < 0) {
    throw new RangeError(`lossesBroughtForward must not be negative, received ${lossesBroughtForward.minor}`);
  }

  const buckets: Bucket[] = [];
  let gains = 0;
  let losses = 0;
  for (const disposal of disposals) {
    checkMoney(disposal.gain, "gain");
    if (disposal.kind !== "residential" && disposal.kind !== "other") {
      throw new RangeError(`kind must be residential or other, received "${disposal.kind}"`);
    }
    if (disposal.date < year.start || disposal.date > year.end) {
      throw new RangeError(`the disposal on ${disposal.date} is outside the ${year.label} tax year`);
    }
    const rate = rateFor(disposal);
    if (disposal.gain.minor <= 0) {
      losses -= disposal.gain.minor;
      continue;
    }
    gains += disposal.gain.minor;
    const bucket = buckets.find((b) => b.lower === rate.lower && b.higher === rate.higher);
    if (bucket === undefined) buckets.push({ ...rate, amount: disposal.gain.minor });
    else bucket.amount += disposal.gain.minor;
  }

  const net = gains - losses;
  const annualExemptAmount = rules.annualExemptAmount;
  let broughtForwardUsed = 0;
  let exemptUsed = 0;
  let taxable = 0;
  let carried = lossesBroughtForward.minor;
  if (net > 0) {
    broughtForwardUsed = Math.min(lossesBroughtForward.minor, Math.max(0, net - annualExemptAmount));
    exemptUsed = Math.min(annualExemptAmount, net - broughtForwardUsed);
    taxable = net - broughtForwardUsed - exemptUsed;
    carried -= broughtForwardUsed;
  } else {
    carried += -net;
  }

  // Deductions against the gains taxed hardest first.
  let deductions = gains - taxable;
  const byHigher = [...buckets].sort((a, b) => b.higher - a.higher || b.lower - a.lower);
  for (const bucket of byHigher) {
    const used = Math.min(bucket.amount, deductions);
    bucket.amount -= used;
    deductions -= used;
  }

  // The basic rate band where it saves the most: the widest gap between the two rates.
  const bandAvailable = Math.max(0, rules.basicRateBand - taxableIncome.minor);
  let band = bandAvailable;
  const byGap = [...buckets].sort((a, b) => b.higher - b.lower - (a.higher - a.lower) || b.higher - a.higher);
  const charged = new Map<number, number>();
  const charge = (rate: number, amount: number) => {
    if (amount > 0) charged.set(rate, (charged.get(rate) ?? 0) + amount);
  };
  for (const bucket of byGap) {
    const lower = Math.min(bucket.amount, band);
    band -= lower;
    charge(bucket.lower, lower);
    charge(bucket.higher, bucket.amount - lower);
  }

  const lines: CgtLine[] = [...charged.entries()]
    .sort((a, b) => a[0] - b[0])
    .map(([rate, amount]) => ({ rateBasisPoints: rate, gains: gbp(amount), tax: applyRate(gbp(amount), rate, "down") }));
  const tax = lines.reduce((sum, line) => sum + line.tax.minor, 0);

  return {
    taxYear: year.label,
    gains: gbp(gains),
    losses: gbp(losses),
    lossesBroughtForwardUsed: gbp(broughtForwardUsed),
    annualExemptAmount: gbp(annualExemptAmount),
    annualExemptAmountUsed: gbp(exemptUsed),
    taxableGains: gbp(taxable),
    basicRateBandAvailable: gbp(bandAvailable),
    lines,
    tax: gbp(tax),
    lossesCarriedForward: gbp(carried),
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add invest.capital-gains-tax

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./invest.capital-gains-tax-1.0.1-typescript.fune, or fetch it from a terminal with fune pull invest.capital-gains-tax@1.0.1:typescript.

The whole function, every language, is one file too: invest.capital-gains-tax-1.0.1.fune, 64,796 bytes, sha256 8e0d4a77f71e50cd266ad151218feae9edd76aaa073c769d22c87ac68830b186. It installs into a project of any language.

// fune: before invest.capital-gains-tax

// fune: after invest.capital-gains-tax

// fune: replace dates.uk-tax-year in invest.capital-gains-tax
// fune: replace money.amount in invest.capital-gains-tax
// fune: replace money.apply-rate in invest.capital-gains-tax

// fune: step invest.capital-gains-tax after <n|label>

More from the author

## How it is worked out

1. The year's losses are set against the year's gains in full, even where that takes the net gains below the annual exempt amount and wastes it (CG21500). 2. Losses brought forward are used only to bring the net gains down to the annual exempt amount; the rest carry on (CG21500). 3. The annual exempt amount comes off what is left. 4. The losses and exempt amount are set against the gains charged at the highest rate first, as TCGA 1992 s1F and s1K allow ("in the way that is most beneficial ... generally against gains charged at the highest rate"). 5. What taxable income leaves of the basic rate band is charged at the lower rate, given first to the gains whose two rates are furthest apart (in 2024/25, 10%/20% gains before 18%/24% ones), since that saves the most. 6. Tax is worked out for each rate and rounded down to the penny.

For the rates in the data this order gives the lowest tax. The rates follow the date of each disposal, so 2024/25 mixes 10%/20% for shares sold up to 29 October 2024 with 18%/24% from 30 October.

## Rules data

`data/cgt-years.json` has, per tax year, the annual exempt amount and the basic rate band (in pence). `data/cgt-rates.json` has the lower and higher rate for residential property and other assets by disposal date. Years covered: 2020/21 to 2026/27. A tax year outside those, or a date before a pruned build's horizon, is refused rather than guessed.

| Tax year | AEA | Basic rate band | |---|---|---| | 2020/21 | £12,300 | £37,500 | | 2021/22, 2022/23 | £12,300 | £37,700 | | 2023/24 | £6,000 | £37,700 | | 2024/25 to 2026/27 | £3,000 | £37,700 |

| Disposals | Residential property | Other | |---|---|---| | 6 Apr 2016 to 5 Apr 2024 | 18% / 28% | 10% / 20% | | 6 Apr 2024 to 29 Oct 2024 | 18% / 24% | 10% / 20% | | from 30 Oct 2024 | 18% / 24% | 18% / 24% |

## Out of scope

Business Asset Disposal Relief and Investors' Relief (and the basic rate band they use first), carried interest, trusts and personal representatives, losses carried back on death, non-residents, and the reliefs that extend the basic rate band (gift aid and personal pension contributions: pass `taxableIncome` less the grossed-up contributions). CGT bands are UK-wide, so a Scottish taxpayer uses the UK basic rate band here, not the Scottish income tax bands. Each gain is the caller's: work it out per disposal first (for shares, `invest.section-104-pool`).

## Sources

Read on 2026-09-23:

- GOV.UK, "Capital Gains Tax rates and allowances" (AEA 2021/22 to 2026/27; rates by period including 6 April 2024 to 29 October 2024 and from 30 October 2024): https://www.gov.uk/guidance/capital-gains-tax-rates-and-allowances - HMRC Capital Gains Manual CG10246, "Capital Gains Tax: rates of tax - before 30 October 2024" (10%/20% and 18%/28% from 6 April 2016; basic rate band use): https://www.gov.uk/hmrc-internal-manuals/capital-gains-manual/cg10246 - The Capital Gains Tax (Annual Exempt Amount) Order 2020, SI 2020/333 (£12,300 for 2020/21): https://www.legislation.gov.uk/uksi/2020/333/made - CG21500, "Individuals: losses: assessment" (order of loss set-off; TCGA92/S1F most beneficial): https://www.gov.uk/hmrc-internal-manuals/capital-gains-manual/cg21500 - CG10150, "Partial re-write of TCGA 1992" (old s4B is now s1F and s1K): https://www.gov.uk/hmrc-internal-manuals/capital-gains-manual/cg10150 - GOV.UK, "Income Tax: Personal Allowance and basic rate limit from 2019-20" (£37,500 for 2019/20 and 2020/21): https://www.gov.uk/government/publications/income-tax-personal-allowance-and-basic-rate-limit-from-2019-to-2020/income-tax-personal-allowance-and-basic-rate-limit-from-2019-20 - GOV.UK, Budget 2021 OOTLAR Annex A (basic rate band £37,700 for 2021/22 to 2025/26): https://www.gov.uk/government/publications/budget-2021-overview-of-tax-legislation-and-rates-ootlar/annex-a-rates-and-allowances - GOV.UK, "Income Tax rates and allowances for current and previous tax years" (£37,700 for 2023/24 to 2026/27): https://www.gov.uk/government/publications/rates-and-allowances-income-tax/income-tax-rates-and-allowances-current-and-past

## What a reviewer should check

- The allocation order in steps 4 and 5, and the line rounding (down to the penny per rate; HMRC's return rounds gains to whole pounds). - That a zero gain is simply ignored and a loss of any kind offsets gains of any kind.

## Before you rely on this

**Not professional advice.** This capability calculates investment figures from published rules. It is a software component for developers, not financial advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a tax adviser review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified tax adviser has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

## Notices

Contains public sector information licensed under the Open Government Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).

Legislation: Crown copyright and database right.

1.0.1 marks it unreviewed and adds its attribution notices (NOTICE). The code and the tests are unchanged.

Files