chore(release): 1.1.0

- playout: run-scoped R2 manifest URIs (candidate a rewrite via rewriteManifestToRun) - tests: playlist_rewrite_test.go (rewrite + publish integration + slate guard) - docs: STREAMING, cloudflare-workers-setup, architecture (incl. Level-2 diagram) - release housekeeping: TODO->DONE, CHANGELOG 1.1.0, version bump
2026-09-03 09:27:38 +02:00
1 parent 8c5e70959b
commit d8cf853842
@@ -2,10 +2,10 @@

 ## Environments

-| Environment | Host | Docker Target | Purpose |
-|---|---|---|---|
-| **Test Lab** | `192.168.88.40` (internal) | `tcp://192.168.88.40:2375` | Integration testing, staging, CI/CD validation |
-| **Production** | Hetzner VPS (TBD) | `tcp://<hetzner-ip>:2375` | Public linearvoid.tv |
+| Environment    | Host                       | Docker Target              | Purpose                                        |
+| -------------- | -------------------------- | -------------------------- | ---------------------------------------------- |
+| **Test Lab**   | `192.168.88.40` (internal) | `tcp://192.168.88.40:2375` | Integration testing, staging, CI/CD validation |
+| **Production** | Hetzner VPS (TBD)          | `tcp://<hetzner-ip>:2375`  | Public linearvoid.tv                           |

 **Current state (2026-08-06):** Test lab is active and receives automated CD deploys. Production Hetzner VPS is **not yet provisioned**. `cd.yml` and `docker-compose.prod.yml` target the test lab; switching to production only requires changing `DOCKER_HOST`.

@@ -14,12 +14,14 @@
 **Status: Not provisioned.** Plan documented and pipeline ready; only the VPS needs creation.

 ### Planned Infrastructure
+
 - Provider: Hetzner Cloud, Region: Ashburn, VA (us-east)
 - Instance: CX22 (2 vCPU, 4 GB RAM, 40 GB SSD) or equivalent
 - OS: Ubuntu 24.04 LTS or Debian 12
 - Bandwidth: 20 TB included traffic/month; Estimated cost: ~€7–10/month base

 ### Cutover Plan
+
 1. Provision Hetzner VPS
 2. Add production secrets to Gitea (`CI_PROD_*` prefix)
 3. Update `DOCKER_HOST` in CD workflow to Hetzner public IP
@@ -29,6 +31,7 @@
 7. Decommission test lab as public target

 ### Production Preflight (minimum readiness gate)
+
 1. Verify Hetzner host reachable over SSH and Docker remote API TLS works for the Gitea runner
 2. Confirm all production secrets exist under `CI_PROD_*` prefix
 3. Confirm `linearvoid.tv`, `www.linearvoid.tv`, `media.linearvoid.tv` DNS targets match intended phase
@@ -37,22 +40,24 @@
 6. Verify rollback possible before final DNS switch

 ### Firewall / Security Group
-| Port | Source | Purpose |
-|---|---|---|
-| 22 | Admin IPs | SSH management |
-| 80 | 0.0.0.0/0 | HTTP (redirect to HTTPS) |
-| 443 | 0.0.0.0/0 | HTTPS (nginx) |
-| 2375 | Gitea runner IP only | Docker remote API (TLS) |
+
+| Port | Source                | Purpose                        |
+| ---- | --------------------- | ------------------------------ |
+| 22   | Admin IPs             | SSH management                 |
+| 80   | 0.0.0.0/0             | HTTP (redirect to HTTPS)       |
+| 443  | 0.0.0.0/0             | HTTPS (nginx)                  |
+| 2375 | Gitea runner IP only  | Docker remote API (TLS)        |
 | 9090 | Admin IPs or internal | Prometheus (or tunnel via SSH) |
-| 3001 | Admin IPs or internal | Grafana (or tunnel via SSH) |
+| 3001 | Admin IPs or internal | Grafana (or tunnel via SSH)    |

 ### Pipeline Readiness
