btctax-cli 0.12.0

//! reconcile decision emitters (FR6/FR7/FR8, §7.2). Each fn builds exactly ONE `EventPayload` decision
//! variant and appends it via `append_decision` (monotonic `decision_seq`), then saves. Decisions are
//! append-only and re-projectable; the engine resolves precedence (latest-`decision_seq`, Void-first).
//! `now` is the injected decision creation-time / safe-harbor made-date (§6.2) — deterministic in tests.
//!
//! Also contains the `set-donation-details` / `show-donation-details` side-table commands (no decision
//! append — these write to the `donation_details` side-table directly, like `tax-profile set`).
use crate::{
    BulkFilter, BulkLinkPlan, BulkReclassifyOutflowPlan, BulkResolvePlan, BulkStiFilter,
    BulkStiPlan, BulkVoidPlan, CliError, MatchProposal, Session,
};
use btctax_core::conventions::{tax_date, TRANSITION_DATE};
use btctax_core::persistence::{append_decision, load_all};
use btctax_core::{
    AllocMethod, BlockerKind, ClassifyInbound, ClassifyRaw, DisposeKind, DonationDetails, EventId,
    EventPayload, InboundClass, IncomeKind, LedgerEvent, LotId, LotMethod, LotPick, LotSelection,
    ManualFmv, MethodElection, OutflowClass, ReclassifyIncome, ReclassifyOutflow, RejectImport,
    RemovalKind, SafeHarborAllocation, SelfTransferPassthrough, SupersedeImport, TaxDate,
    TransferLink, TransferTarget, Usd, VoidDecisionEvent, WalletId,
};
use btctax_store::Passphrase;
use std::path::Path;
use time::{OffsetDateTime, UtcOffset};

use crate::eventref::parse_event_id;

/// Append one decision (creation tz = UTC; decisions are not wallet-scoped) and persist.
fn append_and_save(
    session: &mut Session,
    payload: EventPayload,
    now: OffsetDateTime,
) -> Result<EventId, CliError> {
    let id = append_decision(session.conn(), payload, now, UtcOffset::UTC, None)?;
    session.save()?;
    Ok(id)
}

/// UX-P4-3: refuse — AT RECORD TIME, before any append (fail-closed) — a reconcile decision the
/// resolver would adjudicate as a NEW `DecisionConflict`: a first-wins duplicate, a wrong-type or
/// unknown target, or a non-revocable/unknown `void`. The predicate is `btctax_core::would_conflict`
/// (the real projection run with pseudo forced OFF), so record-time == resolver by CONSTRUCTION — a
/// hand-rebuilt subset would drift (SPEC §3.2 mandate). The refusal carries the resolver's own reason
/// plus the unified discoverability pointer (`events list` + `void decision|N`). Call it from the
/// single-verb append fns AFTER the payload is built and BEFORE `append_and_save`; the bulk `apply_*`
/// paths are deliberately OUT of scope (plan-generated, not user-typed, refs — SPEC §3.2).
fn guard_decision_conflict(
    session: &Session,
    payload: &EventPayload,
    now: OffsetDateTime,
) -> Result<(), CliError> {
    let events = load_all(session.conn())?;
    let cfg = session.config()?.to_projection();
    if let Some(detail) = btctax_core::would_conflict(&events, session.prices(), &cfg, payload, now)
    {
        // The resolver's `detail` is now surface-neutral and self-contained (it names `events list`
        // and, for duplicates, the void remedy — UX-P4-3 hint unification), so the record-time layer
        // only frames it as a refusal (nothing was appended); no second, contradictory hint.
        return Err(CliError::Usage(format!(
            "cannot record this decision — {detail}"
        )));
    }
    Ok(())
}

/// FR6: classify an externally-sourced inbound `TransferIn` as Income or a received Gift. For Income
/// this supplies the FMV basis; for Gift it supplies donor basis/date + fmv_at_gift (TP11 dual-basis).
/// This is the re-supply path for the §9.1 Swan `deposit` basis GAP.
pub fn classify_inbound(
    vault_path: &Path,
    pp: &Passphrase,
    in_ref: &str,
    class: InboundClass,
    now: OffsetDateTime,
) -> Result<EventId, CliError> {
    let transfer_in_event = parse_event_id(in_ref)?;
    let mut session = Session::open(vault_path, pp)?;

    // UX-P4-4(b): a supplied acquisition date that STRICTLY post-dates the receipt is impossible —
    // self-transferred / gifted coins cannot have been acquired after they arrived. Refuse at record
    // time, BEFORE any decision is appended (fail-closed). The acquisition date and the receipt come
    // from different sources (the CLI `--acquired`/`--donor-acquired` flag vs. the imported TransferIn),
    // so the message prints the receipt date + its tz basis. Same-day is allowed (a same-day
    // acquire→receive is legitimate, and a tz skew can already shift the calendar day by one). The
    // receipt lives on the referenced TransferIn event; if the ref does not resolve to a TransferIn
    // (wrong-target), the guard is skipped and the existing DecisionConflict path adjudicates.
    let acquired_override: Option<(&str, TaxDate)> = match &class {
        InboundClass::SelfTransferMine { acquired_at, .. } => {
            acquired_at.map(|d| ("--acquired", d))
        }
        InboundClass::GiftReceived {
            donor_acquired_at, ..
        } => donor_acquired_at.map(|d| ("--donor-acquired", d)),
        InboundClass::Income { .. } => None,
    };
    if let Some((flag, acquired)) = acquired_override {
        let events = load_all(session.conn())?;
        if let Some(ev) = events.iter().find(|e| e.id == transfer_in_event) {
            if let EventPayload::TransferIn(_) = &ev.payload {
                let receipt = tax_date(ev.utc_timestamp, ev.original_tz);
                if acquired > receipt {
                    return Err(CliError::Usage(format!(
                        "{flag} {acquired} is after the receipt date {receipt} (recorded in {tz}); \
                         coins cannot be acquired after they are received. Same-day is allowed.",
                        tz = tz_label(ev.original_tz),
                    )));
                }
            }
        }
    }

    let payload = EventPayload::ClassifyInbound(ClassifyInbound {
        transfer_in_event,
        as_: class,
    });
    guard_decision_conflict(&session, &payload, now)?;
    append_and_save(&mut session, payload, now)
}

/// Render a `UtcOffset` as a human tz basis for record-time messages: `UTC` for the zero offset,
/// otherwise `UTC±HH:MM` (UX-P4-4(b)). Kept dependency-free (no `time` `formatting` feature) via
/// `as_hms`, so it also works when the offset carries seconds (rendered at minute resolution).
fn tz_label(tz: UtcOffset) -> String {
    let (h, m, _s) = tz.as_hms();
    if h == 0 && m == 0 {
        "UTC".to_string()
    } else {
        let sign = if h < 0 || m < 0 { '-' } else { '+' };
        format!("UTC{sign}{:02}:{:02}", h.unsigned_abs(), m.unsigned_abs())
    }
}

/// FR6: reclassify a pending `TransferOut` as a Sell/Spend disposition, a Gift out, or a Donation.
/// `principal` is the gross proceeds (Dispose) or FMV-at-transfer (Gift/Donate); `fee_usd` is the
/// optional disposition fee (TP8 / TP2). The engine applies the configured TP8 (c)/(b) fee treatment.
/// `donee` is the optional free-form donee identifier (Chunk 2); `None` for disposals and legacy records.
#[allow(clippy::too_many_arguments)]
pub fn reclassify_outflow(
    vault_path: &Path,
    pp: &Passphrase,
    out_ref: &str,
    class: OutflowClass,
    principal: Usd,
    fee_usd: Option<Usd>,
    donee: Option<String>,
    now: OffsetDateTime,
) -> Result<EventId, CliError> {
    let transfer_out_event = parse_event_id(out_ref)?;
    let mut session = Session::open(vault_path, pp)?;

    let payload = EventPayload::ReclassifyOutflow(ReclassifyOutflow {
        transfer_out_event: transfer_out_event.clone(),
        as_: class,
        principal_proceeds_or_fmv: principal,
        fee_usd,
        donee,
    });
    // UX-P4-3 × UX-P4-4(d) (whole-branch review Minor #1): run the record-time conflict guard FIRST, so a
    // refused decision returns HERE and the "recording it as entered" `--amount` advisory below is never
    // printed for a decision that is then refused (the contradictory message pair). The advisory is
    // reached only once the decision is accepted.
    guard_decision_conflict(&session, &payload, now)?;

    // UX-P4-4(d): a price-based sanity check on `--amount` (the USD FMV / proceeds). Emit the advisory
    // (if any) to stderr — non-fatal; the amount is recorded as entered. Resolve the outflow's sats +
    // date from its TransferOut event and the market value from the event-date close.
    {
        let events = load_all(session.conn())?;
        if let Some(ev) = events.iter().find(|e| e.id == transfer_out_event) {
            if let EventPayload::TransferOut(out) = &ev.payload {
                let date = tax_date(ev.utc_timestamp, ev.original_tz);
                let market_value = btctax_core::price::fmv_of(session.prices(), date, out.sat);
                let btc = Usd::from(out.sat) / Usd::from(100_000_000);
                if let Some(line) = amount_fmv_advisory(principal, market_value, btc, date) {
                    eprintln!("{line}");
                }
            }
        }
    }

    append_and_save(&mut session, payload, now)
}

/// UX-P4-4(d): the stderr line (if any) for the `--amount` FMV sanity check. `market_value` is
/// `fmv_of(prices, event_date, out_sats)` — the USD value of the disposed BTC at the event-date
/// close (`None` when that date has no price). The FMV of donated BTC is its value AT the
/// contribution date (26 CFR 1.170A-1(c)(1)), so the yardstick is that close, NOT cost basis — a
/// $0/low-basis long-held gift is the common case, and a basis threshold would false-warn on it.
///
/// - `amount` exceeding **100x** a positive market value is almost certainly the sats count typed
///   into a dollars field (`sat ≈ 1e8·BTC` vs. `value ≈ BTC·close`, a ratio ≈ `1e8/close`): WARN.
/// - a plausible amount (≤ 100x), or a dust market value that rounds to $0 (no meaningful ratio):
///   no line.
/// - no price for the date: the check cannot run — emit a NOTE, so the guard never dies silently.
///
/// Pure (all I/O — price lookup, stderr — is the caller's) so the decision is unit-testable.
fn amount_fmv_advisory(
    amount: Usd,
    market_value: Option<Usd>,
    btc: Usd,
    date: TaxDate,
) -> Option<String> {
    match market_value {
        Some(mv) if mv > Usd::ZERO && amount > mv * Usd::from(100) => Some(format!(
            "warning: --amount ${amount} is more than 100x the ${mv} market value of {btc} BTC at \
             the {date} close — did you enter the sats amount as dollars? --amount is the USD \
             proceeds/FMV; recording it as entered (not fatal)."
        )),
        Some(_) => None, // plausible amount, or dust whose market value rounds to $0
        None => Some(format!(
            "note: no BTC price for {date}; skipping the --amount FMV sanity check."
        )),
    }
}

/// FR3: set a manual FMV on an event (`ManualEntry`), clearing its `fmv_missing` blocker.
pub fn set_fmv(
    vault_path: &Path,
    pp: &Passphrase,
    event_ref: &str,
    usd_fmv: Usd,
    now: OffsetDateTime,
) -> Result<EventId, CliError> {
    let event = parse_event_id(event_ref)?;
    let mut session = Session::open(vault_path, pp)?;
    // UX-P4-3: `set-fmv` is exempt from the DUPLICATE refusal ONLY (ManualFmv is last-wins — re-pointing
    // an FMV is a sanctioned correction, so the resolver raises no conflict on a second one) but STILL
    // gets existence/type validation. `would_conflict` gives exactly this for free: a `set-fmv` on an
    // unknown or non-Income target IS a new DecisionConflict the resolver excludes → refused here.
    let payload = EventPayload::ManualFmv(ManualFmv { event, usd_fmv });
    guard_decision_conflict(&session, &payload, now)?;
    append_and_save(&mut session, payload, now)
}

/// BG-D9 Task 8 (arch/tax r1 I-3): the prior-year fold-diff advisory in the VOID direction, or `Vec::new()`
/// when the void `target` is not an EFFECTIVE promote void. Voiding a `PromoteTranche` decision reverts a
/// filed floor basis toward `$0`, which can HIFO-reorder a PRIOR filed year's 8949/8283 (amend-to-PAY).
/// Non-gating; the caller PRINTS it BEFORE recording the void. A single stored `profile` cannot fit the
/// multi-year span, so `None` is passed (the tax-Δ arm falls back to the gain/deduction Δ sign — the amend
/// direction is still correct). `now` (the void's own injected creation-time) supplies the advisory's
/// `current` tax-year cutoff (Task 10 handoff) — the BTCTAX_NOW seam, never a wall clock.
fn promote_void_advisory_lines(
    session: &Session,
    events: &[LedgerEvent],
    target_event_id: &EventId,
    now: OffsetDateTime,
) -> Vec<String> {
    // Only an EFFECTIVE void reverts a filed floor: the void `target` IS a `PromoteTranche` decision.
    // The DeclareTranche-with-live-promote void does NOT reach here — it is refused UPSTREAM at record
    // time by `guard_decision_conflict`/`would_conflict` (the engine holds the tranche in force via its
    // live promote → an inert `DecisionConflict`; record-time == resolver by construction), and the
    // bulk/TUI void plans exclude it via `voidable_decisions`' `promoted_target` filter. So this fn only
    // ever sees the effective PromoteTranche-target void — never a DeclareTranche target (arch r1 M-3: the
    // former `.or_else` DeclareTranche path was unreachable dead code that would have printed a reversion
    // + amend advisory for a void that changes nothing).
    let promote_id = events
        .iter()
        .find(|e| e.id == *target_event_id && matches!(e.payload, EventPayload::PromoteTranche(_)))
        .map(|e| e.id.clone());
    let Some(pid) = promote_id else {
        return Vec::new();
    };
    let Ok(cfg) = session.config().map(|c| c.to_projection()) else {
        return Vec::new();
    };
    let tables = btctax_adapters::BundledTaxTables::load();
    let current = tax_date(now, UtcOffset::UTC).year();
    btctax_core::conservative::promote_prior_year_advisory(
        events,
        session.prices(),
        &cfg,
        &pid,
        btctax_core::conservative::Direction::Void,
        None,
        &tables,
        current,
    )
}

/// FR8: void a revocable decision. Voiding a non-revocable / effective-allocation target raises
/// `decision_conflicts` in the projection (no effect) — the CLI only appends; the engine adjudicates.
///
/// When the voided decision is a `LotSelection`, also clears that disposal's `optimize_attestation`
/// row ATOMICALLY (same in-memory DB, one `session.save()`). This closes the revocation-completeness
/// edge: without the clear, a post-void re-run where the FIFO default equals the optimum
/// (`proposed==current`, D ∈ unchanged) could mislabel D as `AttestedRecording` from a stale row
/// the user never attested in this context. Non-LotSelection decisions are unaffected (the
/// `optimize_attestation` table has no row to clear — the delete is a no-op).
pub fn void(
    vault_path: &Path,
    pp: &Passphrase,
    target_ref: &str,
    now: OffsetDateTime,
) -> Result<EventId, CliError> {
    let target_event_id = parse_event_id(target_ref)?;
    let mut session = Session::open(vault_path, pp)?;

    // Determine if the target decision is a LotSelection so we can clear its attestation row.
    // Load events first; the find is O(n) but n is small and void is infrequent.
    let events = load_all(session.conn())?;
    let disposal_to_clear: Option<EventId> = events
        .iter()
        .find(|e| e.id == target_event_id)
        .and_then(|e| match &e.payload {
            EventPayload::LotSelection(ls) => Some(ls.disposal_event.clone()),
            _ => None,
        });
    // Symmetric side-effect [WB]: voiding a ReclassifyOutflow must clear its `bulk_estimated` `[est]`
    // flag (keyed by transfer_out_event == Disposal.event) — else a stale marker survives a
    // void→re-reclassify (the R0-I1 gap, closed on the CLI path too, mirroring optimize_attest above).
    let reclass_out_to_clear: Option<EventId> = events
        .iter()
        .find(|e| e.id == target_event_id)
        .and_then(|e| match &e.payload {
            EventPayload::ReclassifyOutflow(ro) => Some(ro.transfer_out_event.clone()),
            _ => None,
        });

    // UX-P4-3: refuse a void the resolver would adjudicate as a NEW DecisionConflict — a non-revocable
    // target (SupersedeImport/RejectImport/VoidDecisionEvent) or an unknown target.
    guard_decision_conflict(
        &session,
        &EventPayload::VoidDecisionEvent(VoidDecisionEvent {
            target_event_id: target_event_id.clone(),
        }),
        now,
    )?;
    // Plus an explicit already-voided refusal: the resolver treats a double-void of a REVOCABLE target
    // as idempotent (no new conflict), but the SPEC refuses it at record time — a live VoidDecisionEvent
    // already names this target.
    if events.iter().any(|e| {
        matches!(&e.payload,
            EventPayload::VoidDecisionEvent(v) if v.target_event_id == target_event_id)
    }) {
        return Err(CliError::Usage(format!(
            "cannot record this decision — {} is already voided — see `btctax events list` for event \
             refs + decision status",
            target_event_id.canonical()
        )));
    }

    // BG-D9 Task 8 (arch/tax r1 I-3): if this void removes a live promote (or targets a promoted tranche),
    // WARN — before recording, non-gating — about the PRIOR-year 8949/8283 rewrites the floor→$0 revert
    // re-exposes (an amend-to-pay warning). Printed only when the target actually has a live promote.
    for line in promote_void_advisory_lines(&session, &events, &target_event_id, now) {
        println!("{line}");
    }

    // Append the VoidDecisionEvent (no save yet — we batch with the attestation clear below).
    let id = append_decision(
        session.conn(),
        EventPayload::VoidDecisionEvent(VoidDecisionEvent { target_event_id }),
        now,
        UtcOffset::UTC,
        None,
    )?;

    // If the voided decision was a LotSelection, clear the attestation row for its disposal
    // ATOMICALLY — both the void event and the row delete land in the same in-memory Connection
    // and are flushed together by the single `session.save()` below (mirrors accept's atomic
    // co-persist). Idempotent: clearing an absent row is Ok (no error).
    if let Some(disposal) = disposal_to_clear {
        crate::optimize_attest::clear(session.conn(), &disposal)?;
    }
    if let Some(out_event) = reclass_out_to_clear {
        crate::bulk_estimated::clear(session.conn(), &out_event)?;
    }

    session.save()?;
    Ok(id)
}

/// Pseudo-reconcile mode toggle (sub-project 2). Persists the `pseudo_reconcile` flag in `cli_config`
/// (a projection input parameter, NOT ledger state — NFR6). `on = true` ⇒ projection synthesizes
/// non-persisted default decisions to clear the Hard classification blockers; `off` reverts to real-only
/// instantly (no fictional events were ever written). Returns the new flag value.
pub fn pseudo_set_mode(vault_path: &Path, pp: &Passphrase, on: bool) -> Result<bool, CliError> {
    let mut session = Session::open(vault_path, pp)?;
    crate::config::set_pseudo_reconcile(session.conn(), on)?;
    session.save()?;
    Ok(on)
}

/// One row of a `reconcile pseudo approve` preview (sub-project 2, T5). `target` is the imported event the
/// synthetic governs; `kind` is the default TYPE; `wallet`/`year` are the target's provenance (for the
/// filter + preview). Deterministic order (mirrors `pseudo_plan`).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PseudoApproveRow {
    pub target: EventId,
    pub kind: btctax_core::PseudoKind,
    pub wallet: Option<WalletId>,
    pub year: Option<i32>,
}

/// The `--kind`/`--wallet`/`--year` filter for `reconcile pseudo approve`. `None` fields = no restriction.
#[derive(Debug, Clone, Default)]
pub struct PseudoApproveFilter {
    pub kind: Option<btctax_core::PseudoKind>,
    pub wallet: Option<WalletId>,
    pub year: Option<i32>,
}

/// Compute the pseudo-default plan and KEEP only the entries matching `filter`, paired with the target's
/// (wallet, tax-year) provenance. Shared by the read (`pseudo_approve_plan`) and write
/// (`apply_bulk_pseudo_approve`) phases so the preview and the apply are guaranteed identical (the
/// own-loop RE-derives — never trusts a threaded list). `plan` order is `pseudo_plan`'s stable order [N2].
fn filtered_pseudo_plan<'a>(
    plan: &'a [btctax_core::PseudoDefault],
    index: &std::collections::HashMap<&EventId, &btctax_core::LedgerEvent>,
    filter: &PseudoApproveFilter,
) -> Vec<(
    &'a btctax_core::PseudoDefault,
    Option<WalletId>,
    Option<i32>,
)> {
    plan.iter()
        .filter_map(|pd| {
            let ev = index.get(&pd.target);
            let wallet = ev.and_then(|e| e.wallet.clone());
            let year = ev.map(|e| tax_date(e.utc_timestamp, e.original_tz).year());
            if let Some(k) = filter.kind {
                if pd.kind != k {
                    return None;
                }
            }
            if let Some(want) = &filter.wallet {
                if wallet.as_ref() != Some(want) {
                    return None;
                }
            }
            if let Some(y) = filter.year {
                if year != Some(y) {
                    return None;
                }
            }
            Some((pd, wallet, year))
        })
        .collect()
}

