Catalog: enforce identical truth predicates for rows, counts, pagination and provider pseudo-items

[MrFr3di]

Context

Derived from the reusable architectural lesson behind StreamVault #2797. This is not a request to copy StreamVault SQL or provider-specific heuristics; it is a MuxTV invariant package required before bounded Guide/pagination work.

Core invariant

For every user-facing channel surface, authoritative membership is defined semantically as:

1. a canonical channel has at least one stream variant whose provider channel belongs to the source's activeRevision;
2. the channel is visible for the selected profile (COALESCE(user_channel_overlays.isHidden, 0) = 0);
3. only then is the surface-specific predicate applied (Favorites, Search query, Recent history, Guide viewport, etc.).

Sorting may differ per surface, but active/profile-visible membership must not drift.

Current inventory

Accepted main already aligns most row projections:

• PlaybackCatalogDao.observeActiveChannels/findActiveChannel/getActiveVariants use current source revision; profile-facing row/direct-playback paths enforce hidden-overlay filtering.
• ChannelSearchDao revalidates active stream/source truth and profile visibility after FTS candidate selection.
• EpgGuideDao now/next membership and programme candidates enforce active catalog revision plus profile visibility.
• feat: add profile-scoped Recent channels v10 #107 RecentChannelsDao uses the same active/current-revision + non-hidden read rule.
• CatalogDao.observeActiveCanonicalChannels is intentionally profile-agnostic low-level catalog truth and must not be treated as a profile UI projection.

Search already demonstrates the preferred bounded-result contract: ChannelSearchSnapshot carries explicit isTruncated; Search UI says Показано результатов when truncated and only says Найдено результатов when the snapshot is known not to be truncated. Guide/window work should follow this explicit-state pattern rather than infer completeness from rows.size.

Concrete defect found during inventory

The Channels surface used rows.size from bounded queries as if it were an authoritative total:

• ChannelQuery default 200 / max 500;
• feat: add profile-scoped Recent channels v10 #107 Recent default 20 / max 50;
• UI labels previously said Активных каналов: N, Избранных каналов: N, Недавно просмотренных каналов: N.

That is exactly the false-total/pagination bug class this issue exists to prevent. It is corrected in #107, where ChannelsRoute is already owned: bounded lists now say Показано каналов / избранных / недавних. No duplicate COUNT SQL is introduced just to preserve old wording.

Execution plan

Phase A — semantic inventory and ownership

Keep explicit owners rather than a giant shared SQL string:

• Playback rows/direct playback: PlaybackCatalogDao.
• Search candidate/revalidation/summary: ChannelSearchDao.
• Recent active projection: RecentChannelsDao after feat: add profile-scoped Recent channels v10 #107.
• Guide now/next and future viewport: EpgGuideDao.
• profile-agnostic canonical maintenance: CatalogDao.

Document base truth and ensure every profile-facing owner has contract coverage for active revision + hidden overlay.

Phase B — no fake totals / no fake has-more

Rules:

1. never present rows.size as a total when the query is bounded;
2. never infer hasMore from an unrelated capped query;
3. a UI may show Показано N without an exact count query;
4. add an authoritative count only when the product actually needs one;
5. if count/pagination are added, row/count/window must share the same semantic predicates and deterministic tie-breaks;
6. prefer explicit isTruncated/window-completeness state (as Search already does) over deriving completeness from list size.

#107 owns the immediate Channels wording correction. A broader count API is explicitly out of scope there.

Phase C — cross-surface active-truth contract after #107 merge

Create a fresh branch from accepted main and add a focused ActiveChannelTruthContractTest (or equivalent repository-level integration contract). Seed one database with:

• active revision containing channels A/B;
• a staged/newer revision not activated;
• profile-hidden B;
• favorite overlay on A;
• Search documents for both active and stale identities;
• Recent history for active, hidden and temporarily inactive IDs;
• Guide match/programme fixtures where applicable.

Assert membership, not presentation order:

• Playback rows expose only active/profile-visible IDs;
• direct playback cannot resolve hidden/stale IDs;
• Search result revalidation exposes the same active/profile-visible identities;
• Recent exposes only active/profile-visible history while retaining bounded hidden/inactive history internally;
• Guide now/next/viewport never resurrects hidden/stale channels.

Then perform an active-revision swap and repeat the assertions. Avoid duplicating every existing unit test; this contract exists specifically to catch cross-owner drift.

Phase D — Guide row/window/count contract

Before implementing full Guide UI, define the Guide database window as one coherent contract:

• bounded canonical-channel slice with deterministic stable key/tie-break;
• bounded time interval plus small prefetch margin;
• programme overlap predicate defined once for window reads;
• profile visibility/current source revision applied before surface-specific time projection;
• explicit window completeness/truncation state when useful;
• no total derived from viewport rows;
• if an exact channel count is needed, its predicate is tested against the same seeded truth set.

This phase is the gate for replacing the current Guide placeholder.

Phase E — provider pseudo-items only from evidence

