Admin dashboard: pages, Lane observability, poll pass log, per-Series intervention (#134) (#148)

Spec #134, all ten tickets. Closes #134.

## What ships

The admin surface becomes four bookmarkable addresses behind one nav row, and Lane observability stops dying with the process.

- **#138** `/admin` splits into Overview, Lanes, Readers, Series, each a real route with the active tab underlined.
- **#139** `poll_passes` and `poll_lanes` land as durable tables with their store surface.
- **#140** cross-Series admin read model, with the privacy boundary in the projection: the Reader id that raised a Latest Chapter never leaves the store package.
- **#141** the poller records exactly one pass row per exit, with a skip reason and outcome counts.
- **#142** Series list: eight hygiene filters, Site and Library narrowing, paging — all of it in the query string, so a filtered list is a bookmark.
- **#143** Overview: a three-state verdict line and a stats block where every non-zero figure links to the list that counts it.
- **#144** per-Series detail page, keyed by the `site:series_id` composite the rest of the system already uses.
- **#145** the Lanes page reads the database; the in-memory Lane state, `web.LaneReporter` and `latest.Status` are deleted.
- **#146** Forced Poll: *Check now* stamps `series.force_poll_at` and never commands the poller.
- **#147** pause and resume one Site's Lane, with a mandatory 1h/6h/24h expiry.

## Shape of the design

Two decisions carry the rest. **Commands go through the database, never at the poller**: both *Check now* and a Lane pause write a row the next pass reads, so they survive a restart and the whole surface stays testable with no poller running. And **pending is derived, never stored** — the request stamp being newer than the check stamp — which self-clears on the check stamp with no second write and no sweeper, because the check stamp is written before the fetch.

ADRs: `docs/adr/0012-persisted-lane-state.md`, `docs/adr/0013-commands-through-the-database.md`.

## Verification

`go test ./...` green on the merged base (`264839e`), all packages, Docker-backed. `gofmt -l` and `go vet` clean.

Every ticket was reviewed on both axes (`cr-spec` + `cr-standards`) before merge.

## Known, non-blocking

- **#143** the verdict ignores never-reported Lanes when other Lanes have reported, and the per-Site table lists Sites that have Series rather than the whole registry. The ticket prose asks for eight hygiene figures per Site; the design mock and the landed `.tbl.sites` grid both say six columns, and the mock won.
- **#146** two `SeriesPage` scans per press instead of a keyed read — `ponytail:`-commented in-tree with the upgrade path.
- **#147** a paused Site with no pass row yet renders no row and so no control, since the Lanes page lists Sites that have passed.
- **#141** a sibling browser Lane declining at the top of a pass records as `sidecar-down`. Specified deliberately; the later spec in this series settles it.

Reviewed-on: #148
Co-authored-by: Sulthan Zaki <sultankiki05@gmail.com>
Co-committed-by: Sulthan Zaki <sultankiki05@gmail.com>
This commit was merged in pull request #148.
This commit is contained in:
2026-08-22 08:27:19 +07:00
committed by sulthan
parent 0a245a0dde
commit 889f0f3f38
33 changed files with 6112 additions and 634 deletions
+44
View File
@@ -0,0 +1,44 @@
# ADR-0012: Persisted lane state
Date: 2026-08-21
Status: accepted
Supersedes the in-memory lane snapshot carried by `latest`'s `LaneState`/`Status`
and the `web.LaneReporter` seam (ADR-0010 wrote the durable rows this page now
reads).
## Decision
The admin Lanes page stops reading the poller's in-memory Lane state and
becomes a read of `poll_passes`/`poll_lanes` in Postgres. There is no
`LaneReporter` interface: `web/admin_lanes.go` walks `store.LatestLanePasses()`
into one row per Site and adds the window's outcome sums from
`store.LanePassOutcomes()`. The `latest` package's `LaneState`/`Status` snapshot
and its `web.LaneReporter` seam are deleted.
The browser is a deployment configuration fact plus a reachability derived
from the pass log: `BROWSER_WS_URL` set means "configured", and the browser is
"reachable" unless a recent browser-Site pass inside `latest.RefuseBackoff` is
a sidecar loss, a missing fetcher, or an interrupted read. A skip reason is
the whole difference between a Lane resting and a Lane stuck: a skipped pass
prints its sentence, and only an empty skip with Series due and none read
draws the true-stall fault. Sleep skips never count toward `Attention`.
## Why
The old page lived on a poller snapshot. Because that state was in memory, a
deploy erased it: the page read zeroes until a fresh pass ran, and browser
reachability came through a reporter interface only a live poller could
serve. Making the page answer from the database means a restart is complete
the instant the store is up, the browser fact survives a poller restart, and
a Lane that has not yet gathered figures shows a placeholder rather than a
confident zero.
## Constraints
The poller still owns the writes: each pass exit records one row (ADR-0010),
and a pass that returns before gathering figures carries the previous pass's
numbers forward instead of recording zeroes. A skip is a stable wire string;
`asleep` never counts toward `Attention`. When polling is switched off
(`LATEST_CHAPTER_POLL_ENABLED` unset) the page must say so, and the browser
statusline appears only when polling is switched on.
@@ -0,0 +1,60 @@
# ADR-0013: Commands through the database
Date: 2026-08-22
Status: accepted
## Decision
Owner interventions are **facts about rows, never commands to the poller**.
*Check now* (`POST /admin/series/{key}/poll`) writes one stamp —
`series.force_poll_at`, unix ms, zero meaning never asked (the column landed
in migration 0014) — and the poller's next pass reads it through
`Store.DueForLatestCheck`. The control never signals the running process, so
a request survives a restart, and the whole surface is testable with no
poller running at all.
**Pending is derived, never stored**: a Series is pending while
`force_poll_at > latest_checked_at`. It self-clears with no second write and
no sweeper because the check stamp is written *before* the fetch (the same
"attempted" discipline as ADR-0010) — the first attempt ends the pending
state whatever the attempt returns. There is no expiry: a request the Lane
never reaches keeps ageing in the UI, and an old pending marker is itself the
evidence that a Lane is stuck. Writing again re-stamps the request time; the
write is idempotent.
**Queue-jump rules.** A forced Series overrides exactly three gates in the
due query: the rest cutoff, the Sighting-deferral clause and the finished-only
bucket, and it sorts to the front of the queue
(`ORDER BY forced DESC, reader_count DESC, latest_checked_at ASC`). It never
overrides an empty `series_url` (nothing to fetch), the Bookmarks join (a
Series no Reader holds has no consumer for the result), the Lane's refusal
backoff, the sidecar-down skip, or the Lane's gap — the last three are
poller-side gates the query cannot see and must not. The one pass-level gate
a forced Series does open is the browser wake threshold: a human asking wakes
a sleeping Chrome, where the thresholds exist to stop the machine waking
itself for one unattended check. If the home machine is off, nothing happens
and the request ages visibly, which is correct.
Rejected: zeroing the check stamp as the force signal. It would corrupt the
never-checked and stale counts the landing page exists to show, and make a
pending marker impossible.
## Why
A stuck-looking Series previously waited for its turn in the Lane's hour, and
there was no way to ask for one check sooner. A direct poller command would
have been lost on every restart and untestable without a running poller; a
row the poller already reads is neither. Deriving pending from the two stamps
keeps the flag honest across restarts and makes the mechanism two column
writes and three query clauses instead of a state machine.
## Constraints
- The finished-status clause the force flag overrides is today's Lifecycle
test; a later spec in this series deletes it wholesale rather than amending
it, so the clause stays as it stands.
- The control is unconfirmed (it takes nothing away) and renders no
`.confirm-row`; it is hidden on a Series with no `series_url` and on an
orphan — the same pair the due query refuses to override.
- The answer to a press is the freshly rendered row, so the figures describe
the state after the press.