glidepath 0.2.0__py3-none-any.whl

glidepath/persistence/values.py

@@ -0,0 +1,298 @@
+"""Tagged JSON encoding for polymorphic values (roadmap 6.2; planning §4.5).
+
+Entity fields decode by field context — the schema knows a balance is
+``Money`` — but assumption values and scenario override values are
+polymorphic: an override may hold an ``int`` retirement age, a
+``Decimal`` fraction, a ``Money`` amount, a rule tag, a structured
+table, or an annuity product enum. A closed tag vocabulary keeps the
+exact runtime type through the JSON round trip: ``Decimal`` and
+``Money`` travel as strings (never JSON floats — money is ``Decimal``,
+planning §4.6), tables as tagged objects, and enums as their stable
+tokens.
+
+This module also holds the primitive parsers and the enum token tables
+the entity codecs share.
+"""
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import date, datetime
+from decimal import Decimal, InvalidOperation
+from enum import Enum
+from types import MappingProxyType
+
+from glidepath.core import (
+    AnnuityBasis,
+    AnnuityType,
+    LifeStage,
+    Money,
+    ReliefMechanic,
+    RevaluationReference,
+    Sex,
+)
+from glidepath.persistence.document import PersistenceError
+
+_KIND = "kind"
+_VALUE = "value"
+
+_KIND_INT = "int"
+_KIND_TEXT = "text"
+_KIND_DECIMAL = "decimal"
+_KIND_MONEY = "money"
+_KIND_TABLE = "table"
+_KIND_ANNUITY_TYPE = "annuity_type"
+_KIND_ANNUITY_BASIS = "annuity_basis"
+
+
+@dataclass(frozen=True, slots=True)
+class EnumTokens[E: Enum]:
+    """A bidirectional stable-token map for one enum (planning §4.5).
+
+    Tokens are persisted, so they must never change meaning; retire a
+    token by adding a new one, exactly like assumption keys.
+    """
+
+    by_member: Mapping[E, str]
+
+    def token(self, member: E) -> str:
+        """The stable token written for ``member``."""
+        return self.by_member[member]
+
+    def member(self, raw: object, path: str) -> E:
+        """The member a stored token names.
+
+        Raises:
+            PersistenceError: If ``raw`` is not one of the tokens.
+        """
+        for member, token in self.by_member.items():
+            if token == raw:
+                return member
+        known = ", ".join(sorted(self.by_member.values()))
+        msg = f"{path}: unknown token {raw!r} (one of: {known})"
+        raise PersistenceError(msg)
+
+
+SEX_TOKENS = EnumTokens({Sex.FEMALE: "female", Sex.MALE: "male"})
+RELIEF_MECHANIC_TOKENS = EnumTokens(
+    {
+        ReliefMechanic.RELIEF_AT_SOURCE: "relief_at_source",
+        ReliefMechanic.NET_PAY: "net_pay",
+    }
+)
+REVALUATION_REFERENCE_TOKENS = EnumTokens(
+    {
+        RevaluationReference.CPI: "cpi",
+        RevaluationReference.FIXED: "fixed",
+        RevaluationReference.NONE: "none",
+    }
+)
+ANNUITY_TYPE_TOKENS = EnumTokens(
+    {
+        AnnuityType.LEVEL: "level",
+        AnnuityType.ESCALATING: "escalating",
+        AnnuityType.INFLATION_LINKED: "inflation_linked",
+    }
+)
+ANNUITY_BASIS_TOKENS = EnumTokens(
+    {AnnuityBasis.SINGLE: "single", AnnuityBasis.JOINT: "joint"}
+)
+LIFE_STAGE_TOKENS = EnumTokens(
+    {
+        LifeStage.EARLY_ACCUMULATION: "early_accumulation",
+        LifeStage.MID_ACCUMULATION: "mid_accumulation",
+        LifeStage.PRE_RETIREMENT: "pre_retirement",
+        LifeStage.DECUMULATION: "decumulation",
+        LifeStage.GO_GO: "go_go",
+        LifeStage.SLOW_GO: "slow_go",
+        LifeStage.NO_GO: "no_go",
+    }
+)
+
+
+def parse_decimal(raw: object, path: str) -> Decimal:
+    """Parse a stored ``Decimal`` string, exactly and finitely.
+
+    Raises:
+        PersistenceError: If ``raw`` is not a string holding a finite
+            decimal number.
+    """
+    if not isinstance(raw, str):
+        msg = f"{path}: expected a decimal string, got {type(raw).__name__}"
+        raise PersistenceError(msg)
+    try:
+        value = Decimal(raw)
+    except InvalidOperation:
+        msg = f"{path}: not a decimal number: {raw!r}"
+        raise PersistenceError(msg) from None
+    if not value.is_finite():
+        msg = f"{path}: decimal values must be finite, got {raw!r}"
+        raise PersistenceError(msg)
+    return value
+
+
+def parse_int(raw: object, path: str) -> int:
+    """Parse a stored whole number (``bool`` rejected, as ever).
+
+    Raises:
+        PersistenceError: If ``raw`` is not an integer.
+    """
+    if isinstance(raw, bool) or not isinstance(raw, int):
+        msg = f"{path}: expected a whole number, got {type(raw).__name__}"
+        raise PersistenceError(msg)
+    return raw
+
+
+def parse_str(raw: object, path: str) -> str:
+    """Parse a stored string.
+
+    Raises:
+        PersistenceError: If ``raw`` is not a string.
+    """
+    if not isinstance(raw, str):
+        msg = f"{path}: expected a string, got {type(raw).__name__}"
+        raise PersistenceError(msg)
+    return raw
+
+
+def parse_date(raw: object, path: str) -> date:
+    """Parse a stored ISO-8601 calendar date.
+
+    Raises:
+        PersistenceError: If ``raw`` is not an ISO-8601 date string.
+    """
+    text = parse_str(raw, path)
+    try:
+        return date.fromisoformat(text)
+    except ValueError:
+        msg = f"{path}: not an ISO-8601 date: {text!r}"
+        raise PersistenceError(msg) from None
+
+
+def parse_datetime(raw: object, path: str) -> datetime:
+    """Parse a stored ISO-8601 timezone-aware datetime.
+
+    Raises:
+        PersistenceError: If ``raw`` is not an ISO-8601 datetime string
+            carrying a UTC offset.
+    """
+    text = parse_str(raw, path)
+    try:
+        moment = datetime.fromisoformat(text)
+    except ValueError:
+        msg = f"{path}: not an ISO-8601 datetime: {text!r}"
+        raise PersistenceError(msg) from None
+    if moment.tzinfo is None or moment.tzinfo.utcoffset(moment) is None:
+        msg = f"{path}: datetimes must be timezone-aware, got {text!r}"
+        raise PersistenceError(msg)
+    return moment
+
+
+def parse_money(raw: object, path: str) -> Money:
+    """Parse a stored monetary amount (a ``Decimal`` string).
+
+    Raises:
+        PersistenceError: If ``raw`` is not a finite decimal string.
+    """
+    return Money(parse_decimal(raw, path))
+
+
+def encode_value(value: object, path: str) -> dict[str, object]:
+    """Encode one polymorphic value as a tagged JSON object.
+
+    Raises:
+        PersistenceError: If the value's type is outside the closed
+            vocabulary, or a table key is not a string.
+    """
+    kind, payload = _tagged(value, path)
+    return {_KIND: kind, _VALUE: payload}
+
+
+def _tagged(value: object, path: str) -> tuple[str, object]:
+    """The tag and JSON payload for one value."""
+    if isinstance(value, bool):
+        msg = f"{path}: booleans are not a persisted value type"
+        raise PersistenceError(msg)
+    scalar = _tagged_scalar(value, path)
+    if scalar is not None:
+        return scalar
+    if isinstance(value, AnnuityType):
+        return (_KIND_ANNUITY_TYPE, ANNUITY_TYPE_TOKENS.token(value))
+    if isinstance(value, AnnuityBasis):
+        return (_KIND_ANNUITY_BASIS, ANNUITY_BASIS_TOKENS.token(value))
+    if isinstance(value, Mapping):
+        return (_KIND_TABLE, _encode_table(value, path))
+    msg = f"{path}: cannot persist a value of type {type(value).__name__}"
+    raise PersistenceError(msg)
+
+
+def _tagged_scalar(value: object, path: str) -> tuple[str, object] | None:
+    """The tag and payload for a scalar value; ``None`` for non-scalars.
+
+    A non-finite ``Decimal`` is rejected here so the writer never
+    produces a file :func:`parse_decimal` would refuse on reload
+    (``Money`` enforces finiteness at construction already).
+
+    Raises:
+        PersistenceError: If a ``Decimal`` value is not finite.
+    """
+    if isinstance(value, int):
+        return (_KIND_INT, value)
+    if isinstance(value, str):
+        return (_KIND_TEXT, value)
+    if isinstance(value, Decimal):
+        if not value.is_finite():
+            msg = f"{path}: decimal values must be finite, got {value!r}"
+            raise PersistenceError(msg)
+        return (_KIND_DECIMAL, str(value))
+    if isinstance(value, Money):
+        return (_KIND_MONEY, str(value.amount))
+    return None
+
+
+def _encode_table(value: Mapping[object, object], path: str) -> dict[str, object]:
+    """Encode a structured table value, entry by entry."""
+    table: dict[str, object] = {}
+    for key, entry in value.items():
+        if not isinstance(key, str):
+            msg = f"{path}: table keys must be strings, got {type(key).__name__}"
+            raise PersistenceError(msg)
+        table[key] = encode_value(entry, f"{path}.{key}")
+    return table
+
+
+def _decode_table(raw: object, path: str) -> dict[str, object]:
+    """Decode a tagged table's entries back to a plain dictionary."""
+    if not isinstance(raw, dict):
+        msg = f"{path}: expected a table object, got {type(raw).__name__}"
+        raise PersistenceError(msg)
+    return {key: decode_value(entry, f"{path}.{key}") for key, entry in raw.items()}
+
+
+_DECODERS: Mapping[str, Callable[[object, str], object]] = MappingProxyType(
+    {
+        _KIND_INT: parse_int,
+        _KIND_TEXT: parse_str,
+        _KIND_DECIMAL: parse_decimal,
+        _KIND_MONEY: parse_money,
+        _KIND_ANNUITY_TYPE: ANNUITY_TYPE_TOKENS.member,
+        _KIND_ANNUITY_BASIS: ANNUITY_BASIS_TOKENS.member,
+        _KIND_TABLE: _decode_table,
+    }
+)
+
+
+def decode_value(raw: object, path: str) -> object:
+    """Decode one tagged JSON object back to its exact runtime type.
+
+    Raises:
+        PersistenceError: If the tag shape or kind is not recognised.
+    """
+    if not isinstance(raw, dict) or set(raw) != {_KIND, _VALUE}:
+        msg = f"{path}: expected a tagged value object with keys 'kind' and 'value'"
+        raise PersistenceError(msg)
+    kind = raw[_KIND]
+    decoder = _DECODERS.get(kind) if isinstance(kind, str) else None
+    if decoder is None:
+        msg = f"{path}: unknown value kind {kind!r}"
+        raise PersistenceError(msg)
+    return decoder(raw[_VALUE], path)

