@torrent-tv/proxy 2.86.0 → 2.87.0

package/docs/{disk-architecture.md → storage-architecture.md}

@@ -7,7 +7,7 @@ ceilings, each standing for the whole disk.
 | what | where | what bounded it before |
 |---|---|---|
 | segments an encoder produced | `services/encode/SegmentStore.js` | a quarter of what was free, plus a 2 GB floor — both numbers chosen by hand |
-| pieces the memory store spilled | `services/piece-store/piece-disk-store.js` | **nothing at all** |
+| pieces the memory store spilled | `services/storage/piece-store/piece-disk-store.js` | **nothing at all** |
 | diagnostics kept on purpose | `/data` — core dumps, heap snapshots, packet captures | a count of files, never a size |
 
 The middle row is what it cost: one fifty-minute viewing wrote **14 400 MB** to
@@ -159,3 +159,109 @@ distribution.
 **The diagnostics are not a claimant yet.** They are bounded by a count of files
 and never by a size, and they cannot simply be thrown away when space is short: a
 dump is the only evidence of the death it records. That needs a rule of its own.
+
+## One layer, four directories, and under the import rule
+
+`SegmentStore` moved out of `services/encode/` on 2026-09-14 — a store of
+finished pieces inside the ENCODING layer was the encoder owning its own disk.
+It did not move into the room's own directory either: it is a CLAIMANT, and a
+claimant inside the owner of the resource is the same fault one floor down.
+
+**Four directories, deliberately.** They share one property — bytes on a medium
+with a limit — and that is what makes them one layer. What they are is three
+different things: a torrent piece is born when it is downloaded and addressed by
+`(infohash, number)`; a produced segment is born when an encoder closes it and
+addressed by `(output key, number)`; a whole file is born when its last piece
+lands. Different birth, different death, different name, and two of the three
+live in the torrent WORKER thread while the others are on the main one. Flatten
+them and that thread boundary becomes invisible: code that cannot call code
+looks like a sibling, and no rule catches it.
+
+**The rule is written as an exception, not as a list.** `group: ["../**",
+"!../storage/**", "!../piece-store/**", "!../segment-store/**", "!../files/**"]`
+— everything outside the layer, minus the layer. A list of forbidden layers was
+tried first and let `../../utils/logger.js` straight through, because a list
+only catches what somebody remembered to write in it. Checked by breaking it,
+in both directions, in all four directories.
+
+**One reader of how much memory is free** (`machine-memory.js`). It had been
+written three times — the health collector, the memory report and the piece
+store — and the copies had already drifted: the piece store was corrected from
+`os.freemem()` to the kernel's `MemAvailable` on 2026-08-27 and the health
+collector went on publishing the wrong quantity until 2026-09-02.
+
+## Every claimant is told its share
+
+A CLAIMANT IS WHOEVER HOLDS BYTES, and by 2026-09-14 all of them are registered
+with the owner (`wire.js`): the segments an encoder produced, the pieces the
+memory store spilled, the files downloaded whole, and the evidence. Two of the
+four live on the torrent thread and arrive as a pair of closures over its
+channel.
+
+**Whole files had no bound of any kind** until that day — a 2.8 GB film kept
+whole on a host whose disk is often a 32 GB card. They now take a share, and
+over it the whole file nobody has asked for in longest goes. Losing one is not
+losing data: the torrent can fetch it again, and until it does the read falls
+back to the pieces, which is what `piece-from-whole-file.js` exists for. A file
+is also not ASSEMBLED when there is no room for it — writing it and then
+removing it is the same bytes written for nothing.
+
+**The torrent pool's own "disk cap" is gone, and it owned nothing.** It capped
+`torrentDownloadedBytes` — a sum over WebTorrent's bitfield — so a piece held
+purely in MEMORY told against a ceiling called disk, while the bytes it meant to
+bound belong to the spill and to the whole files, each of which has an owner.
+Under it, eviction removed whole idle TORRENTS to free bytes that were not
+necessarily on the disk at all.
+
+**The evidence is a claimant with a rule of its own** (`Diagnostics.js`), and the
+rule is what makes a bound on it safe:
+
+1. over its share, collection STOPS. Nothing already recorded is deleted to make
+   room — a dump is the only evidence of the death it records — and a refusal is
+   a LINE with the figures, so an investigation that finds nothing can tell "it
+   did not happen" from "there was nowhere to put it";
+2. except what is superseded, which is not evidence twice. A capture of a
+   connection already captured adds nothing: the wedge does not un-wedge. Field
+   2026-09-06, thirteen captures of one wedge in six hours, 74 MB, every one
+   saying what the first said;
+3. what it asks for is measured — what it holds plus one more of the largest
+   kind seen — so the claim grows with the evidence and a proxy that has never
+   faulted asks for nothing.
+
+**Core dumps are not ours to refuse, and that is stated rather than papered
+over.** The kernel writes them, whole address space at a time, and no gate of
+ours is consulted. They are counted, so they take room from what the product may
+hold and the figure is visible; the pruning that keeps the newest two is left
+where it is, because changing it is a decision about evidence and not about
+disk.
+
+## One budget
+
+There is one owner, one policy and one place that reads the machine —
+`MachineBudget.js`. What it divides is divided PER RESOURCE, because memory
+cannot be paid for with disk, and "disk" is one resource per DEVICE: measured on
+the addon host 2026-09-05, `/tmp` (the segments and the spill) is the overlay
+and `/data` (the evidence) is ext4 on the nvme. Dividing one figure between
+claimants on both gave each a share of a disk it does not write to, which is
+what the old `DiskSpace` did — it read the free space of the segment root alone.
+The device is read with `statSync(dir).dev`, from the nearest ancestor that
+exists, for the same reason `freeBytesFor` walks up.
+
+**Why one owner and not two.** The claimants trade across resources: pieces that
+do not fit in memory are spilled to disk, whole files exist so that pieces need
+not be held, segments exist because making them again is dear. Field 2026-08-31:
+14 400 MB spilled in fifty minutes while the memory store held 312-424 MB — give
+it memory and there is no spill to bound. Two owners cannot make that trade,
+because neither sees both sides of it. Memory was divided inside the torrent
+thread and disk on the main one until 2026-09-14; the memory share now travels
+the same channel the spill share already did.
+
+**The policy is the operator's, and it is the only chosen number here.**
+`--budget adaptive|share|fixed` with `--budget-share` / `--budget-bytes`, and
+floors with `--min-memory-bytes` / `--min-disk-bytes`. The default is
+`adaptive`, which is the measured rule of `allowance.js` and chooses nothing. A
+floor lifts what the policy allows and can never invent room the machine does
+not have; a claimant left below its own minimum says so in a line, because
+working below what it needs is a fault of the machine and invisible otherwise.
+
+