/// Pseudo-approve — Phase 1 (read): compute the filtered plan of pseudo defaults that WOULD be promoted to
/// real decisions. Renders NOTHING to the vault (the confirmation stays a thin shell in `main.rs`).
pub fn pseudo_approve_plan(
    vault_path: &Path,
    pp: &Passphrase,
    filter: PseudoApproveFilter,
) -> Result<Vec<PseudoApproveRow>, CliError> {
    let session = Session::open(vault_path, pp)?;
    let prices = session.prices();
    let events = load_all(session.conn())?;
    let cfg = session.config()?.to_projection();
    let plan = btctax_core::pseudo_plan(&events, prices, &cfg);
    let index: std::collections::HashMap<&EventId, &btctax_core::LedgerEvent> =
        events.iter().map(|e| (&e.id, e)).collect();
    Ok(filtered_pseudo_plan(&plan, &index, &filter)
        .into_iter()
        .map(|(pd, wallet, year)| PseudoApproveRow {
            target: pd.target.clone(),
            kind: pd.kind,
            wallet,
            year,
        })
        .collect())
}

/// Pseudo-approve — Phase 2 (write): materialize the filtered pseudo defaults as REAL (attested) decisions
/// via btctax-cli's OWN append-loop [R0-M4] (mirrors `apply_bulk_classify_inbound_income`; the CLI CANNOT
/// reach the tui-edit `persist_bulk_decisions` — dependency cycle, Cargo.toml:19). Empty-guard (no matches
/// ⇒ NO save); bare `?`-before-`save` (a mid-batch failure returns before `save`, discarding the in-memory
/// session = CLI atomicity); a SINGLE `save`. Defense-in-depth: RE-derives the plan here (never trusts a
/// threaded list). After approval these decisions are REAL → the next projection resolves them via the real
/// decision path, so pseudo mode injects NO synthetic for them (no longer `[PSEUDO]`). Returns the count.
pub fn apply_bulk_pseudo_approve(
    vault_path: &Path,
    pp: &Passphrase,
    filter: PseudoApproveFilter,
    now: OffsetDateTime,
) -> Result<usize, CliError> {
    let mut session = Session::open(vault_path, pp)?;
    let prices = session.prices();
    let events = load_all(session.conn())?;
    let cfg = session.config()?.to_projection();
    let plan = btctax_core::pseudo_plan(&events, prices, &cfg);
    let index: std::collections::HashMap<&EventId, &btctax_core::LedgerEvent> =
        events.iter().map(|e| (&e.id, e)).collect();
    let selected = filtered_pseudo_plan(&plan, &index, &filter);
    // Empty-guard: nothing to approve ⇒ do NOT touch the vault.
    if selected.is_empty() {
        return Ok(0);
    }
    let mut n = 0usize;
    for (pd, _wallet, _year) in &selected {
        // `?` on a mid-batch failure returns before `save` — the in-memory session is discarded, so
        // nothing lands on disk (CLI atomicity; the TUI path instead ROLLS BACK).
        append_decision(
            session.conn(),
            pd.decision.clone(),
            now,
            UtcOffset::UTC,
            None,
        )?;
        n += 1;
    }
    session.save()?;
    Ok(n)
}

/// FR2/§7.3: resolve an `Unclassified` row to a real imported payload (preserving the target EventId).
/// The payload is supplied as JSON (`EventPayload` is `Deserialize`) — e.g. `{"Acquire":{…}}`.
pub fn classify_raw(
    vault_path: &Path,
    pp: &Passphrase,
    target_ref: &str,
    payload_json: &str,
    now: OffsetDateTime,
) -> Result<EventId, CliError> {
    let target = parse_event_id(target_ref)?;
    let as_: EventPayload = serde_json::from_str(payload_json)
        .map_err(|e| CliError::Usage(format!("bad --payload-json: {e}")))?;
    if !as_.is_imported() {
        return Err(CliError::Usage(
            "classify-raw payload must be an imported variant (Acquire/Income/Dispose/TransferOut/TransferIn/Unclassified)".into(),
        ));
    }
    let mut session = Session::open(vault_path, pp)?;
    let payload = EventPayload::ClassifyRaw(ClassifyRaw {
        target,
        as_: Box::new(as_),
    });
    guard_decision_conflict(&session, &payload, now)?;
    append_and_save(&mut session, payload, now)
}

/// FR1/FR8: accept an `ImportConflict` (apply the new payload to the target, keeping its EventId).
pub fn accept_conflict(
    vault_path: &Path,
    pp: &Passphrase,
    conflict_ref: &str,
    now: OffsetDateTime,
) -> Result<EventId, CliError> {
    let conflict_event = parse_event_id(conflict_ref)?;
    let mut session = Session::open(vault_path, pp)?;
    append_and_save(
        &mut session,
        EventPayload::SupersedeImport(SupersedeImport { conflict_event }),
        now,
    )
}

/// FR1/FR8: reject an `ImportConflict` (keep the original; clear the blocker).
pub fn reject_conflict(
    vault_path: &Path,
    pp: &Passphrase,
    conflict_ref: &str,
    now: OffsetDateTime,
) -> Result<EventId, CliError> {
    let conflict_event = parse_event_id(conflict_ref)?;
    let mut session = Session::open(vault_path, pp)?;
    append_and_save(
        &mut session,
        EventPayload::RejectImport(RejectImport { conflict_event }),
        now,
    )
}

/// bulk-link-transfer D2 — Phase 1 (read): open the session and compute the bulk link-transfer plan.
///
/// Two-phase by design [R0-M2]: this read phase opens/renders NOTHING to the vault, so the
/// interactive `y/N` confirmation stays a thin, untested shell in the `main.rs` dispatch. The plan is
/// the shared read helper `Session::bulk_link_transfer_plan` (D1). The session (and its VaultLock) is
/// dropped on return, before the confirmation prompt runs.
pub fn bulk_link_plan(
    vault_path: &Path,
    pp: &Passphrase,
    filter: BulkFilter,
    dest: WalletId,
) -> Result<BulkLinkPlan, CliError> {
    let session = Session::open(vault_path, pp)?;
    session.bulk_link_transfer_plan(filter, dest)
}

/// bulk-link-transfer D2 — Phase 2 (write): atomically link every `out_event` to `dest` as a
/// self-transfer. Appends one `TransferLink { out_event, Wallet(dest) }` per row, then a SINGLE
/// `save`. All-or-nothing: a mid-batch `append_decision` failure returns `Err` BEFORE the save, and
/// the local `Session` is dropped with nothing written — the exact one-session / N-append / one-save
/// atomicity of `import_selections`. Returns the number of outflows linked.
pub fn apply_bulk_link_transfer(
    vault_path: &Path,
    pp: &Passphrase,
    out_events: Vec<EventId>,
    dest: WalletId,
    now: OffsetDateTime,
) -> Result<usize, CliError> {
    let mut session = Session::open(vault_path, pp)?;
    for out_event in &out_events {
        let payload = EventPayload::TransferLink(TransferLink {
            out_event: out_event.clone(),
            in_event_or_wallet: TransferTarget::Wallet(dest.clone()),
        });
        // `?` on a mid-batch failure returns before `save` — the in-memory session is discarded, so
        // nothing lands on disk (CLI atomicity; the TUI path must instead ROLL BACK, see D3 [R0-I1]).
        append_decision(session.conn(), payload, now, UtcOffset::UTC, None)?;
    }
    session.save()?;
    Ok(out_events.len())
}

/// bulk-classify-inbound-self-transfer D2 — Phase 1 (read): open the session and compute the bulk STI
/// plan. Two-phase by design (mirrors `bulk_link_plan`): this read phase renders NOTHING to the vault,
/// so the interactive `y/N` confirmation stays a thin, untested shell in the `main.rs` dispatch. The
/// plan is the shared read helper `Session::bulk_self_transfer_in_plan` (D1). The session (and its
/// VaultLock) is dropped on return, before the confirmation prompt runs.
pub fn bulk_self_transfer_in_plan(
    vault_path: &Path,
    pp: &Passphrase,
    filter: BulkStiFilter,
) -> Result<BulkStiPlan, CliError> {
    let session = Session::open(vault_path, pp)?;
    session.bulk_self_transfer_in_plan(filter)
}

/// bulk-classify-inbound-self-transfer D2 — Phase 2 (write): atomically classify every `in_event` as
/// a `SelfTransferMine { basis: None, acquired_at: None }` ($0 conservative basis, non-taxable).
/// Appends one `ClassifyInbound { transfer_in_event, SelfTransferMine{None, None} }` per row, then a
/// SINGLE `save`. All-or-nothing: a mid-batch `append_decision` failure returns `Err` BEFORE the save,
/// and the local `Session` is dropped with nothing written — the exact one-session / N-append /
/// one-save atomicity of `apply_bulk_link_transfer`. Returns the number of inbounds classified.
pub fn apply_bulk_self_transfer_in(
    vault_path: &Path,
    pp: &Passphrase,
    in_events: Vec<EventId>,
    now: OffsetDateTime,
) -> Result<usize, CliError> {
    let mut session = Session::open(vault_path, pp)?;
    for in_event in &in_events {
        let payload = EventPayload::ClassifyInbound(ClassifyInbound {
            transfer_in_event: in_event.clone(),
            as_: InboundClass::SelfTransferMine {
                basis: None,
                acquired_at: None,
            },
        });
        // `?` on a mid-batch failure returns before `save` — the in-memory session is discarded, so
        // nothing lands on disk (CLI atomicity; the TUI path must instead ROLL BACK, see D3).
        append_decision(session.conn(), payload, now, UtcOffset::UTC, None)?;
    }
    session.save()?;
    Ok(in_events.len())
}

