Report progress to the server on a decided cadence

[iderex]

The server needs to know where playback is, for resume and for anything else
watching. Reporting too rarely loses a person's place. Reporting too often turns
one household watching four things into a server under constant write load, and
on a metered connection it costs a person money.

The cadence is one decision, made here, with its numbers and their reasons.

What this produces

The reporting interval, stated as a number with the reason for its value.

The events that report immediately regardless of the interval: playback started,
paused, resumed, seeked, stopped.

Coalescing, so that a person scrubbing through a film sends one report rather
than forty.

Every report going through the offline queue from #47 rather than being sent
directly, so that the offline case needs no separate path and cannot be forgotten.

Done when

The cadence and its reason are recorded. A test proves a scrub produces one
report. A test proves each immediate event reports without waiting for the
interval. Every report is observed passing through the queue. Blocked on #47,
#56, and #102 for the clock the cadence is measured against.

[iderex]

The clock this issue was waiting on is decided in docs/decisions/0102-the-clocks-every-deadline-is-measured-against.md.

The reporting cadence is on the elapsed clock. It is a duration and it has to survive a suspension, which is the pair of questions the record asks of any expiry it does not already name, and it names this one.

The record settles a case the cadence would otherwise decide by accident. A device that slept through three cadence ticks owes one report rather than three. That is the same answer this issue already wants for somebody scrubbing through a film, arriving from the clock rather than from the coalescing rule, and the two must not disagree: coalescing that counts missed ticks would send three reports for a sleep and one for a scrub, for no reason a reader could reconstruct.

The immediate events are not intervals at all and no clock moves them. Started, paused, resumed, seeked and stopped report on the event, which is what makes them immediate.

Where a report carries a moment rather than only a position, that moment is on the wall clock, because the server also has an opinion about it and the record allows a moment on no other clock. The position itself is the unit fixed in #56 and is not a time.

[iderex]

The cadence landed as docs/decisions/0057-the-progress-reporting-cadence.md, on 9931223. The clock it is on is settled in the comment above and the record reads 0102 rather than restating it.

Ten seconds while something is playing, with started, paused, resumed, seeked and stopped reporting the moment they happen.

The number sits between a cost that is paid always and a loss that is paid rarely, and it is chosen rather than measured, with #65 named as where a measured replacement comes from. The cost is arithmetic on the chosen number rather than a claim: one stream at ten seconds is three hundred and sixty reports an hour, and a household watching four things is one thousand four hundred and forty writes an hour arriving at a machine an operator runs at home. The loss is that a process the platform killed, a television losing power and an application swiped away all produce no stop event, so the last interval report is the last thing the server heard, which makes the interval the bound on how far back somebody is thrown.

That bound has to be read against the rewind in #58, and the record puts a constraint on that issue rather than taking a number from it: the interval may not exceed the rewind. If #58 fixes a rewind shorter than ten seconds, one of the two records is wrong and the disagreement is visible rather than latent.

The interval does not run while paused. A paused position is not moving, so every report would coalesce into the entry already there and the only thing left is the wake-up, which on a handheld is a wake-up per interval for as long as somebody leaves something paused. Pausing and resuming both report, so nothing is lost between the two.

Reporting immediately means enqueued immediately, and the record says so rather than implying delivery. Whether it reaches the server is 0047's and 0045's. That matters most for stopped, which is the report a person most expects to have landed, and the honest statement is that it is durable rather than delivered. Stopping the core is not a sixth event: 0115 already fixes that a stop neither drains the queue nor discards it, so a report enqueued a moment earlier is still there afterwards.

No second coalescing rule is written, which is the part worth flagging. A scrub already produces one report, because 0047 coalesces at enqueue and replaces an earlier action for one target with the later one while keeping its position in the order. What this record adds is only the granularity that rule is applied at: the target is the item within the session, and the kind is the position, so a seek, a pause and an interval tick are the same kind and forty of them leave one entry holding the last position. That is the same behaviour 0102 already gives a device that slept through three ticks, and the two agree because they are one mechanism rather than two that were made to match.

The unit and the precision of a position are #56's and are not restated. Nothing in the cadence depends on them, which is why it could be decided first: an interval is a duration between reports and a position is what a report carries.

Of the four conditions here, one is met and three are untouched. The cadence and its reason are recorded. Proving a scrub produces one report, proving each immediate event reports without waiting for the interval, and observing every report pass through the queue are statements about running code, and there is no language chosen, no build and no test command in this tree, with #21 open. This stays open on all three.