glidepath/regions/__init__.py

@@ -0,0 +1,7 @@
+"""Region packages implementing the core boundary protocols (planning §4.2).
+
+Everything country-specific — tax rules, wrappers, state pension, age
+rules — lives under this package. The dependency direction is region →
+core only: the core never imports region code (guard-tested), and no
+policy figure appears outside a region's ``data/`` TOML files.
+"""

glidepath/regions/uk/__init__.py

@@ -0,0 +1,189 @@
+"""UK region package (planning §4.2, §5.3).
+
+Implements the core boundary protocols for the UK. Every UK policy
+figure — tax bands, allowances, state pension rates, age rules — is
+loaded from the TOML data files under ``data/`` (each carrying
+``verified_on`` + ``sources``), never hardcoded; a guard test enforces
+this. Shipped default assumptions mirror planning §7 and are kept in
+sync by a doc-sync test.
+"""
+
+from glidepath.regions.uk.ages import UkAgeError, UkAgeRules
+from glidepath.regions.uk.contributions import (
+    AnnualAllowanceAssessment,
+    CarryForwardOutcome,
+    UkContributionError,
+    UkContributionRuleset,
+    adjusted_income,
+    apply_carry_forward,
+    assess_annual_allowance,
+    carry_forward_generated,
+    db_pension_input_amount,
+    is_mpaa_active,
+    roll_carry_forward,
+    tapered_annual_allowance,
+    threshold_income,
+)
+from glidepath.regions.uk.extension import (
+    FutureYearsExtension,
+    FutureYearsMode,
+    FutureYearsPolicy,
+    ScottishBandsPolicy,
+    extend_tax_year,
+)
+from glidepath.regions.uk.loader import (
+    AGE_RULES_FILENAME,
+    ASSUMPTIONS_FILENAME,
+    RETURNS_HISTORY_FILENAME,
+    available_tax_years,
+    data_file_digest,
+    load_age_rules,
+    load_default_assumptions,
+    load_returns_history,
+    load_tax_year,
+    parse_age_rules,
+    parse_default_assumptions,
+    parse_returns_history,
+    parse_tax_year,
+    tax_year_filename,
+)
+from glidepath.regions.uk.region import (
+    default_assumption_set,
+    future_years_extension,
+    uk_region,
+)
+from glidepath.regions.uk.schema import (
+    SCHEMA_VERSION,
+    AgeRulesFile,
+    AssumptionDefault,
+    AssumptionsFile,
+    AssumptionValue,
+    DataFileError,
+    DividendRate,
+    DividendRules,
+    FileMeta,
+    IncomeTaxSchedule,
+    IsaRules,
+    LisaAges,
+    NmpaStep,
+    PensionRules,
+    ReturnsHistoryFile,
+    SavingsRules,
+    SpaAgeBand,
+    SpaBand,
+    SpaDateBand,
+    StatePensionDeferral,
+    TaxBand,
+    TaxYearFile,
+    TaxYearMeta,
+)
+from glidepath.regions.uk.state_pension import (
+    UkStatePensionError,
+    UkStatePensionScheme,
+)
+from glidepath.regions.uk.tax import (
+    DIVIDEND_NIL_RATE_BAND,
+    RUK_RESIDENCY,
+    SAVINGS_NIL_RATE_BAND,
+    SAVINGS_STARTING_RATE_BAND,
+    SCOTLAND_RESIDENCY,
+    UkTaxError,
+    UkTaxSystem,
+)
+from glidepath.regions.uk.wrappers import (
+    CASH_KIND,
+    GIA_KIND,
+    ISA_ALLOWANCE_GROUP,
+    ISA_KIND,
+    LISA_ALLOWANCE_GROUP,
+    LISA_KIND,
+    SIPP_KIND,
+    WORKPLACE_DC_KIND,
+    UkWrapperError,
+    UkWrapperRuleset,
+)
+from glidepath.regions.uk.years import TaxYearSeries, UkTaxYearError
+
+__all__ = [
+    "AGE_RULES_FILENAME",
+    "ASSUMPTIONS_FILENAME",
+    "CASH_KIND",
+    "DIVIDEND_NIL_RATE_BAND",
+    "GIA_KIND",
+    "ISA_ALLOWANCE_GROUP",
+    "ISA_KIND",
+    "LISA_ALLOWANCE_GROUP",
+    "LISA_KIND",
+    "RETURNS_HISTORY_FILENAME",
+    "RUK_RESIDENCY",
+    "SAVINGS_NIL_RATE_BAND",
+    "SAVINGS_STARTING_RATE_BAND",
+    "SCHEMA_VERSION",
+    "SCOTLAND_RESIDENCY",
+    "SIPP_KIND",
+    "WORKPLACE_DC_KIND",
+    "AgeRulesFile",
+    "AnnualAllowanceAssessment",
+    "AssumptionDefault",
+    "AssumptionValue",
+    "AssumptionsFile",
+    "CarryForwardOutcome",
+    "DataFileError",
+    "DividendRate",
+    "DividendRules",
+    "FileMeta",
+    "FutureYearsExtension",
+    "FutureYearsMode",
+    "FutureYearsPolicy",
+    "IncomeTaxSchedule",
+    "IsaRules",
+    "LisaAges",
+    "NmpaStep",
+    "PensionRules",
+    "ReturnsHistoryFile",
+    "SavingsRules",
+    "ScottishBandsPolicy",
+    "SpaAgeBand",
+    "SpaBand",
+    "SpaDateBand",
+    "StatePensionDeferral",
+    "TaxBand",
+    "TaxYearFile",
+    "TaxYearMeta",
+    "TaxYearSeries",
+    "UkAgeError",
+    "UkAgeRules",
+    "UkContributionError",
+    "UkContributionRuleset",
+    "UkStatePensionError",
+    "UkStatePensionScheme",
+    "UkTaxError",
+    "UkTaxSystem",
+    "UkTaxYearError",
+    "UkWrapperError",
+    "UkWrapperRuleset",
+    "adjusted_income",
+    "apply_carry_forward",
+    "assess_annual_allowance",
+    "available_tax_years",
+    "carry_forward_generated",
+    "data_file_digest",
+    "db_pension_input_amount",
+    "default_assumption_set",
+    "extend_tax_year",
+    "future_years_extension",
+    "is_mpaa_active",
+    "load_age_rules",
+    "load_default_assumptions",
+    "load_returns_history",
+    "load_tax_year",
+    "parse_age_rules",
+    "parse_default_assumptions",
+    "parse_returns_history",
+    "parse_tax_year",
+    "roll_carry_forward",
+    "tapered_annual_allowance",
+    "tax_year_filename",
+    "threshold_income",
+    "uk_region",
+]

