feat: community-detection auto-albums over the entity graph (P13e-1)

[blokzdev]

P13e-1 — Community-detection auto-albums

First PR of P13e (advanced graph analytics). Groups library items into thematic "Discovered" albums via deterministic label propagation over the entity graph — items linked through a web of shared signals (uploader / playlist / tag + co-download) that no single-facet smart album captures. The looser, thematic cousin of the P10 "Suggested" similarity albums (whose tight clusterer explicitly deferred this to P13).

Every-device — pulls from Cozo (Datalog) and clusters in pure Dart, no embedder/RAM gate (maintainer call; semantic-similarity + tier enhancements → BACKLOG). No schema change, no deps.

How it works

• cozo_query.dart — entityMembershipScript() (global [mediaId, kind, key] projection for uploader/playlist/tag; site excluded as too coarse) + coDownloadPairsScript() ([a, b]).
• community_clustering.dart (new, pure — mirrors near_duplicate_clustering.dart) — detectCommunities(...): builds an item graph from shared buckets (dropping over-generic buckets > maxGroupSize, the "discard blobs" rule) + co-download edges, runs deterministic label propagation (sequential, ties → smallest label), returns communities with minSize ≤ size ≤ maxSize, largest-first, each with its dominant tag.
• GraphQueryService.communityClusters() — decodes the two scripts → the clusterer; [] when the store is unavailable.
• clusteredAlbumsProvider + clusterLabel — hydrate to MediaItems and label by dominant shared signal (tag → uploader → site → newest-title fallback), reusing the existing SuggestedAlbum model + /suggested-album screen (MediaGrid + Save as collection).
• Collections → Albums gains a "Discovered" section beside "Suggested".

Tests (CI; native Cozo is APK-verified)

• community_clustering_test — entity-bucket splitting, web-merge across signals, co-download edges, minSize filtering, maxGroupSize pruning, dominant-tag (support ≥ 2, tie → smallest), and determinism (a single bridge edge correctly does not merge two dense clusters).
• cozo_query_test — both new script strings; graph_query_service_test — communityClusters() decode + unavailable; clustered_albums_test — provider hydrate/label + clusterLabel truth table + empty-when-unavailable; collections_screen_test — the Discovered section renders.
• Full suite green (892 tests), dart format + flutter analyze clean.

Docs

• P13-PLAN.md — e-1 [~] + parent P13e [~] (1 of 3); GRAPH-SPEC.md §7 — clustered-albums row realized at e-1 over the entity graph; VERIFICATION.md — P13e-1 checklist; BACKLOG.md — semantic-similarity/tier enhancements + richer labels/caching.

Verification

• ✅ CI gates green locally (format · analyze · 892 tests).
• ⏳ APK spot-check owed (native Cozo): Discovered groups are coherent on a real library and appear on a low-end device; Save as collection works; the section is absent when the graph is off.

Next: e-2 centrality "Rediscover", then e-3 path/bridge + graph-view polish.

https://claude.ai/code/session_013JoYmLCosYt5tQ8qwdbL1T

---

Generated by Claude Code