0.3.49

CLAUDE.md

@@ -967,9 +967,24 @@ it hides itself on devices that actually support it.
 
 **Row analytics.** `data/analytics/RowAnalytics.kt` buffers impression/focus/select events
 with dwell timing (injectable clock, unit-tested) and `HomeViewModel` flushes every 20s,
-on `ON_STOP`, and on dispose. Fire-and-forget by design — `reportRowEvents` swallows
-failures, because telemetry must never surface on a TV. Aggregates are read at query time
-in `store.RowStats`; raw events are pruned after 90 days.
+on `ON_STOP`, and on dispose. Aggregates are read at query time in `store.RowStats`; raw
+events are pruned after 90 days. Three things keep the focus/dwell figures honest:
+
+- **The periodic flush *checkpoints* dwell, it does not end it** (`checkpointFocus`): a
+  viewer sitting on one row for two minutes must contribute the whole two minutes, not one
+  ~20s chunk ending at the first flush and nothing after until they move to a different
+  row. `endFocus` (genuine departure — a selection, the rail, the hero, an overlay, leaving
+  home) is the only thing that clears the measurement, and the UI calls it explicitly
+  (`notifyFocusLeftRows`) so time spent above the shelves is never credited to the last row
+  focused.
+- **A batch the upload cannot deliver is put back** (`restore`), so a transient network
+  failure costs a delay rather than the batch — still bounded by `maxBuffered`, still lost
+  to a crash. `reportRowEvents` hands the events back through `onUnsent` on failure or
+  before a session exists; it stays silent on screen and on the direct path.
+- **The server drops free text in the controlled fields.** Row id, kind and item id are
+  vocabulary the television composes (`safeAnalyticsValue` in `toRowEvent`), so an event
+  carrying anything else was misassembled and a pathological value would distort the
+  aggregates — dropped whole, as the journey path does.
 
 **Server logging** answers "who did what, from which television, on which build". Three
 pieces make that true and each is easy to undo: