# Broker Import Execution Plans and Mini-Import Pattern

Use this reference after broker review items have already passed the manual-review readiness gate (e.g. True Wealth ETF/equity items moved to `ready_for_import`) and the user approves a final dry-run plus a controlled productive mini-import.

## B6a — final dry-run / execution plan

Preflight before extracting payloads:

1. Run Git-safety and verify Git status is clean.
2. Verify runtime DB and source/temp files live outside the repo.
3. Verify a recent runtime backup exists; for productive B6b create and verify a fresh backup.
4. Count exactly the approved `ready_for_import` review items for the requested platform.
5. Verify each item has account mapping, instrument mapping and confirmed snapshot date.
6. Read real broker source files only from runtime/temp/Drive context; never copy them into the repo, tests, fixtures or docs.
7. Remove temp files after extraction. Report only aggregate counts/status; never emit real quantities, values or balances.

For each ready item, create a runtime-only execution-plan row (e.g. `broker_import_execution_plans`) with:

- `execution_plan_id`, `dry_run_id`, `review_item_id`, `source_platform`
- `target_account_id`, `target_instrument_id`
- `transaction_type='initial_position_snapshot'`
- `snapshot_date`
- `payload_status` (`ready`, `blocked`, `warning`)
- `payload_quality_flags_json`
- `source_row_hash`
- `planned_write_summary_json` with internal details only
- `execution_status='planned'`, `transaction_id`, `created_at`, `updated_at`, `executed_at`, `notes`

Payload validation rules:

- Preserve quantity/amount/FX fields as Decimal text; never use float.
- If quantity is missing or Decimal parsing fails, block the payload.
- Do not infer cost basis from market value.
- If cost basis is absent or source semantics are unclear, set `cost_basis_quality='missing'` or `uncertain`.
- If historic FX is absent, set `fx_status='missing'` and add quality flags rather than inventing CHF precision.
- Keep `price_original`, `market_value_original`, and `cost_basis_original` only if the source clearly provides them.

B6a report shape:

- payloads checked / ready / blocked
- missing FX count
- cost-basis-uncertain count
- missing quantity/account/instrument mapping counts
- whether exactly one mini-import is technically acceptable
- no quantities, values or account balances

## B6b — exactly one productive mini-import

Before writing:

1. Run `finance backup-runtime-db` (or the project CLI equivalent).
2. Run `finance verify-backup --file <backup-file>` and confirm checksum.
3. Select exactly one `payload_status='ready' AND execution_status='planned'` plan.
4. Check idempotency by execution plan ID, review item ID, row hash and/or source ID.

Write exactly one ledger transaction:

- `transaction_type='initial_position_snapshot'`
- mapped account/instrument IDs
- trade/snapshot date from confirmed snapshot date
- exact quantity text from source
- original currency from source
- price/cost/market fields only when semantically valid
- `fx_status` and `quality_status` reflecting missing/uncertain data
- `source_type='broker_import_reviewed_snapshot'`
- `source_id` as execution plan ID or review item ID
- `external_transaction_id` or row hash for re-import prevention
- notes saying this is an initial snapshot from a reviewed dry-run

Do **not** directly write `positions_snapshot` as the source of truth. Positions may be calculated from ledger transactions, but the confirmed transaction is the durable truth.

After writing:

- Mark execution plan `imported` and link the transaction ID.
- Mark the imported review item `imported`/completed, while leaving other ready items planned/resolved and not imported.
- Record audit events for the transaction import and review-item status change.
- Verify exactly one new transaction and zero direct `positions_snapshot`/cash snapshot writes.
- Verify dashboard position calculation, manual review queue status, data-quality warnings and audit history without emitting real values.
- Run compile, pytest, Git-safety and Git status. If schema/code changed, commit and push after tests/safety pass; if only runtime data changed, do not commit.

## Pitfalls

- Do not import all ready items just because all payloads are valid; B6b is exactly one position unless user explicitly expands scope.
- Do not convert broker quantities or amounts through Python float/SQLite REAL.
- Do not downgrade missing FX/cost-basis issues to `ok`; use warnings/incomplete quality.
- Do not write true broker files, extracted rows, DBs or reports into Git.
- Do not report actual values, quantities, balances, raw file snippets or row payloads in chat.