# Imported financial source → performance activation contract map

Use when existing bank/import records must be mapped into auditable performance cashflows without reading productive rows or activating production behavior.

## Read-only reconnaissance

1. Pin the exact worktree/commit and repository rules; verify the tree is unchanged at the end.
2. Inspect migration source and apply migrations only to an in-memory database. Use `PRAGMA table_info/index_list` there to prove exact current columns and uniqueness without opening a productive database.
3. Trace source candidates, confirmed source rows, mappings, fingerprints, canonical performance transactions, scope roles, coverage, audit, API security, and existing tests end to end.
4. Separate detection, cashflow confirmation, coverage attestation, and production activation. Do not collapse them into one operation.

## Contract rules

- Detection is read-only and returns opaque source IDs. The client never supplies authoritative amounts, dates, signs, currencies, or destination accounts; preview and confirm re-read them server-side.
- Fingerprints bind every relation that can change classification or writes, not just counts or latest timestamps.
- Confirm acquires a write lock or nested savepoint, reconstructs preview under lock, rejects stale state, writes atomically, and audits a redacted summary.
- Maintain two identities: stable source identity for replay idempotency, and an economic collision key for manual-versus-detected duplicates.
- Economic collisions are review states, not automatic duplicates. Require fingerprint-bound `link_existing` or `record_distinct`; persist/audit that choice so later previews remain resolved. In particular, `link_existing` must create an immutable source-row → canonical-cashflow association (or equivalent durable lineage). Merely applying the decision during one Preview/Confirm and recording only a request fingerprint is insufficient: a fresh preview without resubmitting the decision must still resolve the row as linked.
- Validate financial dimensions for internal consistency, not just presence. For a CHF source row, require the stored CHF amount to match the signed original amount and require identity FX semantics (`rate=1`, compatible status/source); contradictory non-null CHF/FX fields are an uncertain review state and must block a matching batch rather than being ignored while the writer reconstructs an amount from another column.
- Detection from one bank/provider does not prove all external flows. Mark coverage complete only with explicit all-source, period-scoped attestation; otherwise leave it unchanged or partial. Preserve contiguous existing coverage and reject silent gaps or shrinkage.
- Cashflow confirmation writes zero valuations and must not call production activation, enable schedulers, or mutate unrelated scope.
- Prefer a shared internal canonical writer for manual/CSV and detected paths while keeping their public request contracts distinct.

## Conservative semantics and privacy

Require explicit sign, supported currency, bounded date, stable provenance, and narrow destination evidence. Never infer direction from unsigned values or provider/account names alone. Keep candidate-only legacy evidence weaker than confirmed import evidence. Generic household transfer pairing may not apply when an investment destination is intentionally outside household account mappings.

Never return or audit raw descriptions, merchant text, account/IBAN references, filenames, CSV bodies, or raw fingerprints. Public rows should contain only opaque detection ID, date, direction, amount/currency, evidence status, duplicate status, and reason codes.

## Minimum tests

- exact/normalized matches and wrong-source/sign/currency/date/identity negatives;
- candidate-stage versus confirmed-source evidence;
- deterministic zero-write preview and API/audit redaction;
- stale preview after any relevant source/scope/coverage/cashflow change;
- exact replay, confirmation-ID payload binding, and atomic rollback;
- manual collision default block plus both explicit decisions;
- no complete coverage without attestation, no shrink/gap bridging;
- zero valuation/scheduler/activation side effects;
- fail-closed write mode and unchanged schema-version/regressions.