async-safety

Async safety: no failure may be silent

Async bugs are silence. A dropped Future swallows its error; a dead BuildContext throws into a void; a leaked subscription fires into a disposed widget. An app with no telemetry has exactly two feedback loops — the analyzer and the test suite — and the analyzer has one hole big enough to drive the product through. Close it structurally, not with discipline. This skill applies whenever you write async/await, wire a callback, or hold a subscription, timer, or sink.

Non-negotiable rules

1. A callback must never touch a Future. Every onTap/onPressed/onSubmitted/VoidCallback handler returns void. onTap: () => vm.save(x) where save is async is caught by NO lint (see below) — the fix is shape, not vigilance.
2. A mounted / ref.mounted guard goes after EVERY await, immediately before the next BuildContext use — never once at the top, never before the await where it proves nothing. Or capture the object you need before the gap.
3. Multiple awaits ⇒ the guard sits after the LAST one. A guard only certifies the interval since the most recent suspension point.
4. unawaited(x) is legal only if x provably cannot fail silently — it ends in a .catchError(...) or is total. Bare unawaited(f) routes errors to PlatformDispatcher.onError, detached from the UI. That is silence with a permission slip.
5. Every StreamSubscription, StreamController, Timer, and sink is released in dispose() / ref.onDispose. Prefer not owning it: a provider gives teardown for free.
6. Every timer/stream callback that calls setState guards mounted first. A Timer holds a strong reference to its closure and fires happily after the widget is gone.
7. No empty catch, no bare catch, no swallow. Every catch has an on clause (except the crash logger's own write), logs with its stack, and surfaces the failure. Use rethrow, never throw e — the latter resets the stack trace.
8. Never assert a platform/plugin return value. Asserts are stripped in release: green in every test, absent on the device — the perfect silent-failure bug.
9. Nothing unbounded runs before runApp. No migration, no plugin warm-up. Show a usable first frame, then warm up in addPostFrameCallback, unawaited.
10. No runZonedGuarded. Two error handlers suffice — app-startup-and-bootstrap owns installing them, their pre-runApp ordering, the PlatformDispatcher.onError return true rule, and never letting a handler throw. Don't restate that machinery here.