@torrent-tv/proxy 2.89.7 → 2.89.9

package/docs/encode-run-state.md

@@ -1,96 +1,96 @@
-<!-- GENERATED from services/encode/encode-run-state.js by scripts/render-run-graph.js.
-     Do not edit by hand: change the table and run `npm run graph`. -->
-
-# The encoder run — states and transitions
-
-One run of one ffmpeg inside one transcode session. The table this is drawn
-from is executed by `services/encode/EncodeRuns.js`; every transition a real
-run makes is logged as state, event and target, so a run that takes an edge
-absent here is a violation the log names.
-
-```mermaid
-stateDiagram-v2
-    state RUN {
-        [*] --> IDLE
-        state WORKING {
-            state ALIVE {
-                STARTING
-                PRODUCING
-                SUSPENDED
-            }
-            RETRY_WAIT
-        }
-        IDLE
-        STOPPED
-        ENDED_COMPLETE
-        ENDED_FAILED
-    }
-
-    RUN --> STARTING : SPAWNED
-    WORKING --> STOPPED : STOP_ORDERED
-    ALIVE --> SUSPENDED : SUSPEND_ORDERED
-    ALIVE --> ENDED_COMPLETE : EXITED_COMPLETE
-    ALIVE --> ENDED_FAILED : EXITED_SHORT
-    ALIVE --> RETRY_WAIT : EXITED_INPUT_LOST
-    ALIVE --> ENDED_FAILED : EXITED_FAILED
-    STARTING --> PRODUCING : FIRST_SEGMENT
-    SUSPENDED --> PRODUCING : RESUME_ORDERED
-    RETRY_WAIT --> IDLE : RETRY_DUE
-```
-
-## States
-
-| state | means |
-|---|---|
-| `IDLE` | No process, and one is expected — before the first run, or after a retry timer fired. |
-| `STARTING` | Spawned; this run has produced nothing servable yet. |
-| `PRODUCING` | This run has produced at least one servable segment. |
-| `SUSPENDED` | SIGSTOP delivered, process alive — and nothing is reading the input. |
-| `RETRY_WAIT` | The input went away; a restart is timed. Requests are held, not refused. |
-| `STOPPED` | Stopped on purpose with no replacement — a rung the viewer switched away from. |
-| `ENDED_COMPLETE` | Ran through the last segment of the file. Nothing is owed. |
-| `ENDED_FAILED` | Terminal for this target: requests are answered as failures. |
-
-## Events
-
-| event | means |
-|---|---|
-| `SPAWNED` | A process was spawned for this session. |
-| `FIRST_SEGMENT` | The first servable segment of this run was served. |
-| `SUSPEND_ORDERED` | SIGSTOP was delivered. |
-| `RESUME_ORDERED` | SIGCONT was sent. |
-| `STOP_ORDERED` | The run was stopped with no replacement. |
-| `EXITED_COMPLETE` | Exit 0, having produced through the last segment. |
-| `EXITED_SHORT` | Exit 0, short of the last segment — the input dried up. |
-| `EXITED_INPUT_LOST` | Died because the input was not there. Recoverable. |
-| `EXITED_FAILED` | Died for any other reason, or could not be spawned. |
-| `RETRY_DUE` | The input-retry timer fired. |
-
-## What each state answers
-
-Outputs depend on the state alone — computed here by calling the same
-functions the encoding component (`EncodeRuns`) calls.
-
-| state | reads its input | can be signalled | a missing segment | on the wire | may restart |
-|---|---|---|---|---|---|
-| `IDLE` | no | no | hold | `starting` | yes |
-| `STARTING` | yes | yes | hold | `running` | yes |
-| `PRODUCING` | yes | yes | hold | `running` | yes |
-| `SUSPENDED` | no | yes | hold | `running` | yes |
-| `RETRY_WAIT` | no | no | hold | `starting` | yes |
-| `STOPPED` | no | no | hold | `running` | yes |
-| `ENDED_COMPLETE` | no | no | hold | `ready` | no |
-| `ENDED_FAILED` | no | no | fail | `failed` | yes |
-
-## Edges that must never exist
-
-The machine's real content: a near-complete digraph asserts nothing.
-
-| from | event | must not reach | because |
-|---|---|---|---|
-| `SUSPENDED` | `FIRST_SEGMENT` | `PRODUCING` | a segment request must not release a suspended encoder — 2.9.93, where any request did, and the run sawtoothed from 155 s to 922 s ahead of the viewer in three minutes |
-| `ENDED_FAILED` | `FIRST_SEGMENT` | `PRODUCING` | a dead run is not a producing one — 2.9.93, where the handle pointed at a corpse and every later seek was waved through as already covered, so the session answered 500 for ever |
-| `ENDED_FAILED` | `RESUME_ORDERED` | `PRODUCING` | there is no process to continue; only a spawn leads out of a failure |
-| `IDLE` | `FIRST_SEGMENT` | `PRODUCING` | nothing produces before a process exists |
-| `RETRY_WAIT` | `FIRST_SEGMENT` | `PRODUCING` | a run waiting for its input back has no process; only a spawn resumes production |
-| `STOPPED` | `RESUME_ORDERED` | `PRODUCING` | a rung the viewer switched away from must not be revived by its own held requests — the host has one encoder's worth of capacity and the rung on screen needs it |
+<!-- GENERATED from services/encode/encode-run-state.js by scripts/render-run-graph.js.
+     Do not edit by hand: change the table and run `npm run graph`. -->
+
+# The encoder run — states and transitions
+
+One run of one ffmpeg inside one transcode session. The table this is drawn
+from is executed by `services/encode/EncodeRuns.js`; every transition a real
+run makes is logged as state, event and target, so a run that takes an edge
+absent here is a violation the log names.
+
+```mermaid
+stateDiagram-v2
+    state RUN {
+        [*] --> IDLE
+        state WORKING {
+            state ALIVE {
+                STARTING
+                PRODUCING
+                SUSPENDED
+            }
+            RETRY_WAIT
+        }
+        IDLE
+        STOPPED
+        ENDED_COMPLETE
+        ENDED_FAILED
+    }
+
+    RUN --> STARTING : SPAWNED
+    WORKING --> STOPPED : STOP_ORDERED
+    ALIVE --> SUSPENDED : SUSPEND_ORDERED
+    ALIVE --> ENDED_COMPLETE : EXITED_COMPLETE
+    ALIVE --> ENDED_FAILED : EXITED_SHORT
+    ALIVE --> RETRY_WAIT : EXITED_INPUT_LOST
+    ALIVE --> ENDED_FAILED : EXITED_FAILED
+    STARTING --> PRODUCING : FIRST_SEGMENT
+    SUSPENDED --> PRODUCING : RESUME_ORDERED
+    RETRY_WAIT --> IDLE : RETRY_DUE
+```
+
+## States
+
+| state | means |
+|---|---|
+| `IDLE` | No process, and one is expected — before the first run, or after a retry timer fired. |
+| `STARTING` | Spawned; this run has produced nothing servable yet. |
+| `PRODUCING` | This run has produced at least one servable segment. |
+| `SUSPENDED` | SIGSTOP delivered, process alive — and nothing is reading the input. |
+| `RETRY_WAIT` | The input went away; a restart is timed. Requests are held, not refused. |
+| `STOPPED` | Stopped on purpose with no replacement — a rung the viewer switched away from. |
+| `ENDED_COMPLETE` | Ran through the last segment of the file. Nothing is owed. |
+| `ENDED_FAILED` | Terminal for this target: requests are answered as failures. |
+
+## Events
+
+| event | means |
+|---|---|
+| `SPAWNED` | A process was spawned for this session. |
+| `FIRST_SEGMENT` | The first servable segment of this run was served. |
+| `SUSPEND_ORDERED` | SIGSTOP was delivered. |
+| `RESUME_ORDERED` | SIGCONT was sent. |
+| `STOP_ORDERED` | The run was stopped with no replacement. |
+| `EXITED_COMPLETE` | Exit 0, having produced through the last segment. |
+| `EXITED_SHORT` | Exit 0, short of the last segment — the input dried up. |
+| `EXITED_INPUT_LOST` | Died because the input was not there. Recoverable. |
+| `EXITED_FAILED` | Died for any other reason, or could not be spawned. |
+| `RETRY_DUE` | The input-retry timer fired. |
+
+## What each state answers
+
+Outputs depend on the state alone — computed here by calling the same
+functions the session manager calls.
+
+| state | reads its input | can be signalled | a missing segment | on the wire | may restart |
+|---|---|---|---|---|---|
+| `IDLE` | no | no | hold | `starting` | yes |
+| `STARTING` | yes | yes | hold | `running` | yes |
+| `PRODUCING` | yes | yes | hold | `running` | yes |
+| `SUSPENDED` | no | yes | hold | `running` | yes |
+| `RETRY_WAIT` | no | no | hold | `starting` | yes |
+| `STOPPED` | no | no | hold | `running` | yes |
+| `ENDED_COMPLETE` | no | no | hold | `ready` | no |
+| `ENDED_FAILED` | no | no | fail | `failed` | yes |
+
+## Edges that must never exist
+
+The machine's real content: a near-complete digraph asserts nothing.
+
+| from | event | must not reach | because |
+|---|---|---|---|
+| `SUSPENDED` | `FIRST_SEGMENT` | `PRODUCING` | a segment request must not release a suspended encoder — 2.9.93, where any request did, and the run sawtoothed from 155 s to 922 s ahead of the viewer in three minutes |
+| `ENDED_FAILED` | `FIRST_SEGMENT` | `PRODUCING` | a dead run is not a producing one — 2.9.93, where the handle pointed at a corpse and every later seek was waved through as already covered, so the session answered 500 for ever |
+| `ENDED_FAILED` | `RESUME_ORDERED` | `PRODUCING` | there is no process to continue; only a spawn leads out of a failure |
+| `IDLE` | `FIRST_SEGMENT` | `PRODUCING` | nothing produces before a process exists |
+| `RETRY_WAIT` | `FIRST_SEGMENT` | `PRODUCING` | a run waiting for its input back has no process; only a spawn resumes production |
+| `STOPPED` | `RESUME_ORDERED` | `PRODUCING` | a rung the viewer switched away from must not be revived by its own held requests — the host has one encoder's worth of capacity and the rung on screen needs it |

