Review fixes: contact key race, history hot paths, build snapshots, test and doc cleanup

[erikwb]

A batch of fixes from a whole-project review. Each commit stands alone, and each one passes the full hermetic suite (dbus-run-session + pytest), Ruff, and mypy when checked out by itself. Reviewing commit by commit is easiest.

Bluetooth recovery

• Keep recovery state with the daemon that owns the bus name (26e0641). A second daemon, such as blueferry run while the service is running, read the recovery journal before claiming the name. If the claim failed, its stop() still ran finish_shutdown(), which could replay or clear restoration belonging to the live daemon. The journal is now reloaded after the claim, and restoration is skipped when the name was never acquired.

Security

• Give contact pulls a private storage key. The PBAP pull runs on the OBEX worker for up to minutes, using the live StorageSecurity. Relocking, a policy change, or fail_closed zeroes that key buffer in place on the GLib thread. A concurrent encrypt could therefore seal contact rows under a zeroed key, and later reads would fail authentication and put storage into the error state.
  • Each pull now gets its own key snapshot.
  • The new StorageSecurity.revision changes whenever the key or policy does. If it changes during a pull, the result is discarded, the cache cleared, and the download re-queued.

Daemon responsiveness

• Stop decrypting and rewriting history on every few messages.
  • prune_events ran on the GLib loop every 10 writes. It decrypted the whole archive (up to 10k rows) and UPDATEd every row, even rows already normalized. With secure_delete on, that rewrote nearly the whole file every few incoming messages.
  • The hot path now applies only the count and size ceilings, which need no decryption. The age sweep runs at most hourly, plus at every startup and unlock as before.
  • Mark-read uses an incremental handle→row index instead of decrypting the whole table for each read event.
• Bound the periodic bond check. GetManagedObjects runs every 2s on the GLib loop with the default 25s timeout. It now uses a 2s timeout.
• Check daemon compatibility once per bus owner. BackendClient called GetStatus before every operation. Verified daemons are now cached by their unique bus name, which a replacement daemon never reuses.

Packaging

• Build source snapshots from the Git index only. build.sh and the deb and rpm builders packed every untracked, non-ignored file, including .agents/, .codex/, uv.lock, and a website/ checkout. Uncommitted edits to indexed files are still included, and untracked paths are listed.

Tests and structure

• Move contact sync out of Daemon. The state machine lived in eight private Daemon fields and now lives in ContactSync, moved without behavior changes.
• Build real daemons in tests. The new isolated_state / make_daemon fixtures construct a real Daemon against temporary state with no D-Bus or Bluetooth I/O. All 11 Daemon.__new__ + hand-set-private-field constructions in tests are gone.
  • One pairing-policy assertion only held because a stub skipped the step where a manual sync satisfies a deferred pull. It now checks the real behavior.
  • The rule is documented in TESTING.md.
• Restructure ARCHITECTURE.md around a module map.
  • Every backend, client, and Quickshell file is listed.
  • Invariants are grouped by area, and bug-fix narration is condensed.
  • A "Known duplication" section replaces the claim that Quickshell shares onboarding and roster semantics.

Not in this PR

• The runtime completion-marker half of the original recovery branch was dropped. It covered a narrow journal-cleanup failure at the cost of a second persistence layer, and regressed the case where the user logs out while a power cycle is in progress.
• Recovery still refuses to cycle when any other device is paired, not just connected, so for most users it rarely fires. That deserves its own change.

Validation

• 1444 tests pass on a private bus. Ruff, mypy, and Bandit pass.
• No live hardware testing was done.