glidepath 0.2.0__py3-none-any.whl

glidepath/core/provenance.py

@@ -0,0 +1,271 @@
+"""Facts, decisions, assumptions, and provenance (planning §1, §5.1).
+
+Every number in a plan is exactly one of three kinds:
+
+- a :class:`Fact` the user stated (DOB, balances, accrued DB entitlement),
+- a :class:`Decision` the user chose (retirement age, contributions) — the
+  only scenario-overridable plan fields (planning §4.3),
+- an :class:`Assumption` the app defaulted or estimated (returns,
+  inflation, longevity) — always overridable, always carrying its source.
+
+The engine may not read a tunable number any way other than through an
+:class:`AssumptionSet`; per-run reads are recorded by an
+:class:`AssumptionReadRecorder` without mutating the frozen set, so
+``ProjectionResult.provenance`` can list every assumption actually used.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from decimal import Decimal
+from enum import Enum, StrEnum, auto
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+    from datetime import date, datetime
+
+
+class Provenance(Enum):
+    """Where a value came from (planning §5.1)."""
+
+    USER_FACT = auto()
+    DEFAULT_ASSUMPTION = auto()
+    USER_OVERRIDE = auto()
+    SCENARIO_OVERRIDE = auto()
+
+
+def _require_tz_aware(moment: datetime, field_name: str) -> None:
+    """Reject naive datetimes (repo rule: datetimes are always tz-aware)."""
+    if moment.tzinfo is None or moment.tzinfo.utcoffset(moment) is None:
+        msg = f"{field_name} must be timezone-aware"
+        raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class Fact[T]:
+    """A value the user stated (planning §5.1).
+
+    Facts are never scenario-overridable (planning §4.3): a different
+    balance is a different plan.
+    """
+
+    value: T
+    as_of: date
+    recorded_on: datetime
+    note: str | None = None
+
+    def __post_init__(self) -> None:
+        """Reject naive timestamps."""
+        _require_tz_aware(self.recorded_on, "Fact.recorded_on")
+
+
+@dataclass(frozen=True, slots=True)
+class Decision[T]:
+    """A user choice — neither a fact about the world nor an estimate.
+
+    Decision variables are exactly the scenario what-if whitelist
+    (planning §4.3, §5.1).
+    """
+
+    value: T
+    recorded_on: datetime
+    note: str | None = None
+
+    def __post_init__(self) -> None:
+        """Reject naive timestamps."""
+        _require_tz_aware(self.recorded_on, "Decision.recorded_on")
+
+
+class AssumptionKey(StrEnum):
+    """Stable dotted ids for every tunable number (planning §5.1, §7).
+
+    Values are persisted in user files and targeted by scenario overrides,
+    so they must never change meaning; retire a key by adding a new one.
+    """
+
+    INFLATION_CPI = "inflation.cpi"
+    EARNINGS_GROWTH_REAL = "earnings.growth.real"
+    RETURNS_EQUITY_REAL = "returns.equity.real"
+    RETURNS_BONDS_REAL = "returns.bonds.real"
+    RETURNS_CASH_REAL = "returns.cash.real"
+    VOLATILITY_EQUITY = "volatility.equity"
+    VOLATILITY_BONDS = "volatility.bonds"
+    VOLATILITY_CASH = "volatility.cash"
+    CORRELATION_EQUITY_BONDS = "correlation.equity_bonds"
+    CORRELATION_EQUITY_CASH = "correlation.equity_cash"
+    CORRELATION_BONDS_CASH = "correlation.bonds_cash"
+    FEES_PLATFORM = "fees.platform"
+    FEES_FUND = "fees.fund"
+    YIELD_EQUITY = "yield.equity"
+    YIELD_BONDS = "yield.bonds"
+    YIELD_CASH = "yield.cash"
+    HORIZON_PLANNING_AGE = "horizon.planning_age"
+    GLIDEPATH_DEFAULT_SHAPE = "glidepath.default_shape"
+    POLICY_STATE_PENSION_UPRATING = "policy.state_pension.uprating"
+    POLICY_TAX_FUTURE_YEARS = "policy.tax.future_years"
+    ANNUITY_LEVEL_SINGLE_65 = "annuity.level.single.65"
+    ANNUITY_ESCALATING3_SINGLE_65 = "annuity.escalating3.single.65"
+    ANNUITY_INFLATION_LINKED_SINGLE_65 = "annuity.inflation_linked.single.65"
+    ANNUITY_AGE_ADJUSTMENT = "annuity.age_adjustment"
+
+
+@dataclass(frozen=True, slots=True)
+class Assumption[T]:
+    """A value the app defaulted or estimated. Always overridable.
+
+    Carries the shipped default alongside the effective value, plus the
+    source its default is based on, so the UI can always answer "which of
+    these numbers did I state, and which did you assume?" (planning §1).
+    """
+
+    key: AssumptionKey
+    value: T
+    default_value: T
+    provenance: Provenance
+    source: str
+    recorded_on: datetime
+    description: str
+
+    def __post_init__(self) -> None:
+        """Reject impossible provenance and naive timestamps."""
+        if self.provenance is Provenance.USER_FACT:
+            msg = "an Assumption cannot carry USER_FACT provenance"
+            raise ValueError(msg)
+        _require_tz_aware(self.recorded_on, "Assumption.recorded_on")
+
+
+class AssumptionSet:
+    """Immutable typed registry of assumptions, keyed by dotted id.
+
+    The engine may not read a tunable number any other way (planning
+    §5.1): step functions receive only ``Plan`` + ``AssumptionSet`` +
+    ``Region`` + ``RunConfig``.
+    """
+
+    __slots__ = ("_entries",)
+
+    def __init__(self, assumptions: Iterable[Assumption[Any]]) -> None:
+        """Build the registry, rejecting duplicate keys."""
+        entries: dict[AssumptionKey, Assumption[Any]] = {}
+        for assumption in assumptions:
+            if assumption.key in entries:
+                msg = f"duplicate assumption key: {assumption.key!r}"
+                raise ValueError(msg)
+            entries[assumption.key] = assumption
+        self._entries = entries
+
+    def get(self, key: AssumptionKey) -> Assumption[Any]:
+        """Return the assumption registered for ``key``.
+
+        Raises:
+            KeyError: If no assumption is registered for ``key``.
+        """
+        try:
+            return self._entries[key]
+        except KeyError:
+            msg = f"no assumption registered for key {key!r}"
+            raise KeyError(msg) from None
+
+    def __contains__(self, key: AssumptionKey) -> bool:
+        """Whether an assumption is registered for ``key``."""
+        return key in self._entries
+
+    @property
+    def keys(self) -> frozenset[AssumptionKey]:
+        """The keys with a registered assumption."""
+        return frozenset(self._entries)
+
+
+class AssumptionReadRecorder:
+    """Mutable per-run recorder of assumption reads (planning §5.1).
+
+    ``run()`` creates one per run and returns its contents as part of the
+    result; the frozen :class:`AssumptionSet` itself is never mutated.
+    """
+
+    __slots__ = ("_keys_in_order",)
+
+    def __init__(self) -> None:
+        """Start with no reads recorded."""
+        self._keys_in_order: list[AssumptionKey] = []
+
+    def record(self, key: AssumptionKey) -> None:
+        """Note that ``key`` was read (first read wins; later reads dedup)."""
+        if key not in self._keys_in_order:
+            self._keys_in_order.append(key)
+
+    @property
+    def keys_read(self) -> tuple[AssumptionKey, ...]:
+        """Keys read so far, deduplicated, in first-read order."""
+        return tuple(self._keys_in_order)
+
+
+def decimal_assumption_value(assumption: Assumption[Any]) -> Decimal:
+    """The assumption's value as an exact ``Decimal`` rate or factor.
+
+    The engine reads tunable numbers only through assumptions (planning
+    §5.1); a value of the wrong shape is a configuration error and must
+    fail loudly, never coerce — ``Decimal`` end-to-end is the §4.6 rule
+    (a bool is rejected explicitly: it is an ``int`` subtype but never
+    a number here).
+
+    Raises:
+        TypeError: If the value is not a ``Decimal``.
+    """
+    value = assumption.value
+    if not isinstance(value, Decimal):
+        msg = (
+            f"assumption {assumption.key!r} must hold a Decimal value,"
+            f" got {type(value).__name__}"
+        )
+        raise TypeError(msg)
+    return value
+
+
+def int_assumption_value(assumption: Assumption[Any]) -> int:
+    """The assumption's value as a whole number (e.g. a planning age).
+
+    Raises:
+        TypeError: If the value is not an ``int`` (``bool`` rejected).
+    """
+    value = assumption.value
+    if isinstance(value, bool) or not isinstance(value, int):
+        msg = (
+            f"assumption {assumption.key!r} must hold an integer value,"
+            f" got {type(value).__name__}"
+        )
+        raise TypeError(msg)
+    return value
+
+
+def mapping_assumption_value(assumption: Assumption[Any]) -> Mapping[str, Any]:
+    """The assumption's value as a structured table (e.g. a glide shape).
+
+    Raises:
+        TypeError: If the value is not a mapping.
+    """
+    value = assumption.value
+    if not isinstance(value, Mapping):
+        msg = (
+            f"assumption {assumption.key!r} must hold a table value,"
+            f" got {type(value).__name__}"
+        )
+        raise TypeError(msg)
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class TrackedAssumptions:
+    """Read-through view pairing an :class:`AssumptionSet` with a recorder.
+
+    The engine reads assumptions through this view so every read lands in
+    the run's provenance record with no engine-side bookkeeping.
+    """
+
+    assumptions: AssumptionSet
+    recorder: AssumptionReadRecorder
+
+    def get(self, key: AssumptionKey) -> Assumption[Any]:
+        """Record the read, then return the assumption."""
+        self.recorder.record(key)
+        return self.assumptions.get(key)

glidepath/core/randomness.py

@@ -0,0 +1,128 @@
+"""Seeded randomness for Monte Carlo runs (roadmap 7.1; planning §4.6).
+
+Randomness enters the engine only through the :class:`RandomSource`
+protocol, wrapping :class:`random.Random` seeded from the run's
+``RunConfig.seed`` — never module-level ``random`` (planning §4.6).
+Monte Carlo path *i* uses a substream whose seed is derived from
+``(seed, i)`` by :func:`derive_seed`, an explicit fixed-width digest:
+``random.Random((seed, i))`` is a ``TypeError`` on our pinned Python
+(3.11+ restricts seed types), so the derivation cannot be delegated to
+the seed argument. Because the derivation is a pure function, paths are
+order-independent and individually re-runnable — "re-run path 4711"
+needs only the manifest's seed and the path index.
+
+Reproducibility is manifest-level (§4.6): identical manifest →
+identical output, on any runtime. Python guarantees that only
+``random.Random.random()`` reproduces its sequence across versions;
+the float distribution methods (``gauss`` et al.) go through libm,
+whose last-bit rounding varies across platforms and versions. Draws
+therefore cross the float→``Decimal`` boundary at the uniform step —
+each ``random()`` output converts exactly — and the normal transform
+runs in ``Decimal`` (Marsaglia's polar method; ``Decimal.ln()`` and
+``Decimal.sqrt()`` are correctly rounded by specification), so the
+same seed yields bit-identical draws on every platform this checkout
+runs on (e.g. the shared Windows/WSL setup).
+"""
+
+import random
+from decimal import Decimal
+from hashlib import blake2b
+from typing import Protocol
+
+_DIGEST_SIZE = 16
+"""Substream seeds are 128-bit digests — fixed width, planning §4.6."""
+
+_ZERO = Decimal(0)
+_ONE = Decimal(1)
+_TWO = Decimal(2)
+_MINUS_TWO = Decimal(-2)
+
+
+class RandomSource(Protocol):
+    """A seeded stream of random draws (planning §4.6).
+
+    The engine and return models take their randomness only through
+    this protocol, so a run's randomness is exactly determined by the
+    seeds injected into it.
+    """
+
+    def standard_normals(self, count: int, /) -> tuple[Decimal, ...]:
+        """Draw ``count`` independent standard-normal values in order."""
+        ...
+
+
+def derive_seed(root_seed: int, *parts: int | str) -> int:
+    """Derive a substream seed from a root seed and identifying parts.
+
+    The explicit derivation function of planning §4.6: a fixed-width
+    (128-bit) BLAKE2b digest over the root seed and each part, returned
+    as an integer for :class:`random.Random`. Each part is tagged with
+    its type and length-prefixed inside the digest, so distinct part
+    sequences can never collide — neither by concatenation nor by an
+    integer shadowing its string spelling (``1`` vs ``"1"``). The Monte
+    Carlo path runner (roadmap 7.3) derives path *i*'s stream as
+    ``derive_seed(seed, i)``; the stochastic return model further
+    scopes draws per period.
+    """
+    hasher = blake2b(digest_size=_DIGEST_SIZE)
+    for part in (root_seed, *parts):
+        hasher.update(b"i" if isinstance(part, int) else b"s")
+        encoded = str(part).encode("utf-8")
+        hasher.update(len(encoded).to_bytes(8, "big"))
+        hasher.update(encoded)
+    return int.from_bytes(hasher.digest(), "big")
+
+
+class SeededRandomSource:
+    """The :class:`RandomSource` wrapping ``random.Random(seed)`` (§4.6).
+
+    Stateful by design: draws consume the underlying stream in order,
+    and two sources built from the same seed produce identical
+    sequences. Statistical use only — never security (the S311 ignore
+    for this module in ``pyproject.toml``).
+    """
+
+    __slots__ = ("_stream",)
+
+    def __init__(self, seed: int) -> None:
+        """Seed a private stream; no global random state is touched."""
+        self._stream = random.Random(seed)
+
+    def _uniform_signed(self) -> Decimal:
+        """One uniform draw on [-1, 1), converted exactly to Decimal.
+
+        ``random()`` is the one generator method whose sequence Python
+        guarantees stable across versions (module docstring), so it is
+        the only float this class ever consumes.
+        """
+        return _TWO * Decimal(self._stream.random()) - _ONE
+
+    def standard_normals(self, count: int, /) -> tuple[Decimal, ...]:
+        """Draw ``count`` standard normals via the polar method.
+
+        Marsaglia's polar method in ``Decimal``: accept a uniform pair
+        ``(u, v)`` when ``s = u² + v²`` lands strictly inside the unit
+        circle (excluding zero), then scale by ``sqrt(-2 ln(s) / s)``
+        to yield two independent normals. No libm call is involved, so
+        the draws are bit-identical across platforms (module
+        docstring). An odd ``count`` discards the trailing normal of
+        the last accepted pair — deterministically, since rejection
+        sampling consumes the stream identically either way.
+
+        Raises:
+            ValueError: If ``count`` is negative.
+        """
+        if count < 0:
+            msg = f"count must be non-negative, got {count}"
+            raise ValueError(msg)
+        draws: list[Decimal] = []
+        while len(draws) < count:
+            u = self._uniform_signed()
+            v = self._uniform_signed()
+            magnitude = u * u + v * v
+            if magnitude >= _ONE or magnitude == _ZERO:
+                continue
+            scale = (_MINUS_TWO * magnitude.ln() / magnitude).sqrt()
+            draws.append(u * scale)
+            draws.append(v * scale)
+        return tuple(draws[:count])

glidepath/core/region.py

@@ -0,0 +1,46 @@
+"""The region bundle the engine runs against (roadmap 4.1; planning §4.2).
+
+A :class:`Region` gathers one region's implementations of every core
+boundary protocol — fiscal calendar, age rules, tax system, wrapper
+rules, contribution rules, state pension scheme — plus a
+content-version string identifying the data those implementations
+answer from. The engine receives exactly
+this bundle (planning §5.2: ``run(plan, assumptions, region, config)``)
+and never anything region-specific; the version string lands in
+``ProjectionResult.provenance`` so a result records which data produced
+it (planning §4.6).
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from glidepath.core.contributions import ContributionRuleset
+    from glidepath.core.periods import AgeRules, FiscalCalendar
+    from glidepath.core.state_pension import StatePensionScheme
+    from glidepath.core.tax import TaxSystem
+    from glidepath.core.wrappers import WrapperRuleset
+
+
+@dataclass(frozen=True, slots=True)
+class Region:
+    """One region's boundary-protocol implementations, bundled.
+
+    ``data_version`` identifies the region data content backing the
+    bundle (e.g. file names with their ``verified_on`` dates) — part of
+    the run manifest reproducibility is defined over (planning §4.6).
+    """
+
+    calendar: FiscalCalendar
+    ages: AgeRules
+    tax: TaxSystem
+    wrappers: WrapperRuleset
+    contributions: ContributionRuleset
+    state_pension: StatePensionScheme
+    data_version: str
+
+    def __post_init__(self) -> None:
+        """Require a non-empty data version."""
+        if not self.data_version:
+            msg = "Region.data_version must not be empty"
+            raise ValueError(msg)