package/docs/logs.md

@@ -1,97 +1,97 @@
-# Logs — where to look
-
-No browser console copy-paste is needed: the page forwards its own log. But it
-lands in TWO places depending on the phase of the session, and `docker logs` is
-only one of them — see "Browser logs are in TWO places" below before concluding
-anything from a half-session.
-
-## HA proxy (aarch64, addon `b34a1737_torrent_tv_proxy`)
-
-Image `b34a1737/aarch64-addon-torrent_tv_proxy:<version>` = `@torrent-tv/proxy` `<version>` (see `ha-addon/torrent_tv_proxy/config.yaml`).
-
-- Console + file are the same: the proxy logs to both `stdout` and `/data/proxy.log` on start (`logging to /data/proxy.log as well as the console`).
-- **Since 2.71.0 that is true of the torrent thread too, and it was not before.**
-  A worker thread loads its own instance of every module, so the logger's file
-  handle — set once, on the main thread — was null in the worker for the life of
-  the process. Measured over a whole 49 938-line file: zero lines from the piece
-  reader (`read "…"`, `supply "…"`, every wait and its cause) and zero from the
-  torrent pool, against 52 and 36 of them in `docker logs`, which every release
-  destroys. The worker now sends its lines to the main thread, which is the only
-  writer; a line from there reads `torrent-worker: …`.
-- Via container:
-  ```bash
-  ssh ha "sudo docker logs app_b34a1737_torrent_tv_proxy --tail 200"
-  ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy cat /data/proxy.log | tail -n 300"
-  ```
-- Filter by session: every transcode session logs its id, e.g. `003ed2fd-7c9b-4cd5-9d05-ff875ff2be23`, `hold segment-00068.mp4 failed`, `encode-run failed`, `EXITED_*`.
-- Host file `/data/proxy.log` survives `docker logs` rotation; `core dumps: 1 present` line shows kept dump under `/data`.
-
-SSH to HA requires `MACs hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,umac-128-etm@openssh.com` — server `OpenSSH_10.3` on `homeassistant.local` offers only `*-etm` (`Unable to negotiate` / `Corrupted MAC` otherwise). Already in `~/.ssh/config` `Host ha`.
-
-## DO server (webauth.courses, `infra-server-1`)
-
-- Server is `infra-server-1` (`ghcr.io/torrent-tv/server:latest`) on `do` (`206.189.97.152`).
-- Frontend logs reach here only in the phases the proxy cannot be reached in — see "Browser logs are in TWO places" below. When they do, the server `console.log`s them with the prefix `[client <tag> <id> sig=<webrtcSessionId>]` (`server/routes/api/client-logs/post.js`), in the same container as its own lines.
-- Via container:
-  ```bash
-  ssh do "docker logs infra-server-1 --tail 200 | cat"
-  # filter a single viewing:
-  ssh do "docker logs infra-server-1 --tail 500 | grep 003ed2fd"
-  ssh do "docker logs infra-server-1 --tail 500 | grep '\[client'"
-  ```
-- No need to open eruda or copy the browser console on a phone — it is forwarded.
-
-## Browser logs are in TWO places, split by phase — read both
-
-Until 2026-09-13 the page's whole log went to the droplet's standard output,
-which every release of the server destroys. A viewer reported a desync and a
-frozen picture that day and the analysis ran on half the evidence, so the log
-moved to the proxy — beside the proxy's own, on the same durable directory.
-
-The split is by PHASE, and neither half is the whole session:
-
-1. **Before a transport exists** — the page opening, the proxy being chosen, a
-   connection failing — there is nowhere else to send it, so it goes to the
-   SERVER (`infra-server-1`);
-2. **From the moment the data channel is up**, the page's logger is given a
-   proxy sink (`loading.js`, `setProxySink`) and every batch goes to the PROXY
-   over that channel. This is the bulk of a viewing;
-3. **At unload** it goes to the server again: `navigator.sendBeacon` is the only
-   thing a page that is going away can use, and a data channel is not;
-4. **A batch that cannot reach the proxy** falls back to the server.
-
-So a session that failed while connecting is on the droplet, a session that
-failed while playing is on the addon host, and a complete reading of a long
-failure needs both.
-
-### The files on the proxy
-
-One file per viewing session, in the proxy log's own directory (`/data` on the
-addon host), named so the two halves join without guessing:
-
-```
-client-<YYYYMMDD-HHMMSS UTC of the session start>-<sessionId:8>-<torrent name:60>-<infoHash:8>.log
-```
-
-A session that has not chosen a torrent yet writes `no-torrent-yet` in that
-last part — the file is keyed by the session id, not by the name, so choosing a
-torrent later does NOT start a second file. Rotated at 16 MB to `<name>.log.1`.
-
-```bash
-ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy sh -c 'ls -la /data/client-*.log'"
-ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy sh -c 'cat /data/client-20260913-*.log'"
-```
-
-Implementation: `utils/client-log-file.js`, route `routes/api/client-logs/post.js`.
-
-## Quick triage
-
-- Rewind/seek bug (hold 0ms → 500): HA `hold ... failed after 0ms → 500` + `encode-run` lines for the same `<sessionId>`, and DO `[client ...] fragLoadError / levelLoadError 500` for same `sn`.
-- Cushion / link budget: HA `memory: rss=... anon=...` and `cushion` lines; DO `[eta]` / `[cushion]` from client.
-- Update check: `ssh ha "sudo docker exec hassio_cli ha apps info b34a1737_torrent_tv_proxy | grep version"` and `ssh ha "sudo docker ps --filter name=app_b34a1737_torrent_tv_proxy"`.
-
-## Related
-
-- `ha-addon/CLAUDE.md` — addon build/update detour via `hassio_cli`, cache-bust via `config.yaml` version.
-- `docs/container-architecture.md` — what container/track classes log and where.
-- `routes/api/client-logs/post.js` and `server/routes/api/client-logs/post.js` — the two receivers; both sanitize the same way (control chars → space, `MAX_LINES`, `MAX_MSG_LEN`).
+# Logs — where to look
+
+No browser console copy-paste is needed: the page forwards its own log. But it
+lands in TWO places depending on the phase of the session, and `docker logs` is
+only one of them — see "Browser logs are in TWO places" below before concluding
+anything from a half-session.
+
+## HA proxy (aarch64, addon `b34a1737_torrent_tv_proxy`)
+
+Image `b34a1737/aarch64-addon-torrent_tv_proxy:<version>` = `@torrent-tv/proxy` `<version>` (see `ha-addon/torrent_tv_proxy/config.yaml`).
+
+- Console + file are the same: the proxy logs to both `stdout` and `/data/proxy.log` on start (`logging to /data/proxy.log as well as the console`).
+- **Since 2.71.0 that is true of the torrent thread too, and it was not before.**
+  A worker thread loads its own instance of every module, so the logger's file
+  handle — set once, on the main thread — was null in the worker for the life of
+  the process. Measured over a whole 49 938-line file: zero lines from the piece
+  reader (`read "…"`, `supply "…"`, every wait and its cause) and zero from the
+  torrent pool, against 52 and 36 of them in `docker logs`, which every release
+  destroys. The worker now sends its lines to the main thread, which is the only
+  writer; a line from there reads `torrent-worker: …`.
+- Via container:
+  ```bash
+  ssh ha "sudo docker logs app_b34a1737_torrent_tv_proxy --tail 200"
+  ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy cat /data/proxy.log | tail -n 300"
+  ```
+- Filter by session: every transcode session logs its id, e.g. `003ed2fd-7c9b-4cd5-9d05-ff875ff2be23`, `hold segment-00068.mp4 failed`, `encode-run failed`, `EXITED_*`.
+- Host file `/data/proxy.log` survives `docker logs` rotation; `core dumps: 1 present` line shows kept dump under `/data`.
+
+SSH to HA requires `MACs hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,umac-128-etm@openssh.com` — server `OpenSSH_10.3` on `homeassistant.local` offers only `*-etm` (`Unable to negotiate` / `Corrupted MAC` otherwise). Already in `~/.ssh/config` `Host ha`.
+
+## DO server (webauth.courses, `infra-server-1`)
+
+- Server is `infra-server-1` (`ghcr.io/torrent-tv/server:latest`) on `do` (`206.189.97.152`).
+- Frontend logs reach here only in the phases the proxy cannot be reached in — see "Browser logs are in TWO places" below. When they do, the server `console.log`s them with the prefix `[client <tag> <id> sig=<webrtcSessionId>]` (`server/routes/api/client-logs/post.js`), in the same container as its own lines.
+- Via container:
+  ```bash
+  ssh do "docker logs infra-server-1 --tail 200 | cat"
+  # filter a single viewing:
+  ssh do "docker logs infra-server-1 --tail 500 | grep 003ed2fd"
+  ssh do "docker logs infra-server-1 --tail 500 | grep '\[client'"
+  ```
+- No need to open eruda or copy the browser console on a phone — it is forwarded.
+
+## Browser logs are in TWO places, split by phase — read both
+
+Until 2026-09-13 the page's whole log went to the droplet's standard output,
+which every release of the server destroys. A viewer reported a desync and a
+frozen picture that day and the analysis ran on half the evidence, so the log
+moved to the proxy — beside the proxy's own, on the same durable directory.
+
+The split is by PHASE, and neither half is the whole session:
+
+1. **Before a transport exists** — the page opening, the proxy being chosen, a
+   connection failing — there is nowhere else to send it, so it goes to the
+   SERVER (`infra-server-1`);
+2. **From the moment the data channel is up**, the page's logger is given a
+   proxy sink (`loading.js`, `setProxySink`) and every batch goes to the PROXY
+   over that channel. This is the bulk of a viewing;
+3. **At unload** it goes to the server again: `navigator.sendBeacon` is the only
+   thing a page that is going away can use, and a data channel is not;
+4. **A batch that cannot reach the proxy** falls back to the server.
+
+So a session that failed while connecting is on the droplet, a session that
+failed while playing is on the addon host, and a complete reading of a long
+failure needs both.
+
+### The files on the proxy
+
+One file per viewing session, in the proxy log's own directory (`/data` on the
+addon host), named so the two halves join without guessing:
+
+```
+client-<YYYYMMDD-HHMMSS UTC of the session start>-<sessionId:8>-<torrent name:60>-<infoHash:8>.log
+```
+
+A session that has not chosen a torrent yet writes `no-torrent-yet` in that
+last part — the file is keyed by the session id, not by the name, so choosing a
+torrent later does NOT start a second file. Rotated at 16 MB to `<name>.log.1`.
+
+```bash
+ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy sh -c 'ls -la /data/client-*.log'"
+ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy sh -c 'cat /data/client-20260913-*.log'"
+```
+
+Implementation: `utils/client-log-file.js`, route `routes/api/client-logs/post.js`.
+
+## Quick triage
+
+- Rewind/seek bug (hold 0ms → 500): HA `hold ... failed after 0ms → 500` + `encode-run` lines for the same `<sessionId>`, and DO `[client ...] fragLoadError / levelLoadError 500` for same `sn`.
+- Cushion / link budget: HA `memory: rss=... anon=...` and `cushion` lines; DO `[eta]` / `[cushion]` from client.
+- Update check: `ssh ha "sudo docker exec hassio_cli ha apps info b34a1737_torrent_tv_proxy | grep version"` and `ssh ha "sudo docker ps --filter name=app_b34a1737_torrent_tv_proxy"`.
+
+## Related
+
+- `ha-addon/CLAUDE.md` — addon build/update detour via `hassio_cli`, cache-bust via `config.yaml` version.
+- `docs/container-architecture.md` — what container/track classes log and where.
+- `routes/api/client-logs/post.js` and `server/routes/api/client-logs/post.js` — the two receivers; both sanitize the same way (control chars → space, `MAX_LINES`, `MAX_MSG_LEN`).

