# Crypto Single-Coin Runtime Test Pattern

Use when the user asks for a controlled productive test that adds exactly one missing crypto coin from a real XLSX into the external runtime SQLite DB.

## Safety rules

- Keep the XLSX only under runtime/temp, never in the Git repo.
- Run `git status --short --branch` and `PYTHONPATH=src python -m jarvis_finance.cli.main git-safety-scan .` before and after.
- Assert runtime base, DB path, temp input and reports directory are outside the repo.
- Report only aggregate booleans/counts; never echo quantities, CHF values, raw rows or wallet addresses.
- Use `Decimal(str(cell_value))` and write Decimal strings, never floats.
- Use the existing audited management path (`add_crypto_position(..., operation_type='initial_snapshot_addition', confirm=True, ...)`) rather than direct table mutation.

## Preflight workflow

1. Download/read the real XLSX into a runtime temp directory and chmod restrictively.
2. Locate the requested coin by exact symbol/name where possible (e.g. `BTC` / Bitcoin), not broad substring guessing.
3. Identify non-zero wallet columns for that single coin.
4. Match every candidate wallet label against active `crypto_wallets` in the runtime DB.
5. Check whether the asset already exists by exact `coingecko_id`, exact symbol, or exact lowercase coin name.
6. Check existing holdings for the same `asset_id + wallet_id`.
7. Verify no duplicate holdings already exist globally.

## Critical distinction: one coin vs one holding

A real XLSX may contain one coin split across multiple wallet columns. If the user's instruction says **one coin** but also requires an **unambiguous target wallet** or a single holding, do not silently choose a wallet. Stop and ask whether to:

- import all wallet holdings for that one coin,
- import only a user-selected wallet,
- try another coin with a single non-zero wallet cell, or
- skip the runtime test.

If the user explicitly approves "one coin across all wallets", it is still one asset but multiple holdings; verify and report this distinction aggregate-only.

## Post-write verification

After a permitted write, verify aggregate-only:

- asset present with chosen CoinGecko ID,
- expected holding row(s) present,
- no duplicate `asset_id + wallet_id`,
- stored quantity value is text/Decimal-parseable,
- audit-log entry exists for the snapshot,
- initial snapshot/history fields exist with the confirmed snapshot date,
- dashboard/read model contains the coin,
- crypto report context contains the coin,
- Git-safety OK and Git status clean.

## Pitfall

Do not proceed to downstream feature work if the runtime validation step was explicitly a prerequisite and it stopped on ambiguity. Report the stop condition first; continuing would hide a data-governance failure behind unrelated implementation work.