literature-radar

One run answers one question: what appeared in this window, and can I prove the window was actually covered?

The second half is the hard half. A sweep that returns nothing looks identical to a sweep that failed, and both look identical to a sweep that was configured to find nothing.

The run

→ references/window-definitions.md for the nine window terms, each of which changes the result when defined differently. → references/rate-limits.md for transport behaviour: rate limiting, connection failures, truncated payloads, and the two counting rules that are wrong in most implementations. → references/checking.md for the four end-of-run checks and the evidence an empty window must carry. → references/tuning.md for changing the profile without breaking the corpus it was tuned on. → references/pipeline-ops.md for long runs, request batching, probe isolation, and the copied-script trap.

Scripts

Five, standard library only. scan.py fetches one window, score.py applies the profile, selfcheck.py runs the four checks above, regress.py runs the six tuning checks, miss_diag.py explains one absence. Each one is a step of the run table, not a replacement for it: the report, the push-log delta and the cursor are still written by whoever is running the day.

python scripts/scan.py --out _out/2026-01-07 --since 2026-01-01
python scripts/score.py --scan-dir _out/2026-01-07 --config profile.json
python scripts/selfcheck.py --out _out/2026-01-07 --expect-requests 4

scan.py --corpus <dir> replays Atom files already on disk with no network — the path the tests use, and the one to reach for before blaming the profile for an empty window.

Hard rules

• A zero-result report must carry its own proof. "Nothing was published" requires three things: the newest item's date is older than the window start; the shallowest source was walked back past the start; a control query returns items. Without all three, write "the window was not covered", not "nothing was published". Counter-example: a zero reported because a request died at the transport layer; the control query would have shown the source was reachable the whole time.
• Never extrapolate a rate limit from someone else's run. A backoff value is a measurement of one client on one network at one hour. Re-measure, then use yours. Counter-example: a run inheriting a documented wait four times longer than needed, costing most of an hour per failure.
• A count must come from a single-constraint query. Counts returned for compound queries with OR groups are not comparable across queries. Counter-example: a "1,204 results" headline from a query that silently dropped its date clause.
• Copying last period's script is the most expensive shortcut in this skill. After copying, grep every path and identifier to confirm it points at the current period, and confirm the target directory was empty before the run. Counter-example: a script that wrote into the previous period's directory and printed SKIP already-good, producing a report that was complete and entirely from the wrong week.
• status is part of the data. An item count with no transport status cannot be interpreted, and a truncated run that reports 40 items is more dangerous than one that reports 0.

Output contract

A run delivers, in this order:

1. report — items with score and reason, or the empty-window evidence triple
2. push-log delta — new IDs only, checked against the log before writing
3. cursor — covered-through plus a per-source deepest and status
4. self-check — request count reconciled, server count compared to local, per-source completion, shallowest source reaching the window start

Routing