-| Workflow | Trigger | Purpose |
-|---|---|---|
-| `ci.yml` | Push to `main` | Lint, build frontend, vet Go, build & push images (`:latest`, `:main`) |
-| `cd.yml` | Push to `main` | Deploy to test lab (`192.168.88.40:2375`) — runs **in parallel** with CI |
-| `release.yml` | Tag push `*.*.*` | Build & push versioned images (`:X.Y.Z`, `:X.Y`, `:latest`), create Gitea Release |
-| `workers-deploy.yml` | After CI succeeds | Deploy frontend to Cloudflare Workers |
+
+| Workflow             | Trigger           | Purpose                                                                           |
+| -------------------- | ----------------- | --------------------------------------------------------------------------------- |
+| `ci.yml`             | Push to `main`    | Lint, build frontend, vet Go, build & push images (`:latest`, `:main`)            |
+| `cd.yml`             | Push to `main`    | Deploy to test lab (`192.168.88.40:2375`) — runs **in parallel** with CI          |
+| `release.yml`        | Tag push `*.*.*`  | Build & push versioned images (`:X.Y.Z`, `:X.Y`, `:latest`), create Gitea Release |
+| `workers-deploy.yml` | After CI succeeds | Deploy frontend to Cloudflare Workers                                             |

 CI and CD run simultaneously on every push to `main`. Deploy pulls whatever `:latest` images are available at that moment. `cd.yml` uses `DOCKER_HOST` to target the host:

@@ -67,6 +72,7 @@ DOCKER_HOST=tcp://<hetzner-public-ip>:2375
 No pipeline code changes needed to switch targets.

 ## Target Topology
+
 - Host: Linux server with Docker Engine
 - Reverse proxy: nginx container (linearvoid-nginx)
 - Core services: playout, chat, redis, postgres
@@ -74,6 +80,7 @@ No pipeline code changes needed to switch targets.
 - CDN/edge: Cloudflare

 ## Prerequisites
+
 - Docker Engine + Docker Compose plugin
 - Network access to git.allucanget.biz
 - Valid `.env` file with production values
@@ -82,6 +89,7 @@ No pipeline code changes needed to switch targets.
 ## Environment File

 `.env` requires at minimum:
+
 - `DATABASE_URL` — PostgreSQL connection string
 - `REDIS_URL` — Redis connection string
 - `ADMIN_USERNAME` / `ADMIN_PASSWORD` — admin dashboard credentials
@@ -89,18 +97,21 @@ No pipeline code changes needed to switch targets.
 - `VITE_PUBLIC_APP_URL` / `VITE_PUBLIC_WS_URL` / `VITE_PUBLIC_HLS_URL` — frontend URLs

 **Cloudflare R2 (required for HLS segment sync to edge):**
+
 - `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY`
 - `R2_BUCKET_NAME` (e.g. `linearvoid-media`)
 - `R2_ENDPOINT` — S3-compatible endpoint URL
 - `R2_REGION` — set to `auto`

 **Cloudflare (optional, for Workers):**
+
 - `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID`
 - `MEDIA_DOMAIN` — split media domain (e.g. `media.linearvoid.tv`)

 See `.env.example` and `SETUP.md` for full variable reference.

 ### Gitea Secrets
+
 `cd.yml` injects sensitive values from Gitea secrets into `.env` at deploy time. Configure in the Gitea repository:

 `DATABASE_URL`, `ADMIN_USERNAME`, `ADMIN_PASSWORD`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`, `R2_ENDPOINT`, `R2_ADMIN_ACCESS_KEY_ID` (optional), `R2_ADMIN_SECRET_ACCESS_KEY` (optional), `R2_ADMIN_ENDPOINT` (optional), `CLOUDFLARE_API_TOKEN` (optional), `CLOUDFLARE_ACCOUNT_ID` (optional), `CI_REGISTRY_USER`, `CI_REGISTRY_TOKEN`
@@ -116,6 +127,7 @@ docker compose -f docker-compose.prod.yml up -d --remove-orphans
 ```

 ## First-Time or Recovery Provisioning
+
 ```bash
 mkdir -p data/chat data/playlist data/media data/hls
 docker volume ls
@@ -124,10 +136,13 @@ docker compose -f docker-compose.prod.yml up -d
 ```

 ## Health Verification
+
 ```bash
 docker compose -f docker-compose.prod.yml ps
 ```
+
 Endpoint checks:
+
 - App: `http://{host}:8080/`
 - Nginx health: `http://{host}:8080/health`
 - Chat health: `http://{host}:3000/health`
@@ -136,30 +151,38 @@ Endpoint checks:
 - Grafana: `http://{host}:3001`

 Domain checks:
+
 - `https://linearvoid.tv`
 - `https://linearvoid.tv/admin`
 - `https://linearvoid.tv/metrics`

 ## Zero/Low-Downtime Update Pattern
+
 1. Pull newest images.
 2. Recreate changed services only:
-```bash
-docker compose -f docker-compose.prod.yml pull
-docker compose -f docker-compose.prod.yml up -d nginx chat playout
-```
+
+   ```bash
+   docker compose -f docker-compose.prod.yml pull
+   docker compose -f docker-compose.prod.yml up -d nginx chat playout
+   ```
+
 3. Re-run health checks.

 ## Rollback
+
 If new images are unhealthy:
+
 1. Pin previous tags in `docker-compose.prod.yml`.
 2. Pull pinned tags.
 3. Restart impacted services:
+
 ```bash
 docker compose -f docker-compose.prod.yml pull
 docker compose -f docker-compose.prod.yml up -d nginx chat playout
 ```

 ## Operational Tasks
+
 ```bash
 # View logs
 docker compose -f docker-compose.prod.yml logs -f nginx chat playout
@@ -175,30 +198,34 @@ docker compose -f docker-compose.prod.yml down -v
 ```

 ## Nginx and Proxy Considerations
+
 - If an external proxy (e.g. Nginx Proxy Manager) fronts the stack, align request body limits with internal nginx (see `infrastructure/nginx/nginx.conf`).
 - For resumable admin uploads, ensure `client_max_body_size` supports chunk requests in both proxy layers.

 ## Security Baseline
+
 - Use a strong `ADMIN_PASSWORD` and rotate regularly.
 - Keep Docker host access restricted.
 - Prefer HTTPS/WSS through Cloudflare.
 - Restrict exposed ports if only proxy access is needed.

 ## Common Deployment Pitfalls
+
 - Missing frontend build artifacts in local-only compose workflows.
 - Wrong registry credentials or missing login.
 - Misaligned domain env vars (app/ws/hls) causing mixed-origin errors.

 ## Troubleshooting
-| Symptom | Check | Fix |
-|---|---|---|
-| Service not starting | `docker logs linearvoid-<svc> --tail 50` | Check `.env` vars, volume mounts, port conflicts |
-| Playout stall / slate mode | `curl http://<host>:8081/health` — mode=slate | Check playlist file, media paths, disk space |
-| Chat not connecting | `curl http://<host>:3000/health` | Check Redis: `docker exec linearvoid-redis redis-cli ping` |
-| Admin 401 loop | Cookie not sent | Verify `X-Forwarded-Proto: https`, nginx auth_request headers |
-| Upload fails (413) | File too large | Check nginx `client_max_body_size` (should be 64m+) |
-| HLS not playing | `curl http://<host>/hls/playlist.m3u8` | Check playout health, HLS dir permissions |
-| Prometheus no targets | `curl http://<host>:9090/targets` | Verify container network, scrape config |
-| Grafana no data | Check datasource | Verify Prometheus URL `http://prometheus:9090` provisioned |