/// bulk-classify-inbound-income (Cycle 4) — Phase 1 (read): open the session and compute the bulk
/// classify-income plan. Two-phase by design (mirrors `bulk_self_transfer_in_plan`): this read phase
/// renders NOTHING to the vault. The plan is the shared read helper `Session::bulk_classify_income_plan`
/// — it excludes missing-price rows [#a tax-safety] and reports them as `excluded_missing_price`.
pub fn bulk_classify_income_plan(
    vault_path: &Path,
    pp: &Passphrase,
    filter: crate::BulkIncomeFilter,
) -> Result<crate::BulkIncomePlan, CliError> {
    let session = Session::open(vault_path, pp)?;
    session.bulk_classify_income_plan(filter)
}

/// bulk-classify-inbound-income (Cycle 4) — Phase 2 (write): atomically classify every `in_event` as
/// `Income { kind, fmv, business }` with a PER-ROW auto-FMV. Its OWN append-loop (mirrors
/// `apply_bulk_self_transfer_in`; NOT the tui-edit `persist_bulk_decisions`, which btctax-cli cannot
/// reach — dependency cycle, R0-I1). One `ClassifyInbound { transfer_in_event, Income{..} }` per row,
/// bare `?`-before-`save` (a mid-batch failure returns before `save` → the in-memory session is
/// discarded, nothing lands on disk = CLI atomicity), then a SINGLE `session.save()`.
///
/// **[#a] Auto-FMV is resolved per-row via `fmv_of(date, sat)`.** The dispatch derives `in_events`
/// from `plan.included` (the fmv-`Some` rows only), so every id here resolves to a real price and the
/// `fmv: Option<Usd>` field is `Some` — a persisted `Income{fmv:None}` (→ Hard `FmvMissing` year-gate)
/// is never emitted. `kind` + `business` are UNIFORM across the batch; `fmv` is per-row. Returns the
/// number classified.
pub fn apply_bulk_classify_inbound_income(
    vault_path: &Path,
    pp: &Passphrase,
    in_events: Vec<EventId>,
    kind: IncomeKind,
    business: bool,
    now: OffsetDateTime,
) -> Result<usize, CliError> {
    let mut session = Session::open(vault_path, pp)?;
    let prices = session.prices();
    let events = load_all(session.conn())?;
    let index: std::collections::HashMap<&EventId, &btctax_core::LedgerEvent> =
        events.iter().map(|e| (&e.id, e)).collect();
    // Resolve (sat, date) per in_event from the event log (the FMV is a per-row auto-value; R0-M3:
    // `fmv` is already Option<Usd> so it takes `fmv_of(..)` DIRECTLY — never `Some(fmv_of(..))`).
    let mut n = 0usize;
    for in_event in &in_events {
        let Some(ev) = index.get(in_event) else {
            continue;
        };
        let EventPayload::TransferIn(ti) = &ev.payload else {
            continue;
        };
        let date = btctax_core::conventions::tax_date(ev.utc_timestamp, ev.original_tz);
        // #a defense-in-depth: a missing-price row must NEVER be emitted as `Income { fmv: None }`
        // (→ Hard `FmvMissing` year-gate, unrecoverable without void+reclassify). The plan already
        // excludes these; skipping here makes `Income{fmv:None}` STRUCTURALLY unreachable from this
        // `pub` apply even if a future caller passed a non-plan-filtered id.
        let Some(fmv) = btctax_core::price::fmv_of(prices, date, ti.sat) else {
            continue;
        };
        let payload = EventPayload::ClassifyInbound(ClassifyInbound {
            transfer_in_event: in_event.clone(),
            as_: InboundClass::Income {
                kind,
                fmv: Some(fmv),
                business,
            },
        });
        // `?` on a mid-batch failure returns before `save` — the in-memory session is discarded, so
        // nothing lands on disk (CLI atomicity; the TUI path instead ROLLS BACK).
        append_decision(session.conn(), payload, now, UtcOffset::UTC, None)?;
        n += 1;
    }
    session.save()?;
    Ok(n)
}

/// bulk-reclassify-outflow (Cycle 5) — Phase 1 (read): open the session and compute the bulk
/// reclassify-outflow plan. Two-phase by design (mirrors `bulk_classify_income_plan`): this read phase
/// renders NOTHING to the vault. The plan is the shared read helper `Session::bulk_reclassify_outflow_plan`
/// — it excludes missing-price rows [#a tax-safety] and reports them as `excluded_missing_price`.
pub fn bulk_reclassify_outflow_plan(
    vault_path: &Path,
    pp: &Passphrase,
    filter: BulkFilter,
) -> Result<BulkReclassifyOutflowPlan, CliError> {
    let session = Session::open(vault_path, pp)?;
    session.bulk_reclassify_outflow_plan(filter)
}

/// bulk-reclassify-outflow (Cycle 5) — Phase 2 (write): atomically reclassify every `out_event` as a
/// `Dispose{kind}` with a PER-ROW auto-FMV as ESTIMATED proceeds, AND mark each in the `bulk_estimated`
/// side-table, then a SINGLE `save`. Its OWN append-loop (mirrors `apply_bulk_classify_inbound_income`;
/// the CLI CANNOT reach the tui-edit `persist_bulk_decisions` — dependency cycle, R0-I1 of Cycle 4).
///
/// **[#a defense-in-depth]** the fmv is RE-DERIVED per-row via `fmv_of(date, sat)`, never trusting a
/// threaded number: `let Some(fmv) = … else { continue };`. The dispatch derives `out_events` from
/// `plan.included` (the fmv-`Some` rows only), so every id resolves — and a missing-price row can NEVER
/// be emitted as a Sell with fabricated `0`/bogus proceeds (a SILENT misreport), even if a future caller
/// passed a non-plan id. `fee_usd: None` always (the on-chain `fee_sat` still flows via resolve.rs
/// regardless — a uniform USD disposition-fee across heterogeneous txns is meaningless); `donee: None`
/// (Dispose has none). `kind` is UNIFORM across the batch. Bare `?`-before-`save`: a mid-batch failure
/// returns before `save` → the in-memory session is discarded, so NEITHER the appends NOR the side-table
/// marks land [R0-M2]. Returns the number reclassified.
pub fn apply_bulk_reclassify_outflow(
    vault_path: &Path,
    pp: &Passphrase,
    out_events: Vec<EventId>,
    kind: DisposeKind,
    now: OffsetDateTime,
) -> Result<usize, CliError> {
    let mut session = Session::open(vault_path, pp)?;
    let prices = session.prices();
    let events = load_all(session.conn())?;
    let index: std::collections::HashMap<&EventId, &btctax_core::LedgerEvent> =
        events.iter().map(|e| (&e.id, e)).collect();
    // Provenance stamp (the batch made-date) recorded on each side-table row.
    let marked_at = tax_date(now, UtcOffset::UTC).to_string();
    let mut n = 0usize;
    for out_event in &out_events {
        let Some(ev) = index.get(out_event) else {
            continue;
        };
        let EventPayload::TransferOut(t) = &ev.payload else {
            continue;
        };
        let date = tax_date(ev.utc_timestamp, ev.original_tz);
        // #a defense-in-depth: re-derive the fmv; a missing-price row is skipped, NEVER emitted as a
        // Dispose with fabricated proceeds. Makes a fabricated-proceeds Sell structurally unreachable.
        let Some(fmv) = btctax_core::price::fmv_of(prices, date, t.sat) else {
            continue;
        };
        let payload = EventPayload::ReclassifyOutflow(ReclassifyOutflow {
            transfer_out_event: out_event.clone(),
            as_: OutflowClass::Dispose { kind },
            principal_proceeds_or_fmv: fmv,
            fee_usd: None,
            donee: None,
        });
        // `?` on a mid-batch failure returns before `save` — the in-memory session is discarded, so
        // nothing lands on disk (CLI atomicity; the TUI path instead ROLLS BACK).
        append_decision(session.conn(), payload, now, UtcOffset::UTC, None)?;
        // Flag the ESTIMATED proceeds in the side-table (same in-memory conn, flushed by the single
        // save below; discarded together with the append on any mid-batch failure — [R0-M2]).
        crate::bulk_estimated::mark(session.conn(), out_event, &marked_at)?;
        n += 1;
    }
    session.save()?;
    Ok(n)
}

/// bulk-resolve-conflict D2 — Phase 1 (read): open the session and compute the bulk resolve-conflict
/// plan. Two-phase by design (mirrors `bulk_link_plan`): this read phase renders NOTHING to the vault,
/// so the interactive `y/N` confirmation stays a thin, untested shell in the `main.rs` dispatch. The
/// plan is the shared read helper `Session::bulk_resolve_conflict_plan` (D1). The session (and its
/// VaultLock) is dropped on return, before the confirmation prompt runs.
pub fn bulk_resolve_conflict_plan(
    vault_path: &Path,
    pp: &Passphrase,
) -> Result<BulkResolvePlan, CliError> {
    let session = Session::open(vault_path, pp)?;
    session.bulk_resolve_conflict_plan()
}

/// bulk-resolve-conflict D2 — Phase 2 (write), ACCEPT: atomically append one `SupersedeImport` per
/// conflict (adopt each `new_payload` onto its target id), then a SINGLE `save`. All-or-nothing: a
/// mid-batch `append_decision` failure returns `Err` BEFORE the save, and the local `Session` is
/// dropped with nothing written — the exact one-session / N-append / one-save atomicity of
/// `apply_bulk_link_transfer`. Mirrors the shipped single-item split `accept_conflict`/`reject_conflict`
/// [R0-I1 — NO `ResolveKind` in the CLI; it lives only in btctax-tui-edit]. Returns the number accepted.
pub fn apply_bulk_accept_conflicts(
    vault_path: &Path,
    pp: &Passphrase,
    conflict_events: Vec<EventId>,
    now: OffsetDateTime,
) -> Result<usize, CliError> {
    let mut session = Session::open(vault_path, pp)?;
    for conflict_event in &conflict_events {
        let payload = EventPayload::SupersedeImport(SupersedeImport {
            conflict_event: conflict_event.clone(),
        });
        // `?` on a mid-batch failure returns before `save` — the in-memory session is discarded, so
        // nothing lands on disk (CLI atomicity; the TUI path instead ROLLS BACK via persist_bulk_decisions).
        append_decision(session.conn(), payload, now, UtcOffset::UTC, None)?;
    }
    session.save()?;
    Ok(conflict_events.len())
}

