glidepath 0.2.0__py3-none-any.whl

glidepath/core/comparison.py

@@ -0,0 +1,278 @@
+"""Scenario comparison report (roadmap 6.3; planning §4.3).
+
+Comparison is a per-period metrics report across scenarios, computed
+from each scenario's resolved run: :func:`run_scenarios` resolves every
+scenario against the base plan (raising on orphans) and projects each
+through the engine; :func:`compare_scenario_results` aligns the runs
+period by period — household-level totals via the reporting layer, in
+real (today's money) or nominal basis — and diffs every non-base run
+against the base.
+
+Rows cover the union of the runs' periods (a scenario overriding the
+planning-age assumption projects a different horizon); a run simply has
+no entry in a period it never modelled, and a delta appears only where
+the base modelled the period too — over the *same* interval: a
+horizon-clipped partial period (``year_fraction`` < 1) never diffs
+against a whole one. Metric amounts are presentation values (quantized,
+planning §4.6); deltas are exact differences of those.
+"""
+
+from dataclasses import dataclass, fields
+from operator import add, sub
+from typing import TYPE_CHECKING
+
+from glidepath.core.engine import run
+from glidepath.core.reporting import ReportBasis, build_report
+from glidepath.core.scenarios import ScenarioError, resolve_scenario
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+    from decimal import Decimal
+
+    from glidepath.core.config import RunConfig
+    from glidepath.core.entities import Household
+    from glidepath.core.money import Money
+    from glidepath.core.periods import Period
+    from glidepath.core.provenance import AssumptionSet
+    from glidepath.core.region import Region
+    from glidepath.core.reporting import PeriodReportRow
+    from glidepath.core.results import ProjectionResult
+    from glidepath.core.scenarios import Scenario
+
+BASE_RUN_NAME = "base"
+"""The reserved name of the unmodified base plan's run."""
+
+_MIN_RUNS = 2
+"""A comparison needs a baseline plus at least one other run."""
+
+
+@dataclass(frozen=True, slots=True)
+class PeriodMetrics:
+    """One run's household-level totals for one period (roadmap 6.3).
+
+    ``income_total`` is income in payment (employment, DB, state
+    pension, annuity); ``lump_sums`` the one-off tax-advantaged cash
+    (DB commutation, up-front pension lump sums, annuity-purchase
+    tax-free cash). The pension and annuity elements of ``lump_sums``
+    are column views of tax-free cash the wrappers already carry in
+    ``withdrawals_gross`` — only the DB commutation arrives from
+    outside the wrappers — so the two metrics overlap and must never
+    be summed. The rest carry the reporting layer's meanings.
+    Amounts follow the report's basis; a delta's amounts may be
+    negative.
+    """
+
+    closing_balance: Money
+    income_total: Money
+    lump_sums: Money
+    tax_due: Money
+    contributions: Money
+    withdrawals_gross: Money
+    net_withdrawn: Money
+    spending_need: Money
+    planned_outflows: Money
+    shortfall: Money
+
+    def _combined(
+        self, other: PeriodMetrics, combine: Callable[[Money, Money], Money]
+    ) -> PeriodMetrics:
+        """Apply ``combine`` field-wise, producing new metrics."""
+        combined = {
+            field.name: combine(getattr(self, field.name), getattr(other, field.name))
+            for field in fields(self)
+        }
+        return PeriodMetrics(**combined)
+
+    def __add__(self, other: PeriodMetrics) -> PeriodMetrics:
+        """Field-wise sum — totalling persons within a period."""
+        return self._combined(other, add)
+
+    def __sub__(self, other: PeriodMetrics) -> PeriodMetrics:
+        """Field-wise difference — a scenario's delta vs the base."""
+        return self._combined(other, sub)
+
+
+@dataclass(frozen=True, slots=True)
+class ScenarioPeriodEntry:
+    """One run's metrics in one period, with its delta vs the base.
+
+    ``year_fraction`` is the whole-month fraction of the period this
+    run actually modelled (planning §5.2) — less than 1 when ``today``
+    or the run's horizon fell mid-period. ``delta_vs_base`` is ``None``
+    on the base run's own entries, on a period the base run never
+    modelled, and on a period the two runs modelled over *different*
+    intervals (unequal year fractions): flows over half a year minus
+    flows over a whole year is not a meaningful delta.
+    """
+
+    run_name: str
+    metrics: PeriodMetrics
+    year_fraction: Decimal
+    delta_vs_base: PeriodMetrics | None
+
+
+@dataclass(frozen=True, slots=True)
+class ComparisonRow:
+    """One period's metrics across the runs that modelled it.
+
+    Entries appear in run order (base first); a run without this
+    period contributes no entry.
+    """
+
+    period: Period
+    entries: tuple[ScenarioPeriodEntry, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ScenarioComparison:
+    """The per-period metrics report across scenarios (planning §4.3)."""
+
+    basis: ReportBasis
+    run_names: tuple[str, ...]
+    rows: tuple[ComparisonRow, ...]
+
+
+def run_scenarios(
+    household: Household,
+    assumptions: AssumptionSet,
+    scenarios: Sequence[Scenario],
+    region_for: Callable[[AssumptionSet], Region],
+    config: RunConfig,
+) -> tuple[tuple[str, ProjectionResult], ...]:
+    """Project the base plan and every scenario's resolved inputs.
+
+    Returns named runs — the base first under :data:`BASE_RUN_NAME`,
+    then one per scenario in the given order — ready for
+    :func:`compare_scenario_results`.
+
+    ``region_for`` builds the region bundle for one run from that
+    run's *effective* assumption set. Regions derive data from
+    assumptions at build time (e.g. the UK future-years tax extension
+    and state pension uprating read ``policy.tax.future_years``,
+    ``inflation.cpi``, and ``policy.state_pension.uprating``), so a
+    prebuilt region shared across runs would silently pin every
+    scenario to the base policy and misreport the region data version;
+    the factory rebuilds it per resolved set instead. All runs share
+    ``config``: run settings are not scenario-overridable in v1.
+
+    Raises:
+        ScenarioError: If a scenario has orphaned overrides, a
+            mistyped override value, a duplicate name, or the
+            reserved base name.
+        EngineError: If any resolved plan is not projectable.
+    """
+    names = [scenario.name for scenario in scenarios]
+    if BASE_RUN_NAME in names or len(set(names)) != len(names):
+        msg = f"scenario names must be unique and none may be {BASE_RUN_NAME!r}"
+        raise ScenarioError(msg)
+    base_region = region_for(assumptions)
+    runs = [(BASE_RUN_NAME, run(household, assumptions, base_region, config))]
+    for scenario in scenarios:
+        resolution = resolve_scenario(household, assumptions, scenario)
+        runs.append(
+            (
+                scenario.name,
+                run(
+                    resolution.household,
+                    resolution.assumptions,
+                    region_for(resolution.assumptions),
+                    config,
+                ),
+            )
+        )
+    return tuple(runs)
+
+
+def compare_scenario_results(
+    runs: Sequence[tuple[str, ProjectionResult]],
+    basis: ReportBasis = ReportBasis.REAL,
+) -> ScenarioComparison:
+    """Diff named runs per period — the first run is the baseline.
+
+    Raises:
+        ValueError: If fewer than two runs are given or names repeat.
+    """
+    if len(runs) < _MIN_RUNS:
+        msg = "a scenario comparison needs at least two runs"
+        raise ValueError(msg)
+    names = [name for name, _ in runs]
+    if len(set(names)) != len(names):
+        msg = "scenario comparison run names must be unique"
+        raise ValueError(msg)
+    per_run = [(name, _totals_by_period(result, basis)) for name, result in runs]
+    base_totals = per_run[0][1]
+    periods = sorted({period for _, totals in per_run for period in totals})
+    rows = []
+    for period in periods:
+        entries = []
+        base_total = base_totals.get(period)
+        for index, (name, totals) in enumerate(per_run):
+            total = totals.get(period)
+            if total is None:
+                continue
+            delta = None
+            if (
+                index > 0
+                and base_total is not None
+                and total.year_fraction == base_total.year_fraction
+            ):
+                delta = total.metrics - base_total.metrics
+            entries.append(
+                ScenarioPeriodEntry(
+                    run_name=name,
+                    metrics=total.metrics,
+                    year_fraction=total.year_fraction,
+                    delta_vs_base=delta,
+                )
+            )
+        rows.append(ComparisonRow(period=period, entries=tuple(entries)))
+    return ScenarioComparison(basis=basis, run_names=tuple(names), rows=tuple(rows))
+
+
+@dataclass(frozen=True, slots=True)
+class _PeriodTotals:
+    """One run's household totals for one period, with its interval."""
+
+    metrics: PeriodMetrics
+    year_fraction: Decimal
+
+
+def _totals_by_period(
+    result: ProjectionResult, basis: ReportBasis
+) -> dict[Period, _PeriodTotals]:
+    """Household-level period totals of one run, in the report's basis.
+
+    Persons within a period sum; the period's ``year_fraction`` is the
+    snapshot's own (one snapshot per period, so persons share it).
+    """
+    totals: dict[Period, _PeriodTotals] = {}
+    for row in build_report(result, basis).rows:
+        metrics = _row_metrics(row)
+        existing = totals.get(row.period)
+        if existing is not None:
+            metrics = existing.metrics + metrics
+        totals[row.period] = _PeriodTotals(
+            metrics=metrics, year_fraction=row.year_fraction
+        )
+    return totals
+
+
+def _row_metrics(row: PeriodReportRow) -> PeriodMetrics:
+    """One person's report row reduced to the comparison metrics."""
+    return PeriodMetrics(
+        closing_balance=row.closing_balance,
+        income_total=(
+            row.employment_income
+            + row.db_income
+            + row.state_pension_income
+            + row.annuity_income
+        ),
+        lump_sums=row.db_lump_sum + row.pension_lump_sum + row.annuity_lump_sum,
+        tax_due=row.tax_due,
+        contributions=row.contributions,
+        withdrawals_gross=row.withdrawals_gross,
+        net_withdrawn=row.net_withdrawn,
+        spending_need=row.spending_need,
+        planned_outflows=row.planned_outflows,
+        shortfall=row.shortfall,
+    )

glidepath/core/config.py

@@ -0,0 +1,82 @@
+"""Run configuration for the projection engine (roadmap 4.1; planning §5.2).
+
+Kept apart from the engine so the result types can carry the run's
+configuration (part of the §4.6 run manifest) without an import cycle.
+"""
+
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import TYPE_CHECKING
+
+from glidepath.core.withdrawals import (
+    FixedRealWithdrawalStrategy,
+    TaxFreeCashStrategy,
+)
+
+if TYPE_CHECKING:
+    from datetime import date
+
+    from glidepath.core.withdrawals import WithdrawalStrategy
+
+_DEFAULT_STRATEGY = FixedRealWithdrawalStrategy()
+"""The v1 default withdrawal decision (planning §5.2): fixed real.
+
+A frozen, stateless instance, so sharing one default across configs is
+safe.
+"""
+
+
+class EngineError(ValueError):
+    """A projection request the engine cannot honour."""
+
+
+class RunMode(Enum):
+    """Projection mode (planning §5.2).
+
+    The same step function runs under both modes; only the return model
+    differs (planning §5.2). ``MONTE_CARLO`` draws stochastic returns
+    from the run's seed — one substream per path (roadmap 7.3).
+    """
+
+    DETERMINISTIC = auto()
+    MONTE_CARLO = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class RunConfig:
+    """One run's configuration (planning §5.2, §4.6).
+
+    ``today`` anchors the first period and defines "today's money" for
+    the reporting layer. ``horizon_end`` defaults to the date the (v1
+    single) person attains the ``horizon.planning_age`` assumption.
+    ``seed`` is recorded in provenance and seeds the stochastic return
+    model's substreams (roadmap 7.1/7.2); a ``MONTE_CARLO`` run
+    requires it, and ``path`` names the substream the run draws from —
+    the path runner (roadmap 7.3) projects path *i* under
+    ``replace(config, path=i)``, so any single path is re-runnable
+    from the seed and index alone (planning §4.6; a deterministic
+    model ignores the index). ``withdrawal_strategy`` is
+    the decumulation withdrawal decision (planning §5.2; roadmap 5.1),
+    defaulting to fixed real spending — it governs decumulation
+    periods only; planned outflows falling earlier are funded
+    net-defined in the default tax-aware order. ``tax_free_cash`` is
+    the orthogonal tax-free cash decision (roadmap 5.2), defaulting to
+    the split-each-payment mode.
+    """
+
+    today: date
+    horizon_end: date | None = None
+    mode: RunMode = RunMode.DETERMINISTIC
+    seed: int | None = None
+    path: int = 0
+    withdrawal_strategy: WithdrawalStrategy = _DEFAULT_STRATEGY
+    tax_free_cash: TaxFreeCashStrategy = TaxFreeCashStrategy.SPLIT_EACH_PAYMENT
+
+    def __post_init__(self) -> None:
+        """Reject a backwards horizon or a negative path index."""
+        if self.horizon_end is not None and self.horizon_end < self.today:
+            msg = f"horizon_end {self.horizon_end} precedes today {self.today}"
+            raise EngineError(msg)
+        if self.path < 0:
+            msg = f"path must be non-negative, got {self.path}"
+            raise EngineError(msg)

glidepath/core/contributions.py

@@ -0,0 +1,337 @@
+"""Contribution schedules and the relief-mechanics boundary (roadmap 3.2).
+
+A :class:`ContributionSchedule` records what a person has *chosen* to pay
+into one wrapper each year — the employee amount is a
+:class:`~glidepath.core.provenance.Decision` (a scenario-overridable
+choice, planning §4.3), the employer amount a
+:class:`~glidepath.core.provenance.Fact` (employment terms). How tax
+relief is delivered is the region's concern: the core defines the
+mechanics vocabulary (:class:`~glidepath.core.wrappers.ReliefMechanic`)
+and the outcome shape (:class:`MemberContributionOutcome`); a region's
+:class:`ContributionRuleset` turns a gross contribution into cash flows
+under its own relief rules and limits (planning §5.1).
+
+Amounts are *gross* annual contributions — the amount intended to land
+in the wrapper — so schedules are comparable across relief mechanics:
+under relief at source the member pays less cash and the provider tops
+the pot up to the gross amount, while under net pay the member's pay is
+reduced by the full gross amount before tax.
+"""
+
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import TYPE_CHECKING, Protocol
+
+from glidepath.core.money import Money
+
+if TYPE_CHECKING:
+    from datetime import date
+
+    from glidepath.core.entities import EntityId
+    from glidepath.core.periods import Period
+    from glidepath.core.provenance import AssumptionKey, Decision, Fact
+    from glidepath.core.wrappers import ReliefMechanic
+
+_ZERO = Money(Decimal(0))
+
+
+@dataclass(frozen=True, slots=True)
+class ContributionSchedule:
+    """One wrapper's planned annual contributions (planning §5.1).
+
+    ``employee_amount`` is the chosen *gross* annual contribution;
+    ``employer_amount`` is the employer's annual contribution under the
+    employment terms (pension wrappers only). ``relief_mechanic`` is
+    ``None`` for wrapper kinds whose contributions attract no relief
+    (the region's permitted-mechanics set is empty, e.g. an ISA).
+    ``escalation`` names the assumption the engine grows the amounts by
+    (e.g. the earnings-growth assumption); applying it is the engine
+    step's job (roadmap 4.1).
+    """
+
+    employee_amount: Decision[Money]
+    employer_amount: Fact[Money] | None = None
+    relief_mechanic: ReliefMechanic | None = None
+    escalation: AssumptionKey | None = None
+
+    def __post_init__(self) -> None:
+        """Reject negative contribution amounts."""
+        if self.employee_amount.value < _ZERO:
+            msg = "ContributionSchedule.employee_amount must be non-negative"
+            raise ValueError(msg)
+        if self.employer_amount is not None and self.employer_amount.value < _ZERO:
+            msg = "ContributionSchedule.employer_amount must be non-negative"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class MemberContributionRequest:
+    """One member contribution to resolve through a region's relief rules.
+
+    ``gross`` is the intended gross contribution to one wrapper;
+    ``relevant_earnings`` is the period's earned income the region's
+    relief limit measures against; ``date_of_birth`` lets the region
+    apply any relief age limits. Relief limits are per *person* per
+    period, shared across every wrapper and mechanic — so
+    ``already_relieved_gross`` must carry the gross member
+    contributions relief has already been granted on this period
+    (across all the person's wrappers); the region grants relief only
+    on the remaining headroom. ``mechanic`` is ``None`` when the
+    wrapper kind attracts no relief.
+    """
+
+    gross: Money
+    relevant_earnings: Money
+    date_of_birth: date
+    mechanic: ReliefMechanic | None = None
+    already_relieved_gross: Money = _ZERO
+
+    def __post_init__(self) -> None:
+        """Reject negative monetary inputs."""
+        amounts = (self.gross, self.relevant_earnings, self.already_relieved_gross)
+        if any(amount < _ZERO for amount in amounts):
+            msg = "MemberContributionRequest amounts must be non-negative"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class MemberContributionOutcome:
+    """One member contribution resolved through a region's relief rules.
+
+    ``gross_to_pot`` is what lands in the wrapper;
+    ``member_cash_cost`` is the cash the member pays (from taxed income
+    under relief at source, from gross pay under net pay);
+    ``provider_relief`` is the top-up the provider reclaims at source;
+    ``taxable_pay_deduction`` is the pre-tax pay reduction (net pay);
+    ``assessment_relief_gross`` is the gross amount the tax assessment
+    must grant further relief on (feeds
+    :attr:`~glidepath.core.tax.TaxInput.relief_at_source_contributions`);
+    ``unrelieved_excess`` is intended gross beyond the region's relief
+    limit — clipped and reported, never contributed or rerouted: a
+    schedule states intent for one wrapper, and a member's forgone
+    cash under a relief mechanic is not the gross amount (someone who
+    wants taxable saving schedules a GIA contribution directly).
+
+    The identity ``gross_to_pot == member_cash_cost + provider_relief``
+    is enforced, so any outcome that exists is internally consistent.
+    """
+
+    gross_to_pot: Money
+    member_cash_cost: Money
+    provider_relief: Money
+    taxable_pay_deduction: Money
+    assessment_relief_gross: Money
+    unrelieved_excess: Money
+
+    def __post_init__(self) -> None:
+        """Require non-negative amounts and the pot-cash-relief identity."""
+        amounts = (
+            self.gross_to_pot,
+            self.member_cash_cost,
+            self.provider_relief,
+            self.taxable_pay_deduction,
+            self.assessment_relief_gross,
+            self.unrelieved_excess,
+        )
+        if any(amount < _ZERO for amount in amounts):
+            msg = "MemberContributionOutcome amounts must be non-negative"
+            raise ValueError(msg)
+        if self.gross_to_pot != self.member_cash_cost + self.provider_relief:
+            msg = (
+                "MemberContributionOutcome.gross_to_pot must equal"
+                " member_cash_cost + provider_relief"
+            )
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class DbArrangementInput:
+    """One DB arrangement's annual entitlement over a measured year.
+
+    ``opening_annual`` is the accrued annual pension at the period's
+    open (before the year's accrual credit); ``closing_annual`` is the
+    entitlement at the period's close, the year's accrual and
+    revaluation included. How the pair values into a pension input
+    amount — valuation factor, inflation uplift, flooring — is wholly
+    the region's concern (planning §4.2).
+    """
+
+    opening_annual: Money
+    closing_annual: Money
+
+    def __post_init__(self) -> None:
+        """Reject negative entitlements."""
+        if self.opening_annual < _ZERO or self.closing_annual < _ZERO:
+            msg = "DbArrangementInput amounts must be non-negative"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class AnnualAllowanceMeasurement:
+    """One person's pension inputs and income for one period (§5.2 step 5).
+
+    The engine's region-agnostic record of everything a region needs
+    to measure a year's pension savings against its cross-pension
+    allowances (roadmap 3.3): ``member_money_purchase`` is the gross
+    member contribution landed in pension wrappers (provider relief
+    included), ``employer_money_purchase`` the employer contributions
+    alongside them, and ``db_arrangements`` the DB entitlements the
+    region values into pension input amounts. ``total_income`` is the
+    period's taxable income *before* any member pension deduction;
+    ``net_pay_contributions`` and ``relief_at_source_gross`` are the
+    member amounts each mechanic relieved, for the region's income
+    measures. ``cpi`` is the period's inflation rate (a region may
+    uprate DB opening values by it). ``mpaa_triggered_on`` is the
+    flexible-access trigger date *as it stood when the period's
+    contributions were made* — inputs paid before an in-period trigger
+    are measured pre-trigger (planning §5.2). ``scheme_member`` marks
+    membership of at least one pension arrangement this year, and
+    ``carry_forward`` is the unused-allowance pool prior years left,
+    earliest first.
+    """
+
+    member_money_purchase: Money
+    employer_money_purchase: Money
+    db_arrangements: tuple[DbArrangementInput, ...]
+    total_income: Money
+    net_pay_contributions: Money
+    relief_at_source_gross: Money
+    cpi: Decimal
+    mpaa_triggered_on: date | None
+    scheme_member: bool
+    carry_forward: tuple[Money, ...]
+
+    def __post_init__(self) -> None:
+        """Reject negative monetary inputs."""
+        amounts = (
+            self.member_money_purchase,
+            self.employer_money_purchase,
+            self.total_income,
+            self.net_pay_contributions,
+            self.relief_at_source_gross,
+            *self.carry_forward,
+        )
+        if any(amount < _ZERO for amount in amounts):
+            msg = "AnnualAllowanceMeasurement amounts must be non-negative"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class AnnualAllowanceOutcome:
+    """A region's annual-allowance answer for one period (roadmap 3.3).
+
+    ``chargeable_excess`` is the pension input beyond every allowance
+    the region operates — taper, money-purchase cap and carry-forward
+    already applied — for the tax assessment to charge at the region's
+    rates (:meth:`~glidepath.core.tax.TaxSystem.annual_allowance_charge`);
+    ``carry_forward`` is the pool rolled forward one year for the next
+    period's measurement. A region without such machinery returns a
+    zero excess and an empty pool.
+    """
+
+    chargeable_excess: Money
+    carry_forward: tuple[Money, ...]
+
+    def __post_init__(self) -> None:
+        """Reject negative amounts."""
+        if self.chargeable_excess < _ZERO or any(
+            amount < _ZERO for amount in self.carry_forward
+        ):
+            msg = "AnnualAllowanceOutcome amounts must be non-negative"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class SchemeInput:
+    """One pension wrapper's own input amount, for the funding split (#124).
+
+    ``input_amount`` is the wrapper's own money-purchase pension input
+    for the period — member gross (provider relief included) plus
+    employer. DB streams are not schemes here: they have no modelled
+    pot to debit, so a charge their input generates always takes the
+    cash route (planning §5.2).
+    """
+
+    wrapper_id: EntityId
+    input_amount: Money
+
+    def __post_init__(self) -> None:
+        """Reject a negative input amount."""
+        if self.input_amount < _ZERO:
+            msg = "SchemeInput.input_amount must be non-negative"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class SchemePayment:
+    """One scheme-funded debit of a period's priced AA charge (#124)."""
+
+    wrapper_id: EntityId
+    amount: Money
+
+    def __post_init__(self) -> None:
+        """Reject a negative payment."""
+        if self.amount < _ZERO:
+            msg = "SchemePayment.amount must be non-negative"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class AnnualAllowanceFunding:
+    """How a period's priced AA charge is funded (planning §5.2, #124).
+
+    ``scheme_payments`` are debits against pension wrappers (the UK's
+    Scheme Pays — a scheme-administrator payment, not a member
+    withdrawal); ``cash`` falls to the person's bare taxable accounts
+    at period close, alongside the portfolio-income tax charge. The
+    split covers the whole charge; what a drained wrapper cannot fund
+    joins the person's shortfall (planning §5.2).
+    """
+
+    scheme_payments: tuple[SchemePayment, ...]
+    cash: Money
+
+    def __post_init__(self) -> None:
+        """Reject a negative cash share."""
+        if self.cash < _ZERO:
+            msg = "AnnualAllowanceFunding.cash must be non-negative"
+            raise ValueError(msg)
+
+
+class ContributionRuleset(Protocol):
+    """Region-supplied contribution relief mechanics (planning §4.2).
+
+    Resolves one member contribution for one period under the region's
+    relief rules — gross-up at source, pre-tax deduction, and the
+    region's member relief limits. Which mechanics a wrapper kind may
+    operate is the wrapper ruleset's call
+    (:meth:`~glidepath.core.wrappers.WrapperRuleset.permitted_relief_mechanics`).
+    Cross-wrapper contribution measures — the pension annual allowance,
+    its taper, and any money-purchase cap — are the per-period
+    :meth:`annual_allowance` measurement (roadmap 3.3).
+    """
+
+    def member_contribution(
+        self, request: MemberContributionRequest, period: Period
+    ) -> MemberContributionOutcome:
+        """Resolve one gross member contribution for ``period``."""
+        ...
+
+    def annual_allowance(
+        self, measurement: AnnualAllowanceMeasurement, period: Period
+    ) -> AnnualAllowanceOutcome:
+        """Measure a period's pension inputs against the region's allowances."""
+        ...
+
+    def annual_allowance_funding(
+        self, charge: Money, schemes: tuple[SchemeInput, ...], period: Period
+    ) -> AnnualAllowanceFunding:
+        """Split a period's priced AA charge between scheme pays and cash.
+
+        ``charge`` is the priced charge the tax system appended to the
+        period's assessment; ``schemes`` are the person's pension
+        wrappers with their own input amounts. A region without
+        scheme-funded payment returns the whole charge as cash
+        (planning §5.2, #124).
+        """
+        ...