-Additional notes: proxy-layer body size limits can return 413 on upload; health checks may fail before service warmup completes.
+| Symptom                    | Check                                         | Fix                                                           |
+| -------------------------- | --------------------------------------------- | ------------------------------------------------------------- |
+| Service not starting       | `docker logs linearvoid-<svc> --tail 50`      | Check `.env` vars, volume mounts, port conflicts              |
+| Playout stall / slate mode | `curl http://<host>:8081/health` — mode=slate | Check playlist file, media paths, disk space                  |
+| Chat not connecting        | `curl http://<host>:3000/health`              | Check Redis: `docker exec linearvoid-redis redis-cli ping`    |
+| Admin 401 loop             | Cookie not sent                               | Verify `X-Forwarded-Proto: https`, nginx auth_request headers |
+| Upload fails (413)         | File too large                                | Check nginx `client_max_body_size` (should be 64m+)           |
+| HLS not playing            | `curl http://<host>/hls/playlist.m3u8`        | Check playout health, HLS dir permissions                     |
+| Prometheus no targets      | `curl http://<host>:9090/targets`             | Verify container network, scrape config                       |
+| Grafana no data            | Check datasource                              | Verify Prometheus URL `http://prometheus:9090` provisioned    |
+
+Additional notes: proxy-layer body size limits can return 413 on upload; health checks may fail before service warmup completes.
@@ -26,14 +26,14 @@ Nginx `/hls/` is a local/test fallback, not the production origin. The SPA, admi

 Only validated files may enter the production playlist.

-| Property   | Required profile                                                         |
-| ---------- | ------------------------------------------------------------------------ |
-| Container  | MP4                                                                      |
-| Video      | H.264/AVC, `yuv420p`                                                     |
-| Resolution | 1280x720 or 1920x1080; avoid resolution changes within a playlist block   |
-| Frame rate | Constant 30 fps                                                          |
-| GOP        | Closed, fixed 2 seconds: `-g 60 -keyint_min 60 -sc_threshold 0`          |
-| Audio      | AAC-LC, stereo, 48 kHz, 128–192 kbit/s                                   |
+| Property   | Required profile                                                        |
+| ---------- | ----------------------------------------------------------------------- |
+| Container  | MP4                                                                     |
+| Video      | H.264/AVC, `yuv420p`                                                    |
+| Resolution | 1280x720 or 1920x1080; avoid resolution changes within a playlist block |
+| Frame rate | Constant 30 fps                                                         |
+| GOP        | Closed, fixed 2 seconds: `-g 60 -keyint_min 60 -sc_threshold 0`         |
+| Audio      | AAC-LC, stereo, 48 kHz, 128–192 kbit/s                                  |

 The ingest gate uses `ffprobe` to reject incompatible codecs, variable frame rate, missing audio, invalid dimensions, or wrong keyframe cadence. Assets are immutable after acceptance; corrections create a new asset ID/object key.

@@ -62,14 +62,14 @@ ffmpeg -i input.mov \

 The playout service wraps FFmpeg, tracks the active item/revision, restarts failed processes, and exposes `/health` plus Prometheus metrics.

-| Setting        | Value                                                                              |
-| -------------- | ---------------------------------------------------------------------------------- |
-| Protocol       | Standard live HLS, not LL-HLS                                                       |
-| Segment format | fMP4 (`.m4s`) with init segment; `.ts` may be supported during migration            |
-| Segment target | 2 seconds (`HLS_SEGMENT_DURATION=2`)                                               |
-| Live window    | 12 segments (`HLS_WINDOW_SIZE=12`), ~24 seconds                                    |
-| Codec path     | Stream copy for conforming assets; no per-viewer transcoding                       |
-| Expected latency | 15–35 seconds                                                                    |
+| Setting          | Value                                                                    |
+| ---------------- | ------------------------------------------------------------------------ |
+| Protocol         | Standard live HLS, not LL-HLS                                            |
+| Segment format   | fMP4 (`.m4s`) with init segment; `.ts` may be supported during migration |
+| Segment target   | 2 seconds (`HLS_SEGMENT_DURATION=2`)                                     |
+| Live window      | 12 segments (`HLS_WINDOW_SIZE=12`), ~24 seconds                          |
+| Codec path       | Stream copy for conforming assets; no per-viewer transcoding             |
+| Expected latency | 15–35 seconds                                                            |

 Segment boundaries must align with keyframes; timestamps must stay monotonic across item boundaries. If FFmpeg cannot preserve a seamless timeline, insert `#EXT-X-DISCONTINUITY` and publish the corresponding new init segment.

