# Brokerage Depot + Settlement-Cash Anchor Activation

Use this procedure when onboarding a brokerage source whose portfolio consists of a securities depot plus one or more settlement-cash accounts and whose official statement exposes a combined control total.

## Activation boundary

A matched official snapshot proves only a **source-level anchor**. It does not prove:

- canonical component rows are projected correctly;
- activity/cashflow history is complete after the anchor;
- internal transfers have the right direction at the selected performance boundary;
- fees, taxes, FX legs, and settlement movements are counted exactly once;
- TTWROR/XIRR or an isolated writer job may be enabled.

Keep these states separate in reports and APIs:

1. `source_anchor_confirmed`
2. `canonical_components_materialized`
3. `activity_coverage_complete`
4. `performance_ready`
5. `source_job_enabled`

Never promote a later state from an earlier one by implication.

## Read-only inventory

Before deciding whether code or data work is needed, query the productive database and inspect the protected source bundle directly.

Inventory, without printing account identifiers or raw rows:

- stable source and account roles;
- depot, settlement-cash, and control/non-scope accounts;
- document types, fingerprints, dates, and covered activity periods;
- official snapshots and their reconciliation status;
- position count, ISIN/currency/mapping completeness, and duplicates;
- settlement-cash components by source currency;
- activity counts by economic type and quality status;
- explicit period coverage rows;
- writer/job activation state.

Treat archive dates and individual confirmation dates as evidence limits, not as proof that no later activity occurred.

## Earliest common anchor

Select the earliest date on which the same evidence set proves all of:

- every position and quantity;
- valuation/price date;
- every settlement-cash component;
- any other in-scope cash component;
- official control total;
- currency and FX basis;
- no unresolved open orders or unsettled trades.

Reconcile with the existing tolerance:

`securities + settlement cash + other evidenced components = official control total`

The control total is non-additive. Store/use it only as reconciliation evidence; never materialize it as a third asset beside depot and cash.

If depot and cash dates differ, status remains `partial` or `not_comparable`.

## Projection-counterexample probes

Do not trust a correct summary API alone. Compare the source components against every canonical representation that a writer or reader can consume.

Probe at least:

- source snapshot securities and cash totals;
- source-currency cash rows and their converted total;
- canonical cash balances on the settlement account;
- account-level valuation snapshots;
- component-level valuation snapshots;
- same-day official-versus-modelled selection;
- performance reader’s selected opening value.

A common silent defect is that an importer stores the combined official total in each cash component or on the settlement account while a summary endpoint recomputes the right cash total from original currency. The UI can look correct while activation would double-count the portfolio. Any such mismatch blocks materialization and the source job.

## Activity semantics and direction

Classify economic events before aggregating storage rows:

- buy/sell and trade settlement: internal, performance-neutral cash/security exchange;
- depot-to-associated-settlement transfer: internal;
- outside-to-scope funding: external deposit;
- scope-to-outside movement: external withdrawal unless stronger linked evidence proves it is a portfolio fee/tax;
- dividend/interest: internal income;
- fee/tax: internal expense;
- in-scope FX conversion: internal;
- split/corporate action: quantity event, no external cashflow;
- unclear movement: unsupported and blocking.

Do not infer transfer direction from an unsigned positive amount. Verify direction from the original debit/credit document, account role, and cash-balance transition. Parser direction fields and account-role assignment require source-document counterprobes before activation.

For a fee funded through a scope-crossing FX/transfer chain, link the evidence before classification. Do not count both the boundary transfer and the fee as separate performance losses unless the documents prove two distinct economic effects.

## Position and cash-chain proof

From the anchor to the requested end, reconstruct in booking/value-date order.

For positions, prove per instrument:

`opening quantity + buys - sells + corporate-action delta = observed closing quantity`

For cash, prove per currency:

`opening balance + external flows + settlements + income - fees - taxes + internal transfers = observed closing balance`

Open or unvalued trades stay unresolved. A split must retain old quantity, new quantity, ratio, source line, and document fingerprint; a zero-amount generic corporate-action row is not enough.

A cash chain that exactly bridges a monthly statement balance to a later official snapshot is strong anchor evidence, but it does not grant cashflow coverage after that snapshot.

## Instrument mapping gate

Count mappings as safe only when the canonical instrument is unique and the approved evidence establishes ISIN, price currency, and listing/venue where required.

If a new snapshot omits ISIN but reuses an already owner-confirmed canonical mapping, report two separate facts:

- canonical mapping status;
- source-row provenance status for the new snapshot.

Do not silently label name-only snapshot linkage as fresh ISIN confirmation.

## Stop gate and exact evidence request

If post-anchor activities or external flows are incomplete, stop before backup, Confirm, writer execution, performance calculations, or job activation. Supply an exact evidence list, typically:

1. settlement-account statement or transaction export from the anchor through the intended end date, including booking date, value date, signed amount, currency, running balance, and counterparty/account role;
2. complete broker document export for the same interval: trades, distributions, interest, fees, taxes, FX, transfers, and corporate actions;
3. official closing depot/account overview with positions, quantities, cash by currency, control total, valuation date, and preferably ISIN per row;
4. an official zero-activity statement when no movements occurred.

A verbal no-flow statement is not a substitute when the activation contract requires documentary period coverage.

## No-write closure evidence

When the stop gate fires:

- keep performance coverage rows unchanged;
- keep the source-specific job disabled;
- do not run performance metrics and then present them as a dry-run;
- do not create a code branch merely to compensate for missing documents;
- report any genuine code/contract defect separately from the missing-data blocker;
- record exact table row deltas as zero;
- compare database and protected source-file sentinels before and after normal GET/API probes;
- run integrity/FK and duplicate checks;
- state that backup and writer replay were not triggered because the write phase was never authorized.

Normal dashboard GETs must not call providers or mutate the database.

## Required counterexamples

- Correct source control total but combined total stored on settlement cash: activation blocked.
- Correct read-only component preview but no materialized two-account component rows: source anchor confirmed, performance not ready.
- Two transfer legs with positive unsigned amounts: direction unresolved until debit/credit evidence is checked.
- Fee plus linked cross-boundary funding transfer: exactly one economic performance loss.
- Position overview without ISIN joined by name to an existing instrument: canonical mapping and source-row provenance reported separately.
- One official opening snapshot plus modelled closes but no post-anchor activity coverage: opening anchor may be retained; return, XIRR, TTWROR, and jobgate stay closed.
- Source bundle ending before the requested performance period: no-flow cannot be inferred from absence of later documents.