# Read-only performance-activation data preview

Use this procedure before enabling an existing TTWROR/XIRR source, importing history, confirming cashflow coverage, backfilling valuations, or enabling a scheduler.

## 1. Freeze and prove the production boundary

- Verify the exact deployed worktree SHA, schema version, service unit, activation environment flag, and timer state.
- Capture a pre-sentinel that is comparable byte-for-byte: database SHA-256, size, inode, mtime, integrity check, foreign-key check, relevant table counts, and repository status.
- Open SQLite with URI `mode=ro` plus `PRAGMA query_only=ON`; use `immutable=1` only after checking there is no live WAL whose contents would be ignored.
- Run preview/service readers directly against that read-only connection. Do not invoke Confirm routes, migrations, provider adapters, or commands that initialize runtime directories.
- Repeat the identical sentinel after all probes and require `sentinel_equal=true` and `total_changes=0`.

## 2. Classify records by role before counting them

A raw snapshot count is not a performance-coverage count. For each source, separate:

- canonical account valuations usable as opening/closing values;
- instrument snapshots usable only for attribution or drill-down;
- legacy account-total snapshots accepted by the current reader;
- active latest versions versus superseded versions;
- complete, partial, and unavailable quality;
- confirmed values versus provisional/manual values;
- persisted canonical valuations versus values that could only be derived from holdings and prices.

Count logical latest-version groups as well as physical rows. Explain why redundant/superseded rows do not add valuation dates.

## 3. Probe the actual engine, not only inventory SQL

Run the shipped coverage builder and source-specific performance reader over candidate periods. Inventory can look sufficient while the engine still rejects it.

Counterprobes:

- Every account included in a scope must have an account valuation on the same opening and closing dates. A combined depot-plus-cash value stored only on the depot account is incompatible with a two-account scope unless the canonical contract explicitly models that aggregation; adding a separate cash value may double count, so stop rather than improvise.
- Inspect the canonical `activity_kind` consumed by the engine, not merely the provider event type. A generic projected kind can make otherwise detailed dividends, fees, or transfers `cashflow_classification_incomplete`.
- Identify external flows at the selected performance boundary. A paired transfer may be internal globally but external to a scope when its counter-account is excluded.
- Require valuations on every external-flow day for TTWROR under the documented calendar-day convention.
- Distinguish missing period coverage from missing activities. An empty activity table is not evidence of zero flows.

## 4. Determine exact source completeness

For every source report:

- physical and logical valuation counts, date bounds, values, quality, and provenance;
- opening and closing values currently accepted by the engine;
- confirmed activities by type and date range;
- externally classified deposits/withdrawals at the performance boundary;
- transaction FX completeness and price/FX date coverage;
- flow days with and without compatible valuations;
- snapshots usable for XIRR, TTWROR, attribution, or wealth history;
- partial, superseded, redundant, incompatible, provisional, or noncanonical rows;
- the precise reason cashflow coverage remains zero.

Do not certify a source as complete merely because an imported bundle contains many documents or because its first/last dates span the period. Completeness requires explicit source evidence or a truthful period attestation.

## 5. Produce actionable user-input checklists

Avoid vague requests such as “complete history required.” For each source specify:

- exact missing interval;
- exact opening/closing business timestamp;
- file type and parser constraints;
- required fields for each external flow;
- FinanceManager Preview/Confirm area;
- existing rows that will be reused;
- metric unlocked by each input;
- whether the input is sufficient by itself.

A year-end statement can be a valid opening anchor only when it contains the complete source scope and reconciled value. It never proves subsequent transaction or external-flow completeness. If the current parser does not accept that statement shape, say so rather than promising importability.

For managed-total sources, distinguish official total-value PDFs, provisional/manual totals, and dated external flows. If no dedicated flow importer exists, flag the recording gap before activation; do not convert a flow list into a coverage attestation without canonical storage.

For crypto, inventory every wallet/exchange, populated versus empty or duplicate-looking entries, verified holding dates, transaction history, transfer pairing, and exact historical price coverage. A verified holding snapshot is a potential start anchor, not a performance series. Require complete activity since that anchor or an explicit truthful no-activity attestation.

## 6. Compare activation variants honestly

For YTD, use the previous year-end close as the opening anchor and list each remaining source blocker.

For an earliest-common-start variant:

- compute the intersection of compatible confirmed valuation days across sources;
- if any required source has no canonical valuation, report that no common start exists today;
- separately identify a contingent common candidate date and the exact missing evidence needed to make it valid;
- identify which source can produce an individual XIRR first and what additional flow-day valuations TTWROR needs.

## 7. Stop at the authorization boundary

The final report should state separately what a later authorization would write:

1. source imports through Preview → Confirm → Audit;
2. source-scope and cashflow-coverage confirmation (normally no financial snapshot);
3. append-only valuation backfill and run/audit records;
4. scheduler activation as a separate explicit decision.

If engine/data-shape incompatibilities are found, do not hide them inside a user-file checklist and do not begin a development sprint. Report them as independent blockers and wait for a decision.