@@ -96,15 +96,25 @@ Order prevents a manifest referencing an unavailable segment:

 Never upload an actively written segment or publish the manifest first. Use a single publisher (or fencing/leader election) so two workers can't update the live manifest concurrently.

+**Run-scoped manifest URIs.** Segments and the init file are stored run-scoped under `hls/r-{runID}/…`, so the live `hls/playlist.m3u8` must reference them with that run prefix. Before the final commit step, the publisher rewrites each bare relative media URI (segments plus `#EXT-X-MAP:URI`) to `r-{runID}/<name>`. `publishManifest` in `backend/playout/src/playlist.go` does this via `rewriteManifestToRun`, using the same `runID` under which the segments were uploaded; the rewrite is skipped in slate mode (its manifest is served as-is). The published manifest therefore contains, e.g.:
+
+```m3u8
+#EXT-X-MAP:URI="r-20260807T170412Z/init.mp4"
+#EXTINF:2.000000,
+r-20260807T170412Z/seg-000001234.m4s
+```
+
+The `linearvoid-media` Worker on `media.linearvoid.tv` is a faithful path→R2 mapper and serves these run-scoped paths directly; it does **not** rewrite URIs at serve time.
+
 `data/hls/` is regenerable staging. Source media, playlist revisions, and schedule state are authoritative; generated HLS is not backed up as application state.

 ## Cache contract

-| Objects                    | Edge policy                       | Browser policy                          | Required headers/behavior                                                     |
-| -------------------------- | --------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------- |
-| `.m4s`, `.ts`, init `.mp4` | Cache eligible; TTL 1 year        | TTL 1 year                              | `Cache-Control: public, max-age=31536000, immutable`; full path in cache key |
-| Live `.m3u8`               | Cache eligible; edge TTL 2s       | Do not retain beyond freshness interval | `Cache-Control: public, max-age=1, s-maxage=2, must-revalidate`              |
-| Versioned JS/CSS           | Cache eligible; TTL 1 year        | TTL 1 year                              | Content-hashed filenames and `immutable`                                     |
+| Objects                    | Edge policy                 | Browser policy                          | Required headers/behavior                                                    |
+| -------------------------- | --------------------------- | --------------------------------------- | ---------------------------------------------------------------------------- |
+| `.m4s`, `.ts`, init `.mp4` | Cache eligible; TTL 1 year  | TTL 1 year                              | `Cache-Control: public, max-age=31536000, immutable`; full path in cache key |
+| Live `.m3u8`               | Cache eligible; edge TTL 2s | Do not retain beyond freshness interval | `Cache-Control: public, max-age=1, s-maxage=2, must-revalidate`              |
+| Versioned JS/CSS           | Cache eligible; TTL 1 year  | TTL 1 year                              | Content-hashed filenames and `immutable`                                     |

 Further rules:

@@ -159,21 +169,21 @@ A release is streaming-ready only when: one full playlist boundary plays without

 ## Required configuration

