Repository navigation
Description
Parent: #28
Depends on: #29
Related: #25
Objective
Automatically recognize live-event and team channels and match them to canonical schedules without requiring users to create regex/AED rules.
Scope
- Cluster related channels by provider, group, naming pattern, platform, and observed lifecycle.
- Infer sport, league, platform, event type, and temporary/permanent channel behavior.
- Support matchup, single-team, tournament, session, event-card, and generic-event classifications.
- Resolve team and competitor aliases using league and provider context.
- Combine channel name, group, timing, provider history, XMLTV, and schedule evidence.
- Produce ranked event candidates and an explainable confidence breakdown.
- Detect likely provider errors when schedule evidence strongly contradicts channel text.
- Apply only high-confidence decisions automatically; route material ambiguity to one plain-language review question.
MLB proving scenarios
Yankees vs Red SoxCubs @ Cardinals- numbered temporary event slots
- persistent Yankees/team channels
- ESPN+ or similar platform prefixes
- doubleheaders and same-day repeated matchups
- abbreviated and ambiguous team names
Acceptance criteria
- No regex creation is required for supported scenarios.
- Every decision records positive, negative, and conflicting evidence.
- Team aliases are context-aware rather than blindly global.
- Ambiguous names such as
Giantsdo not auto-resolve without sufficient league/provider context. - The engine distinguishes event channels from single-team channels automatically.
- Regression fixtures prove stable classifications and confidence scores.
ChannelForge product premise and scope guardrail
ChannelForge exists to make the user's existing content and services easier to discover and use.
Required product test
Before implementation, this issue must answer yes to the following question:
Does this reduce the effort required to find, understand, choose, or open content from services the user already has?
If the answer is no, unclear, or depends on building a parallel provider product, stop and re-scope the issue.
Scope rules
- Aggregate content and capabilities across providers into a clearer discovery experience.
- Use, link to, or delegate to provider-owned systems wherever available; do not recreate provider products.
- Keep providers as the systems of record for content, playback, recordings, schedules, entitlements, accounts, billing, storage, permissions, and service-specific state.
- Limit ChannelForge-owned behavior to what makes aggregation easier: permitted ingestion, normalization, identity matching, source comparison, presentation, routing, explainability, and safe configuration.
- Preserve provider attribution, access controls, terms, content rights, capability differences, and failure boundaries.
- Prefer the smallest integration that removes meaningful user effort. A deep link is better than a new subsystem when it solves the user's problem.
- Do not add setup, decisions, dashboards, automation, or maintenance burden unless the issue removes more complexity than it introduces.
- Default to a simple path for beginners; expose advanced controls only when they provide real value.
Definition-of-done addition
This issue is not complete until evidence shows that it makes a real user task easier without duplicating a provider capability or creating a second system of record.
Integrate before rebuild. Aggregate without taking ownership. Make things easier.
Current implementation status — 2026-08-11
Status: In progress; local implementation evidence is strong, but live provider/runtime certification remains open.
Implemented in the current beta/containerized-guide working checkout:
- deterministic event and live-event classification across matchup, single-team, tournament, session, event-card, generic-event, and non-event cases
- scoped alias evidence, explicit schedule candidate matching, review routing for ambiguity/doubleheaders, and metadata-only reports
- schedule reconciliation with source freshness, reliability, lifecycle, start-time conflicts, optional provider stop-time conflicts, and provenance
- candidate guide generation that uses a valid provider stop time when present and an explicit configured-duration fallback otherwise
- web review filters for team, league, event ID, lifecycle, confidence, freshness, and conflict evidence
Evidence: EventDiscovery.Tests.ps1, EventSchedule.Tests.ps1, and EventEpgDelivery.Tests.ps1 pass 9/9; the complete unit suite passes 648/648. The active NAS deployment and provider state are unchanged.
Remaining before this issue can be closed:
- validate additional authoritative provider adapters and permitted live-source contracts
- complete disposable Docker/NAS runtime evidence
- verify downstream behavior without treating format validity as playback or entitlement proof
- complete release review and maintainer approval
Activity
Jumpstile commentedon Jul 27, 2026
Ecosystem evidence — 2026-07-27
Teamarr exposed two useful lifecycle invariants for ChannelForge's event pipeline:
segmentandcard_segmentcaused hundreds of needless delete/recreate cycles: fix: segmented channels no longer delete/recreate every run (#514) Pharaoh-Labs/teamarr#515Implication for this issue: add regression fixtures proving stable identity for event sessions/segments, and ensure missing-from-derived-pool is treated as uncertainty rather than deletion evidence. Genuine rotation and scheduled withdrawal must still work.
Jumpstile commentedon Aug 3, 2026
Ecosystem evidence — 2026-08-03
Teamarr v2.12.4 adds a stronger lifecycle invariant for multi-session events: persist the session-aware event-end estimate when the managed channel is created, then let later recalculation apply only the configured withdrawal policy and buffer. Re-deriving event end from a generic event date plus sport duration pulled a race-weekend channel's deletion time back to Friday practice and could remove it before the main race.
ChannelForge implication: the canonical matched session/event end should be durable provenance-bearing state. Cleanup/reconciliation may derive a withdrawal deadline from that fact, but must not silently replace it with a less-specific duration heuristic. Legacy rows without the fact may use an explicit, diagnosable fallback. Add a fixture covering a multi-day event whose lifecycle policy is recalculated after creation.
Source: Pharaoh-Labs/teamarr@d8c55cc
Jumpstile commentedon Aug 10, 2026
Ecosystem evidence — 2026-08-10
Teamarr exposed the create-side counterpart to the multi-session withdrawal invariant already recorded here. A race-weekend parent event used the first session's start for every derived session channel, so a Sunday race channel was created when Saturday practice entered the pre-buffer window; its guide text also incorrectly said “today.”
ChannelForge implication: lifecycle eligibility, creation threshold, display date wording, and withdrawal must all use the canonical matched session's own start/end facts. Parent-event timing may group sessions but must not substitute for a session timestamp. Add a regression fixture with practice/qualifying on day one and the race on day two, proving each session publishes only inside its own window and renders timezone-aware “today/tomorrow/weekday” wording correctly.
Source: Pharaoh-Labs/teamarr#550
Jumpstile commentedon Aug 12, 2026
Implemented and validated session-specific lifecycle timing in the beta checkout (no commit or deployment change).
Evidence:
New-ChannelForgeEventLifecyclePlan.ps1now uses a valid matched providerstop_utcfor live, grace-period, and archive decisions.timing_basis(provider-stop-timeorconfigured-duration-fallback),stop_utc, and derived duration.git diff --checkpassed.Runtime Docker/NAS certification, live provider contract validation, and downstream certification remain open. Active NAS deployment was not touched.
Jumpstile commentedon Aug 29, 2026
Ecosystem discovery/ranking evidence — Dispatcharr matchup tooling
Dispatcharr Ranked Matchups / Top Games provides additional external validation for automatic event discovery and ranking.
Required ChannelForge boundary:
This is supporting research only; it does not change #30's scope or authorize copying opaque ranking algorithms.
Jumpstile commentedon Sep 3, 2026
Ecosystem watch reconciliation — Teamarr v2.13.1/v2.13.2/v2.14.0 (2026-08-31)
These releases were identified by the paused secondary monitor but were not durably recorded in the tracker. Classification: Study / Compatibility impact. Priority: Medium.
Observed lessons relevant to ChannelForge: session-aware event-end persistence and deletion-policy safety; explicit home/away/unknown feed identity; closed-loop remote-number swaps; common game-state template conditions; duplicate-channel protection; timezone/day-bucket correctness across sports; and failed-prefetch handling that preserves the last-known-good result instead of silently degrading.
Recommended ChannelForge action: keep canonical session identity and source provenance separate from derived scheduling/deletion policy; require cross-sport identity and timezone fixtures; make failed prefetch and stale/last-known-good behavior visible and non-destructive; and retain duplicate-channel safeguards. These are development requirements only and do not authorize provider or publication mutation.
Sources: https://github.com/Pharaoh-Labs/teamarr/releases/tag/v2.13.1, https://github.com/Pharaoh-Labs/teamarr/releases/tag/v2.13.2, https://github.com/Pharaoh-Labs/teamarr/releases/tag/v2.14.0
Cross-reference: related ChannelForge concerns are tracked in #26, #30, #40, and #57.
Jumpstile commentedon Oct 3, 2026
Wrestling card v2 consumer dependency
PR #204 and the decision packet on #191 propose synthetic-only card-revision evidence linked to unchanged v1 event observations. No #30 consumer change is approved or included. If a future #30 slice consumes v2, it must explicitly dispatch on v2, preserve the linked v1 event identity, and use only source-supported bout references for cross-revision matching; participant/title/card-position similarity must not create canonical bout identity. Missing items in a later card revision remain uncertainty, not removal or cancellation.
The independent technical review recommends deferring consumer approval until the downstream owner/storage path is named. Storage/index decisions remain under #36. Product-owner and formal architecture decisions remain pending; this note is a dependency record, not acceptance of implementation.
Related to #29, #36, and #191.
Jumpstile commentedon Nov 14, 2026
Status update, Nov 14, 2026
Done and merged (PR #250, PR #252): the event-aware channels design note (docs/planning/EVENT-AWARE-CHANNELS-DESIGN-NOTE.md) and slice 1, which finds event channels and lists them in the build report. Nothing changes in the guide yet.
How it works: a scored detector rates each channel high, medium, or low. A PPV or Pay Per View name is the strongest signal. Only
highwill be applied automatically later. Medium and low stay on the normal provider guide and are only listed. It is fully automatic, with no approve or reject step.Checked on two real provider guides (read only): 21 channels rated high, no false positives seen, and every channel with PPV or Pay Per View as a whole word was rated high (9 of 9). Two small misses found: names like "PPV1" to "PPV4" are not matched, and a title that echoes the channel name with a small difference counts as real. A small fix PR is next.
Owner rules for this work:
Next slices: (2) agree event times across channels, report only; (3) apply automatically and build a per-channel event guide; (4) optional override.
Not verified: the
lowrule on real data (XMLTV carries no category), and Windows PowerShell 5.1 behavior of the detector.Jumpstile commentedon Nov 14, 2026
Status update, Nov 14, 2026 (5:40 pm EST)
Merged since the last note: the detector fix for PPV1-style names and near-echo placeholder titles (PR #254), and event slice 2 (PR #255): for channels the detector rated, it compares each event's start time across channels, keeps each channel's own time, and lists conflicts in the build summary. Report only; nothing in the guide or playlist output changes.
In progress: event slice 3, which builds the event guide automatically for channels rated high and falls back to the normal provider guide for a channel on any problem. No channel is dropped.
Not verified: the new report on real provider guides, Windows PowerShell 5.1, and the low rule on real data.
Jumpstile commentedon Nov 14, 2026
Status update, Nov 14, 2026 (7:00 pm EST)
Event slice 3 is merged (PR #256). Channels the detector rates high now get an event guide built automatically from their own provider programmes: real titles and times, and the channel name where there is no event. On any problem (unreadable time, no programmes, an error) the channel keeps its normal provider guide. No channel is dropped. Saved user choices win. Medium and low channels are unchanged.
Checked read-only on two real provider guides: 26 channels rated high, all 26 got an event guide, none fell back, none dropped. Eight converted times were checked by hand against the raw file. The reader accepts any time offset.
Known, not fixed: 1-second filler entries where a provider ends a programme at hh:59:59 and starts the next at hh:00:00 (cosmetic).
Not verified: a full Build-My-Lineup run with an applied event channel, Windows PowerShell 5.1, and the low rule on real data. Venue, city and carrying channels are not written yet (no free source named; provider guides only).
Next: optional override (slice 4).