/// bulk-resolve-conflict D2 — Phase 2 (write), REJECT: atomically append one `RejectImport` per
/// conflict (keep each target's current payload; clear the blocker), then a SINGLE `save`. Same
/// all-or-nothing CLI atomicity as `apply_bulk_accept_conflicts`. Returns the number rejected.
pub fn apply_bulk_reject_conflicts(
    vault_path: &Path,
    pp: &Passphrase,
    conflict_events: Vec<EventId>,
    now: OffsetDateTime,
) -> Result<usize, CliError> {
    let mut session = Session::open(vault_path, pp)?;
    for conflict_event in &conflict_events {
        let payload = EventPayload::RejectImport(RejectImport {
            conflict_event: conflict_event.clone(),
        });
        append_decision(session.conn(), payload, now, UtcOffset::UTC, None)?;
    }
    session.save()?;
    Ok(conflict_events.len())
}

/// bulk-void D2 — Phase 1 (read): open the session and compute the bulk-void plan. Two-phase by design
/// (mirrors `bulk_resolve_conflict_plan`): this read phase renders NOTHING to the vault, so the
/// interactive `y/N` confirmation stays a thin, untested shell in the `main.rs` dispatch. The plan is
/// the shared read helper `Session::bulk_void_plan` (D1) — the SINGLE `voidable_decisions` predicate,
/// which OMITS effective allocations (#7). The session (and its VaultLock) is dropped on return.
pub fn bulk_void_plan(vault_path: &Path, pp: &Passphrase) -> Result<BulkVoidPlan, CliError> {
    let session = Session::open(vault_path, pp)?;
    session.bulk_void_plan()
}

/// bulk-void D2 — Phase 2 (write): atomically append one `VoidDecisionEvent` per `target` AND, for each
/// `LotSelection` target, clear its optimizer attestation (`optimize_attest::clear`), then a SINGLE
/// `save`. All-or-nothing: a mid-batch `append_decision` / `clear` failure returns `Err` BEFORE the
/// save, and the local `Session` is dropped with nothing written — the exact one-session / N-append /
/// one-save atomicity of `apply_bulk_accept_conflicts` (the TUI path instead ROLLS BACK explicitly via
/// `persist_bulk_void`).
///
/// # [R0-M3] the ONLY CLI-layer #7 defense
/// `targets` MUST be exactly the `bulk_void_plan` rows (predicate-filtered), re-derived from the vault
/// inside the dispatch — NEVER raw `--ref` ids. The single CLI `void` does NO `effective_alloc` check,
/// so a raw-id bulk path would let a caller void an effective allocation → Hard `DecisionConflict`.
/// Each target is `(target_event_id, disposal_to_clear)` carried straight from the plan row. Returns
/// the number voided.
pub fn apply_bulk_void(
    vault_path: &Path,
    pp: &Passphrase,
    targets: Vec<(EventId, Option<EventId>)>,
    now: OffsetDateTime,
) -> Result<usize, CliError> {
    let mut session = Session::open(vault_path, pp)?;
    // Map ReclassifyOutflow decision id → its transfer_out_event, so voiding one clears its
    // bulk_estimated `[est]` flag — symmetric with single `void` + TUI persist_bulk_void [WB — R0-I1
    // closed on the CLI bulk path]. Idempotent clear; O(n) build, void is infrequent.
    let events = load_all(session.conn())?;
    let reclass_map: std::collections::HashMap<EventId, EventId> = events
        .iter()
        .filter_map(|e| match &e.payload {
            EventPayload::ReclassifyOutflow(ro) => {
                Some((e.id.clone(), ro.transfer_out_event.clone()))
            }
            _ => None,
        })
        .collect();
    // BG-D9 Task 8: warn per promoted target (against the pre-batch snapshot) about the prior-year
    // rewrites the floor→$0 revert re-exposes — before recording, non-gating.
    for (target_event_id, _) in &targets {
        for line in promote_void_advisory_lines(&session, &events, target_event_id, now) {
            println!("{line}");
        }
    }
    for (target_event_id, disposal_to_clear) in &targets {
        // `?` on a mid-batch failure returns before `save` — the in-memory session is discarded, so
        // nothing lands on disk (CLI atomicity; the TUI path instead ROLLS BACK via persist_bulk_void).
        append_decision(
            session.conn(),
            EventPayload::VoidDecisionEvent(VoidDecisionEvent {
                target_event_id: target_event_id.clone(),
            }),
            now,
            UtcOffset::UTC,
            None,
        )?;
        // Per-LotSelection side-effect: clear its disposal's optimizer attestation ATOMICALLY (same
        // in-memory conn, flushed by the single save below). Idempotent — clearing an absent row is Ok.
        if let Some(disposal) = disposal_to_clear {
            crate::optimize_attest::clear(session.conn(), disposal)?;
        }
        // Symmetric ReclassifyOutflow side-effect: clear its bulk_estimated flag in the same batch.
        if let Some(out_event) = reclass_map.get(target_event_id) {
            crate::bulk_estimated::clear(session.conn(), out_event)?;
        }
    }
    session.save()?;
    Ok(targets.len())
}

/// FR6/TP7: confirm a self-transfer. `target` is a destination `TransferIn` event (`--to-event`) or a
/// known wallet (`--to-wallet`); the engine relocates the lots carrying basis + acquired_at.
pub fn link_transfer(
    vault_path: &Path,
    pp: &Passphrase,
    out_ref: &str,
    target: TransferTarget,
    now: OffsetDateTime,
) -> Result<EventId, CliError> {
    let out_event = parse_event_id(out_ref)?;
    let mut session = Session::open(vault_path, pp)?;
    let payload = EventPayload::TransferLink(TransferLink {
        out_event,
        in_event_or_wallet: target,
    });
    append_and_save(&mut session, payload, now)
}

/// self-transfer-passthrough C3 — Phase 1 (read): compute the self-transfer match proposals on the HELD
/// session (READ-ONLY; appends/persists NOTHING). Mirrors `bulk_link_plan`: the shared read helper is
/// `Session::self_transfer_match_plan`; the session (and its VaultLock) is dropped on return.
pub fn self_transfer_match_plan(
    vault_path: &Path,
    pp: &Passphrase,
) -> Result<Vec<MatchProposal>, CliError> {
    let session = Session::open(vault_path, pp)?;
    session.self_transfer_match_plan()
}

/// self-transfer-passthrough C3 — Phase 2 (write), DROP: append one `SelfTransferPassthrough` decision
/// mapping BOTH legs to `Op::Skip` (non-taxable passthrough). Mirrors `link_transfer` (one append + save).
/// The RELOCATE case is NOT here — it routes to the EXISTING `link_transfer(out, InEvent(in))` (G-RELOCATE-REUSE).
pub fn apply_self_transfer_passthrough(
    vault_path: &Path,
    pp: &Passphrase,
    in_ref: &str,
    out_ref: &str,
    now: OffsetDateTime,
) -> Result<EventId, CliError> {
    let in_event = parse_event_id(in_ref)?;
    let out_event = parse_event_id(out_ref)?;
    let mut session = Session::open(vault_path, pp)?;
    let payload = EventPayload::SelfTransferPassthrough(SelfTransferPassthrough {
        in_event,
        out_event,
    });
    append_and_save(&mut session, payload, now)
}

/// FR7/§7.4: build a Path-B safe-harbor allocation that seeds from the **pre-2025 residue** (the
/// 2025-01-01 Universal-pool position), so it conserves against the engine's allocation-independent
/// conservation guard.
///
/// I-1: the engine's guard compares `Σ alloc.lots.sat`/`usd_basis` to `transition::universal_snapshot`
/// — a pre-2025-ONLY fold of the Universal pool (resolve.rs §7.4, step 3). The FULL projection's
/// `state.lots` reflects POST-2025-disposal residuals (a 2025 Sell consumes pre-2025 lots in FIFO), so
/// seeding from them would yield `alloc_sat < snap.held_sat` → hard `SafeHarborUnconservable` → Path A,
/// breaking the normal workflow. Instead we re-project a pre-2025-only event subset and read ITS lots:
///   - keep ONLY import events whose tax-date `< 2025-01-01` (drop every 2025+ acquire/dispose/transfer);
///   - keep ALL reconciliation decisions/conflicts — they SHAPE the residue (a 2026 `ClassifyInbound`
///     supplies a pre-2025 `TransferIn`'s basis; `ReclassifyOutflow`/`TransferLink` consume/relocate a
///     pre-2025 lot) — and carry a 2026 made-date, so they must NOT be tax-date-filtered;
///   - DROP any prior `SafeHarborAllocation` so the residue stays allocation-INDEPENDENT (matches
///     `universal_snapshot`, which never applies a seed) → re-allocation is idempotent.
///
/// This subset re-runs the IDENTICAL `fold_event` arms the engine's snapshot uses, so the totals match
/// exactly (the only difference, Path A's per-wallet relocation, preserves sat/basis 1:1; `finalize`
/// attributes Universal-pool lots by `lot.wallet`). For `ActualPosition` the per-wallet assignment falls
/// out of those residue lots' `wallet` (= the wallet holding each lot at 2025-01-01). `ProRata` still
/// seeds from these actuals; a true cross-wallet pro-rata redistribution is a manual-input refinement
/// (Open question O4). The engine's `SafeHarborUnconservable` guard remains the backstop for any residual
/// drift (e.g. a rare self-transfer straddling the 2025 boundary) — fails closed, never silent wrong tax.
pub fn safe_harbor_allocate(
    vault_path: &Path,
    pp: &Passphrase,
    method: AllocMethod,
    attested: bool,
    now: OffsetDateTime,
) -> Result<EventId, CliError> {
    let mut session = Session::open(vault_path, pp)?;

    // D-8: refuse recording an allocation while a pre-2025 conservative-filing tranche is on file
    // (v1 makes them mutually exclusive). Chokepoint shared with `safe_harbor_attest` and both TUI
    // persist sites; the engine `SafeHarborUnconservable` backstop is the guarantee behind it.
    crate::cmd::tranche::guard_allocation_vs_tranche(&load_all(session.conn())?)?;

    // R-M7b / D3: attestation gate — EARLY, before empty-lots / conservation work.
    // A SafeHarborAllocation permanently records pre2025_method and is irrevocable; require an
    // explicit declared+attested pre-2025 method so the commitment is a deliberate, attested choice
    // rather than a silent FIFO default. Note: the `attested` parameter to this function is
    // `timely_allocation_attested` (§5.02(4)) — a separate attestation; do not conflate the two.
    {
        let cli_cfg = session.config()?;
        if !cli_cfg.pre2025_method_attested {
            let m = match cli_cfg.pre2025_method {
                LotMethod::Fifo => "fifo",
                LotMethod::Lifo => "lifo",
                LotMethod::Hifo => "hifo",
            };
            return Err(CliError::Usage(format!(
                "refusing to record a safe-harbor allocation under an UNDECLARED pre-2025 method \
                 ({m}); a safe-harbor allocation permanently records the method used to reconstruct \
                 your pre-2025 basis. Declare your filed method first: \
                 config --set-pre2025-method {m} --attest-pre2025-method"
            )));
        }
    }

    // Pre-2025 residue + the recorded `pre2025_method` come from the single shared read helper
    // (`Session::safe_harbor_residue`, D3) — the same source the TUI allocate opener uses. It reads
    // config ONCE, so the returned method is STRUCTURALLY the one the residue was projected under.
    let (lots, pre2025_method) = session.safe_harbor_residue()?;
    if lots.is_empty() {
        return Err(CliError::Usage(
            "no pre-2025 lots to allocate (Path A applies; safe harbor unnecessary)".into(),
        ));
    }
    let payload = EventPayload::SafeHarborAllocation(SafeHarborAllocation {
        lots,
        as_of_date: TRANSITION_DATE,
        method,
        timely_allocation_attested: attested,
        // §A.7: the recorded pre-2025 method is the SAME config method the residue above was projected
        // under (both from the one `safe_harbor_residue` config read), so the listed lots conserve
        // against the engine's method-aware snapshot. Immutable thereafter; a later live-config change
        // fires the hard `Pre2025MethodConflictsAllocation` rather than silently breaking conservation.
        pre2025_method,
    });
    append_and_save(&mut session, payload, now)
}