glidepath/core/reporting.py

@@ -0,0 +1,231 @@
+"""The real/nominal reporting layer (roadmap 4.4; planning §5.2).
+
+The engine computes nominal — tax bands are nominal objects — and every
+:class:`~glidepath.core.results.PeriodSnapshot` records the cumulative
+CPI factor the run inflated by. This layer presents a projection in one
+of two bases: **real (today's money), the default**, deflates by the
+run's own CPI path; nominal presents the ledger amounts unchanged. No
+inflation source of its own enters here — the deflators come exactly
+from what the engine recorded, so the one-inflation-truth rule of
+planning §5.2 holds by construction.
+
+Two deflators per row under the real basis, matching what each amount
+is: *flows* divide by the snapshot's ``inflation_factor`` — the
+period-start price level the engine inflated them with — while
+*closing balances* divide by the level at the period's modelled end,
+``inflation_factor * (1 + cpi * year_fraction)`` (the linear
+partial-period convention of §5.2), because a closing balance already
+contains the period's own nominal growth. Presented totals are sums of
+the presented per-wrapper amounts, so a report table is internally
+consistent after rounding.
+
+Report amounts are quantized for presentation (they are derived views,
+not ledger writes); the snapshots remain the exact ledger record.
+"""
+
+from dataclasses import dataclass
+from decimal import Decimal
+from enum import Enum, auto
+from typing import TYPE_CHECKING
+
+from glidepath.core.money import Money
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from glidepath.core.entities import EntityId
+    from glidepath.core.glide import LifeStage
+    from glidepath.core.periods import Period
+    from glidepath.core.results import (
+        PeriodSnapshot,
+        PersonPeriodResult,
+        ProjectionResult,
+    )
+    from glidepath.core.wrappers import WrapperKindId
+
+_ONE = Decimal(1)
+_ZERO = Money(Decimal(0))
+
+
+class ReportBasis(Enum):
+    """The money basis a report presents (planning §5.2).
+
+    ``REAL`` is today's money — the default presentation; ``NOMINAL``
+    is the engine's ledger basis.
+    """
+
+    REAL = auto()
+    NOMINAL = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class WrapperReportBalance:
+    """One wrapper's closing balance, in the report's basis."""
+
+    wrapper_id: EntityId
+    kind: WrapperKindId
+    closing_balance: Money
+
+
+@dataclass(frozen=True, slots=True)
+class PeriodReportRow:
+    """One person's period figures, in the report's basis.
+
+    ``deflator`` is the factor divided out of the nominal flow amounts:
+    the snapshot's cumulative ``inflation_factor`` (the period-start
+    price level) under ``ReportBasis.REAL`` and 1 under
+    ``ReportBasis.NOMINAL``. ``balance_deflator`` is the factor divided
+    out of the closing balances — the price level at the period's
+    modelled end, since a closing balance embeds the period's own
+    nominal growth. ``closing_balance`` is the sum of the presented
+    ``wrapper_balances``, so the row stays consistent after rounding.
+    ``contributions`` totals what landed in the pots (employee gross,
+    including provider relief, plus employer and any government bonus,
+    roadmap 9.2); ``withdrawals_gross`` totals the tax-free and
+    taxable draws across wrappers; ``annuity_purchases`` totals the
+    capital that left the wrappers to buy annuity income this period
+    (roadmap 5.5). ``growth_tax`` totals the portfolio-income tax
+    charged to taxable-growth wrappers, ``aa_charge`` totals the
+    annual-allowance charge the wrappers funded at close — scheme
+    pays and the cash route together (#124) — and ``banked`` is the
+    period's surplus — decumulation income and draws beyond the need,
+    or pre-retirement non-employment income beyond the planned
+    outflows — swept into one (roadmap 9.2).
+    """
+
+    period: Period
+    person_id: EntityId
+    age_at_period_start: int
+    stage: LifeStage
+    year_fraction: Decimal
+    deflator: Decimal
+    balance_deflator: Decimal
+    employment_income: Money
+    db_income: Money
+    db_lump_sum: Money
+    pension_lump_sum: Money
+    state_pension_income: Money
+    annuity_income: Money
+    annuity_lump_sum: Money
+    annuity_purchases: Money
+    tax_due: Money
+    spending_need: Money
+    planned_outflows: Money
+    net_withdrawn: Money
+    shortfall: Money
+    contributions: Money
+    fees: Money
+    growth: Money
+    growth_tax: Money
+    aa_charge: Money
+    banked: Money
+    withdrawals_gross: Money
+    closing_balance: Money
+    wrapper_balances: tuple[WrapperReportBalance, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectionReport:
+    """A projection presented in one money basis (roadmap 4.4).
+
+    Rows appear in period order; with a multi-person household each
+    period contributes one row per person, in plan order.
+    """
+
+    basis: ReportBasis
+    rows: tuple[PeriodReportRow, ...]
+
+
+def build_report(
+    result: ProjectionResult, basis: ReportBasis = ReportBasis.REAL
+) -> ProjectionReport:
+    """Present ``result`` in ``basis`` — real (today's money) by default.
+
+    Real amounts deflate by the run's single CPI path as the engine
+    recorded it period by period (planning §5.2): flows by the
+    period-start level, closing balances by the level at the period's
+    modelled end (see the module docstring).
+    """
+    rows = tuple(
+        _person_row(snapshot, person, basis)
+        for snapshot in result.snapshots
+        for person in snapshot.persons
+    )
+    return ProjectionReport(basis=basis, rows=rows)
+
+
+def _total(amounts: Iterable[Money]) -> Money:
+    """Sum a stream of amounts exactly."""
+    total = _ZERO
+    for amount in amounts:
+        total = total + amount
+    return total
+
+
+def _person_row(
+    snapshot: PeriodSnapshot, person: PersonPeriodResult, basis: ReportBasis
+) -> PeriodReportRow:
+    """One report row: the person's snapshot figures deflated to ``basis``."""
+    deflator = _ONE
+    balance_deflator = _ONE
+    if basis is ReportBasis.REAL:
+        deflator = snapshot.inflation_factor
+        balance_deflator = snapshot.inflation_factor * (
+            _ONE + snapshot.returns.cpi.value * snapshot.year_fraction
+        )
+
+    def flow(amount: Money) -> Money:
+        """Deflate a flow by the period-start level and quantize."""
+        return Money(amount.amount / deflator).quantized()
+
+    def balance(amount: Money) -> Money:
+        """Deflate a closing balance by the period-end level and quantize."""
+        return Money(amount.amount / balance_deflator).quantized()
+
+    wrappers = person.wrappers
+    wrapper_balances = tuple(
+        WrapperReportBalance(
+            wrapper_id=entry.wrapper_id,
+            kind=entry.kind,
+            closing_balance=balance(entry.closing_balance),
+        )
+        for entry in wrappers
+    )
+    return PeriodReportRow(
+        period=snapshot.period,
+        person_id=person.person_id,
+        age_at_period_start=person.age_at_period_start,
+        stage=person.stage,
+        year_fraction=snapshot.year_fraction,
+        deflator=deflator,
+        balance_deflator=balance_deflator,
+        employment_income=flow(person.employment_income),
+        db_income=flow(person.db_income),
+        db_lump_sum=flow(person.db_lump_sum),
+        pension_lump_sum=flow(person.pension_lump_sum),
+        state_pension_income=flow(person.state_pension_income),
+        annuity_income=flow(person.annuity_income),
+        annuity_lump_sum=flow(person.annuity_lump_sum),
+        annuity_purchases=flow(_total(entry.annuity_purchase for entry in wrappers)),
+        tax_due=flow(person.tax.tax_due),
+        spending_need=flow(person.spending_need),
+        planned_outflows=flow(person.planned_outflows),
+        net_withdrawn=flow(person.net_withdrawn),
+        shortfall=flow(person.shortfall),
+        contributions=flow(
+            _total(
+                entry.employee_contribution
+                + entry.employer_contribution
+                + entry.contribution_bonus
+                for entry in wrappers
+            )
+        ),
+        fees=flow(_total(entry.fee for entry in wrappers)),
+        growth=flow(_total(entry.growth for entry in wrappers)),
+        growth_tax=flow(_total(entry.growth_tax for entry in wrappers)),
+        aa_charge=flow(_total(entry.aa_charge for entry in wrappers)),
+        banked=flow(person.banked),
+        withdrawals_gross=flow(_total(entry.withdrawal_gross for entry in wrappers)),
+        closing_balance=_total(entry.closing_balance for entry in wrapper_balances),
+        wrapper_balances=wrapper_balances,
+    )