subtitle-resolution: expose the retained contiguous determination span (or a first-successor proof) under the active seek generation

[cmcpherson274]

What should the engine do?

Add a same-generation positive claim about retained subtitle determination — either

1. a field on the existing [SubtitleResolution] line (e.g. retainedFrom=) reporting an upper bound on the session store's contiguous determined-from point after the store and the post-seek drainer have been reconciled — i.e. a value that may legitimately stay ≤ 0 across a seek when the store genuinely retains the from-start run; or
2. an equivalent first-successor proof: a fenced statement that the earliest undecoded display set at-or-after the covered floor sits at PTS X (for our fixture, 88.380), with the floor itself reported.

Either form would ride the same emit-on-transition philosophy the statement already follows (a line when the reconciled floor changes, plus the existing tick). The fence semantics you shipped in #250 (stamped post-reposition, requesting generation) are exactly right as-is — this is purely an additional claim, not a change to coveredFrom. For our gate's purposes, renaming or clamping coveredFrom, or inferring from packet-store lifetime, wouldn't help: the emitted statement itself has to carry the claim.

Motivating media or use case

The #250 subtitle-resolution statement has been running in our combined seek-stopwatch harness since 6.0.2, and one truth class turns out to be structurally unprovable from the current fields: "empty because nothing was ever authored before this point."

On a PGS track whose first display set sits at 88.380 s, a seek to 30 s renders (correctly) nothing. To adjudicate that as determined emptiness rather than a dead pipeline, our gate needs coverage reaching back to track start — the earliest point that could change the answer. The statement's coveredFrom reports the post-reset drain window (≈ target − 15 after any far seek), and per your close it is an unclamped upper bound on where the contiguous decoded run begins — so a post-seek value of ~15 can neither affirm nor refute track-start coverage. The pre-seek line (coveredFrom=-15.00 at load) does carry the needed bound, but under the previous seekGen — and cross-generation combination is exactly what the fence exists to forbid.

Net: the state is rendered correctly, the pipeline is live (fenced via=prefetch lines resolve through the evaluated time), and the claim we need is one the statement cannot currently make. Our adjudicator has to score the target "apparatus-inexpressible" rather than pass or fail it.

Area

Other

Host app / integration context

(tvOS Jellyfin client) — external QA/conformance harness, same integration as #240/#250. tvOS 26.5, Apple TV 4K 3rd gen, wired.

Would you be willing to open a PR?

Maybe, with guidance

[superuser404notfound]

Shipped in 6.4.4 (22ee29fd, PR #278, CI green on macOS / tvOS / iOS). Went with form 1: a new retainedFrom= field on the existing line.

[AetherEngine] #250 subtitle-resolution loadGen=3 seekGen=8 stream=4 \
  coveredFrom=15.00 retainedFrom=-15.00 resolvedThrough=90.00 \
  via=prefetch decodedThrough=none reason=reconstruction

The field is inserted between coveredFrom= and resolvedThrough=, since the two floors are read as a pair. A key-based parser needs no change; a positional one does.

Why the claim is real rather than optimistic bookkeeping

The determination already survived the seek, it just was not recorded. reanchorSubtitleOverlays deliberately leaves a drained channel's cues in place across a seek and rebuilds only the decoder and the PGS stale-arrival gate. What overwrote the history was SubtitleDrainCursor.coverageStart, which is reset at every .resetAndDecode by design (it is coveredFrom, and that is exactly what it should say). The cursor now carries a second value, the retained run: a floor plus a high-water of that run's determined end. A reset folds its window into it instead of replacing it.

So retainedFrom is the union of decoded runs, not newly measured coverage, which is what makes it fenceable at all.

Two constraints worth knowing when reading it

It is deliberately not seek-fenced, and that is not a hole in the fence. By the time a reset tick runs, seekGeneration has already advanced, so the outgoing run's frontier no longer passes its own fence. Asking for it there would be precisely the cross-generation combination the fence forbids. Instead each run's determined end is banked on the tick that produced it, while it was still live. The engine is stamping its own history at the moment it was valid, not combining two numbers after the fact. The value dies with the drain cursor, which every track switch and every session teardown clears, so it is still load-fenced.

The runs join only when the new window opens inside the retained span. Two rejections, both silent over-claims otherwise:

• A forward seek past the retained determined end leaves a hole the 15 s backscan does not reach over. The run restarts.
• A backward seek whose window opens below the retained floor leaves two disjoint intervals until the new run climbs back up. The run restarts there too, and the old ceiling goes with it.

An idle drain tick decoded nothing and banks nothing, so frontier growth nobody decoded over is never folded in. A lagging high-water reads as a gap at the next reset and under-claims, which is the safe direction for a field an adjudicator scores on.

The one case where it will read as no proof

Seek to 30 before the reader ever passed 15 and the line will say retainedFrom=15.00. That is correct rather than a miss: the span between the frontier and the new window was genuinely never decoded, and the backscan does not fill it. On the fixture as described (first display set at 88.380, playback established before the seek) the load run's determined end is well past 15, so the fold holds and the floor stays below zero.

Two properties the harness can assert on: retainedFrom is never later than coveredFrom, and it is unclamped for the same reason coveredFrom is, so a container with start_time != 0 does not get coverage claimed below its first PTS. It reads none when a channel has decoded no run at all.

On form 2

Not built, and worth saying why rather than leaving it as an omission. The first-successor proof does not close the case on its own: the covered floor after the seek is 15, so a display set at 5 stays unrefuted, and once retainedFrom is on the line the successor adds nothing. Real store harvest coverage ("the store was filled from track start") would have been the other tempting shape and is unfounded, since the producer tap has no read-position surface at all. That is the same reason via=pump is the weak state in #250.

12 new tests in Issue276RetainedCoverageTests, one per way the field could lie, including both rejection cases above.

Leaving this open for the retest. Thanks for the precise write-up, naming the truth class and the two acceptable shapes made this a short investigation.