/// §A.4 / SPEC Task 5: emit a `LotSelection` decision for a specific disposal. `disposal_ref` is the
/// canonical `EventId` string of the disposal event; `picks` is at least one `LotPick`. The engine
/// validates completeness (Σsat == disposal principal) and lot existence in the fold; this function
/// only appends the decision — it does NOT attempt to validate up-front (that would require a full
/// projection, which the engine always does). Identification must exist by the time of sale (§1.1012-1(j)).
pub fn select_lots(
    vault_path: &Path,
    pp: &Passphrase,
    disposal_ref: &str,
    picks: Vec<LotPick>,
    now: OffsetDateTime,
) -> Result<EventId, CliError> {
    let disposal_event = parse_event_id(disposal_ref)?;
    if picks.is_empty() {
        return Err(CliError::Usage(
            "select-lots needs at least one --from <lot-id>:<sat>".into(),
        ));
    }
    let mut session = Session::open(vault_path, pp)?;
    append_and_save(
        &mut session,
        EventPayload::LotSelection(LotSelection {
            disposal_event,
            lots: picks,
        }),
        now,
    )
}

/// §A.4 / SPEC Task 5: batch-import `LotSelection` decisions from a CSV file.
///
/// CSV format: `disposal_ref,origin_event_id,split_sequence,sat` (header required, validated loudly).
/// Rows sharing a `disposal_ref` are grouped into a single `LotSelection` (one decision per disposal);
/// grouping is by BTreeMap on the canonical disposal_ref string → deterministic order (NFR4).
/// All decisions are written in one session → one `save()`.
pub fn import_selections(
    vault_path: &Path,
    pp: &Passphrase,
    csv_path: &Path,
    now: OffsetDateTime,
) -> Result<Vec<EventId>, CliError> {
    let mut rdr = csv::ReaderBuilder::new()
        .has_headers(true)
        .from_path(csv_path)?;
    {
        let hdr = rdr.headers()?;
        let cols: Vec<&str> = hdr.iter().collect();
        if cols != ["disposal_ref", "origin_event_id", "split_sequence", "sat"] {
            return Err(CliError::Usage(format!(
                "import-selections CSV header must be \
                 disposal_ref,origin_event_id,split_sequence,sat; got {cols:?}"
            )));
        }
    }
    // Group picks by disposal_ref; BTreeMap gives deterministic iteration order (NFR4).
    let mut by_disposal: std::collections::BTreeMap<String, Vec<LotPick>> =
        std::collections::BTreeMap::new();
    for rec in rdr.records() {
        let rec = rec?;
        let disposal_ref = rec
            .get(0)
            .ok_or_else(|| CliError::Usage("missing disposal_ref".into()))?
            .to_string();
        let origin_str = rec
            .get(1)
            .ok_or_else(|| CliError::Usage("missing origin_event_id".into()))?;
        let split_str = rec
            .get(2)
            .ok_or_else(|| CliError::Usage("missing split_sequence".into()))?;
        let sat_str = rec
            .get(3)
            .ok_or_else(|| CliError::Usage("missing sat".into()))?;
        let origin_event_id = parse_event_id(origin_str)?;
        let split_sequence = split_str
            .trim()
            .parse::<u32>()
            .map_err(|e| CliError::Usage(format!("bad split_sequence {split_str:?}: {e}")))?;
        let sat = sat_str
            .trim()
            .parse::<i64>()
            .map_err(|e| CliError::Usage(format!("bad sat {sat_str:?}: {e}")))?;
        by_disposal.entry(disposal_ref).or_default().push(LotPick {
            lot: LotId {
                origin_event_id,
                split_sequence,
            },
            sat,
        });
    }
    let mut session = Session::open(vault_path, pp)?;
    let mut ids = Vec::new();
    for (disposal_ref, lots) in by_disposal {
        let disposal_event = parse_event_id(&disposal_ref)?;
        let id = append_decision(
            session.conn(),
            EventPayload::LotSelection(LotSelection {
                disposal_event,
                lots,
            }),
            now,
            UtcOffset::UTC,
            None,
        )?;
        ids.push(id);
    }
    session.save()?;
    Ok(ids)
}

/// M3 / SPEC A.1 / A.5(a): append a `MethodElection` decision — the forward standing order.
///
/// This is an EVENT, not a config flag mutation. The standing order is irrevocable (unless voided)
/// and governs all method-honoring disposals on/after `effective_from`. Back-dating is blocked by
/// the engine (`MethodElectionBackdated` hard blocker when `effective_from < made-date`).
///
/// `wallet` carries the optional per-ACCOUNT scope (§A.5(a)): `None` = a GLOBAL election (unchanged);
/// `Some(WalletId::Exchange{..})` = that exchange account's method. [R0-M3] Only `Exchange` wallets
/// are electable (a `self:LABEL` scope is rejected), and the account MUST be one the vault already
/// knows — an unknown/typo'd account is rejected LOUDLY so it can't silently create a dead election
/// the user believes is in force. [R0-M1] The scope lives in the `MethodElection` PAYLOAD, not the
/// `LedgerEvent.wallet` column (`append_decision` passes `None` for the event-level wallet).
///
/// When `effective_from` is `None`, defaults to the decision's made-date (`now` in UTC), which
/// satisfies the `effective_from >= made-date` invariant by construction.
pub fn set_forward_method(
    vault_path: &Path,
    pp: &Passphrase,
    m: LotMethod,
    wallet: Option<WalletId>,
    effective_from: Option<TaxDate>,
    now: OffsetDateTime,
) -> Result<EventId, CliError> {
    let effective_from = effective_from.unwrap_or_else(|| now.to_offset(UtcOffset::UTC).date());
    let mut session = Session::open(vault_path, pp)?;
    // [R0-M3] Validate an explicit --exchange scope BEFORE appending: only Exchange wallets are
    // electable, and the account must be present in the loaded events (enumerate distinct
    // WalletId::Exchange). A silent dead election (typo'd provider/account) would mislead the user
    // into thinking a method is in force when it isn't — so reject unknown scopes loudly.
    if let Some(w) = &wallet {
        let WalletId::Exchange { .. } = w else {
            return Err(CliError::Usage(format!(
                "--exchange must name an exchange account (exchange:PROVIDER:ACCOUNT); \
                 {w:?} is not electable — a method election is a brokerage-account concept"
            )));
        };
        let events = load_all(session.conn())?;
        let known: std::collections::BTreeSet<WalletId> = events
            .iter()
            .filter_map(|e| e.wallet.clone())
            .filter(|w| matches!(w, WalletId::Exchange { .. }))
            .collect();
        if !known.contains(w) {
            let names: Vec<String> = known
                .iter()
                .map(|k| match k {
                    WalletId::Exchange { provider, account } => {
                        format!("exchange:{provider}:{account}")
                    }
                    other => format!("{other:?}"),
                })
                .collect();
            return Err(CliError::Usage(format!(
                "--exchange {w:?} is not a known exchange account in this vault \
                 (accounts are created by importing events). Known exchange accounts: [{}]",
                names.join(", ")
            )));
        }
    }
    append_and_save(
        &mut session,
        EventPayload::MethodElection(MethodElection {
            effective_from,
            method: m,
            wallet,
        }),
        now,
    )
}

