Document persistence failure-surfacing and overlay-store conventions

docs/architecture/02-persistence.md

@@ -410,6 +410,20 @@ export async function saveSnippet(s: Snippet): Promise<void> {
 > **Do:** surface quota warnings _before_ the budget is hit (the 80% threshold) and hard errors loudly when a write fails.
 > **Don't:** wrap a save in a bare `try/catch {}` that logs and returns — that turns "your work wasn't saved" into a silent data-loss bug. The only thing the adapter may safely swallow is a _read_ failure, where falling back to defaults/empty is the correct behavior.
 
+**The adapter propagating is only half — a consumer must catch and surface it.** A
+fire-and-forget `void saveSnippet(n)` re-buries the very error the adapter took care to
+throw. Persistence write-backs are wired as store subscribers, so the surfacing path is:
+
+`orchestration/persistence.ts` (write-through `.catch`) / `orchestration/startup.ts` (load
+`.catch`, then run in memory) → `services/storage-errors.ts` (pure error→message mapper) →
+`notify()` (`stores/NotificationStore`) → `Toaster`.
+
+Rules this encodes (spec §10 "told when a save fails"): never `void`-fire a persist without
+a `.catch` that calls `notify(storageErrorNotification(op, err))`; the mapper splits
+user-fixable (storage full → next step, no diagnostic) from not (blocked storage → plain
+explanation **+** a reportable `detail`); and a blocked store at startup **warns and runs
+in memory** rather than rejecting into the void.
+
 ---
 
 ## 7. Checklist for Adding a New Persisted Entity