fix(analyzer): clamp cue position across long track gaps

A line drawn between the ends of a 0.9 s hole is not a measurement:
on shot_07 it swept within CUE_EXCL_M of six still balls in turn
(the 2 at 4.1 mm), switching their detections off. Each half of a
hole over LOST_MAX_S now answers with its own end; shorter holes
still interpolate. The two detections that stole ball 8's track sit
3.4 mm from the end and stay excluded. 271 passed / 27 skipped.

src/poolcoach_cv/broadcast.py

@@ -228,6 +228,10 @@ LOST_MAX_S = 0.5          # object-ball tracks: a track that goes this long
                           # no resurrection on purpose: without the close, a
                           # different ball rolling past the pocket later gets
                           # picked up by the track of the ball that went in.
+                          # ``cue_at`` reuses the same number for the same
+                          # reason: past it, a straight line between two
+                          # measurements says nothing about what happened
+                          # in between, so it clamps instead of drawing one.
 POT_NEAR_M = 0.10         # pocketed_guess: the last track point has to end
                           # within this of a pocket mouth (~3.5R, a pocket
                           # jaw plus position noise)
@@ -951,8 +955,9 @@ def cue_positions(rows: list[dict] | None) -> list[tuple[float, float, float]]:
 def cue_at(pts: list[tuple[float, float, float]],
            t: float) -> tuple[float, float] | None:
     """Where the cue ball was at time ``t``: LINEAR between the two
-    measured points around it, and the nearest end point outside the range
-    the track covers.
+    measured points around it, the nearest end point outside the range the
+    track covers, and the nearest end point of the HOLE when the two
+    measured points are more than LOST_MAX_S apart.
 
     Holding the end point rather than giving up is deliberate. The frames
     before the cue is first seen and after it is last seen are exactly the
@@ -961,6 +966,21 @@ def cue_at(pts: list[tuple[float, float, float]],
     would switch the exclusion off precisely where it is needed. The cue
     barely moves in those stretches anyway: it is standing still before the
     shot, and it was lost, not teleported, after it.
+
+    The same argument stops applying INSIDE a long hole, and the clamp is
+    where it stops. A straight line between the two ends of a 0.9 s gap is
+    not a measurement of anything: it is a ball-shaped eraser dragged
+    across the cloth at whatever speed the gap demands. On shot_07 of the
+    demo (cue coverage 0.5772, two holes of exactly 0.9 s where the other
+    thirteen shots never exceed 0.2 s) that line swept within CUE_EXCL_M
+    of SIX still balls in turn -- the 2 at 4.1 mm, the 9 at 12.6 mm, the 4
+    at 34.9 mm -- switching their detections off one after another while
+    the cue was in fact nowhere near any of them. Clamping to the nearer
+    end IN TIME keeps every exclusion that rests on a real measurement
+    (the same shot's two stolen detections sit 3.4 mm from the end point
+    of the hole and stay excluded) and drops every one that rested on the
+    line. Short holes keep interpolating: over 0.2 s the cue cannot cross
+    the table, so the line is still a fair reading of where it was.
     """
     if not pts:
         return None