/// FR7: attest an existing allocation. Events are immutable, so attestation = void the single live prior
/// allocation and re-append it with `timely_allocation_attested = true`. Attestation only cures a
/// §5.02(4) TIME-BAR; it is NOT valid on an already-effective allocation (which needs nothing) nor on one
/// that fails CONSERVATION (which needs a corrected allocation, not an attestation).
///
/// Uses `Session::load_events_and_project` to load the event log exactly once — the old pattern
/// (separate `load_all(session.conn())` + `session.project()`) loaded the same DB rows twice.
pub fn safe_harbor_attest(
    vault_path: &Path,
    pp: &Passphrase,
    now: OffsetDateTime,
) -> Result<EventId, CliError> {
    let mut session = Session::open(vault_path, pp)?;
    let (events, state, _cfg) = session.load_events_and_project()?;

    // D-8: refuse re-appending an allocation while a pre-2025 tranche is on file (defense-in-depth —
    // the guarded record paths already keep them apart; this closes any future unguarded coexistence).
    crate::cmd::tranche::guard_allocation_vs_tranche(&events)?;

    // Eng-I1 / I-2(a): EXCLUDE voided allocations from the single-allocation guard, so the legitimate
    // allocate→inert→void→re-allocate→attest workflow (which leaves an OLD, voided allocation in the log)
    // is not blocked by "multiple allocations present." Build the voided-target set from `VoidDecisionEvent`s
    // (mirrors resolve.rs pass-1 step 1a) and keep only LIVE (non-voided) allocations.
    let voided: std::collections::BTreeSet<EventId> = events
        .iter()
        .filter_map(|e| match &e.payload {
            EventPayload::VoidDecisionEvent(v) => Some(v.target_event_id.clone()),
            _ => None,
        })
        .collect();
    let allocs: Vec<(&EventId, &SafeHarborAllocation)> = events
        .iter()
        .filter(|e| !voided.contains(&e.id))
        .filter_map(|e| match &e.payload {
            EventPayload::SafeHarborAllocation(a) => Some((&e.id, a)),
            _ => None,
        })
        .collect();
    let (prior_id, prior) = match allocs.as_slice() {
        [one] => (one.0.clone(), one.1.clone()),
        [] => {
            return Err(CliError::Usage(
                "no allocation to attest; run `safe-harbor allocate` first".into(),
            ))
        }
        _ => {
            return Err(CliError::Usage(
                "multiple live allocations present; void the stale one before attesting".into(),
            ))
        }
    };
    if prior.timely_allocation_attested {
        return Err(CliError::Usage("allocation is already attested".into()));
    }

    // I-2(b) / N-2: classify the prior allocation's CURRENT status via the projection loaded above
    // (`load_events_and_project`), reading the engine's own effectiveness verdict (the blockers it
    // stamps onto `prior_id`):
    //   * `SafeHarborUnconservable` (hard) → attestation CANNOT cure it (only a corrected allocation can).
    //   * `SafeHarborTimebar` (advisory)   → inert PURELY because of the §5.02(4) bar → attestation cures it.
    //   * neither                          → ALREADY EFFECTIVE → attesting would Void an effective allocation
    //     (→ irrevocable `decision_conflicts`, §7.4) AND append a second effective allocation (→ two effective
    //     → Path A, irrecoverable). Refuse and advise `verify` (NOT "void the effective one").
    let blocked_with = |k: BlockerKind| {
        state
            .blockers
            .iter()
            .any(|b| b.event.as_ref() == Some(&prior_id) && b.kind == k)
    };
    let unconservable = blocked_with(BlockerKind::SafeHarborUnconservable);
    let timebarred = blocked_with(BlockerKind::SafeHarborTimebar);
    // (closure's borrow of `prior_id` ends here, so the move into the Void below is sound.)
    if unconservable {
        return Err(CliError::Usage(
            "allocation fails conservation (not a time-bar); re-run `safe-harbor allocate` to rebuild it — attestation cannot cure conservation".into(),
        ));
    }
    if !timebarred {
        return Err(CliError::Usage(
            "allocation already effective; no attestation needed — run `verify`".into(),
        ));
    }

    // Inert PURELY due to a time-bar → attestation cures it. Append Void(prior) + a re-attested copy.
    // (N2: same `now` for both; `decision_seq` orders/distinguishes them — Void first, then re-attest.)
    append_decision(
        session.conn(),
        EventPayload::VoidDecisionEvent(VoidDecisionEvent {
            target_event_id: prior_id,
        }),
        now,
        UtcOffset::UTC,
        None,
    )?;
    let attested = SafeHarborAllocation {
        timely_allocation_attested: true,
        ..prior
    };
    let id = append_decision(
        session.conn(),
        EventPayload::SafeHarborAllocation(attested),
        now,
        UtcOffset::UTC,
        None,
    )?;
    session.save()?;
    Ok(id)
}

/// SE-completion Chunk C (D3): flip `business` (and optionally `kind`) on an already-imported
/// `Income` event. Enables SE-tax treatment for professional miners / stakers whose River (and
/// other adapter) income arrives with `business: false` hard-coded at ingest time.
///
/// The engine validates the target at collection time: if the referenced event does not exist OR its
/// effective payload is not `Income`, a Hard `DecisionConflict` blocker fires and the decision is
/// excluded (not silently inert, not a panic). To correct a `TransferIn` row use `classify-inbound-income`
/// instead. **DecisionConflict is Hard — to re-decide, `void` the prior decision then re-issue.**
pub fn reclassify_income(
    vault_path: &Path,
    pp: &Passphrase,
    income_ref: &str,
    business: bool,
    kind: Option<IncomeKind>,
    now: OffsetDateTime,
) -> Result<EventId, CliError> {
    let income_event = parse_event_id(income_ref)?;
    let mut session = Session::open(vault_path, pp)?;
    let payload = EventPayload::ReclassifyIncome(ReclassifyIncome {
        income_event,
        business,
        kind,
    });
    guard_decision_conflict(&session, &payload, now)?;
    append_and_save(&mut session, payload, now)
}

/// Chunk 3b D2: store Form 8283 Section-B donation + appraiser details in the
/// `donation_details` side-table for the donation identified by `event_ref`.
///
/// **[R0-M] Projected-removals validation:** the `event_ref` must resolve to a
/// `Removal { kind == Donation }` in the PROJECTED `state.removals` — NOT by scanning the raw
/// event log. A ref to a non-donation removal (Gift) or to an event that produces no removal
/// (e.g. an Acquire) → `CliError::Usage` with a clear message. No decision is appended; this
/// is a side-table write (last-write-wins upsert, like `tax_profile::set`).
pub fn set_donation_details(
    vault_path: &Path,
    pp: &Passphrase,
    event_ref: &str,
    details: DonationDetails,
) -> Result<(), CliError> {
    let event_id = parse_event_id(event_ref)?;
    let mut session = Session::open(vault_path, pp)?;
    let (state, _cfg) = session.project()?;

    // [R0-M] Validate against the PROJECTED state.removals.
    let matched_removal = state.removals.iter().find(|r| r.event == event_id);
    match matched_removal {
        None => {
            return Err(CliError::Usage(format!(
                "not a donation / not found: {event_ref:?} does not match any removal in the \
                 projected ledger. If this is an outflow you intend to donate, first classify it: \
                 `reconcile reclassify-outflow <out-ref> --as-kind donate --amount <usd> …` — once \
                 classified, its ref appears in removals.csv (the 'event' column)."
            )));
        }
        Some(r) if r.kind != RemovalKind::Donation => {
            return Err(CliError::Usage(format!(
                "not a donation: {event_ref:?} is a {:?} removal, not a Donation",
                r.kind
            )));
        }
        Some(_) => {} // confirmed Donation — proceed
    }

    crate::donation_details::set(session.conn(), &event_id, &details)?;
    session.save()?;
    Ok(())
}

/// Chunk 3b D2: read back stored `DonationDetails` for the donation identified by `event_ref`.
/// Returns `None` when no details have been stored yet. Read-only — no projection needed.
pub fn show_donation_details(
    vault_path: &Path,
    pp: &Passphrase,
    event_ref: &str,
) -> Result<Option<DonationDetails>, CliError> {
    let event_id = parse_event_id(event_ref)?;
    let session = Session::open(vault_path, pp)?;
    crate::donation_details::get(session.conn(), &event_id)
}

#[cfg(test)]
mod tests {
    use super::*;
    use btctax_core::event::{Acquire, BasisSource, TransferOut};
    use btctax_core::persistence::append_import_batch;
    use btctax_core::{
        EventId, LedgerEvent, OutflowClass, ReclassifyOutflow, Source, SourceRef, WalletId,
    };
    use btctax_store::Passphrase;
    use rust_decimal_macros::dec;
    use time::macros::date;

    fn pp() -> Passphrase {
        Passphrase::new("test-pass".into())
    }

    // ── UX-P4-4(d): the --amount FMV sanity advisory (pure decision; mutation-proven) ──

    /// A `--amount` entered as the sats count (5_000_000 for 0.05 BTC) dwarfs 100x the ~$3,044
    /// market value → a non-fatal warning that names --amount and the sats mistake.
    #[test]
    fn amount_fmv_advisory_warns_on_sats_as_dollars() {
        let line = amount_fmv_advisory(
            dec!(5000000),
            Some(dec!(3044.48)),
            dec!(0.05),
            date!(2024 - 07 - 03),
        )
        .expect("a sats-as-dollars amount must warn");
        assert!(
            line.contains("warning")
                && line.contains("--amount")
                && line.to_lowercase().contains("sats"),
            "warning must name --amount + the sats mistake: {line}"
        );
    }

    /// A legitimate FMV — even a few multiples above the market value — does NOT warn.
    #[test]
    fn amount_fmv_advisory_silent_on_plausible_amount() {
        assert!(amount_fmv_advisory(
            dec!(3044.48),
            Some(dec!(3044.48)),
            dec!(0.05),
            date!(2024 - 07 - 03)
        )
        .is_none());
        assert!(amount_fmv_advisory(
            dec!(9000),
            Some(dec!(3044.48)),
            dec!(0.05),
            date!(2024 - 07 - 03)
        )
        .is_none());
    }

    /// The threshold is a STRICT 100x: exactly 100x is silent, a cent over warns.
    #[test]
    fn amount_fmv_advisory_boundary_is_strict_100x() {
        let mv = dec!(3000);
        assert!(
            amount_fmv_advisory(dec!(300000), Some(mv), dec!(0.05), date!(2024 - 07 - 03))
                .is_none(),
            "exactly 100x must not warn"
        );
        assert!(
            amount_fmv_advisory(dec!(300000.01), Some(mv), dec!(0.05), date!(2024 - 07 - 03))
                .is_some(),
            "just over 100x must warn"
        );
    }

    /// A dust market value that rounds to $0 yields no meaningful ratio → no warning.
    #[test]
    fn amount_fmv_advisory_skips_dust_that_rounds_to_zero() {
        assert!(amount_fmv_advisory(
            dec!(100),
            Some(dec!(0)),
            dec!(0.00000001),
            date!(2024 - 07 - 03)
        )
        .is_none());
    }

    /// No price for the date ⇒ the check cannot run: emit a NOTE (never silent), not a warning.
    #[test]
    fn amount_fmv_advisory_notes_missing_price() {
        let line = amount_fmv_advisory(dec!(3000), None, dec!(0.05), date!(2024 - 07 - 03))
            .expect("no-price must produce a note");
        assert!(
            line.contains("no BTC price") && !line.contains("warning"),
            "no-price must be a note, not a warning: {line}"
        );
    }

    /// UX-P4-4(b) review r1 M3: `tz_label` renders UTC and signed non-UTC offsets — including the
    /// subtle `h==0, m<0` (UTC−00:30) sign arm and non-zero minutes — so a sign-handling regression
    /// in the receipt-date refusal message reds here.
    #[test]
    fn tz_label_renders_utc_and_signed_offsets() {
        use time::macros::offset;
        assert_eq!(tz_label(UtcOffset::UTC), "UTC");
        assert_eq!(tz_label(offset!(-05:00)), "UTC-05:00");
        assert_eq!(tz_label(offset!(+05:45)), "UTC+05:45");
        assert_eq!(tz_label(offset!(-00:30)), "UTC-00:30");
    }