-| Variable                                   | Purpose                                            |
-| ------------------------------------------ | -------------------------------------------------- |
-| `PLAYLIST_PATH`                            | Active playlist file                               |
-| `HLS_SEGMENT_DURATION`                     | Target segment duration; baseline `2`              |
-| `HLS_WINDOW_SIZE`                          | Manifest window; baseline `12`                     |
-| `R2_ENDPOINT`, `R2_REGION`                 | S3-compatible publication endpoint                 |
-| `R2_BUCKET_NAME`                           | Media bucket                                       |
-| `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY` | Write credentials, publisher only                  |
-| `R2_KEEP_RUNS`                             | Run folders to retain (default `2`)                |
-| `R2_MAX_RETENTION_BYTES`                   | Max bytes across run folders (10 GiB)              |
-| `MEDIA_DOMAIN`                             | Public R2 custom domain                            |
-| `VITE_PUBLIC_HLS_URL`                      | Public live manifest URL                           |
+| Variable                                   | Purpose                               |
+| ------------------------------------------ | ------------------------------------- |
+| `PLAYLIST_PATH`                            | Active playlist file                  |
+| `HLS_SEGMENT_DURATION`                     | Target segment duration; baseline `2` |
+| `HLS_WINDOW_SIZE`                          | Manifest window; baseline `12`        |
+| `R2_ENDPOINT`, `R2_REGION`                 | S3-compatible publication endpoint    |
+| `R2_BUCKET_NAME`                           | Media bucket                          |
+| `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY` | Write credentials, publisher only     |
+| `R2_KEEP_RUNS`                             | Run folders to retain (default `2`)   |
+| `R2_MAX_RETENTION_BYTES`                   | Max bytes across run folders (10 GiB) |
+| `MEDIA_DOMAIN`                             | Public R2 custom domain               |
+| `VITE_PUBLIC_HLS_URL`                      | Public live manifest URL              |

 Production values: `MEDIA_DOMAIN=media.linearvoid.tv`, `VITE_PUBLIC_HLS_URL=https://media.linearvoid.tv/hls/playlist.m3u8`. Local fallback may use `http://localhost/hls/playlist.m3u8`.

 ## Explicitly deferred

-ABR ladders, LL-HLS, DVR/catch-up, multi-origin playout, and regional chat affinity are outside the v1 contract. Adding any requires an ADR and an update to this document.
+ABR ladders, LL-HLS, DVR/catch-up, multi-origin playout, and regional chat affinity are outside the v1 contract. Adding any requires an ADR and an update to this document.
@@ -156,11 +156,12 @@ graph TD
 graph TB
    subgraph "Cloudflare Edge"
        CF[CDN + WAF<br/>Cache Rules]
-        R2[R2 Bucket<br/>media + HLS]
-        WORKERS[Workers<br/>SPA hosting]
+        R2["R2 Bucket<br/>media + HLS<br/>hls/r-{runID}/… run-scoped"]
+        MEDIA[linearvoid-media Worker<br/>R2-bound · media.linearvoid.tv]
+        WORKERS[linearvoid-frontend Worker<br/>SPA hosting]
    end

-    subgraph "Docker Host (Hetzner CX22)"
+    subgraph "Docker Host"
        NGINX[nginx<br/>:80/:443<br/>proxy + auth]
        CHAT[chat service<br/>:3000<br/>Go + gorilla/websocket]
        PLAYOUT[playout service<br/>:8081<br/>Go + FFmpeg]
@@ -173,13 +174,14 @@ graph TB
        ADMIN[Admin Browser<br/>SPA + uploads]
    end

-    VIEWER -->|HTTPS| CF
-    VIEWER -->|WSS| NGINX
+    VIEWER -->|HTTPS SPA| CF
+    VIEWER -->|WSS Chat| NGINX
+    VIEWER -->|HTTPS /hls| MEDIA
    ADMIN -->|HTTPS| CF
    CF --> NGINX
+    MEDIA --> R2
    NGINX --> CHAT
    NGINX --> PLAYOUT