@@ -979,6 +999,8 @@ def cue_at(pts: list[tuple[float, float, float]],
     t1, x1, y1 = pts[hi]
     if t1 <= t0:
         return x0, y0
+    if t1 - t0 > LOST_MAX_S:
+        return (x0, y0) if t - t0 <= t1 - t else (x1, y1)
     u = (t - t0) / (t1 - t0)
     return x0 + u * (x1 - x0), y0 + u * (y1 - y0)
 
@@ -1235,8 +1257,10 @@ def track_others(meta: list[tuple[str, float]], others_by_frame: dict,
 
     ``cue_rows``: the ``track_cue`` result of the SAME clip. Any candidate,
     in EITHER band, that lies within ``CUE_EXCL_M`` of where the cue ball
-    is at that instant (linear interpolation of that track, the nearest end
-    point outside its range) is struck off before matching. The cue is
+    is at that instant (``cue_at``: linear interpolation of that track, the
+    nearest end point outside its range, and the nearer end of a hole
+    longer than LOST_MAX_S rather than a line drawn across it) is struck
+    off before matching. The cue is
     occasionally classified as a Solid, and an object track whose own ball
     has just disappeared into a pocket will happily adopt it: on shot_02
     that pulled ball 5 backwards out of the far corner pocket and into the

tests/test_broadcast_analytics.py

@@ -1297,6 +1297,69 @@ def test_cue_at_interpolates_between_points_and_holds_the_ends():
     assert bc.cue_at([], 1.0) is None             # no track, no exclusion
 
 
+def test_cue_at_clamps_to_the_nearer_end_across_a_long_hole():
+    """A hole longer than LOST_MAX_S is NOT interpolated. On shot_07 the
+    cue is lost for 0.9 s twice, and the line the old reading drew between
+    the ends of a hole swept within CUE_EXCL_M of six still balls in turn
+    -- the 2 at 4.1 mm -- while the cue was near none of them. Past the
+    close-the-track threshold a straight line is not a measurement, so
+    each half of the hole answers with the end it belongs to. Holes the
+    cue cannot cross the table in keep interpolating."""
+    long_hole = round(0.9 / DT)                   # 27 frames, exactly 0.9 s
+    pts = bc.cue_positions(cue_rows_from(
+        [(0.30, 0.40)] + [None] * (long_hole - 1) + [(1.00, 0.40)]))
+    t0, t1 = pts[0][0], pts[-1][0]
+    assert t1 - t0 > bc.LOST_MAX_S
+    mid = (t0 + t1) / 2
+    assert bc.cue_at(pts, t0 + DT) == (0.30, 0.40)        # the near half...
+    assert bc.cue_at(pts, mid - DT) == (0.30, 0.40)
+    assert bc.cue_at(pts, mid + DT) == (1.00, 0.40)       # ...and the far
+    assert bc.cue_at(pts, t1 - DT) == (1.00, 0.40)
+    # the midpoint of the LINE is exactly the answer that is gone
+    assert bc.cue_at(pts, mid - DT) != pytest.approx((0.65, 0.40), abs=1e-3)
+
+    short = bc.cue_positions(cue_rows_from(
+        [(0.30, 0.40)] + [None] * 5 + [(0.60, 0.40)]))    # 0.2 s, as usual
+    assert short[-1][0] - short[0][0] < bc.LOST_MAX_S
+    assert bc.cue_at(short, (short[0][0] + short[-1][0]) / 2) == \
+        pytest.approx((0.45, 0.40), abs=1e-9)
+
+
+def test_a_long_cue_hole_excludes_at_its_ends_and_nowhere_between():
+    """The shot_07 shape end to end. The cue is measured, lost for 0.9 s,
+    and measured again on the far side; an object ball rolls THROUGH the
+    midpoint of the line the old reading drew, and the cue is then read as
+    a Solid 3.4 mm from the far end of the hole -- the two detections that
+    took ball 8's track on the real clip.
+
+    Both halves in one scene: the ball crossing the middle keeps every
+    point (the cue was never there), and the detection at the END is still
+    struck off (the cue really was there, measured)."""
+    n, gone, steal_from = 45, 20, 25
+    a, b = (0.30, 0.40), (1.00, 0.40)
+    hole_end = round(0.9 / DT)                    # covered again at 0.9 s
+    ball = straight(0.65, 0.04, 0.0, 0.8, n)
+    path = [p if i <= gone else None for i, p in enumerate(ball)]
+    meta, others, diffs, init = make_scene([path])
+    ghost = (b[0] + 0.0034, b[1])                 # the cue wearing a Solid
+    for i in range(steal_from, n):
+        others[f"{i:05d}"] = [{"cls": "Solid", "conf": 0.9,
+                               "table_x_m": ghost[0],
+                               "table_y_m": ghost[1]}]
+    cue = [a] + [None] * (hole_end - 1) + [b] * (n - hole_end)
+
+    stolen = bc.track_others(meta, others, diffs, init)
+    assert stolen[0]["track"][-1]["x_m"] == pytest.approx(ghost[0], abs=1e-3)
+
+    kept = bc.track_others(meta, others, diffs, init,
+                           cue_rows=cue_rows_from(cue))
+    # the ball crosses the old line at t ~ 0.45 and loses NOTHING there
+    assert len(kept[0]["track"]) == gone + 1
+    assert kept[0]["track"][-1]["t_s"] == pytest.approx(round(gone * DT, 3))
+    assert kept[0]["track"][-1]["y_m"] == pytest.approx(ball[gone][1],
+                                                        abs=1e-3)
+
+
 def test_a_detection_sitting_on_the_cue_cannot_continue_an_object_track():
     """The shot_02 shape: the object ball disappears into a pocket, the cue
     arrives at that very spot a frame later and is classified Solid. Without