package/openspec/changes/adaptive-bitrate/design.md

@@ -1,6 +1,6 @@
 # Design: Adaptive bitrate (proxy)
 
-Read before coding: `services/hwaccel.js` (`chooseSoftwareEncodeSettings`,
+Read before coding: `services/encode/hwaccel.js` (`chooseSoftwareEncodeSettings`,
 the software descriptor's `buildVideoArgs`), `services/hls-session-manager.js`
 (the `BUDGET_*` constants, `#chooseEncodeBudget`, the budget interval check
 `#enforceRealtimeBudget`, `#classifyTranscodeBound`, `#applyBudgetDownshift`,
@@ -28,7 +28,7 @@ constrained-CRF). Do NOT touch hardware descriptors in this change.
 ## (b) Net report intake
 
 Route: `POST /api/transcode-sessions/:id/net-report` (data-channel path, so
-add the prefix to the allowlist regex in `data-channel-handler.js` if not
+add the prefix to the allowlist regex in `transport/data-channel-handler.js` if not
 covered by the existing `/api/` rule — verify). Body:
 
     { linkMbps: number, bufferedAheadSec: number }

package/openspec/changes/adaptive-bitrate/proposal.md

@@ -46,7 +46,7 @@ trigger is skipped.
 
 ## Impact
 
-- `services/hwaccel.js` — nominal-rate table + caps in the software
+- `services/encode/hwaccel.js` — nominal-rate table + caps in the software
   descriptor's video args.
 - `services/hls-session-manager.js` — accept/store net reports per session;
   link trigger in the budget check; log line.

package/openspec/changes/adaptive-bitrate/tasks.md

@@ -2,7 +2,7 @@
 
 ## 1. Caps
 
-- [x] 1.1 `hwaccel.js`: `RUNG_NOMINAL_KBPS` table + nearest-rung lookup;
+- [x] 1.1 `encode/hwaccel.js`: `RUNG_NOMINAL_KBPS` table + nearest-rung lookup;
       software descriptor's video args emit `-maxrate`/`-bufsize`
       (1.3× / 1.5× nominal for the actual encode height). Hardware
       descriptors untouched.

package/openspec/changes/chunked-request-bodies/design.md

@@ -3,7 +3,7 @@
 Written to be executed as specified — the wire format, constants, limits
 and do-NOT list are normative. Read before coding:
 
-- `services/data-channel-handler.js`: the whole file — the wire-protocol
+- `services/transport/data-channel-handler.js`: the whole file — the wire-protocol
   doc comment (~lines 9–37), `handleChannel` (onMessage string handling),
   `handleRequest`, `sendChunk` (the response frame writer whose layout the
   request frames mirror), `send`.

package/openspec/changes/chunked-request-bodies/proposal.md

@@ -46,7 +46,7 @@ the server repo's `chunked-request-bodies` change. Release order: proxy
 
 ## Impact
 
-- `services/data-channel-handler.js` — binary inbound frame parsing;
+- `services/transport/data-channel-handler.js` — binary inbound frame parsing;
   per-channel partial-body assembly with caps/TTL; `request-start`
   handling; shared execution path.
 - Release: folds into the PENDING proxy 2.9.35 (extend its CHANGELOG entry;

package/openspec/changes/chunked-request-bodies/tasks.md

@@ -5,7 +5,7 @@ its top first.
 
 ## 1. Implementation
 
-- [ ] 1.1 `data-channel-handler.js`: factor the execution tail of
+- [ ] 1.1 `transport/data-channel-handler.js`: factor the execution tail of
       `handleRequest` so a legacy `request` message and an assembled
       chunked request run the SAME function. `node --check`.
 - [ ] 1.2 `request-start` + binary inbound frames + per-channel assembly

package/openspec/changes/cold-start/design.md

@@ -11,7 +11,7 @@ Written to be executed as specified. Read before coding:
   ~854), the segment-ready path (where segment 00000 first becomes
   servable — grep the long-poll the `routes/transcode/session-file/get.js`
   route uses).
-- `services/torrent-pool.js`: `prefetchFileEdges` (~line 608) — signature
+- `services/torrent/torrent-pool.js`: `prefetchFileEdges` (~line 608) — signature
   `(torrent, fileIndex, { headBytes, tailBytes, timeoutMs })`.
 - `server.js`: how `playbackPlanner` and `hlsSessionManager` are constructed
   and injected.

package/openspec/changes/disk-cap/proposal.md

@@ -32,6 +32,6 @@ Assistant itself. This adds the last missing Level 1 piece: a global cap.
 
 ## Impact
 
-- `services/torrent-pool.js` (access tracking, cap enforcement),
+- `services/torrent/torrent-pool.js` (access tracking, cap enforcement),
   `bin/cli.js` (`--max-disk-bytes`), `server.js` (option pass-through);
   ha-addon bump. Part of the proxy transcode/hygiene batch (2.9.29).

package/openspec/changes/proxy-observability/proposal.md

@@ -42,8 +42,8 @@ failures:
 
 - `routes/healthz/get.js`, `routes/health/get.js` (or their handlers) —
   version field.
-- `services/torrent-pool.js` — warning/announce logging, stats origin tags.
-- `services/port-mapper.js` — SSDP listener fix.
+- `services/torrent/torrent-pool.js` — warning/announce logging, stats origin tags.
+- `services/transport/port-mapper.js` — SSDP listener fix.
 - CHANGELOG entry at current package.json version + 1 patch (2.9.25);
   requires the usual ha-addon version bump (0.2.47) after `npm run patch`
   (npm publish needs the user's npm key).

package/openspec/changes/track-selection/proposal.md

@@ -40,6 +40,6 @@ subtitle streams were unreachable by the browser.
 
 - `services/playback-planner.js`, `services/hls-session-manager.js`,
   `routes/api/transcode-sessions/post.js`, new `routes/api/subtitles/get.js`,
-  `server.js` wiring, `services/torrent-pool.js` (log masking).
+  `server.js` wiring, `services/torrent/torrent-pool.js` (log masking).
 - Pairs with the server-side `track-selection-ui` change; requires the usual
   ha-addon bump.

package/openspec/changes/transcode-quality/proposal.md

@@ -44,7 +44,7 @@ manual-quality menu also needs the server UI).
 
 ## Impact
 
-- `services/hwaccel.js` (fps, benchmark, tonemap args),
+- `services/encode/hwaccel.js` (fps, benchmark, tonemap args),
   `services/hls-session-manager.js` (fps probe, runtime speed watch),
   `services/playback-planner.js` (HDR/fps in the plan);
   server player UI for the Quality menu; ha-addon bump.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.86.0",
+  "version": "2.87.0",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {
@@ -8,7 +8,7 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=24 <25"
+    "node": ">=24"
   },
   "bin": {
     "torrent-tv-proxy": "./bin/cli.js"