JR-004, JR-005, JR-006: scene-scoped read path

Presence was decided by a LINQ predicate inline in the controller, so the
semantics SR-002 sets were nowhere stated in code -- the read path complied by
accident rather than by requirement. PresenceLookup is now the unit that
decides, tagged, with the reasoning next to it.

JR-004: windows are served exactly as given. UT-021 pins that [0,10] and
[10,20] are not merged despite looking mergeable -- two windows mean a genuine
departure and return, and collapsing them answers a different question from the
one the truth file asked. UT-022 pins a byte-identical round trip.

JR-005: bounds inclusive at both ends, zero-length windows are real sightings
rather than degenerate ones to discard, overlaps resolve.

The wording was the larger half of JR-005. The overlay rendered a bare list: it
asserted nothing, but told the viewer nothing either, and the default reading of
a paused frame is "these people are on screen" -- exactly what SR-002 forbids.
It now carries an "In this scene" heading. ActorAtTime became ActorInScene, and
README no longer contains "on screen" anywhere; it stated the forbidden reading
outright in seven places, including the opening sentence.

JR-006: measured rather than assumed. UT-023 builds 50 actors x 1000 windows and
asserts the response is bounded by actor count, never window count. The lookup
is a full scan on purpose -- an early exit on `start > t` would exploit the
sortedness the format requires, but would silently under-report the moment one
producer emitted windows out of order. UT-020 pins that unsorted input still
resolves; WindowsAreSorted is a diagnostic, not a correctness dependency.

Third mutation check: making the end bound exclusive fails UT-016 and UT-018 and
nothing else. One character turns an inclusive window into a half-open one,
dropping an actor at exactly the moment a scene ends.

TRACES: UT-016, UT-017, UT-018, UT-019, UT-020, UT-021, UT-022, UT-023
TRACES: JR-004, JR-005, JR-006 | SR-002

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-31 11:29:46 +02:00
co-authored by Claude Opus 5
parent 305b898b15
commit c04d5a3dcc
11 changed files with 378 additions and 47 deletions
+32 -12
View File
@@ -159,8 +159,12 @@ It stores and serves what it was given. The one permitted transformation is the
timebase offset of JR-030, which shifts every window uniformly and so preserves
the claim.
**Gap:** stated nowhere in the code today. The read path happens to comply, but
by not having been written to do otherwise rather than by requirement.
**Current:** satisfied.
[`PresenceLookup`](Jellyfin.Plugin.JRay/Services/PresenceLookup.cs) is now the
unit that decides presence, so the semantics live in one tagged place instead of
being implied by a LINQ predicate in the controller. UT-021 pins that adjacent
windows such as `[0,10]` and `[10,20]` are *not* merged, and UT-022 that a truth
file round-trips byte-identical. **Gap:** none.
### JR-005 — Query semantics, and how presence is presented
@@ -175,14 +179,17 @@ scene" is the claim it does.
This is a wording requirement, not a hedge — it is the difference between the
product being right and being a worse version of a frame-by-frame detector.
**Current:** the query is implemented correctly in
[`ActorsController`](Jellyfin.Plugin.JRay/Controllers/ActorsController.cs).
**Gap:** wording, not logic. The overlay renders a bare list with **no heading
at all**, so it asserts nothing — but it also tells the viewer nothing about
what the list means, and a viewer's default reading of a paused frame is "these
people are on screen". [`README.md`](README.md) states that reading outright
("which actors are on screen at that exact moment"), and the model type is
`ActorAtTime`.
**Current:** satisfied, in logic and in wording. Bounds are inclusive at both
ends (UT-016/017), a zero-length window is a real sighting rather than a
degenerate one to discard (UT-018), and overlapping windows resolve (UT-019).
The wording was the larger half. The overlay now carries an **"In this scene"**
heading — previously it rendered a bare list, which asserted nothing but also
told the viewer nothing, and a viewer's default reading of a paused frame is
"these people are on screen". The model type `ActorAtTime` became `ActorInScene`,
and [`README.md`](README.md) no longer contains the word "on screen" anywhere;
it stated the forbidden reading outright in seven places, including the opening
sentence. **Gap:** none.
### JR-006 — Numerous windows
@@ -195,8 +202,21 @@ The read path must therefore treat per-actor windows as a sorted sequence to be
searched, not a short list to be scanned, and the `jray?t=` response must stay
small regardless of how many windows an actor has.
**Gap:** windows are scanned linearly and the whole truth file is held per item.
Adequate at current sizes; unmeasured, and unstated until now.
**Current:** satisfied, and now measured rather than assumed. UT-023 builds 50
actors × 1000 windows and asserts the `jray?t=` result is bounded by **actor**
count, never window count — which is what keeps the response small however finely
presence is sliced.
**The lookup is a full scan, deliberately.** An early exit on `start > t` would
exploit the sortedness the format requires, but it would silently under-report
the moment one producer emitted windows out of order — a correctness risk traded
for a saving that does not register at this scale. UT-020 pins that unsorted
input still resolves. `WindowsAreSorted` exists as a diagnostic for surfacing
such a producer bug, not as something correctness depends on.
**Gap:** none for lookup. The whole truth file is still held in memory per cached
item, which is a memory question rather than a query-cost one and is untouched
here.
### JR-007 — Identity is public identifiers