0.2.68

server/internal/credits/README.md

@@ -8,7 +8,7 @@ is in the library" and answers by reading all of it. This asks "what will somebo
 on over the next few evenings", which Tracearr already knows, and reads almost nothing:
 
 ```
-Tracearr demand → priority queue → marker cached? → tiny tail scan → one write → never again
+Tracearr demand → priority queue → marker/cooldown check → tiny tail scan → history + marker
 ```
 
 ## Why it exists
@@ -57,6 +57,19 @@ postgres.go    the store adapter
 load.go        whether the server is too busy for speculative work
 ```
 
+## Operator controls and history
+
+Admin Console → Credits detection controls three different bounds: the number of candidates
+allowed to wait, the ordinary and maximum episode look-ahead, and the retry delay after an
+inconclusive or failed speculative scan. The environment values are first-run defaults; a
+saved console choice is restored on restart.
+
+The retry delay is important. A successful marker excludes an episode naturally, but an old
+worker forgot a no-match result and selected the episode again at the next ten-minute
+refresh. Completed attempts now have a small durable history and no-match/failed episodes
+cool down before prediction may select them again. Live playback may still raise an episode
+immediately because a viewer is waiting.
+
 ## Two detectors, and the cheap one is often better
 
 **Behavioural** clustering costs nothing: no file is opened, no decoder runs, no new row is
@@ -111,7 +124,7 @@ number belonging to neither.
 | Fine pass | 750ms over ±30s — ~80 frames |
 | Frame buffer | 14,400 bytes, allocated once and reused for the whole pass |
 | Writes, cached marker | **0** |
-| Writes, successful scan | **1** |
+| Writes, completed scan | **1 history row**, plus **1 marker** only when accepted |
 
 Against scanning the full library: 20,000 items read end to end versus a queue capped at 20
 candidates, most of which are rejected by the marker check before any media is touched. Once
@@ -135,7 +148,8 @@ in which demand-driven narrowing is doing nothing, and the design would need rev
 
 - **The queue is deliberately not durable.** Candidate priorities are rebuilt from one
   Tracearr query on restart, which is cheaper and simpler than a second persistent job
-  scheduler. The database holds markers and nothing else.
+  scheduler. Completed scan history is durable because it is an operator record and the
+  source of retry cooldowns; it does not preserve or resume queue state.
 - **A single worker, and it is not a placeholder for a pool.** Concurrent scans multiply the
   two costs this exists to minimise on a machine whose real job is streaming video.
 - **Live playback does not scan immediately.** `livePlaybackDelay` (45s) is what stops a