Report a play when the track is done with, not at the halfway mark

[jeffcrouse]

Every web play was landing with a completion ratio of almost exactly 0.5, whatever the listener actually heard.

usePlayTracking delivered the play the moment listening crossed min(duration / 2, 4 min), sending completion_ratio as measured at that instant. Nothing revised it afterwards — so the figure recorded for hearing a track once through and for hearing half of it was the same number.

The evidence

Measured on the live database, 2026-08-01 (815 rows, first 2026-07-27):

outcome	count	avg completion
skipped	428	0.026
completed	357	0.485
errored	30	0.005

289 of the 357 completed events sit in the 0.5–0.6 bucket. Sample rows are exact — 166.0/331.4, 124.3/248.6, 120.6/241.0, 146.3/292.5. Rows from the native client, which reports at the end, correctly read 0.95–1.00.

Why it matters more than it looks

ADR-0004 exists so that ADR-0005's recommender has a taste signal that can only accumulate in wall-clock time, and completion is that signal. A constant carries none of it.

familiar #53 is parked waiting for roughly a month of play_events before ADR-0010's cache budget can come from measured locality. That clock started 2026-07-27 and lands around 27 August — so without this, the month being waited for would have been a month of noise. The failure is invisible in aggregate precisely because 0.5 is such a plausible-looking average.

What changes, and what does not

Which plays count does not change. The early delivery only decided when: a play past 30s but short of the half mark was already reported on track change, by the same rule that now reports all of them. The Last.fm half/4-minute threshold turned out to gate nothing, which is why it is deleted rather than moved.

Two things came with it:

• A page-hide flush. The early delivery was quietly buying durability — close the tab mid-track and the play still counted, because it had already been sent. Reporting at the end alone would have dropped that silently, so it is restored on pagehide / visibilitychange, with the ratio actually heard. Best effort, and documented as such: a browser tearing down a page owes the request nothing.
• The ratio is clamped. Played time accumulates from the engine's clock while the duration comes from track metadata, so a looping or mis-tagged track could send 1.1. The server clamps too, but agreeing with the native client — which has always clamped — beats leaving every stored figure a question about which end did it.

Tests

The three that asserted mid-playback delivery now assert delivery on track change. Two added:

• one pinning the ratio for a track heard nearly to the end (the defect above, so it cannot come back quietly)
• one covering the page-hide path, including that it cannot double-report if the page survives

940 frontend tests pass; lint clean on the changed file.

Not addressed here

Existing rows keep their frozen ratios. They are distinguishable — web completions cluster at 0.5 with context of other/null, native ones at 0.95–1.00 with library — so ADR-0005 can filter them, but it is worth deciding deliberately whether to exclude anything recorded before this lands.