glidepath 0.2.0__py3-none-any.whl

glidepath/persistence/document.py

@@ -0,0 +1,101 @@
+"""The ``.glidepath.json`` plan document model (roadmap 6.2; planning §4.5).
+
+One JSON document per plan holds everything the user owns: the household
+(facts and decisions), the scenarios over it, and the user's assumption
+*overrides* — never resolved assumption values. Shipped defaults
+re-resolve on every load against the region data the app carries, and
+the document records the region data version it was last resolved
+against so a default change surfaces visibly instead of silently
+re-pricing the plan (planning §4.5).
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+    from glidepath.core import AssumptionKey, Household, Scenario
+
+SCHEMA_VERSION = 4
+"""The schema version this build reads and writes (planning §4.5).
+
+v2 (roadmap 9.6): every DB pension carries an ``active_membership``
+key — ``null`` for a deferred entitlement.
+
+v3 (#97): the state pension record loses the qualifying-years
+derivation fields (``ni_record_start``, ``qualifying_years``,
+``planned_extra_years``) — the official DWP forecast is the only
+route to an amount.
+
+v4 (#129): the spending plan loses the accumulation-stage multiplier
+keys (``early_accumulation``, ``mid_accumulation``,
+``pre_retirement``) — spending is modelled only in retirement, so
+they never bound (#114 retired the tokens without a migration).
+"""
+
+
+class PersistenceError(ValueError):
+    """A plan document that cannot be encoded, decoded, or resolved."""
+
+
+@dataclass(frozen=True, slots=True)
+class AssumptionOverride:
+    """One stored user override of a shipped default (planning §4.5).
+
+    Only the override is persisted — the effective assumption is rebuilt
+    on load from the current shipped default plus this record, carrying
+    ``USER_OVERRIDE`` provenance. ``source`` is the user's stated basis
+    for departing from the default; ``recorded_on`` is when they did.
+    """
+
+    key: AssumptionKey
+    value: Any
+    source: str
+    recorded_on: datetime
+
+    def __post_init__(self) -> None:
+        """Reject an empty source and a naive timestamp."""
+        if not self.source:
+            msg = "AssumptionOverride.source must be non-empty"
+            raise ValueError(msg)
+        moment = self.recorded_on
+        if moment.tzinfo is None or moment.tzinfo.utcoffset(moment) is None:
+            msg = "AssumptionOverride.recorded_on must be timezone-aware"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class PlanDocument:
+    """Everything one ``.glidepath.json`` file stores (planning §4.5).
+
+    ``region`` names the region module whose shipped data the plan
+    resolves against (e.g. ``"uk"``); ``assumptions_resolved_against``
+    is that region's data content version at the last resolution, so a
+    later load against newer data can tell the user their defaults
+    moved. The schema version is a wire-format detail stamped by the
+    writer, not part of the in-memory model.
+    """
+
+    region: str
+    assumptions_resolved_against: str
+    household: Household
+    assumption_overrides: tuple[AssumptionOverride, ...] = ()
+    scenarios: tuple[Scenario, ...] = ()
+
+    def __post_init__(self) -> None:
+        """Reject empty identifiers and ambiguous duplicates."""
+        if not self.region:
+            msg = "PlanDocument.region must be non-empty"
+            raise ValueError(msg)
+        if not self.assumptions_resolved_against:
+            msg = "PlanDocument.assumptions_resolved_against must be non-empty"
+            raise ValueError(msg)
+        keys = [override.key for override in self.assumption_overrides]
+        if len(set(keys)) != len(keys):
+            msg = "PlanDocument.assumption_overrides must target distinct keys"
+            raise ValueError(msg)
+        names = [scenario.name for scenario in self.scenarios]
+        if len(set(names)) != len(names):
+            msg = "PlanDocument.scenarios must have distinct names"
+            raise ValueError(msg)

glidepath/persistence/encode.py

@@ -0,0 +1,433 @@
+"""Canonical writer for ``.glidepath.json`` (roadmap 6.2; planning §4.5).
+
+Deterministic output for clean diffs: ``schema_version`` stamped in,
+keys sorted, 2-space indent, LF line endings, ``Decimal`` as strings,
+ISO-8601 timezone-aware datetimes. A given document always serializes
+to the same bytes and a load→save round trip is byte-stable; value
+representations are preserved exactly (a ``Decimal`` keeps the
+exponent the user stated, a datetime its offset), so two values that
+compare equal but were written differently keep their distinct
+spellings. Only the user's assumption *overrides* are written;
+defaults re-resolve on load against shipped region data.
+
+The writer never produces a file the reader rejects: everything the
+strict reader refuses that the domain model does not already rule out
+(non-finite decimals, booleans in whole-number fields, empty entity
+ids) is rejected here too.
+"""
+
+import contextlib
+import json
+from typing import TYPE_CHECKING
+
+from glidepath.core import (
+    AssumptionTarget,
+    ContributionSchedule,
+    DBPension,
+    Household,
+    Person,
+    PlannedOutflow,
+    Scenario,
+    SpendingPlan,
+    StatePensionRecord,
+    Wrapper,
+)
+from glidepath.persistence.document import (
+    SCHEMA_VERSION,
+    PersistenceError,
+    PlanDocument,
+)
+from glidepath.persistence.values import (
+    ANNUITY_BASIS_TOKENS,
+    ANNUITY_TYPE_TOKENS,
+    LIFE_STAGE_TOKENS,
+    RELIEF_MECHANIC_TOKENS,
+    REVALUATION_REFERENCE_TOKENS,
+    SEX_TOKENS,
+    encode_value,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+    from datetime import date
+    from decimal import Decimal
+    from pathlib import Path
+
+    from glidepath.core import (
+        AnnuityPurchase,
+        AssetAllocation,
+        DBActiveMembership,
+        Decision,
+        EntityId,
+        Fact,
+        FeeSchedule,
+        GlidePathConfig,
+        LifeStage,
+        Money,
+        Override,
+        RevaluationBasis,
+        Sex,
+    )
+    from glidepath.persistence.document import AssumptionOverride
+
+
+def dumps_plan(document: PlanDocument) -> str:
+    """The document as canonical ``.glidepath.json`` text (planning §4.5).
+
+    Raises:
+        PersistenceError: If an override value's type is outside the
+            persistable vocabulary.
+    """
+    payload = _document_payload(document)
+    return json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+
+
+def save_plan(document: PlanDocument, path: Path) -> None:
+    """Write the document to ``path`` in canonical form.
+
+    Serialization completes before any file is opened, so a document
+    that cannot be encoded never touches the disk; the text is then
+    written to a sibling temporary file and moved over ``path`` only
+    once the write has closed cleanly, so a mid-write failure (disk
+    full, power loss) can never truncate the last saved plan.
+    ``newline=""`` disables platform newline translation so the file
+    carries LF endings on every platform (planning §4.5).
+    """
+    text = dumps_plan(document)
+    temp = path.with_name(path.name + ".tmp")
+    try:
+        with temp.open("w", encoding="utf-8", newline="") as handle:
+            handle.write(text)
+        temp.replace(path)
+    finally:
+        with contextlib.suppress(OSError):
+            temp.unlink(missing_ok=True)
+
+
+def _document_payload(document: PlanDocument) -> dict[str, object]:
+    """The whole document as a JSON-ready payload."""
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "region": document.region,
+        "assumptions_resolved_against": document.assumptions_resolved_against,
+        "household": _household(document.household),
+        "assumption_overrides": [
+            _assumption_override(override, f"assumption_overrides[{index}]")
+            for index, override in enumerate(document.assumption_overrides)
+        ],
+        "scenarios": [
+            _scenario(scenario, f"scenarios[{index}]")
+            for index, scenario in enumerate(document.scenarios)
+        ],
+    }
+
+
+def _assumption_override(override: AssumptionOverride, path: str) -> dict[str, object]:
+    """One stored assumption override."""
+    return {
+        "key": override.key.value,
+        "recorded_on": override.recorded_on.isoformat(),
+        "source": override.source,
+        "value": encode_value(override.value, f"{path}.value"),
+    }
+
+
+def _scenario(scenario: Scenario, path: str) -> dict[str, object]:
+    """One named what-if with its override deltas."""
+    return {
+        "name": scenario.name,
+        "note": scenario.note,
+        "overrides": [
+            _override(override, f"{path}.overrides[{index}]")
+            for index, override in enumerate(scenario.overrides)
+        ],
+    }
+
+
+def _override(override: Override, path: str) -> dict[str, object]:
+    """One scenario override: its target and replacement value."""
+    target = override.target
+    if isinstance(target, AssumptionTarget):
+        target_payload: dict[str, object] = {
+            "kind": "assumption",
+            "key": target.key.value,
+        }
+    else:
+        target_payload = {
+            "kind": "decision",
+            "entity_id": _entity_id(target.entity_id),
+            "field_path": target.field_path,
+        }
+    return {
+        "note": override.note,
+        "target": target_payload,
+        "value": encode_value(override.value, f"{path}.value"),
+    }
+
+
+def _household(household: Household) -> dict[str, object]:
+    """The household: persons plus shared economics."""
+    return {
+        "persons": [_person(person) for person in household.persons],
+        "planned_outflows": [
+            _planned_outflow(outflow) for outflow in household.planned_outflows
+        ],
+        "spending": _optional(household.spending, _spending_plan),
+    }
+
+
+def _person(person: Person) -> dict[str, object]:
+    """One person and everything that hangs off them."""
+    return {
+        "id": _entity_id(person.id),
+        "date_of_birth": _fact(person.date_of_birth, _date_value),
+        "target_retirement_age": _decision(person.target_retirement_age, _int_value),
+        "tax_residency": str(person.tax_residency),
+        "sex_for_longevity": _optional_fact(person.sex_for_longevity, _sex_value),
+        "employment_income": _optional_fact(person.employment_income, _money_value),
+        "mpaa_triggered_on": _optional_fact(person.mpaa_triggered_on, _date_value),
+        "lsa_used": _optional_fact(person.lsa_used, _money_value),
+        "wrappers": [_wrapper(wrapper) for wrapper in person.wrappers],
+        "db_pensions": [_db_pension(pension) for pension in person.db_pensions],
+        "annuity_purchases": [
+            _annuity_purchase(purchase) for purchase in person.annuity_purchases
+        ],
+        "state_pension": _optional(person.state_pension, _state_pension),
+        "glide_path": _optional(person.glide_path, _glide_path),
+    }
+
+
+def _wrapper(wrapper: Wrapper) -> dict[str, object]:
+    """One account, of an opaque region-defined kind."""
+    return {
+        "id": _entity_id(wrapper.id),
+        "kind": str(wrapper.kind),
+        "balance": _fact(wrapper.balance, _money_value),
+        "crystallised_balance": _optional_fact(
+            wrapper.crystallised_balance, _money_value
+        ),
+        "contributions": _optional(wrapper.contributions, _contribution_schedule),
+        "allocation": _optional(wrapper.allocation, _allocation),
+        "fees": _optional(wrapper.fees, _fee_schedule),
+    }
+
+
+def _contribution_schedule(schedule: ContributionSchedule) -> dict[str, object]:
+    """One wrapper's planned annual contributions."""
+    mechanic = schedule.relief_mechanic
+    escalation = schedule.escalation
+    return {
+        "employee_amount": _decision(schedule.employee_amount, _money_value),
+        "employer_amount": _optional_fact(schedule.employer_amount, _money_value),
+        "relief_mechanic": (
+            None if mechanic is None else RELIEF_MECHANIC_TOKENS.token(mechanic)
+        ),
+        "escalation": None if escalation is None else escalation.value,
+    }
+
+
+def _allocation(allocation: AssetAllocation) -> dict[str, object]:
+    """Portfolio weights over the three priced asset classes."""
+    return {
+        "equity": str(allocation.equity),
+        "bonds": str(allocation.bonds),
+        "cash": str(allocation.cash),
+    }
+
+
+def _fee_schedule(fees: FeeSchedule) -> dict[str, object]:
+    """One wrapper's annual percentage fees."""
+    return {"platform": str(fees.platform.value), "fund": str(fees.fund.value)}
+
+
+def _db_pension(pension: DBPension) -> dict[str, object]:
+    """One DB entitlement's scheme facts and choices."""
+    return {
+        "id": _entity_id(pension.id),
+        "accrued_annual_pension": _fact(pension.accrued_annual_pension, _money_value),
+        "statement_date": pension.statement_date.isoformat(),
+        "normal_pension_age": _fact(pension.normal_pension_age, _int_value),
+        "revaluation_basis": _revaluation_basis(pension.revaluation_basis),
+        "early_late_factors": _factor_table(pension.early_late_factors.factors),
+        "commuted_fraction": _decision(pension.commuted_fraction, _decimal_value),
+        "commutation_factor": _optional_fact(
+            pension.commutation_factor, _decimal_value
+        ),
+        "taken_at_age": _optional_decision(pension.taken_at_age, _int_value),
+        "active_membership": _optional(pension.active_membership, _active_membership),
+    }
+
+
+def _active_membership(membership: DBActiveMembership) -> dict[str, object]:
+    """Active CARE-style accrual on a DB entitlement (roadmap 9.6)."""
+    return {
+        "accrual_rate": _fact(membership.accrual_rate, _decimal_value),
+        "pensionable_salary": _fact(membership.pensionable_salary, _money_value),
+        "active_until_age": _optional_decision(membership.active_until_age, _int_value),
+    }
+
+
+def _revaluation_basis(basis: RevaluationBasis) -> dict[str, object]:
+    """How a DB entitlement revalues."""
+    return {
+        "reference": REVALUATION_REFERENCE_TOKENS.token(basis.reference),
+        "cap": None if basis.cap is None else str(basis.cap.value),
+        "fixed_rate": None if basis.fixed_rate is None else str(basis.fixed_rate.value),
+    }
+
+
+def _factor_table(factors: Mapping[int, Decimal]) -> dict[str, str]:
+    """A whole-year-age → factor table, ages as JSON object keys."""
+    return {str(age): str(factor) for age, factor in factors.items()}
+
+
+def _annuity_purchase(purchase: AnnuityPurchase) -> dict[str, object]:
+    """One planned annuity purchase — wholly a decision record."""
+    return {
+        "id": _entity_id(purchase.id),
+        "at_age": _decision(purchase.at_age, _int_value),
+        "fraction_of_pot": _decision(purchase.fraction_of_pot, _decimal_value),
+        "annuity_type": ANNUITY_TYPE_TOKENS.token(purchase.annuity_type),
+        "basis": ANNUITY_BASIS_TOKENS.token(purchase.basis),
+    }
+
+
+def _state_pension(record: StatePensionRecord) -> dict[str, object]:
+    """One person's state pension position."""
+    return {
+        "forecast_weekly_amount": _optional_fact(
+            record.forecast_weekly_amount, _money_value
+        ),
+        "protected_payment": _optional_fact(record.protected_payment, _money_value),
+        "deferral_years": _decision(record.deferral_years, _decimal_value),
+    }
+
+
+def _glide_path(config: GlidePathConfig) -> dict[str, object]:
+    """A person's own glide path: the factor-table knots in order."""
+    return {
+        "points": [
+            {
+                "years_to_retirement": _int_value(point.years_to_retirement),
+                "allocation": _allocation(point.allocation),
+            }
+            for point in config.points
+        ]
+    }
+
+
+def _spending_plan(spending: SpendingPlan) -> dict[str, object]:
+    """The household's retirement spending need."""
+    multipliers = spending.stage_multipliers
+    return {
+        "annual_spending_real": _fact(spending.annual_spending_real, _money_value),
+        "stage_multipliers": (
+            None if multipliers is None else _stage_multipliers(multipliers)
+        ),
+    }
+
+
+def _stage_multipliers(multipliers: Mapping[LifeStage, Decimal]) -> dict[str, str]:
+    """Per-life-stage spending multipliers, stages as stable tokens."""
+    return {
+        LIFE_STAGE_TOKENS.token(stage): str(value)
+        for stage, value in multipliers.items()
+    }
+
+
+def _planned_outflow(outflow: PlannedOutflow) -> dict[str, object]:
+    """One dated one-off outflow."""
+    person_id, age = outflow.at_age_of
+    return {
+        "id": _entity_id(outflow.id),
+        "label": outflow.label,
+        "amount_real": _decision(outflow.amount_real, _money_value),
+        "at_age_of": {"person_id": _entity_id(person_id), "age": _int_value(age)},
+    }
+
+
+def _fact[T](fact: Fact[T], value: Callable[[T], object]) -> dict[str, object]:
+    """A user-stated fact with its provenance fields."""
+    return {
+        "value": value(fact.value),
+        "as_of": fact.as_of.isoformat(),
+        "recorded_on": fact.recorded_on.isoformat(),
+        "note": fact.note,
+    }
+
+
+def _optional_fact[T](
+    fact: Fact[T] | None, value: Callable[[T], object]
+) -> dict[str, object] | None:
+    """A fact the schema allows to be absent."""
+    return None if fact is None else _fact(fact, value)
+
+
+def _decision[T](
+    decision: Decision[T], value: Callable[[T], object]
+) -> dict[str, object]:
+    """A user choice with its provenance fields."""
+    return {
+        "value": value(decision.value),
+        "recorded_on": decision.recorded_on.isoformat(),
+        "note": decision.note,
+    }
+
+
+def _optional_decision[T](
+    decision: Decision[T] | None, value: Callable[[T], object]
+) -> dict[str, object] | None:
+    """A decision the schema allows to be absent."""
+    return None if decision is None else _decision(decision, value)
+
+
+def _optional[T](
+    value: T | None, encode: Callable[[T], dict[str, object]]
+) -> dict[str, object] | None:
+    """An optional nested record."""
+    return None if value is None else encode(value)
+
+
+def _money_value(money: Money) -> str:
+    """A monetary amount as its exact decimal string."""
+    return str(money.amount)
+
+
+def _decimal_value(value: Decimal) -> str:
+    """A decimal figure as its exact string."""
+    return str(value)
+
+
+def _int_value(value: int) -> int:
+    """A whole number, natively JSON (``bool`` rejected, as ever).
+
+    Raises:
+        PersistenceError: If the value is a smuggled boolean — the
+            strict reader would refuse it on reload.
+    """
+    if isinstance(value, bool):
+        msg = "booleans are not persisted whole numbers"
+        raise PersistenceError(msg)
+    return value
+
+
+def _entity_id(entity_id: EntityId) -> str:
+    """A stable entity id, required non-empty so the reader accepts it.
+
+    Raises:
+        PersistenceError: If the id is empty.
+    """
+    if not entity_id:
+        msg = "entity ids must be non-empty"
+        raise PersistenceError(msg)
+    return str(entity_id)
+
+
+def _date_value(value: date) -> str:
+    """A calendar date in ISO-8601 form."""
+    return value.isoformat()
+
+
+def _sex_value(value: Sex) -> str:
+    """The longevity-default sex as its stable token."""
+    return SEX_TOKENS.token(value)

glidepath/persistence/migrations.py

@@ -0,0 +1,158 @@
+"""Versioned schema migrations for ``.glidepath.json`` (roadmap 6.4; §4.5).
+
+The harness exists from day one — the accepted cost of the §4.5
+persistence decision — so a future schema change is a registered
+upgrader, not a file-format fork. Upgraders are keyed by the schema
+version they *read* and each returns the document exactly one version
+higher; loading applies them in sequence from the file's version up to
+:data:`~glidepath.persistence.document.SCHEMA_VERSION`. A file already
+at the current version passes through untouched.
+"""
+
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any
+
+from glidepath.persistence.document import SCHEMA_VERSION, PersistenceError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+type RawDocument = dict[str, Any]
+"""A parsed ``.glidepath.json`` document before strict decoding."""
+
+type Upgrader = Callable[[RawDocument], RawDocument]
+"""One registered migration: reads version *n*, returns version *n + 1*."""
+
+
+def _upgrade_v1_to_v2(raw: RawDocument) -> RawDocument:
+    """v2 adds ``active_membership`` to every DB pension (roadmap 9.6).
+
+    A v1 file predates active DB accrual, so every pension it holds is
+    deferred — the new key decodes as ``null``. The document is
+    upgraded in place at the parsed-JSON layer; a malformed document
+    passes through shape-checked, for the strict decoder to reject
+    with a proper path-carrying error.
+    """
+    household = raw.get("household")
+    persons = household.get("persons") if isinstance(household, dict) else []
+    for person in persons if isinstance(persons, list) else []:
+        pensions = person.get("db_pensions") if isinstance(person, dict) else []
+        for pension in pensions if isinstance(pensions, list) else []:
+            if isinstance(pension, dict):
+                pension["active_membership"] = None
+    raw[_VERSION_KEY] = 2
+    return raw
+
+
+def _upgrade_v2_to_v3(raw: RawDocument) -> RawDocument:
+    """v3 drops the state pension qualifying-years derivation (#97).
+
+    The official DWP forecast is the only route to a state pension
+    amount, so the fields that existed solely to feed the derivation —
+    the qualifying-years count, the NI record start date, and the
+    planned extra accrual years — are removed from the record. A
+    migrated record without a forecast still loads (the deferral
+    choice is kept); projecting it fails with a clear demand for a
+    forecast, and the facts form requires one on the next save.
+    """
+    household = raw.get("household")
+    persons = household.get("persons") if isinstance(household, dict) else []
+    for person in persons if isinstance(persons, list) else []:
+        record = person.get("state_pension") if isinstance(person, dict) else None
+        if isinstance(record, dict):
+            for key in ("ni_record_start", "qualifying_years", "planned_extra_years"):
+                record.pop(key, None)
+    raw[_VERSION_KEY] = 3
+    return raw
+
+
+def _upgrade_v3_to_v4(raw: RawDocument) -> RawDocument:
+    """v4 drops the accumulation-stage spending multipliers (#129).
+
+    Spending is modelled only in retirement, so the accumulation-stage
+    keys older builds accepted and wrote never scaled anything —
+    dropping them loses no behaviour. #114 retired the tokens from the
+    ``SpendingPlan`` invariant without a migration, so a genuine v1-era
+    file carrying them failed to load until this step.
+    """
+    household = raw.get("household")
+    spending = household.get("spending") if isinstance(household, dict) else None
+    multipliers = (
+        spending.get("stage_multipliers") if isinstance(spending, dict) else None
+    )
+    if isinstance(multipliers, dict):
+        for key in ("early_accumulation", "mid_accumulation", "pre_retirement"):
+            multipliers.pop(key, None)
+    raw[_VERSION_KEY] = 4
+    return raw
+
+
+UPGRADERS: Mapping[int, Upgrader] = MappingProxyType(
+    {1: _upgrade_v1_to_v2, 2: _upgrade_v2_to_v3, 3: _upgrade_v3_to_v4}
+)
+"""The registered upgraders, keyed by the version each reads."""
+
+_VERSION_KEY = "schema_version"
+_FLOOR_VERSION = 1
+
+
+def document_schema_version(raw: RawDocument) -> int:
+    """The document's declared schema version, validated.
+
+    Raises:
+        PersistenceError: If the key is missing, not a whole number, or
+            below the version-1 floor.
+    """
+    if _VERSION_KEY not in raw:
+        msg = f"document is missing required key {_VERSION_KEY!r}"
+        raise PersistenceError(msg)
+    version = raw[_VERSION_KEY]
+    if isinstance(version, bool) or not isinstance(version, int):
+        msg = f"{_VERSION_KEY} must be a whole number, got {type(version).__name__}"
+        raise PersistenceError(msg)
+    if version < _FLOOR_VERSION:
+        msg = f"{_VERSION_KEY} must be at least {_FLOOR_VERSION}, got {version}"
+        raise PersistenceError(msg)
+    return version
+
+
+def apply_migrations(
+    raw: RawDocument,
+    *,
+    upgraders: Mapping[int, Upgrader] = UPGRADERS,
+    target: int = SCHEMA_VERSION,
+) -> RawDocument:
+    """Upgrade a parsed document to ``target``, one version at a time.
+
+    A document already at ``target`` is returned as-is (the v1→v1
+    no-op). ``upgraders`` and ``target`` are injectable so the harness
+    itself is testable ahead of any real schema change.
+
+    Raises:
+        PersistenceError: If the document declares a version newer than
+            ``target``, no upgrader is registered for a needed step, or
+            an upgrader fails to step exactly one version.
+    """
+    version = document_schema_version(raw)
+    if version > target:
+        msg = (
+            f"document schema version {version} is newer than this build"
+            f" reads (up to {target}); upgrade glidepath to open it"
+        )
+        raise PersistenceError(msg)
+    while version < target:
+        upgrader = upgraders.get(version)
+        if upgrader is None:
+            msg = f"no migration is registered from schema version {version}"
+            raise PersistenceError(msg)
+        raw = upgrader(raw)
+        upgraded_version = document_schema_version(raw)
+        if upgraded_version != version + 1:
+            msg = (
+                f"migration from schema version {version} produced"
+                f" version {upgraded_version}; upgraders must step"
+                " exactly one version"
+            )
+            raise PersistenceError(msg)
+        version = upgraded_version
+    return raw