package/docs/playback-start-forecast.md

@@ -1,113 +1,113 @@
-# Playback start forecast
-
-For resource r, measured service is S_r(t) = rate_r * t. New observations
-replace the conditional future rate; polling cannot invent acceleration,
-exponential recovery or a new physical measurement.
-
-Source work uses the file's measured byte density, missing local byte ranges
-and the observed torrent download rate. Shared input ranges are downloaded
-once. Files on the same torrent share a queue; distinct torrents use distinct
-observed services. Local input reading is included in effective processing
-speed, rather than charged again as a separate disk or memory delay.
-
-Each output's remaining processing work subtracts progress only within its
-actual live run intervals. Initial video rates use existing codec/size/encoder
-calibration. Initial audio rates use short packaged per-codec measurements and
-sample work (encoding) or encoded bytes (copying). Actual output progress
-replaces these initial rates. That rate is the run's processing speed: film
-made over the run's own working time, with the time its input waited for the
-swarm and the time it was stopped taken out (`RunClock`, fed by the stream
-route, which marks each wait of a run's input read). The download is charged
-once, by the source service, and not a second time inside the processing rate. Startup is charged once, separately from processing
-throughput, and disappears once actual run progress establishes processing.
-
-Input arrival and processing overlap. With arrival time D(m), processing rate
-e and previous completion C, completion for an interval [a,b] is
-
-    max(C + (b-a)/e, sup_m(D(m) + (b-m)/e)).
-
-Between service boundaries these functions are linear, so only endpoints are
-needed. Client delivery follows production and shares the observed link queue.
-Measured client ranges and prepared media establish each track's deadlines.
-
-The minimum start delay for this conditional trajectory is
-
-    max(0, max_j(completion_j - presentation_deadline_j)).
-
-This covers the remaining finite movie, including rates below real time. Slow
-positive service gives a finite preproduction delay; it is not rejected by a
-browser-capacity threshold or a capped search. Observed supply-interruption
-coverage is held in prepared proxy media and client media, without requiring
-the browser to hold it all.
-
-Critical review: future rates can change, average byte density is an initial
-mapping rather than an exact packet index, initial audio sample-work scaling
-does not model every decoder's nonlinear cost, and client receive/append time
-is not separately measured. These are approximation limits, not hidden weights.
-Actual progress, segment sizes and link observations refine the prediction.
-The client countdown uses elapsed local monotonic time; expiration cannot
-authorize playback. Only the proxy's readiness and real track coverage can.
-
-Zero service, missing media facts and a genuine timestamp gap remain explicit
-noncomputable states. The UI reports their causes instead of an estimating
-placeholder or a fabricated duration.
-
-## Continuity is decided in exact time
-
-The forecast lives in the viewer component (`services/viewer/`), because what
-it predicts is how the viewer's browser will play; the request operation
-(`ViewerRequests`) is handed it by `wire-outputs.js`.
-
-1. **The file states integers.** A piece's media is read as presentation
-   intervals in the integer ticks of each track's timescale
-   (`readPresentationRanges`, `services/encode/segment-formats/mp4-boxes.js`).
-   Intervals are joined there only where they touch or overlap; the format
-   states what the samples say and nothing about browsers.
-2. **One function places a piece.** The position written into `tfdt` when a
-   piece is served and the position its coverage is read at both come from
-   `readTrackEdits`, which converts the movie-timescale edit into track ticks
-   with one stated rounding. The reader and the writer cannot disagree.
-3. **Seconds from the page are exact fractions.** A buffered range, a position
-   or a cut time arrives as a JavaScript number, which is a binary fraction;
-   `services/viewer/media-time.js` converts it to that fraction exactly. No unit
-   is chosen. A buffered range is widened by `REPORTED_TIME_ERROR`, the bound of
-   Chromium's three truncations to whole microseconds, so that it denotes every
-   exact time the report can stand for.
-4. **The join rule holds in every engine.** The Media Source specification
-   leaves the threshold to the implementation, so a gap counts as joined only
-   when Chromium, Gecko and WebKit all join it: twice the gap within the two
-   ranges' longest frames since a keyframe (Gecko's fuzz), and the gap within
-   2002/24000 s (WebKit's `timeFudgeFactor`). Chromium's own bound follows from
-   the first. Old iOS without Media Source plays HLS in a closed player, and
-   nothing is derived for it.
-
-Seconds appear again only for rates, schedules and the answer.
-
-## A piece is finished when its frames reach its cut
-
-A closed non-final fragment is reusable only if the end of its last frame, on
-every track, reaches its muxer's cut less `SEGMENT_CUT_TIME_DELTA_SECONDS`,
-the delta the muxer is configured with. That is a fact of production, so no
-browser frame allowance is used to decide completeness. For explicit cuts the
-closure channel is CSV: its reference packet end has not lost the fraction of
-a movie tick that MP4's empty edit loses. The first reference packet's time is
-recovered from that end minus the first piece's exact sample span (the first
-CSV start is zero even after a seek), and is added to the relative cut times
-handed to FFmpeg. Comparisons use integer microseconds, as FFmpeg's segment
-muxer does. A stored piece without this closure reading carries the upper
-uncertainty of its empty edit, read from the movie and track timescales.
-
-The last frame must still reach the cut on every track. No playable media, a
-missing full frame, or a failed rename remains a publication failure. Such a
-failure stops the run, records that cause and releases its claimed interval;
-the existing repeated-start failure limit applies to subsequent attempts. A
-refused file cannot stay claimed while the encoder finishes the whole film.
-
-The encoding decides completeness
-(`encode/piece-completeness.js`): `EncodeRuns` judges a closed file before it is
-published, and judges a stored piece left by an earlier process when the
-forecast asks for it, taking a short one off the disk. The segment store keeps
-the bytes and the media intervals read from them and judges nothing. Interrupted
-fragments are therefore never served or counted, so the production schedule
-treats their media as unfinished work. The final fragment uses its actual media
-end rather than the container's approximate duration.
+# Playback start forecast
+
+For resource r, measured service is S_r(t) = rate_r * t. New observations
+replace the conditional future rate; polling cannot invent acceleration,
+exponential recovery or a new physical measurement.
+
+Source work uses the file's measured byte density, missing local byte ranges
+and the observed torrent download rate. Shared input ranges are downloaded
+once. Files on the same torrent share a queue; distinct torrents use distinct
+observed services. Local input reading is included in effective processing
+speed, rather than charged again as a separate disk or memory delay.
+
+Each output's remaining processing work subtracts progress only within its
+actual live run intervals. Initial video rates use existing codec/size/encoder
+calibration. Initial audio rates use short packaged per-codec measurements and
+sample work (encoding) or encoded bytes (copying). Actual output progress
+replaces these initial rates. That rate is the run's processing speed: film
+made over the run's own working time, with the time its input waited for the
+swarm and the time it was stopped taken out (`RunClock`, fed by the stream
+route, which marks each wait of a run's input read). The download is charged
+once, by the source service, and not a second time inside the processing rate. Startup is charged once, separately from processing
+throughput, and disappears once actual run progress establishes processing.
+
+Input arrival and processing overlap. With arrival time D(m), processing rate
+e and previous completion C, completion for an interval [a,b] is
+
+    max(C + (b-a)/e, sup_m(D(m) + (b-m)/e)).
+
+Between service boundaries these functions are linear, so only endpoints are
+needed. Client delivery follows production and shares the observed link queue.
+Measured client ranges and prepared media establish each track's deadlines.
+
+The minimum start delay for this conditional trajectory is
+
+    max(0, max_j(completion_j - presentation_deadline_j)).
+
+This covers the remaining finite movie, including rates below real time. Slow
+positive service gives a finite preproduction delay; it is not rejected by a
+browser-capacity threshold or a capped search. Observed supply-interruption
+coverage is held in prepared proxy media and client media, without requiring
+the browser to hold it all.
+
+Critical review: future rates can change, average byte density is an initial
+mapping rather than an exact packet index, initial audio sample-work scaling
+does not model every decoder's nonlinear cost, and client receive/append time
+is not separately measured. These are approximation limits, not hidden weights.
+Actual progress, segment sizes and link observations refine the prediction.
+The client countdown uses elapsed local monotonic time; expiration cannot
+authorize playback. Only the proxy's readiness and real track coverage can.
+
+Zero service, missing media facts and a genuine timestamp gap remain explicit
+noncomputable states. The UI reports their causes instead of an estimating
+placeholder or a fabricated duration.
+
+## Continuity is decided in exact time
+
+The forecast lives in the viewer component (`services/viewer/`), because what
+it predicts is how the viewer's browser will play; the request operation
+(`ViewerRequests`) is handed it by `wire-outputs.js`.
+
+1. **The file states integers.** A piece's media is read as presentation
+   intervals in the integer ticks of each track's timescale
+   (`readPresentationRanges`, `services/encode/segment-formats/mp4-boxes.js`).
+   Intervals are joined there only where they touch or overlap; the format
+   states what the samples say and nothing about browsers.
+2. **One function places a piece.** The position written into `tfdt` when a
+   piece is served and the position its coverage is read at both come from
+   `readTrackEdits`, which converts the movie-timescale edit into track ticks
+   with one stated rounding. The reader and the writer cannot disagree.
+3. **Seconds from the page are exact fractions.** A buffered range, a position
+   or a cut time arrives as a JavaScript number, which is a binary fraction;
+   `services/viewer/media-time.js` converts it to that fraction exactly. No unit
+   is chosen. A buffered range is widened by `REPORTED_TIME_ERROR`, the bound of
+   Chromium's three truncations to whole microseconds, so that it denotes every
+   exact time the report can stand for.
+4. **The join rule holds in every engine.** The Media Source specification
+   leaves the threshold to the implementation, so a gap counts as joined only
+   when Chromium, Gecko and WebKit all join it: twice the gap within the two
+   ranges' longest frames since a keyframe (Gecko's fuzz), and the gap within
+   2002/24000 s (WebKit's `timeFudgeFactor`). Chromium's own bound follows from
+   the first. Old iOS without Media Source plays HLS in a closed player, and
+   nothing is derived for it.
+
+Seconds appear again only for rates, schedules and the answer.
+
+## A piece is finished when its frames reach its cut
+
+A closed non-final fragment is reusable only if the end of its last frame, on
+every track, reaches its muxer's cut less `SEGMENT_CUT_TIME_DELTA_SECONDS`,
+the delta the muxer is configured with. That is a fact of production, so no
+browser frame allowance is used to decide completeness. For explicit cuts the
+closure channel is CSV: its reference packet end has not lost the fraction of
+a movie tick that MP4's empty edit loses. The first reference packet's time is
+recovered from that end minus the first piece's exact sample span (the first
+CSV start is zero even after a seek), and is added to the relative cut times
+handed to FFmpeg. Comparisons use integer microseconds, as FFmpeg's segment
+muxer does. A stored piece without this closure reading carries the upper
+uncertainty of its empty edit, read from the movie and track timescales.
+
+The last frame must still reach the cut on every track. No playable media, a
+missing full frame, or a failed rename remains a publication failure. Such a
+failure stops the run, records that cause and releases its claimed interval;
+the existing repeated-start failure limit applies to subsequent attempts. A
+refused file cannot stay claimed while the encoder finishes the whole film.
+
+The encoding decides completeness
+(`encode/piece-completeness.js`): `EncodeRuns` judges a closed file before it is
+published, and judges a stored piece left by an earlier process when the
+forecast asks for it, taking a short one off the disk. The segment store keeps
+the bytes and the media intervals read from them and judges nothing. Interrupted
+fragments are therefore never served or counted, so the production schedule
+treats their media as unfinished work. The final fragment uses its actual media
+end rather than the container's approximate duration.