glidepath/regions/uk/ages.py

@@ -0,0 +1,156 @@
+"""UK age rules (roadmap 2.4; planning §4.1, §4.2, §6).
+
+Implements the core :class:`~glidepath.core.AgeRules` protocol plus the
+UK-only LISA age gates. Every figure — the SPA timetable, the NMPA
+schedule, the LISA ages — comes from ``age_rules.toml`` (§5.3); nothing
+is hardcoded here (guard-tested).
+
+The three §4.1 conventions appear as three shapes here:
+
+- **Access gates** (NMPA, LISA access at 60) are booleans per period,
+  open only if the age is attained on or before the period's first day.
+- **Income entitlements** (SPA) are exact dates for the core to
+  pro-rate.
+- **Eligibility windows** (LISA opening 18-39, contributions to 50) are
+  exact date spans — never rounded to periods in either direction; the
+  consumer (the wrapper ruleset, roadmap 3.1/9.2) intersects them with
+  the period and pro-rates any flow by whole months.
+
+The NMPA schedule is effective-dated, and the age in force is read on
+the period's first day. Around a legislated step-up this correctly
+denies *new* access to the caught cohort — old enough under the
+outgoing age but not the incoming one — until they attain the new age;
+benefits already in payment are never re-gated (planning §5.1).
+Protected pension ages are out of scope for v1 (§6).
+"""
+
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import TYPE_CHECKING
+
+from glidepath.core import (
+    Period,
+    add_months,
+    date_age_attained,
+    is_age_attained_by_period_start,
+)
+from glidepath.regions.uk.loader import load_age_rules
+from glidepath.regions.uk.schema import SpaAgeBand
+
+if TYPE_CHECKING:
+    from datetime import date
+
+    from glidepath.regions.uk.schema import AgeRulesFile, SpaBand
+
+
+class UkAgeError(ValueError):
+    """An age query the shipped UK data cannot answer."""
+
+
+@dataclass(frozen=True, slots=True)
+class UkAgeRules:
+    """UK implementation of the core ``AgeRules`` protocol.
+
+    Holds one validated :class:`AgeRulesFile`; every answer is a pure
+    function of that file and the query.
+    """
+
+    rules: AgeRulesFile
+
+    @classmethod
+    def from_shipped_data(cls) -> UkAgeRules:
+        """Build the rules over the shipped ``age_rules.toml``."""
+        return cls(rules=load_age_rules())
+
+    def state_pension_date(self, date_of_birth: date) -> date:
+        """The exact date this date of birth reaches state pension age.
+
+        Age-based timetable bands add whole years then whole months to
+        the (leap-day-deemed) birthday, clamping to the target month's
+        end; date-based bands reach SPA on their legislated date.
+
+        Raises:
+            UkAgeError: If the date of birth predates the timetable's
+                coverage (earlier cohorts had phased, pre-2016-system
+                SPAs this forward-looking planner does not model).
+        """
+        band = self._spa_band_for(date_of_birth)
+        if isinstance(band, SpaAgeBand):
+            return add_months(date_age_attained(date_of_birth, band.years), band.months)
+        return band.reaches_on
+
+    def _spa_band_for(self, date_of_birth: date) -> SpaBand:
+        """The SPA timetable band containing ``date_of_birth``."""
+        bands = self.rules.spa_bands
+        first_covered = bands[0].dob_from
+        if first_covered is not None and date_of_birth < first_covered:
+            msg = (
+                f"date of birth {date_of_birth} predates SPA timetable"
+                f" coverage (which starts {first_covered})"
+            )
+            raise UkAgeError(msg)
+        *bounded, open_ended = bands
+        for band in bounded:
+            if band.dob_to is not None and date_of_birth <= band.dob_to:
+                return band
+        return open_ended
+
+    def normal_minimum_pension_age(self, on: date) -> int:
+        """The normal minimum pension age in force on ``on``."""
+        baseline, *dated = self.rules.nmpa
+        age = baseline.age
+        for step in dated:
+            if step.effective_from is not None and step.effective_from <= on:
+                age = step.age
+        return age
+
+    def is_pension_access_open(self, date_of_birth: date, period: Period) -> bool:
+        """Whether new pension access is open for ``period`` (§4.1).
+
+        The NMPA in force on the period's first day must be attained on
+        or before that day. Only *new* crystallisations are gated here;
+        benefits already in payment continue regardless (planning §5.1).
+        """
+        age = self.normal_minimum_pension_age(period.start)
+        return is_age_attained_by_period_start(date_of_birth, age, period)
+
+    def lisa_opening_window(self, date_of_birth: date) -> Period:
+        """The exact dates a LISA may be opened (§4.1 eligibility window).
+
+        Runs from the opening birthday to the day before the birthday
+        after the last eligible age. Consumers intersect this with the
+        engine period; a mid-period opening birthday makes the rest of
+        that period eligible.
+        """
+        lisa = self.rules.lisa
+        return _age_window(date_of_birth, lisa.open_age_min, lisa.open_age_max + 1)
+
+    def lisa_contribution_window(self, date_of_birth: date) -> Period:
+        """The exact dates LISA contributions may be made (§4.1 window).
+
+        The age window only — holding an open LISA is the wrapper's
+        concern (roadmap 9.2). It runs from the opening birthday (a
+        contributor must be old enough to hold an account) to the eve
+        of the closing birthday; contribution flows crossing either
+        edge are pro-rated by the consumer like other partial years.
+        """
+        lisa = self.rules.lisa
+        return _age_window(date_of_birth, lisa.open_age_min, lisa.contribute_until_age)
+
+    def is_lisa_access_open(self, date_of_birth: date, period: Period) -> bool:
+        """Whether charge-free LISA access is open for ``period`` (§4.1 gate).
+
+        The age gate only; the other charge-free events (first home,
+        terminal illness, death) are out of scope for v1 (§6).
+        """
+        return is_age_attained_by_period_start(
+            date_of_birth, self.rules.lisa.access_age, period
+        )
+
+
+def _age_window(date_of_birth: date, opens_at: int, closes_at: int) -> Period:
+    """The inclusive span from one birthday to the eve of a later one."""
+    return Period(
+        start=date_age_attained(date_of_birth, opens_at),
+        end=date_age_attained(date_of_birth, closes_at) - timedelta(days=1),
+    )