Do not add generic name/hash heuristics for M3U. If a real provider fixture demonstrates structural/pseudo rows, introduce a typed ingestion classification such as:

Playable / StructuralPseudoItem / Malformed(reason)

at the provider/import boundary, not in presentation SQL. Quarantine only evidence-backed structural rows before they enter canonical channel truth.

Acceptance

When self-hosted CI returns, #114 implementation must demonstrate:

1. exact-head database instrumentation contract on old-edge/current APIs;
2. row membership after active-revision swap;
3. hidden-overlay agreement across Playback/Search/Recent/Guide;
4. no bounded list presented as total and no fake hasMore;
5. deterministic ordering/tie-break where a window is paged;
6. zero provider-specific heuristic without a committed fixture;
7. zero unresolved review threads.

Ordering

Immediate correction lives in #107 because that PR already owns the affected Channels UI. The cross-surface DB contract should start only after #107 is accepted/merged, from fresh main; do not stack a broad #114 implementation on the unverified Room-v10 branch while self-hosted CI is disabled.

[MrFr3di]

Refined execution package after Recent/EPG acceptance review

Start only from fresh accepted main after #107 merges. Do not stack this on the draft Room-v10 branch.

Architectural decision

Do not introduce a giant shared SQL fragment, generic channel-membership table, Paging abstraction or another repository layer. Playback, Search, Recent and Guide keep their current owners. The missing protection is one executable cross-owner semantic contract.

Task 1 — durable plan and source inventory

Create docs/superpowers/plans/2026-08-05-active-channel-truth-contract.md and record the exact current owners:

• Playback: RoomPlaybackCatalog / PlaybackCatalogDao;
• Search: RoomChannelSearchRepository / ChannelSearchDao;
• Recent: RoomRecentChannelsRepository / RecentChannelsDao;
• Guide: RoomEpgGuideRepository / EpgGuideDao;
• catalog publication: RoomSourceRevisionStore.

Explicitly document that profile-agnostic low-level helpers such as raw variant lookup or canonical maintenance are not user-facing membership surfaces.

Task 2 — TDD cross-surface contract

Add core/database/src/androidTest/kotlin/app/muxtv/database/ActiveChannelTruthContractTest.kt using one in-memory MuxTvDatabase.

Seed two profiles and one source with:

• revision 1 active: canonical A and B;
• revision 2 staged only: canonical C;
• profile A hides B and favorites A;
• profile B leaves B visible;
• Search documents for A/B plus staged C;
• Recent history for A/B/C;
• one current EPG match/programme for A, B and staged/stale C as applicable.

Before activation swap assert membership sets, not UI order:

• Playback rows for profile A: {A};
• direct Playback resolution for hidden B and staged C: unavailable;
• Search for profile A: only A, never hidden B/staged C;
• Recent for profile A: only active+visible A while B/C history stays retained internally;
• Guide/NowNext for profile A: A may be READY; hidden B and staged C are NO_GUIDE/absent;
• profile B can see active B, proving overlay isolation.

Task 3 — active revision swap

Activate revision 2 with a deliberate new set, for example {B, C}, leaving A stale. Refresh/match the EPG relation needed for the new active catalog revision.

Repeat the cross-surface assertions:

• stale A disappears from Playback/Search/Guide/Recent projection;
• profile A still hides B;
• visible C appears consistently where the surface predicate permits it;
• Recent retains A/B/C history internally but projects only current active+visible identities;
• profile B sees active B/C according to its overlay;
• no staged or previous-revision provider row is resurrected.

Task 4 — minimal production correction only on RED

Run the new test first and preserve the failure evidence. If a surface drifts, change only its owner query/repository and add the smallest local regression assertion. Do not pre-emptively centralize SQL.

Potential high-risk boundary to prove explicitly: PlaybackCatalogDao.getActiveVariants(channelId) is profile-agnostic by design and must remain reachable only after profile-aware findActiveChannel/repository resolution; the public direct-playback result must never resolve a hidden/stale channel.

Task 5 — bounded-result semantics

Add a structural/source-level assertion or focused UI contract only where needed:

• bounded lists may say Показано N;
• they must not claim exact totals from rows.size;
• no fake hasMore inferred from an unrelated cap;
• exact count SQL is out of scope unless a current product surface actually requires it.

Task 6 — Guide gate definition

In the same plan, define but do not yet build the full Guide UI contract:

• bounded canonical-channel slice;
• bounded time interval with small prefetch margin;
• one programme-overlap predicate;
• active revision + profile visibility applied before time projection;
• deterministic stable key/tie-break;
• explicit completeness/truncation state where needed;
• no full-guide materialization in Compose.

This becomes the immediate next PR after the cross-surface membership package.

Acceptance

• new cross-surface test passes on the final exact head;
• old-edge/current database device matrix executes it with non-zero counts;
• Full host validation is green;
• active-revision swap and profile-overlay isolation are proven;
• no bounded list is presented as an exact total;
• no provider pseudo-item heuristic without a committed fixture;
• no schema bump unless a RED demonstrates an actual storage requirement;
• zero unresolved review threads and final privacy review.