every.channel: sanitized baseline

evolution/proposals/ECP-0004-global-stream-identifiers.md

@@ -0,0 +1,54 @@
+# ECP-0004: global stream identifiers and swarms
+
+Status: Draft
+
+## Problem
+
+We need a global, deterministic way to identify streams so that identical broadcasts from different antennas can converge in the same swarm without coordination.
+
+## Decision
+
+Adopt a two-layer identifier scheme:
+
+1. **Broadcast identity**: a logical identifier derived from broadcast metadata (PSIP/ATSC) such as transport stream ID and program number. This is the primary convergence key.
+2. **Source identity**: a physical identifier used when broadcast identity is not yet available (e.g., early ingestion). This is a fallback.
+
+A canonical stream ID string will be generated as:
+
+`ec/stream/v1/<scope>/<fields...>/profile-<profile>/variant-<variant>`
+
+Where `<scope>` is `broadcast` or `source`.
+
+### Broadcast scope fields
+
+- `standard` (e.g., `atsc`)
+- `tsid-<transport_stream_id>` (when known)
+- `program-<program_number>` (when known)
+- optional `callsign-<callsign>` and `region-<region>` as hints
+
+### Source scope fields
+
+- `kind` (e.g., `hdhr` or `linux-dvb`)
+- `device-<device_id>` when available
+- `channel-<channel_reference>` when available
+
+### Profile and variant
+
+- `profile` identifies the deterministic encoding profile.
+- `variant` identifies audio language, resolution, or alternate tracks.
+
+## Consequences
+
+- The network can converge on the same stream even when multiple relays ingest the same broadcast.
+- Early ingestion may start with `source` scope and migrate to `broadcast` scope once PSIP metadata is parsed.
+
+## Alternatives considered
+
+- Single opaque UUID per stream: rejected because it prevents convergence without coordination.
+- Content hash as stream ID: deferred; may be layered later as an availability primitive.
+
+## Rollout / teardown
+
+- Implement `StreamKey` in `ec-core`.
+- Extend ingest pipeline to parse PSIP/ATSC IDs and promote `source` to `broadcast` IDs.
+- Revise once PSIP parsing is in place.