    /// Build a minimal `DonationDetails` for tests (synthetic — no real PII).
    fn test_details() -> DonationDetails {
        DonationDetails {
            donee_name: "Test Charity".into(),
            donee_address: None,
            donee_ein: Some("12-3456789".into()),
            appraiser_name: "Test Appraiser".into(),
            appraiser_address: None,
            appraiser_tin: Some("987654321".into()),
            appraiser_ptin: None,
            appraiser_qualifications: Some("Certified bitcoin appraiser".into()),
            appraisal_date: Some(date!(2025 - 06 - 01)),
            fmv_method_override: None,
        }
    }

    /// Create a vault + Acquire + TransferOut + ReclassifyOutflow(Donate). Returns
    /// (vault_path, donation_event_id, acquire_event_id) where donation_event_id is the
    /// TransferOut EventId (which becomes the Removal.event in the projected ledger).
    /// PRIVACY: synthetic values only.
    fn setup_donation_vault(dir: &tempfile::TempDir) -> (std::path::PathBuf, EventId, EventId) {
        use crate::Session;

        let vault_path = dir.path().join("vault.pgp");
        let mut session = Session::create(&vault_path, &pp()).unwrap();

        // Fixed timestamps (deterministic, reproducible). Both pre-2025 (< 2025-01-01 =
        // Unix 1_735_689_600) to stay in the Universal-pool path (no per-wallet allocation needed).
        // ts_acq ≈ 2023-11-14, ts_out ≈ 2024-07-03.
        let ts_acq = time::OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap();
        let ts_out = time::OffsetDateTime::from_unix_timestamp(1_720_000_000).unwrap();

        // Both events use the same exchange wallet so lots can be consumed from the same pool.
        let wallet = WalletId::Exchange {
            provider: "coinbase".into(),
            account: "default".into(),
        };

        // Acquire 2_000_000 sats at $60,000 cost basis.
        let acq_id = EventId::import(Source::Coinbase, SourceRef::new("in|test-acq-001"));
        let acq_ev = LedgerEvent {
            id: acq_id.clone(),
            utc_timestamp: ts_acq,
            original_tz: UtcOffset::UTC,
            wallet: Some(wallet.clone()),
            payload: EventPayload::Acquire(Acquire {
                sat: 2_000_000,
                usd_cost: dec!(60000),
                fee_usd: dec!(0),
                basis_source: BasisSource::ComputedFromCost,
            }),
        };
        append_import_batch(session.conn(), &[acq_ev]).unwrap();

        // TransferOut 500_000 sats from the same wallet.
        let out_id = EventId::import(Source::Coinbase, SourceRef::new("out|test-donation-001"));
        let out_ev = LedgerEvent {
            id: out_id.clone(),
            utc_timestamp: ts_out,
            original_tz: UtcOffset::UTC,
            wallet: Some(wallet.clone()),
            payload: EventPayload::TransferOut(TransferOut {
                sat: 500_000,
                fee_sat: None,
                dest_addr: None,
                txid: None,
            }),
        };
        append_import_batch(session.conn(), &[out_ev]).unwrap();

        // ReclassifyOutflow as Donation with explicit FMV (no price lookup needed).
        let classify_payload = EventPayload::ReclassifyOutflow(ReclassifyOutflow {
            transfer_out_event: out_id.clone(),
            as_: OutflowClass::Donate {
                appraisal_required: false,
            },
            principal_proceeds_or_fmv: dec!(15000),
            fee_usd: None,
            donee: Some("Test Charity".into()),
        });
        append_decision(
            session.conn(),
            classify_payload,
            ts_out,
            UtcOffset::UTC,
            None,
        )
        .unwrap();

        session.save().unwrap();
        (vault_path, out_id, acq_id)
    }

    /// `set_donation_details` on a real Donation event stores it;
    /// `show_donation_details` reads it back correctly.
    #[test]
    fn set_then_show_round_trips_on_real_donation() {
        let dir = tempfile::tempdir().unwrap();
        let (vault_path, out_id, _acq_id) = setup_donation_vault(&dir);

        // Store details.
        set_donation_details(&vault_path, &pp(), &out_id.canonical(), test_details()).unwrap();

        // Read back.
        let stored = show_donation_details(&vault_path, &pp(), &out_id.canonical())
            .unwrap()
            .expect("details must be present");
        assert_eq!(stored, test_details());
    }

    /// UX-P4-4(c) at the CLI surface: a malformed `--donee-ein` is refused end-to-end (through the
    /// projection check + the `donation_details::set` choke point), and nothing is stored. The
    /// accept + normalize + other-shape cases are unit-tested on `validate_and_normalize`; this proves
    /// the CLI path actually reaches the choke point and fails closed.
    #[test]
    fn set_donation_details_refuses_malformed_donee_ein() {
        let dir = tempfile::tempdir().unwrap();
        let (vault_path, out_id, _acq_id) = setup_donation_vault(&dir);

        let mut bad = test_details();
        bad.donee_ein = Some("banana".into());
        let err = set_donation_details(&vault_path, &pp(), &out_id.canonical(), bad).unwrap_err();
        assert!(
            matches!(err, CliError::Usage(_)),
            "expected Usage, got: {err}"
        );
        assert!(
            err.to_string().contains("--donee-ein"),
            "the refusal must name --donee-ein: {err}"
        );

        // Fail-closed: nothing was stored for the refused donation.
        assert!(
            show_donation_details(&vault_path, &pp(), &out_id.canonical())
                .unwrap()
                .is_none(),
            "a refused set must store no details"
        );
    }

    /// Targeting a missing ref → a clear `CliError::Usage` (not a panic).
    #[test]
    fn set_donation_details_missing_ref_is_usage_error() {
        let dir = tempfile::tempdir().unwrap();
        let (vault_path, _out_id, _acq_id) = setup_donation_vault(&dir);

        let bogus = EventId::import(Source::Coinbase, SourceRef::new("out|no-such-event"));
        let err = set_donation_details(&vault_path, &pp(), &bogus.canonical(), test_details())
            .unwrap_err();
        assert!(
            matches!(err, CliError::Usage(_)),
            "expected Usage error, got: {err}"
        );
        let msg = err.to_string();
        assert!(
            msg.contains("not a donation") || msg.contains("not found"),
            "error must mention 'not a donation' or 'not found': {msg}"
        );
        // UX-P4-12(g): the message names the MISSING PRIOR STEP with VALID syntax (reclassify-outflow
        // --as-kind donate …), not just a circular pointer at removals.csv (where an unclassified
        // outflow does not yet appear).
        assert!(
            msg.contains("reclassify-outflow") && msg.contains("--as-kind donate"),
            "error must point at the missing prior step with valid syntax: {msg}"
        );
    }

    /// Targeting the Acquire event (not a Donation removal) → a clear `CliError::Usage`.
    #[test]
    fn set_donation_details_non_donation_event_is_usage_error() {
        let dir = tempfile::tempdir().unwrap();
        let (vault_path, _out_id, acq_id) = setup_donation_vault(&dir);

        // The Acquire event is not a Donation removal in the projected ledger.
        let err = set_donation_details(&vault_path, &pp(), &acq_id.canonical(), test_details())
            .unwrap_err();
        assert!(
            matches!(err, CliError::Usage(_)),
            "expected Usage error, got: {err}"
        );
    }

    /// `show_donation_details` returns `None` before any details are stored.
    #[test]
    fn show_donation_details_returns_none_before_set() {
        let dir = tempfile::tempdir().unwrap();
        let (vault_path, out_id, _acq_id) = setup_donation_vault(&dir);

        let stored = show_donation_details(&vault_path, &pp(), &out_id.canonical()).unwrap();
        assert_eq!(stored, None);
    }

    /// Build a vault with a Gift removal (not a Donation). Returns (vault_path, gift_event_id).
    fn setup_gift_vault(dir: &tempfile::TempDir) -> (std::path::PathBuf, EventId) {
        use crate::Session;
        let vault_path = dir.path().join("gift-vault.pgp");
        let mut session = Session::create(&vault_path, &pp()).unwrap();

        let ts_acq = time::OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap();
        let ts_out = time::OffsetDateTime::from_unix_timestamp(1_720_000_000).unwrap();
        let wallet = WalletId::Exchange {
            provider: "coinbase".into(),
            account: "default".into(),
        };

        let acq_id = EventId::import(Source::Coinbase, SourceRef::new("in|gift-acq-001"));
        let acq_ev = LedgerEvent {
            id: acq_id.clone(),
            utc_timestamp: ts_acq,
            original_tz: UtcOffset::UTC,
            wallet: Some(wallet.clone()),
            payload: EventPayload::Acquire(Acquire {
                sat: 2_000_000,
                usd_cost: dec!(60000),
                fee_usd: dec!(0),
                basis_source: BasisSource::ComputedFromCost,
            }),
        };
        append_import_batch(session.conn(), &[acq_ev]).unwrap();

        let out_id = EventId::import(Source::Coinbase, SourceRef::new("out|gift-001"));
        let out_ev = LedgerEvent {
            id: out_id.clone(),
            utc_timestamp: ts_out,
            original_tz: UtcOffset::UTC,
            wallet: Some(wallet.clone()),
            payload: EventPayload::TransferOut(TransferOut {
                sat: 500_000,
                fee_sat: None,
                dest_addr: None,
                txid: None,
            }),
        };
        append_import_batch(session.conn(), &[out_ev]).unwrap();

        // Reclassify as GiftOut (NOT Donate)
        let classify_payload = EventPayload::ReclassifyOutflow(ReclassifyOutflow {
            transfer_out_event: out_id.clone(),
            as_: OutflowClass::GiftOut,
            principal_proceeds_or_fmv: dec!(15000),
            fee_usd: None,
            donee: None,
        });
        append_decision(
            session.conn(),
            classify_payload,
            ts_out,
            UtcOffset::UTC,
            None,
        )
        .unwrap();

        session.save().unwrap();
        (vault_path, out_id)
    }

    /// `set_donation_details` targeting a Gift removal → "is a Gift removal, not a Donation" error.
    /// Exercises the `Some(r) if r.kind != RemovalKind::Donation` arm (previously untested).
    #[test]
    fn set_donation_details_gift_removal_is_usage_error() {
        let dir = tempfile::tempdir().unwrap();
        let (vault_path, gift_out_id) = setup_gift_vault(&dir);

        let err =
            set_donation_details(&vault_path, &pp(), &gift_out_id.canonical(), test_details())
                .unwrap_err();
        assert!(
            matches!(err, CliError::Usage(_)),
            "expected Usage error, got: {err}"
        );
        let msg = err.to_string();
        assert!(
            msg.contains("not a donation") || msg.contains("Gift"),
            "error must mention 'not a donation' or 'Gift': {msg}"
        );
    }
}