refactor(errors): establish user-facing error sanitization pattern (#1895)

[ethicnology]

refactor(errors): establish the user-facing error sanitization pattern (#1895)

This PR is the anchor for #1895 — Sanitize All User-Facing Error Messages. It
fixes the leak in the first features and defines the error standard the rest of
the codebase converges to. The standard, snippets, and rollout are below.

---

Why

User-facing flows rendered raw exception text into the UI — e.toString(), node
rejection reasons, BDK/Electrum/NFC internals. Both a UX problem and an
information leak. Root causes: a legacy BullException base whose hardcoded
English message reached users; widespread catch (e) { emit(error: e.toString()) };
~219 exception classes and ~171 throw sites with no enforced "never reaches the
UI" boundary.

The standard

Three words, three jobs — kept strictly apart:

Word	Meaning	Lives	Reaches UI?
Exception	thrown, low-level, recoverable	data layer	❌ caught at the boundary
Error (dart:core)	programmer bug — do not catch	anywhere	❌ crashes → Sentry
Failure	modeled, recoverable value	domain/	✅ carried by Err, translated by the UI

One rule: exactly one try/catch, at the data boundary. Above it, a failure
is a typed Failure value, and the only thing the UI may do with it is translate it.

---

Error propagation by layer

Layer	Job with errors
Datasource	Talks to foreign code (BDK, Electrum, keychain, HTTP, drift). Throws whatever the SDK throws. Knows nothing about Failure / Result.
Repository	The boundary — the only place that try/catches. Catches the foreign Exception, logs the raw reason (log.* / Sentry), maps it to a domain Failure, returns Result<T, F>. (When a feature wraps a shared core repo that still throws, this mapping happens in the feature's use-case instead — the first layer the feature owns.)
Use-case	Orchestration only — no try/catch (unless it is the owning boundary above). Forwards a single Result, or composes several with an explicit short-circuit. Returns Result<T, F>.
Bloc / Cubit	Consumes the Result with an exhaustive switch. Ok → success state; Err → store the typed Failure in state. No try/catch, no cast.
UI	Renders failure.toTranslated(context). Never sees raw text, never switches on the type.

Datasource ──throws──▶ Repository ───Result<T,F>──▶ Use-case ──Result<T,F>──▶ Bloc ──state.failure──▶ UI
  (raw SDK)          (catch + log + map)          (forward / compose)       (switch)        .toTranslated()

A domain Failure in the bloc is not a leak: dependencies point inward
(presentation → domain → data), so presentation consuming a domain type is
correct — same as a bloc holding a Wallet. The leak we prevent is a data
exception reaching the bloc, which the repository's mapping stops.

---

File layout (failures in domain, translations in presentation)

The repository constructs the failure, so its type lives where the data layer can
reach it — domain/ — and stays Flutter-free. Translation needs BuildContext,
so it lives in a presentation extension, the only place that imports Flutter.

lib/features/<feature>/
├── domain/
│   └── <feature>_failure.dart       ← sealed Failure family. PURE Dart, no flutter import.
├── data/
│   └── <feature>_repository.dart    ← imports the failure; maps raw exc → Err(<Feature>Failure)
└── presentation/
    ├── <feature>_failure_l10n.dart  ← extension toTranslated(BuildContext); imports flutter + l10n
    └── bloc/                         ← stores the failure in state; UI imports the extension

domain/ and data/ stay Flutter-free and unit-testable without bindings.
Exhaustiveness is still compiler-enforced: a switch over a sealed type fails to
compile when a variant is added, wherever the switch lives.

---

Building blocks

1. Result<T, F> — generic over the failure type (core)

// lib/core/utils/result.dart
sealed class Result<T, F extends Failure> {
  const Result();

  R fold<R>(R Function(T value) onOk, R Function(F failure) onErr) => switch (this) {
        Ok(:final value) => onOk(value),
        Err(:final failure) => onErr(failure),
      };

  Result<R, F> map<R>(R Function(T value) f) => switch (this) {
        Ok(:final value) => Ok<R, F>(f(value)),
        Err(:final failure) => Err<R, F>(failure),
      };

  // Convert the failure type — to unify two failure domains before returning,
  // or to lift a CoreFailure into a feature failure.
  Result<T, G> mapErr<G extends Failure>(G Function(F failure) f) => switch (this) {
        Ok(:final value) => Ok<T, G>(value),
        Err(:final failure) => Err<T, G>(f(failure)),
      };
}

final class Ok<T, F extends Failure> extends Result<T, F> {
  const Ok(this.value);
  final T value;
}

final class Err<T, F extends Failure> extends Result<T, F> {
  const Err(this.failure);
  final F failure; // concrete failure type — no `as` cast anywhere
}

@useResult (package:meta) on Result-returning methods so a discarded result warns.

2. Failure base + shared CoreFailure (pure)

Failure is an open abstract base (it spans every feature). Cross-cutting modes
— recurring across the audit (network, storage-locked, not-found, timeout, auth,
device, insufficient-funds) — live once in a sealed CoreFailure, composed by
features instead of redefined 48 times.

// lib/core/failures/failure.dart — PURE  (errors/ stays the legacy graveyard)
abstract class Failure {
  const Failure([this.logMessage]);
  final String? logMessage; // logs/Sentry ONLY — never read by the UI
}

// lib/core/failures/core_failure.dart — PURE (translation extension lives in presentation)
sealed class CoreFailure extends Failure {
  const CoreFailure([super.logMessage]);
}

final class NetworkFailure extends CoreFailure {
  const NetworkFailure([super.logMessage]);
}
final class StorageLockedFailure extends CoreFailure {
  const StorageLockedFailure([super.logMessage]);
}
// NotFoundFailure, TimeoutFailure, AuthFailure, DeviceNotFoundFailure, InsufficientFundsFailure ...

3. Feature failure — pure, in domain/

// lib/features/pin_code/domain/pin_code_failure.dart — NO flutter import
import 'package:bb_mobile/core/failures/failure.dart';

sealed class PinCodeFailure extends Failure {
  const PinCodeFailure([super.logMessage]);
}

final class PinCodeSaveFailure extends PinCodeFailure {
  const PinCodeSaveFailure();
}
final class PinCodeDeleteFailure extends PinCodeFailure {
  const PinCodeDeleteFailure();
}
final class PinCodeNotSetFailure extends PinCodeFailure {
  const PinCodeNotSetFailure();
}

// A variant carrying data → fields first, then constructor (AGENTS.md ordering).
// `logMessage` is positional on the base, so forward it explicitly.
final class PinCodeFetchFailure extends PinCodeFailure {
  final String key;
  const PinCodeFetchFailure({required this.key, String? logMessage}) : super(logMessage);
}

/// Catch-all. `logMessage` is for logs ONLY and MUST never reach the UI.
final class PinCodeUnexpectedFailure extends PinCodeFailure {
  const PinCodeUnexpectedFailure([super.logMessage]);
}

4. Translation — presentation extension (the only Flutter import)

// lib/features/pin_code/presentation/pin_code_failure_l10n.dart
import 'package:bb_mobile/core/utils/build_context_x.dart';
import 'package:bb_mobile/features/pin_code/domain/pin_code_failure.dart';
import 'package:flutter/widgets.dart';

extension PinCodeFailureL10n on PinCodeFailure {
  // Exhaustive: add a variant to the sealed type and this switch breaks at
  // compile time until you give it a user-safe message.
  String toTranslated(BuildContext context) => switch (this) {
        PinCodeSaveFailure() => context.loc.pinCodeSaveError,
        PinCodeDeleteFailure() => context.loc.pinCodeDeleteError,
        PinCodeNotSetFailure() => context.loc.pinCodeNotSetError,
        PinCodeFetchFailure() => context.loc.coreScreensFetchFailed,
        PinCodeUnexpectedFailure() => context.loc.oopsSomethingWentWrong, // generic, never the raw reason
      };
}

5. Repository — the boundary (catch → log raw → map → Result)

// lib/features/pin_code/data/.../pin_code_repository.dart
import 'package:bb_mobile/features/pin_code/domain/pin_code_failure.dart'; // pure, no Flutter

Future<Result<Null, PinCodeFailure>> setPinCode(String pin) async {
  try {
    await _storage.saveValue(key: _key, value: pin);
    return const Ok(null);
  } on KeychainLockedException {
    return const Err(PinCodeSaveFailure());            // foreign exception -> domain failure
  } catch (e, st) {
    log.severe(message: 'save pin failed', error: e, trace: st); // raw -> logs ONLY
    return Err(PinCodeUnexpectedFailure(e.toString()));  // generic -> UI
  }
}

6. Use-case — forward, or compose with short-circuit (no try/catch)

// pass-through: zero boilerplate
Future<Result<Null, PinCodeFailure>> execute(String pin) => _repository.setPinCode(pin);

// composing two calls from the SAME failure domain (Dart has no `?` operator)
Future<Result<bool, PinCodeFailure>> execute(String pin) async {
  final exists = await _repository.isPinCodeSet();
  if (exists case Err(:final failure)) return Err(failure); // stop at first failure
  return _repository.verifyPinCode(pin);                    // also Result<_, PinCodeFailure>
}
// Composing across repos with DIFFERENT failure types needs a `.mapErr(...)`
// step (or a shared CoreFailure) to unify F before returning.

7. Bloc — exhaustive switch, no cast; domain failure stored in state

switch (await _setPinCodeUsecase.execute(state.pinCode)) {
  case Ok():
    emit(state.copyWith(status: PinCodeSettingStatus.success));
  case Err(:final failure): // failure is PinCodeFailure — already typed
    emit(state.copyWith(status: PinCodeSettingStatus.failure, failure: failure));
}

8. UI — translate only

import 'package:bb_mobile/features/pin_code/presentation/pin_code_failure_l10n.dart';

BlocListener<PinCodeSettingBloc, PinCodeSettingState>(
  listenWhen: (p, c) => p.failure != c.failure,
  listener: (context, state) {
    if (state.failure case final failure?) {
      SnackBarUtils.showSnackBar(context, failure.toTranslated(context));
    }
  },
  child: /* ... */,
);

---

Conventions (mandatory)

1. No raw exception text reaches the UI. UI renders failure.toTranslated(context) only. e.toString() / e.message is for log.* / Sentry exclusively.
2. try/catch lives only at the data boundary — the feature's repository, or its use-case when wrapping a shared core repo. Above it: switch.
3. Failures are sealed, one closed family per feature, declared in domain/<feature>_failure.dart, Flutter-free. Cross-cutting modes come from CoreFailure.
4. Naming. Family <Feature>Failure; base Failure. Error is reserved for dart:core bugs only — never a domain family. Exception only for thrown infra.
5. Translation is a presentation extension (presentation/<feature>_failure_l10n.dart) — the only place BuildContext / flutter appears for failures.
6. Catch-all variant (<Feature>UnexpectedFailure) carries String? logMessage — logs only; the raw reason is logged at the boundary, the field is secondary (equality/debug). Keep the type String? consistently.
7. Member ordering: fields → constructor → methods (AGENTS.md).
8. Result<T, F> is generic over the failure type (no as casts); annotate returning methods @useResult.
9. Every migrated use-case gets a test asserting the sanitized failure is returned for bad input (no raw leak).

---

Rollout plan (#1895)

This is a sanctioned, staged migration — it supersedes the prior "don't
mass-migrate exception code" guidance for the scope of #1895.

Do not migrate the high-fan-out core repos first (WalletRepository ~30
dependents, Exchange ~19, Blockchain/Swap ~12, Payjoin ~12) — that turns
incremental into big-bang. Adapt at the feature boundary: a feature's own
repo/use-case wraps the still-throwing core call locally. Core repos move last.

Future<Result<Wallet, ImportFailure>> execute(...) async {
  try {
    return Ok(await _coreWalletRepo.importWatchOnly(...)); // core still throws
  } on Object catch (e, st) {
    log.warning('import failed', error: e, trace: st);
    return const Err(ImportFailedFailure());
  }
}

Sequencing

1. Foundation: Failure base, generic Result<T, F> + fold/map/mapErr, the CoreFailure set.
2. Kill the leak hotspots (immediate Sanitize All User-Facing Error Messages #1895 win): status_check, legacy_seed_view, psbt_flow, all_seed_view, address_view, bip85_entropy, dca, electrum_settings, import_mnemonic, mempool_settings, onboarding, receive, sell, send, swap.
3. Finish the near-done sealed families (add the translation extension): ledger. (labels is done — see below.)
4. Migrate the S/M features behind adapters.
5. The three monsters last, each its own PR + tests: send, swap, wallet.

---

Core / package failures (melos phase — not in #1895's feature sweep)

lib/core is shared infrastructure with no presentation/ — and post-melos it
becomes packages, which by rule never export a bloc or screen. So failures that
originate in core split two ways, and translation can't live in core.

Where they live:

• Owned by a specific core domain (lib/core/wallet, lib/core/exchange, …) — that module owns its family in its own domain, exactly like a feature: lib/core/<domain>/domain/<domain>_failure.dart (WalletFailure, ExchangeFailure, …).
• Cross-cutting, no single owner (network, timeout, storage-locked, not-found, auth, device, insufficient-funds) — the shared sealed CoreFailure in lib/core/failures/ (failure.dart base + core_failure.dart).

How they're translated (core has no BuildContext):

• Default — lift into the feature's failure. The consuming feature's use-case maps the core failure into its own <Feature>Failure via mapErr, then its presentation extension translates. Core stays Flutter-free; a core failure never reaches a bloc untranslated.

  final r = await _coreWalletRepo.loadWallet(id); // Result<Wallet, WalletFailure>
  return r.mapErr(SendFailure.fromWallet);         // -> Result<Wallet, SendFailure>

• Uniform messages — one shared extension. For modes shown identically everywhere (network / timeout), define a single CoreFailureL10n extension in a presentation-capable spot every consumer imports (today lib/core/widgets/; post-melos the app or a ui package). One definition avoids copying the same switch into N features — and the rare co-import ambiguity when two same-member extensions land in one file. The switch stays exhaustive-checked because all CoreFailure variants live in one library.

Melos-forward: the rule survives the core→packages move unchanged — a domain/data package has no presentation, so whoever owns the BuildContext (the app, a feature, or a ui package) owns the extension; the package failure stays pure.

Scope: lands with the core→packages migration, not in #1895. This PR and the
feature sweep sanitize feature-facing errors now; core/package failure families
plus the shared extension are the next phase.

---

Feature inventory (audit summary)

coins is empty. Effort is a fast-scan estimate — verify the L-tier before scheduling.

Already sealed + translated (finish, don't rebuild): pin_code, withdraw,
buy, recoverbull, recoverbull_google_drive, replace_by_fee,
fund_exchange, pay, broadcast_signed_tx, import_watch_only, labels —
plus core-level bitbox, ledger (sealed but missing the translation layer).

Effort	Features
S (~21)	app_unlock, ark_setup, backup_settings, bitcoin_price, exchange, exchange_settings, exchange_support_chat, import_coldcard_q, import_qr_device, import_wallet, legacy_seed_view, pin_code, psbt_flow, recipients, recoverbull_google_drive, replace_by_fee, settings, status_check, tor_settings, withdraw, wizard
M (~18)	address_view, all_seed_view, app_startup, bip85_entropy, bitbox, buy, dca, import_mnemonic, import_watch_only_wallet, labels, mempool_settings, onboarding, receive, recoverbull, sell, test_wallet_backup, transactions
L (~10)	ark, autoswap, electrum_settings, fund_exchange, ledger, pay, send, swap, wallet, broadcast_signed_tx

Top three (deep chains + many variants): swap (15+ variants, 5–7 call
chain), send (8+ variants, ~7 steps), wallet (12+ variants, 20+ use-cases).

broadcast_signed_tx is the reference this PR ships and is now complete: the
legacy errors.dart is gone, the domain/presentation split and the *Failure
rename are done, and the cubit emits typed sanitized failures. It keeps try/catch
only as the data boundary for direct QR/NFC/SDK scanning, which the standard
permits (no use-case sits beneath those calls).

---

What this PR lands

• broadcast_signed_tx, import_watch_only, labels fully migrated to the
  standard: sealed <Feature>Failure in domain/ (pure Dart), translation in a
  presentation/<feature>_failure_l10n.dart extension, and Result<T, F>
  propagation (use-cases/repos return it; cubits switch). The real leaks are
  removed — transaction_review_view's coreScreensUnexpectedError(message ?? 'unknown')
  and the BIP329 labels cubit's raw 'Export failed: $e'.
• State types narrowed from Exception? / String to the concrete sealed Failure.
• import_watch_only: the inline satoshifier parse is extracted into
  ParseWatchOnlyInputUsecase returning Result, so the cubit holds no try/catch.
• labels: the facade returns Result on writes (store/trash) and stays
  best-effort on reads (degrade to empty + log) so the ~15 core wallet read sites
  are untouched; unused LabelFailure variants pruned.
• pin_code: the failure extension is renamed to pin_code_failure_l10n.dart
  (naming convergence; pin_code itself was already on the standard).
• Localization: added the new *Error* keys; removed dead keys
  (coreScreensUnexpectedError, labelErrorUnexpected, and the pruned label
  variants' keys).
• docs(agents + architecture): member-ordering convention, the _failure_l10n
  naming, and the Result/Failure standard.
• New use-case tests asserting the sanitized failure on bad input (import
  descriptor/xpub/parse, broadcast build_reviewable, all four labels use-cases).

Convergence note. These three features are now fully on the standard —
<Feature>Failure naming, the domain/+presentation/ split, and Result<T, F>
propagation — and serve as the reference implementation the rest of the rollout
copies. They no longer use the legacy <Feature>Error / toTranslated-on-the-error
/ throw-based shape. The NFC collapse (PushTxNoNdefRecordsError /
PushTxNoUriError / PushTxMissingFragmentParamsError → one InvalidPushTxFailure)
is a deliberate granularity trade for sanitization.