glidepath 0.2.0__py3-none-any.whl

glidepath/core/pensions.py

@@ -0,0 +1,298 @@
+"""Defined-benefit pension entitlements (roadmap 4.2, 9.6; planning §5.1).
+
+Models deferred/accrued DB entitlements plus CARE-style active
+membership (:class:`DBActiveMembership`, roadmap 9.6). Every scheme
+parameter (accrued pension, normal pension age, revaluation basis,
+early/late factors, commutation factor, accrual rate, pensionable
+salary) is a user-entered fact: schemes vary too much to ship as data
+(planning §5.1), so scheme facts drive results and nothing here is ever
+guessed — taking benefits at an age the factor table does not cover is
+a construction-time error, not a default.
+
+Modelling conventions (documented in planning §5.1/§5.2):
+
+- The scheme's one :class:`RevaluationBasis` applies both to
+  revaluation in deferment and to increases in payment; splitting the
+  two bases is a deferred extension (planning §2).
+- Revaluation compounds per engine period from the statement date; the
+  span before the run's ``today`` is not modelled period-by-period, so
+  the engine folds it into a starting factor via
+  :func:`revaluation_factor_for_months` — whole years compound with an
+  integer exponent and the remaining whole months scale the annual
+  rate linearly, both exact ``Decimal`` arithmetic (planning §4.6).
+- Commutation trades pension for a lump sum at the stated factor, at
+  the moment benefits start.
+- Active accrual credits ``accrual_rate x pensionable_salary`` per year
+  of service on top of the revalued entitlement, service ending at the
+  earliest of the leave-and-defer age, the benefits start, and the
+  engine's retirement gate (planning §5.1); final-salary linkage and
+  member DB contributions are not modelled (planning §2).
+"""
+
+from dataclasses import dataclass
+from decimal import Decimal
+from enum import Enum, auto
+from typing import TYPE_CHECKING
+
+from glidepath.core.money import Money
+from glidepath.core.periods import date_age_attained
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from datetime import date
+
+    from glidepath.core.entities import EntityId
+    from glidepath.core.money import Rate
+    from glidepath.core.provenance import Decision, Fact
+
+_ZERO = Decimal(0)
+_ONE = Decimal(1)
+_ZERO_MONEY = Money(_ZERO)
+_MONTHS_PER_YEAR = 12
+
+
+class RevaluationReference(Enum):
+    """What a DB scheme's revaluation and increases track (planning §5.1)."""
+
+    CPI = auto()
+    """Tracks the run's CPI path, optionally capped (e.g. CPI max 5%)."""
+    FIXED = auto()
+    """A fixed annual rate, whatever inflation does."""
+    NONE = auto()
+    """No revaluation: the pension is frozen in nominal terms."""
+
+
+@dataclass(frozen=True, slots=True)
+class RevaluationBasis:
+    """How a DB entitlement revalues — a scheme fact (planning §5.1).
+
+    The same basis governs deferment revaluation and increases in
+    payment in v1 (module docstring).
+    """
+
+    reference: RevaluationReference
+    cap: Rate | None = None
+    """Annual cap on CPI-linked revaluation (CPI reference only)."""
+    fixed_rate: Rate | None = None
+    """The annual rate of a ``FIXED`` basis (required exactly then)."""
+
+    def __post_init__(self) -> None:
+        """Require the fields the reference uses, and only those."""
+        requires_fixed = self.reference is RevaluationReference.FIXED
+        if (self.fixed_rate is not None) != requires_fixed:
+            msg = "RevaluationBasis.fixed_rate is required exactly for FIXED"
+            raise ValueError(msg)
+        if self.cap is not None and self.reference is not RevaluationReference.CPI:
+            msg = "RevaluationBasis.cap applies only to a CPI reference"
+            raise ValueError(msg)
+        if self.cap is not None and self.cap.value < _ZERO:
+            msg = "RevaluationBasis.cap must be non-negative"
+            raise ValueError(msg)
+
+    def annual_rate(self, cpi: Decimal) -> Decimal:
+        """The basis's revaluation rate in a year whose CPI is ``cpi``.
+
+        CPI-linked revaluation is floored at zero (statutory revaluation
+        never reduces the entitlement) and capped when the scheme caps
+        it; a fixed rate ignores CPI entirely.
+        """
+        if self.reference is RevaluationReference.CPI:
+            rate = max(cpi, _ZERO)
+            if self.cap is not None:
+                rate = min(rate, self.cap.value)
+            return rate
+        if self.fixed_rate is not None:  # FIXED, by the __post_init__ invariant
+            return self.fixed_rate.value
+        return _ZERO
+
+
+@dataclass(frozen=True, slots=True)
+class FactorTable:
+    """Early/late retirement factors — scheme facts, user-entered (§5.1).
+
+    Maps the whole-year age benefits are taken at to the multiplier the
+    scheme applies to the revalued pension (e.g. ``{58: Decimal("0.80")}``
+    for a 20% early-retirement reduction at 58). Taking at the normal
+    pension age needs no entry (factor 1); taking at any other age not
+    in the table is rejected at :class:`DBPension` construction — scheme
+    facts drive results, the model never guesses a factor.
+    """
+
+    factors: Mapping[int, Decimal]
+
+    def __post_init__(self) -> None:
+        """Require positive ages and positive factors."""
+        for age, factor in self.factors.items():
+            if age <= 0:
+                msg = "FactorTable ages must be positive"
+                raise ValueError(msg)
+            if factor <= _ZERO:
+                msg = "FactorTable factors must be positive"
+                raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class DBActiveMembership:
+    """CARE-style active membership of a DB scheme (planning §5.1, 9.6).
+
+    ``accrual_rate`` is the fraction of pensionable salary earned as
+    annual pension per year of service (a 1/60th scheme enters e.g.
+    ``0.0166667``); ``pensionable_salary`` is the annual pensionable
+    salary — often below total pay — escalated by the earnings-growth
+    assumption within the run like employment income.
+    """
+
+    accrual_rate: Fact[Decimal]
+    pensionable_salary: Fact[Money]
+    active_until_age: Decision[int] | None = None
+    """The age service ends with the pension left deferred; ``None``
+    means service continues until benefits start (module docstring —
+    the engine's retirement gate applies either way)."""
+
+    def __post_init__(self) -> None:
+        """Reject impossible scheme facts and choices."""
+        if not _ZERO < self.accrual_rate.value <= _ONE:
+            msg = "DBActiveMembership.accrual_rate must lie in (0, 1]"
+            raise ValueError(msg)
+        if self.pensionable_salary.value < _ZERO_MONEY:
+            msg = "DBActiveMembership.pensionable_salary must be non-negative"
+            raise ValueError(msg)
+        if self.active_until_age is not None and self.active_until_age.value <= 0:
+            msg = "DBActiveMembership.active_until_age must be positive"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class DBPension:
+    """One DB entitlement — deferred, or active via ``active_membership``.
+
+    ``accrued_annual_pension`` is the annual pension at the statement
+    (or leaving) date; ``commuted_fraction`` is the user's decision to
+    trade that fraction of the pension for a lump sum of
+    ``pension given up x commutation_factor`` when benefits start
+    (planning §5.1).
+    """
+
+    id: EntityId
+    accrued_annual_pension: Fact[Money]
+    statement_date: date
+    normal_pension_age: Fact[int]
+    revaluation_basis: RevaluationBasis
+    early_late_factors: FactorTable
+    commuted_fraction: Decision[Decimal]
+    commutation_factor: Fact[Decimal] | None = None
+    """Pounds of lump sum per pound of annual pension given up."""
+    taken_at_age: Decision[int] | None = None
+    """The age benefits start; ``None`` means the normal pension age."""
+    active_membership: DBActiveMembership | None = None
+    """Active CARE-style accrual; ``None`` means deferred (roadmap 9.6)."""
+
+    def __post_init__(self) -> None:
+        """Reject inconsistent scheme facts and choices loudly.
+
+        Everything checkable without a run date is checked here, so an
+        instance that exists is projectable: the engine never has to
+        guess a factor or a commutation basis mid-run.
+        """
+        if self.accrued_annual_pension.value < _ZERO_MONEY:
+            msg = "DBPension.accrued_annual_pension must be non-negative"
+            raise ValueError(msg)
+        if self.normal_pension_age.value <= 0:
+            msg = "DBPension.normal_pension_age must be positive"
+            raise ValueError(msg)
+        fraction = self.commuted_fraction.value
+        if not _ZERO <= fraction <= _ONE:
+            msg = "DBPension.commuted_fraction must lie between 0 and 1"
+            raise ValueError(msg)
+        if fraction > _ZERO:
+            if self.commutation_factor is None:
+                msg = "DBPension.commutation_factor is required to commute pension"
+                raise ValueError(msg)
+            if self.commutation_factor.value <= _ZERO:
+                msg = "DBPension.commutation_factor must be positive"
+                raise ValueError(msg)
+        taken = db_taken_age(self)
+        if taken <= 0:
+            msg = "DBPension.taken_at_age must be positive"
+            raise ValueError(msg)
+        if taken != self.normal_pension_age.value and taken not in (
+            self.early_late_factors.factors
+        ):
+            msg = (
+                f"DBPension.early_late_factors has no factor for age {taken};"
+                " scheme facts drive results (planning §5.1)"
+            )
+            raise ValueError(msg)
+        membership = self.active_membership
+        if (
+            membership is not None
+            and membership.active_until_age is not None
+            and membership.active_until_age.value > taken
+        ):
+            msg = (
+                "DBPension.active_membership.active_until_age must not"
+                " exceed the age benefits are taken (planning §5.1)"
+            )
+            raise ValueError(msg)
+
+
+def db_taken_age(pension: DBPension) -> int:
+    """The age benefits start: the taken-at decision, else the NPA."""
+    if pension.taken_at_age is not None:
+        return pension.taken_at_age.value
+    return pension.normal_pension_age.value
+
+
+def db_start_date(pension: DBPension, date_of_birth: date) -> date:
+    """The exact date benefits start (an income entitlement, §4.1)."""
+    return date_age_attained(date_of_birth, db_taken_age(pension))
+
+
+def db_service_end_date(pension: DBPension, date_of_birth: date) -> date:
+    """The date active service ends: leave-and-defer age, else benefits.
+
+    Meaningful only for a pension with an ``active_membership``; the
+    engine's retirement gate (planning §5.1) may stop accrual earlier
+    still. The construction-time invariant keeps this at or before
+    :func:`db_start_date`.
+    """
+    membership = pension.active_membership
+    if membership is not None and membership.active_until_age is not None:
+        return date_age_attained(date_of_birth, membership.active_until_age.value)
+    return db_start_date(pension, date_of_birth)
+
+
+def db_early_late_factor(pension: DBPension) -> Decimal:
+    """The scheme factor applied to the revalued pension at start.
+
+    Taking at the normal pension age defaults to a factor of 1 unless
+    the table states otherwise; every other age has a table entry
+    (enforced at construction).
+    """
+    taken = db_taken_age(pension)
+    factor = pension.early_late_factors.factors.get(taken)
+    if factor is not None:
+        return factor
+    return _ONE
+
+
+def revaluation_factor_for_months(annual_rate: Decimal, months: int) -> Decimal:
+    """Cumulative revaluation over ``months`` whole months at one rate.
+
+    Whole years compound with an integer exponent; the remaining months
+    scale the annual rate linearly — the §4.1/§5.2 whole-month
+    convention in exact ``Decimal`` arithmetic (planning §4.6 rejects
+    fractional-exponent powers). Used for the span before the run's
+    ``today``, which the engine never models period-by-period.
+
+    Raises:
+        ValueError: If ``months`` is negative.
+    """
+    if months < 0:
+        msg = "months must be non-negative"
+        raise ValueError(msg)
+    years, remainder = divmod(months, _MONTHS_PER_YEAR)
+    factor = (_ONE + annual_rate) ** years
+    return factor * (
+        _ONE + annual_rate * Decimal(remainder) / Decimal(_MONTHS_PER_YEAR)
+    )