-    NGINX -->|/hls/*| R2
    CHAT --> REDIS
    CHAT --> DB
    PLAYOUT --> R2
@@ -189,7 +191,8 @@ graph TB
 **Playout Service** (`backend/playout/src/playlist.go`)

 - Role: continuous HLS encoding loop via FFmpeg concat demuxer.
- Input: `data/playlist/playlist.txt` (ordered MP4 paths); Output: HLS segments (`.m4s`, `.ts`) + live `.m3u8` to `data/hls/`, mirrored to R2.
+- Input: `data/playlist/playlist.txt` (ordered MP4 paths); Output: HLS segments (`.m4s`, `.ts`) + live `.m3u8` to `data/hls/`, mirrored to R2 run-scoped under `hls/r-{runID}/…`.
+- Run-scoped manifest: before publishing the live `hls/playlist.m3u8`, `publishManifest` rewrites bare media URIs to the current run folder (`rewriteManifestToRun`), so manifest → segment links resolve on `media.linearvoid.tv`. See [`STREAMING.md`](../STREAMING.md).
 - Resilience: restart counter (>5/60s → slate); Prometheus on 8081.
 - Validation: ffprobe gate (codec/fps/resolution/keyframe); `-validate` mode checks playlist without running.
 - Seamless looping: resets HLS only when playlist fingerprint (SHA-256) changes, crash/slate recovery, or first run; else continues via `-start_number`.
@@ -267,7 +270,7 @@ graph TB

 1. Admin adds normalized MP4 to R2 + updates playlist.
 2. Playout worker (FFmpeg concat loop) reads next file, packages HLS segments (2s).
-3. Segments uploaded to R2 with unique immutable names; live `.m3u8` updated.
+3. Segments uploaded to R2 with unique immutable, run-scoped names (`hls/r-{runID}/…`); the live `.m3u8` is published referencing those run-prefixed URIs (see `STREAMING.md`).
 4. Viewer loads SPA → requests manifest → hls.js follows current edge.
 5. Cloudflare serves `.m4s`/`.ts` from nearest edge cache (origin hit once per POP/region).
 6. Parallel WebSocket to chat service for synchronized interaction.
@@ -400,7 +403,7 @@ _Cache rules baseline_: `.ts`/`.m4s` Cache Everything, long TTL, immutable; `.m3

 _Edge security/controls_: enforce HTTPS/WSS + redirect HTTP; WAF baseline; rate limits on abusive patterns (auth/admin); minimize origin exposure.

-_Worker & header policy_: the `linearvoid-media` Worker ([`infrastructure/cloudflare/`](../../infrastructure/cloudflare/), R2-bound) owns `media.linearvoid.tv` and enforces immutable caching for segments, short TTL for live manifests, plus HLS CORS/Range; the `linearvoid-frontend` Worker ([`frontend/wrangler.toml`](../../frontend/wrangler.toml)) serves the static SPA on `linearvoid.tv`. Automated deploys: `workers-deploy.yml` (SPA) and `workers-media-deploy.yml` (media).
+_Worker & header policy_: the `linearvoid-media` Worker ([`infrastructure/cloudflare/`](../../infrastructure/cloudflare/), R2-bound) owns `media.linearvoid.tv` and enforces immutable caching for segments, short TTL for live manifests, plus HLS CORS/Range; it is a faithful path→R2 mapper and does **not** rewrite manifest URIs at serve time (playout rewrites them to run-scoped paths at publish — see [`STREAMING.md`](../STREAMING.md)). The `linearvoid-frontend` Worker ([`frontend/wrangler.toml`](../../frontend/wrangler.toml)) serves the static SPA on `linearvoid.tv`. Automated deploys: `workers-deploy.yml` (SPA) and `workers-media-deploy.yml` (media). Ops detail: [`cloudflare-workers-setup.md`](../operations/cloudflare-workers-setup.md).

 _Operations & validation_: verify cache status progression (MISS→HIT), manifest freshness under active playout; track hit ratio, request/error rates, ToS/cost posture.

@@ -21,6 +21,8 @@ Both are managed under **Workers & Pages** in the Cloudflare dashboard.

 The Worker in [`infrastructure/cloudflare/`](../../infrastructure/cloudflare/) runs on the `linearvoid-media` Workers service. It owns the `media.linearvoid.tv` host, serves HLS objects from the R2 bucket (bound as `MEDIA_BUCKET`), and stamps immutable `Cache-Control` on segments plus a short TTL on live manifests (CORS + Range supported). See its [README](../../infrastructure/cloudflare/README.md).

+**Run-scoped layout.** R2 objects are stored run-scoped (`hls/r-{runID}/seg-*.m4s`, `…/init.mp4`), and the live `hls/playlist.m3u8` references them with the run prefix (the playout rewrites bare URIs before publishing — see [`docs/STREAMING.md`](../STREAMING.md)). The Worker is a faithful path→R2 mapper: it serves whatever key the request path resolves to (e.g. `/hls/r-…/seg-*.m4s`), adds the cache headers by file type, and does not rewrite manifest URIs at serve time.
+
 Test / deploy:

 ```bash