# Provider-component valuation and cashflow activation maps

Use this reference when a finance sprint must turn already-confirmed provider data into performance-ready component valuations and external-flow evidence without inventing a new engine.

## Current-code mapping sequence

1. Pin the exact worktree SHA, schema version, and clean status before describing implementation.
2. Trace each source through parser/provider → Preview → Confirm → source tables → canonical valuation/activity tables → performance loader → API. Inspect all parallel ingestion lineages; do not assume similarly named providers share one canonical path.
3. Compare authoritative source components with their canonical projections. A provider control total may be valid for reconciliation while still being wrong as an additive performance-account value.
4. Inspect actual readers, not only writers. Confirm which cash/valuation table the daily job and performance engine consume, including `as_of` and version precedence.
5. Distinguish schema gaps from activation gaps. Existing append-only valuation snapshots, transactions, coverage, and audit tables usually suffice when the missing work is projection, classification, routing, or request validation.

## Component valuation pattern

For a provider whose official total equals securities plus settlement cash:

- persist the source total as a reconciliation control;
- materialize canonical account values as separate components (for example depot securities and settlement cash);
- require the components to reconcile exactly to the official total;
- never expose the control total as a third additive performance value;
- append versions with explicit supersession rather than overwrite;
- include source snapshot/run lineage in every canonical row and audit.

Changing future import confirmation is insufficient for already-confirmed history. Historical projection needs a bounded, fingerprinted Preview → Confirm → Audit operation over immutable source snapshots. Preview must report eligible dates, conflicts, expected writes, and the input revision; Confirm must re-evaluate, reject drift, append only, and be idempotent.

## Immutable activity-semantics repair

Official imported transactions may be trigger-protected. If an old writer persisted coarse or wrong activity labels:

- correct future writes to use exact semantic kinds (`buy`, `sell`, `dividend`, `interest`, `fee`, `internal_transfer`, supported non-external FX);
- repair historical interpretation in a narrow source-specific read adapter using immutable source-event fields;
- do not update protected financial rows merely to change classification;
- preserve direction from source events when canonical amounts are unsigned or ambiguous.

Dividends, interest, fees, trades, and intra-scope FX are performance/null flows, not investor external cashflows. A transfer fully inside the selected performance scope is neutral; the same transfer crossing the selected-scope boundary is an external deposit or withdrawal. Test both scopes explicitly.

## Managed-total external-flow/nullflow contract

A managed-total source needs confirmed external-flow evidence in addition to opening/closing values.

Use a strict Preview → Confirm → Audit contract with:

- period and account binding;
- evidence reference;
- mode `external_flows` or `no_external_flows`;
- normalized dated deposit/withdrawal rows with positive source amounts, currency, and stored FX for non-base currency;
- side-effect-free preview, deterministic fingerprint, stale-input rejection, atomic confirm, request-bound idempotency, and one bounded audit.

Persist real flows as canonical transactions. Represent an explicit no-flow decision through audited period coverage, **not** a synthetic zero-value transaction. Tighten source activation so a boolean attestation alone cannot claim complete flow history when no confirmed flow/nullflow contract covers the requested period.

Flow confirmation does not make TTWROR complete by itself. Every external-flow day still needs the valuation boundary required by the performance engine; preview should surface missing boundary valuations as blockers or explicit downstream limitations.

## High-value implementation-map format

Keep the map concise and code-grounded:

1. exact base SHA/schema and whether the tree is clean;
2. current gap with file/function/table evidence;
3. smallest file-and-symbol changes by vertical slice;
4. migration decision with field-level justification;
5. focused synthetic acceptance tests;
6. blockers such as dual ingestion paths, immutable legacy rows, unspecified source format, and missing valuation boundaries.

Do not claim an implementation map is grounded merely because filenames were listed. Tie each recommendation to the current writer, canonical table, reader precedence, and fail-closed performance requirement.