feat: a queue entry can name a section — start.position_ms and end.position_ms

[Sawtaytoes]

Adds the two fields that let a queue entry name a section of a playable unit —
start.position_ms and end.position_ms. Implements
2026-09-01-a-start-point-carries-a-position-and-end-is-its-mirror;
design in docs/clip-playback-design.md.

Follows #299 (the design) and #300 (the entry id that lets one file hold two lines).

Scope

The DATA path only. The fields are stored, written, served and described. Playback
and the editor control are the next two changes, so this one stays reviewable.

No UI change, so no screenshots. Nothing renders differently: web/src/lib/types.ts
gains type declarations and the shelf skeleton spells one more null. There is no
control, no editor and no tag in this diff.

What lands

• Types. Start.position_ms, a new End, EntryExtras.end.
• Normalise + write. normalizeStart() carries the position, normalizeEnd() and
  setEnd() mirror their start siblings, and both follow the sparse rule every other
  per-entry override follows: an absent, blank, negative or non-numeric value drops the
  key, a start left with none of its three fields is null rather than {}, and an
  end with no position is null.
• Routes. PATCH /queues/:set/items/:key/end, the house shape exactly. end joins
  the bulk reset arm.
• The wire. endOf beside startOf, one line in the queueTile literal.
• The descriptor. describe() carries end on the raw type, on EntryDescriptor
  and in all three return arms.
• Provider capability. Provider.playsSections (true only on Plex), PLAYS_SECTIONS
  keyed by kind beside DELIVERY, and plays_sections on ProviderPublicView.
• The debt from feat(server): an entry can carry an id, so one queue can hold the same file twice #300. e2e/entry-id-test.ts loses its as EntryValue cast.

Where the cross-field check lives, and why

On the writers — setStart and setEnd — inside the YAML lock, not on the route.

end must be strictly after start. Equal is refused by name and never swapped,
because a zero-length section plays nothing and a swap would hide the typo that made it.
When only one side is set there is nothing to compare, so the write is accepted.

Both writers ask, and that is the point. Either one can be the second of two
individually-valid writes that together invert the window: set end: 90s, then set
start: 120s, and each request on its own looks fine. A route-level check reads one side
off the request body and the other off a file it has not locked, so it cannot close that
door. The writers are the only place both sides of one entry are visible at once.

rewriteEntry's mutator may now return false to refuse the write, which leaves the file
exactly as it was found. Every other mutator returns void and is unaffected. A refusal
comes back {ok: false, error} with both offsets named; a plain {ok: false} still means
"no such entry", so the two stay distinguishable.

normalizeStart's early return was the predicted trap

Its first line was if (!hasSeries && src.episode == null) return null. That was right
while a start could only pick a unit. A film section has neither a series nor an
episode — only a position — so the guard would have discarded every one of them and
returned null with nothing logged. It reads all three fields now, and both
server/src/sectionWindow.test.ts and e2e/yaml-roundtrip-test.ts pin the movie case.

hasSection was real, but disagreed with the sparse rule

hasSection() landed in #300, ahead of the fields, and it is what decides an add is
deliberate — it mints an entry id and walks the add past the duplicate guard. It was not a
placeholder, but its hasPositionMs() helper tested Number(side.position_ms) directly,
and Number(null) is 0. So {start: {position_ms: null}} answered true. null is
this file format's spelling of "no value" ({start: null} is how a start is cleared), so a
cleared window read as a section at offset zero: an id minted and a duplicate add let
through, while the writer correctly dropped the key. '' did the same.

entryFormat.toPositionMs() is now the one coercion and hasPositionMs() calls it, so the
predicate and the two writers cannot drift. Zero itself is a real position — it is the
other half of an end-only window — so every test is != null, never truthiness.

Tests

Extended in place rather than as a parallel suite.

• server/src/sectionWindow.test.ts (new): the two normalizers, every unusable
  spelling of a position, the movie case, the four optionality states, and a cross-check
  that hasSection() answers true exactly when a normalizer keeps a position.
• e2e/yaml-roundtrip-test.ts: for both fields — the value is written, it survives an
  unrelated later edit, the sparse case drops the key, junk drops the key — each wrapped
  with assertCommentsSurvive. Plus the pair rule from both directions, that a refused
  write changed nothing on disk, and that an unknown entry is not-found rather than a
  refusal.
• e2e/entry-objects-test.ts: a film section and an episode section cross the
  migration, then come back through the engine's describe().
• e2e/api-v2-test.ts: the route lands, clears, drops a junk value and refuses an
  equal end by name; the bulk reset clears both ends; the capability reads true for Plex
  and false for a pull provider, off a providers.yaml of the suite's own with neither
  provider configured — which is the point of the kind-keyed map.

Gates

Run on this branch rebased onto aa56f74.

yarn install --immutable                        ok
yarn workspace queuepilot-web run build         exit 0
yarn workspace queuepilot-server run build      server/dist/index.js — 4011.9 KB
yarn typecheck                                  exit 0, no output
yarn workspace queuepilot-web run lint:biome    exit 0, 75 warnings (baseline: 75)
yarn test                                       web 322/322, server 371/371 (baseline 322 + 355)

33 offline e2e harnesses pass: yaml-roundtrip, entry-objects, entry-id, api-v2,
store-backend-parity, play-one-entry, batch-stops-at, collection-start,
keep-completed, kind-normalize, per-entry-shuffle-write, pending, priority-lane,
pick-contract, skipped-items, collection-reorder, rewatch-members, provider-cache,
provider-seam, people, tonight-routing, queue-people, roster-editor, weights,
ttl-sweep, history-persist, on-complete, lineup-knobs, queue-name,
default-lane-change, host-config, resume-in-queue, resume-on-advance.

Three browser gates pass as well — shelf-remove, tile-lane, pending-dismiss — off the
image's own /opt/pw-browsers, which holds chromium-1234 and matches e2e/package.json's
pin, so no PLAYWRIGHT_BROWSERS_PATH override was needed.

One finding, not touched by this PR

e2e/topup-test.ts fails 16 checks in an agent sandbox, and it fails identically on
origin/main (aa56f74). Verified by checking out origin/main and running it there, so
it is not a regression from this change and no fixture was edited to hide it.

The cause is the store path, not top-up. The harness sets
QUEUES_PATH = '/nonexistent-so-loadEntries-is-never-consulted.yaml' as a sentinel.
config.ts defaultStorePath() derives the SQLite path from that candidate, dirname() of it
is /, / is a directory, so the store lands at
/nonexistent-so-loadEntries-is-never-consulted.queuepilot.sqlite — the filesystem root. The
open fails with unable to open database file for any process that cannot write to /, and
every routing read then reports the fixture unreadable. It passes wherever the runner can
write to the root. The harness calls itself hermetic; it is hermetic in everything except
this. Fixing it is a one-line STORE_PATH in that file, and it belongs in its own change.

[Sawtaytoes]

Design: #299. Entry identity this builds on: #300.