docs(tv): the parked-folder merge, and the laws that gate it

A parked folder whose name parses to a registered show merges into the row
that owns the show. The proof is the episode rows standing under the owner
folder — never the id-less folder list, because one tvdb id can carry two
`Series` rows and an id-less folder that parses gets identified on its own
and keeps its own folder, offering the show twice.

No library file moves while `Scan Media Library` is Running: wait for a
Running sighting and then two consecutive Idle polls, because a gap between
sub-tasks reads as finished. Both sides speak different path dialects (the
server records the container coordinate, the journal speaks the array), so a
join that forgets the translation reads as an empty library.

Lands on [[Media TV Relayout]] — the page that owns the TV arm — so
`Media Relayout.md` stays under the OKF ceiling.
This commit is contained in:
Frank committed 2026-11-02 13:56:03 -08:00
1 parent b232033b11
commit 8f0b1982c2
1 file changed
+40
@@ -171,6 +171,36 @@ sequel (410031), the 2026 Hokuto no Ken remake (465216) and `Mugyutto! Black
Clover` (378762) offered for Black Clover. It is why the map is approved by hand
and the sheet is never fed to the planner.
**A parked folder merges into the row that owns the show.** The folder that never
got an id usually holds episodes the identified folder for that show lacks, and
the server shows the audience neither: the parked copy is invisible and the owner
reads as a short series. One `media-apply.py` plan per show, built from the
server's own rows:
- the **owner is the folder whose `Series` row carries the tvdb id**; the parked
side is the folder with the same words and no id (or the same id under a second
row — see the law below);
- the **comparison is episode identity, not filename**: which (season, episode)
the provider row gives each file, read straight out of the server. Release
folders renumber — one park carried `S01E01-11` of a show tvdb books as seasons
2 and 3, and every episode runs the same eleven minutes, so neither the marker
nor the duration says what one query into the rows says;
- **a season the owner has no file in moves whole**: `mkdir` the `Season NN`,
then one row per file with its name unchanged — the folder shape is the
contract, the file name is not;
- **a subtitle pack is re-keyed, never just moved**: a sidecar attaches only when
its stem equals the video's, so each `.srt` has to land on the OWNER's stem with
the language suffix kept (`… - The Cat and the Claw (1).en.srt`). Moved under
its release-group name it stays a folder of 88 subtitles no player ever offers;
- **the same episode on both sides is the operator's call**, never a plan row:
which copy survives is a quality judgment — the parked copy is usually the
bigger one, and a re-cut is not a worse one — and the parked file often carries
no title to align by. Those pairs are listed and left alone.
The two sides speak different path dialects, since the server records the
container coordinate ([[Jellyfin]]) and the journal speaks the array; a join that
forgets the translation returns zero rows and looks like an empty library.
## Laws of this arm
- **A folder that names two series is not evidence of two series — the files
@@ -187,6 +217,16 @@ and the sheet is never fed to the planner.
them, per-season counts equal, and no duplicate `SxxEyy` key anywhere prove
the layout is already correct. Renumbering files under that evidence buys
nothing and can silently mislabel an episode.
- **One tvdb id can carry two `Series` rows, so the id-less folder list proves
nothing about a merge.** A parked folder whose words parse to a registered show
gets identified on its own and keeps its own folder: the count of id-less
folders drops, and the library now offers the same show twice. Prove a merge by
the episode rows standing under the owner folder, never by that list.
- **Move library files only while `Scan Media Library` is Idle.** A rename that
lands under a running scan is a row the server read a moment ago pointing at a
path that no longer exists. `ScheduledTasks` is the read ([[Jellyfin]]); wait
for a `Running` sighting and then two consecutive `Idle` polls, because a gap
between sub-tasks reads as finished.
## See Also