glidepath/core/periods.py

@@ -0,0 +1,367 @@
+"""Periods, fiscal calendars, and the age/pro-rating conventions.
+
+Implements planning §4.1: the engine steps annually over *periods*
+supplied by a region's :class:`FiscalCalendar` (the core never knows what
+"6 April" is). Age-triggered changes follow one convention, tested at
+boundaries:
+
+- **Access gates** are open for a period only if the age is attained on or
+  before the period's first day (:func:`is_age_attained_by_period_start`).
+- **Income entitlements** begin at their exact date and are pro-rated by
+  whole months within their starting period (:func:`prorata_fraction`).
+"""
+
+import calendar
+from dataclasses import dataclass
+from datetime import date, timedelta
+from decimal import Decimal
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+_FEB_29 = (2, 29)
+_NON_LEAP_YEAR = 2001  # any non-leap year; used to validate calendar anchors
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class Period:
+    """A consecutive span of days, inclusive of both endpoints."""
+
+    start: date
+    end: date
+
+    def __post_init__(self) -> None:
+        """Reject periods that end before they start."""
+        if self.end < self.start:
+            msg = f"Period end {self.end} precedes start {self.start}"
+            raise ValueError(msg)
+
+    def contains(self, day: date) -> bool:
+        """Whether ``day`` falls within this period."""
+        return self.start <= day <= self.end
+
+
+class FiscalCalendar(Protocol):
+    """Region-supplied period scheme (planning §4.1, §4.2).
+
+    The UK region implements this with tax years (6 Apr to 5 Apr); the
+    core only ever sees opaque :class:`Period` values.
+    """
+
+    def period_containing(self, day: date) -> Period:
+        """Return the period that contains ``day``."""
+        ...
+
+    def periods(self, first: date, last: date) -> Iterator[Period]:
+        """Yield consecutive periods covering ``first`` through ``last``."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class AnnualCalendar:
+    """Generic annual calendar: each period runs one year from an anchor.
+
+    The default anchor is 1 January. The anchor must be a day that exists
+    in every year, so 29 February is rejected.
+    """
+
+    anchor_month: int = 1
+    anchor_day: int = 1
+
+    def __post_init__(self) -> None:
+        """Reject anchors that do not exist in every year."""
+        try:
+            date(_NON_LEAP_YEAR, self.anchor_month, self.anchor_day)
+        except ValueError as exc:
+            anchor = f"{self.anchor_month:02d}-{self.anchor_day:02d}"
+            msg = f"anchor {anchor} must be a valid day in every year (no 29 February)"
+            raise ValueError(msg) from exc
+
+    def _anchor_in_year(self, year: int) -> date:
+        """The period start date falling in calendar ``year``."""
+        return date(year, self.anchor_month, self.anchor_day)
+
+    def period_containing(self, day: date) -> Period:
+        """Return the annual period that contains ``day``."""
+        start_year = day.year if day >= self._anchor_in_year(day.year) else day.year - 1
+        start = self._anchor_in_year(start_year)
+        return Period(start, self._anchor_in_year(start_year + 1) - timedelta(days=1))
+
+    def periods(self, first: date, last: date) -> Iterator[Period]:
+        """Yield consecutive annual periods covering ``first`` to ``last``.
+
+        Raises:
+            ValueError: If ``last`` precedes ``first``.
+        """
+        if last < first:
+            msg = f"horizon end {last} precedes start {first}"
+            raise ValueError(msg)
+        current = self.period_containing(first)
+        while current.start <= last:
+            yield current
+            current = self.period_containing(current.end + timedelta(days=1))
+
+
+def birthday_in_year(date_of_birth: date, year: int) -> date:
+    """The date the birthday falls (or is deemed to fall) in ``year``.
+
+    A 29 February birthday is deemed to fall on 1 March in non-leap years,
+    matching the UK legal convention for attaining an age.
+    """
+    if (date_of_birth.month, date_of_birth.day) == _FEB_29 and not calendar.isleap(
+        year
+    ):
+        return date(year, 3, 1)
+    return date(year, date_of_birth.month, date_of_birth.day)
+
+
+def date_age_attained(date_of_birth: date, age: int) -> date:
+    """The exact date on which the person attains ``age`` whole years.
+
+    Raises:
+        ValueError: If ``age`` is negative.
+    """
+    if age < 0:
+        msg = "age must be non-negative"
+        raise ValueError(msg)
+    return birthday_in_year(date_of_birth, date_of_birth.year + age)
+
+
+def age_on(date_of_birth: date, day: date) -> int:
+    """Whole years of age on ``day``.
+
+    Raises:
+        ValueError: If ``day`` precedes the date of birth.
+    """
+    if day < date_of_birth:
+        msg = f"day {day} precedes date of birth {date_of_birth}"
+        raise ValueError(msg)
+    years = day.year - date_of_birth.year
+    if day < birthday_in_year(date_of_birth, day.year):
+        years -= 1
+    return years
+
+
+def is_age_attained_by_period_start(
+    date_of_birth: date, age: int, period: Period
+) -> bool:
+    """The access-gate convention of planning §4.1.
+
+    A gate (NMPA, LISA access, ...) is open for a period only if ``age``
+    is attained on or before the period's first day — conservative, so the
+    model never simulates a withdrawal that would be unauthorised in
+    reality. A birthday on the period's last day unlocks the *next*
+    period, never the current one.
+    """
+    return date_age_attained(date_of_birth, age) <= period.start
+
+
+def add_months(day: date, months: int) -> date:
+    """Shift ``day`` by calendar months, clamping to the target month's end.
+
+    ``add_months(date(2026, 1, 31), 1)`` is 28 February 2026.
+    """
+    total = day.month - 1 + months
+    year = day.year + total // 12
+    month = total % 12 + 1
+    last_day = calendar.monthrange(year, month)[1]
+    return date(year, month, min(day.day, last_day))
+
+
+def whole_months_between(start: date, end_exclusive: date) -> int:
+    """Complete calendar months from ``start`` up to ``end_exclusive``.
+
+    The count is the largest ``n`` such that ``add_months(start, n)`` does
+    not pass ``end_exclusive`` (day-clamped month arithmetic).
+
+    Raises:
+        ValueError: If ``end_exclusive`` precedes ``start``.
+    """
+    if end_exclusive < start:
+        msg = f"end {end_exclusive} precedes start {start}"
+        raise ValueError(msg)
+    months = (end_exclusive.year - start.year) * 12 + (
+        end_exclusive.month - start.month
+    )
+    while months > 0 and add_months(start, months) > end_exclusive:
+        months -= 1
+    return max(months, 0)
+
+
+def _whole_months_in(period: Period) -> int:
+    """Whole months in ``period``, which pro-rating divides by.
+
+    Raises:
+        ValueError: If ``period`` is shorter than one whole month.
+    """
+    months = whole_months_between(period.start, period.end + timedelta(days=1))
+    if months == 0:
+        msg = "period is shorter than one whole month; cannot pro-rate"
+        raise ValueError(msg)
+    return months
+
+
+def prorata_fraction(entitlement_start: date, period: Period) -> Decimal:
+    """Fraction of ``period`` an entitlement starting mid-period is paid for.
+
+    Implements the income-entitlement convention of planning §4.1: incomes
+    (state pension from SPA, DB from NPA, annuity start) begin at their
+    exact date and are pro-rated by whole months within their starting
+    period, as an exact ``Decimal`` fraction.
+
+    Returns:
+        ``1`` if the entitlement started on or before the period began,
+        ``0`` if it starts after the period ends, otherwise
+        ``whole months in payment / whole months in the period``.
+
+    Raises:
+        ValueError: If ``period`` is shorter than one whole month.
+    """
+    if entitlement_start <= period.start:
+        return Decimal(1)
+    if entitlement_start > period.end:
+        return Decimal(0)
+    months_in_period = _whole_months_in(period)
+    end_exclusive = period.end + timedelta(days=1)
+    months_in_payment = whole_months_between(entitlement_start, end_exclusive)
+    return Decimal(months_in_payment) / Decimal(months_in_period)
+
+
+def entitlement_active_fraction(
+    entitlement_start: date,
+    period: Period,
+    window_start: date,
+    window_end: date,
+) -> Decimal:
+    """Fraction of ``period`` an entitlement is in payment inside the window.
+
+    Combines the two §4.1/§5.2 conventions for income entitlements (DB
+    from its start date, state pension from SPA plus deferral): payment
+    runs from ``entitlement_start`` and the run models only
+    ``[window_start, window_end]`` (roadmap 4.6), so the period's
+    payable share is the whole months of the overlap over the whole
+    months of the period. With the window covering the period this is
+    exactly :func:`prorata_fraction`; with the entitlement predating the
+    window it is exactly :func:`period_active_fraction`.
+
+    Returns:
+        ``1`` if payment covers the whole period inside the window,
+        ``0`` if the overlap is under one whole month, otherwise the
+        exact ``Decimal`` month ratio.
+
+    Raises:
+        ValueError: If ``window_end`` precedes ``window_start``, or the
+            period is shorter than one whole month.
+    """
+    if window_end < window_start:
+        msg = f"window end {window_end} precedes window start {window_start}"
+        raise ValueError(msg)
+    payable_start = max(entitlement_start, window_start, period.start)
+    payable_end = min(window_end, period.end)
+    if payable_end < payable_start:
+        return Decimal(0)
+    if payable_start == period.start and payable_end == period.end:
+        return Decimal(1)
+    months_in_period = _whole_months_in(period)
+    end_exclusive = payable_end + timedelta(days=1)
+    months_payable = whole_months_between(payable_start, end_exclusive)
+    return Decimal(months_payable) / Decimal(months_in_period)
+
+
+def service_active_fraction(
+    service_end: date,
+    period: Period,
+    window_start: date,
+    window_end: date,
+) -> Decimal:
+    """Fraction of ``period`` inside the window before ``service_end``.
+
+    The mirror of :func:`entitlement_active_fraction` for a span that
+    *ends* on an exact date — active DB service stopping at the
+    leave-and-defer age or the benefits start (roadmap 9.6, planning
+    §5.1). ``service_end`` is exclusive: service through the day before
+    the birthday counts, the birthday itself does not.
+
+    Returns:
+        ``1`` if service covers the whole period inside the window,
+        ``0`` if the overlap is under one whole month, otherwise the
+        exact ``Decimal`` month ratio.
+
+    Raises:
+        ValueError: If ``window_end`` precedes ``window_start``, or the
+            period is shorter than one whole month.
+    """
+    if window_end < window_start:
+        msg = f"window end {window_end} precedes window start {window_start}"
+        raise ValueError(msg)
+    active_start = max(window_start, period.start)
+    active_end_exclusive = min(
+        service_end, min(window_end, period.end) + timedelta(days=1)
+    )
+    if active_end_exclusive <= active_start:
+        return Decimal(0)
+    if active_start == period.start and active_end_exclusive == period.end + timedelta(
+        days=1
+    ):
+        return Decimal(1)
+    months_in_period = _whole_months_in(period)
+    months_active = whole_months_between(active_start, active_end_exclusive)
+    return Decimal(months_active) / Decimal(months_in_period)
+
+
+def period_active_fraction(
+    period: Period, window_start: date, window_end: date
+) -> Decimal:
+    """Fraction of ``period`` inside the run window, by whole months.
+
+    Implements the partial first/last period convention (planning §5.2,
+    roadmap 4.6): the engine models only the window from ``window_start``
+    (the run's ``today``) through ``window_end`` (the horizon end), both
+    inclusive. A period partly outside that window is scaled by
+    ``whole months inside the window / whole months in the period`` —
+    the same §4.1 whole-month convention as other partial years. For a
+    window open at the end, this agrees with :func:`prorata_fraction`.
+
+    Returns:
+        ``1`` if the period lies wholly inside the window, ``0`` if less
+        than one whole month of it does, otherwise the exact ``Decimal``
+        month ratio.
+
+    Raises:
+        ValueError: If ``window_end`` precedes ``window_start``, or the
+            period is shorter than one whole month.
+    """
+    if window_end < window_start:
+        msg = f"window end {window_end} precedes window start {window_start}"
+        raise ValueError(msg)
+    if window_start <= period.start and window_end >= period.end:
+        return Decimal(1)
+    active_start = max(window_start, period.start)
+    active_end_exclusive = min(window_end, period.end) + timedelta(days=1)
+    if active_end_exclusive <= active_start:
+        return Decimal(0)
+    months_in_period = _whole_months_in(period)
+    months_active = whole_months_between(active_start, active_end_exclusive)
+    return Decimal(months_active) / Decimal(months_in_period)
+
+
+class AgeRules(Protocol):
+    """Region-supplied age rules (planning §4.1, §4.2).
+
+    Turns a date of birth into the exact dates and period gates behind
+    age-triggered changes: state pension entitlement is an *income
+    entitlement* (begins at its exact date, pro-rated via
+    :func:`prorata_fraction`) while private pension access is an
+    *access gate* (following :func:`is_age_attained_by_period_start`).
+    Wrapper-specific age gates (e.g. UK LISA ages) stay behind the
+    region's wrapper rules rather than crossing the boundary here.
+    """
+
+    def state_pension_date(self, date_of_birth: date) -> date:
+        """The exact date state pension entitlement begins."""
+        ...
+
+    def is_pension_access_open(self, date_of_birth: date, period: Period) -> bool:
+        """Whether new pension benefits may be accessed in ``period``."""
+        ...