# Unified modelled wealth-series reuse map

Use this reference when extending an existing finance system with a household wealth/history projection while preserving canonical performance calculations.

## Audit order

1. Pin the exact deployed commit and schema version.
2. Trace each source's authoritative anchor, exact-date valuation writer, activation gate, fingerprint, audit, and supersession behavior.
3. Follow timer → service → CLI → actual worker list. A worker present in source is not necessarily scheduled.
4. Trace effective daily selection: business-date normalization, complete component-set rules, source priority, version, capture timestamp, official-anchor precedence, and data cutoff.
5. Trace cash separately, including official components, manual/CSV anchors, post-anchor confirmed movements, FX, and `balance_date <= as_of`.
6. Identify overlapping contracts, especially performance-account valuations versus current-value virtual aggregates. Never sum both.
7. Map the performance firewall: exact opening/closing and cash-flow boundary valuations, complete flow coverage, supported activity classification, stored FX, and provisional endpoint handling.
8. Inspect schema definitions and tests before proposing persistence changes.

## Minimal read-model design

Prefer a pure projection over a second valuation engine:

- Read only persisted valuation, account-value, and cash observations plus existing official component projections.
- Reuse established period parsing and source-role classification.
- Build an event-driven date set from source observation dates and requested boundaries.
- For each component/date, select only evidence with a business date on or before that point.
- Assign semantic quality independently of storage quality:
  - `confirmed`: exact-date authoritative or manually confirmed observation;
  - `modelled`: exact-date persisted market/model valuation;
  - `carried`: an older eligible observation reused without repricing;
  - `unknown`: no eligible observation.
- Aggregate conservatively using `unknown > carried > modelled > confirmed`.
- Return a complete total only when all required components are known; otherwise return a known subtotal and explicit missing components.
- Preserve safe mixed-date provenance: component key, observation date, and oldest/newest evidence date. Public payloads must not expose account IDs or raw source references.
- Derive correction markers from explicit snapshot version/supersession lineage where available. If using same-day winner replacement as a marker, label it as derived rather than audit-grade lineage.

## No current-price historical backfill

Historical series construction must not call current position readers that multiply quantities by the latest quote. It must not invoke providers or valuation writers. Use only persisted observations dated on or before the historical point. A gap is `carried` or `unknown`, never a newly repriced historical value.

Current-value cards may continue using current audited readers, but that path stays separate from history.

## Performance isolation

Never feed display-oriented carried/modelled household points into XIRR or TTWROR. Existing performance readers retain their exact endpoint, flow-boundary, coverage, FX, scope, and quality gates. Add regression tests proving return outputs and statuses are unchanged.

## Migration rule

No database migration is needed when existing storage already represents value, business date, source, capture time, version/supersession, quality/reasons, run fingerprint, and audit lineage. API/Pydantic typing is not a DB migration.

Use a migration only for evidence that cannot be represented honestly, such as mandatory explicit correction lineage for every source. State any source-specific lineage limitation instead of inventing speculative tables.

## Verification checklist

- Exact commit/schema cited.
- Actual scheduled workers cited.
- Source overlap/deduplication rules explicit.
- Official-anchor precedence deterministic.
- Missing remains null/unknown, never zero.
- Future evidence rejected.
- Current readers/providers unreachable from historical tests.
- Correction markers evidence-based.
- Period boundaries deterministic.
- XIRR/TTWROR behavior unchanged.
- Audit remained read-only against production state.