every.channel: sanitized baseline

evolution/proposals/ECP-0003-hdhomerun-ingest.md

@@ -0,0 +1,29 @@
+# ECP-0003: HDHomeRun discovery and lineup ingest
+
+Status: Draft
+
+## Problem
+
+We need a reliable way to discover HDHomeRun devices on a LAN and ingest their channel lineups (including all fields) so we can map channels into every.channel.
+
+## Decision
+
+Implement a two-path discovery and ingest flow:
+
+1. UDP discovery broadcast to port 65001 using the HDHomeRun TLV packet format, wildcard device ID, and tuner device type filter.
+2. HTTP hydration using `/discover.json` and `/lineup.json` for full metadata.
+
+The UDP response supplies the IP and base capabilities, while the HTTP endpoints provide rich metadata and lineup entries. The ingest layer stores all unknown fields as raw JSON to keep future flexibility.
+
+Where mDNS is available, allow host-based discovery via `hdhomerun.local` or `<deviceid>.local` by fetching `http://<host>/discover.json`.
+
+## Alternatives considered
+
+- mDNS-only discovery: rejected because UDP discovery is the documented primary path and does not depend on mDNS configuration.
+- Manual IP entry only: rejected because it prevents zero-config onboarding.
+
+## Rollout / teardown
+
+- Add discovery and lineup ingestion to `ec-hdhomerun`.
+- Expose CLI commands for discovery and lineup JSON parsing.
+- If discovery proves unreliable on some platforms, add interface-specific broadcast addresses or a user-provided host override.