mangaBookmark/docs/adr/0016-the-failure-row-is-the-state.md

ADR-0016: The failure row is the state

Date: 2026-08-22 Status: accepted

Decision

A Series that used to work and has stopped is recorded in one table, poll_failures, keyed by the same (site, series_id) composite the rest of the system uses. One row per failing Series, carrying the outcome word and a failing_since stamp. The row's existence is the failure state: there is no success sentinel, no counter, no history, and nothing added to the Series row. A correct read deletes the row, and a repeated identical failure writes nothing — the stamp ages the run of failures, not the current word.

The write is one upsert, from the poll pass loop:

INSERT INTO poll_failures (site, series_id, outcome, failing_since)
VALUES ($1, $2, $3, $4)
ON CONFLICT (site, series_id) DO UPDATE SET outcome = EXCLUDED.outcome
WHERE poll_failures.outcome <> EXCLUDED.outcome

failing_since is simply absent from the SET arm, so it is never overwritten, and the WHERE makes an unchanged word write nothing at all — one statement, no read-then-write race. The clear is a plain DELETE; a row that is not there is not an error, because the poller clears on every successful read and most clears find nothing. The composite foreign key cascades: deleting a Series takes its failure row, so orphan removal stays a single statement.

Why a future reader will find this surprising

The failure state lives in a table of its own, not on the Series row and not in the pass log. A flag on series would be the familiar shape, and the pass log already records outcomes per pass — why a third place?

Because the failure must outlive the pass that observed it and mean something the pass row cannot say. The pass log is a per-Lane stream: it records that a Site returned N errors and M not_found on a given run, but "this exact Series has been failing for three months" is not a question any single pass row answers — it is a question across rows, and the Lanes page is a live view of the last 14 days, not a Series index. A Series-level fact needs Series-level storage, and a flag on the Series row is the wrong shape too: the failure is transient by definition (a correct read ends it) and repeatable (the same Series can fail again next year), so the honest record of "failing since" is a stamp that moves, not a column that flips. A row that is created and deleted by the read's outcome is that stamp, and nothing else: the moment a read succeeds the row is gone, so "is this Series failing?" is answered by one indexed existence check — no success sentinel to keep consistent with the failure, no counter to reset, no history to prune. The state cannot drift out of step with the reads that maintain it, because the reads are the maintenance.

The two no-write outcomes are the second surprise. refused (the Site is holding a challenge) and unreachable (the browser sidecar was lost mid-loop) issue no statement at all — neither an upsert nor a delete. The direction matters, and both directions are wrong to touch:

• Writing would condemn a whole library for one Site's bad day. A refusal is the Site's mood, not a fact about any particular Series: when Cloudflare turns a zone's JS detection on, every Series on that Site reads refused in the same pass. Writing those rows would stamp every Series in the library as failing on the evidence of one Site's configuration, and #166's worklist would present a Site-wide outage as thousands of broken Series.
• Deleting would claim a recovery nothing read. A lost sidecar tells us nothing about the page — the read never happened. Deleting the row would report the Series healthy, and worse, it would reset failing_since: the age that makes a three-month failure findable would start over on a browser restart, erasing evidence no page read contradicted.

So a refusal or an unreachable pass leaves the table exactly as it found it — the pass neither adds rows that would condemn nor deletes rows that would claim recovery. The four outcomes that are real evidence about the page (not_found, no_chapter, unfetchable, errors) write; the two that are not write nothing; success deletes. There is no third case.

Considered options

A failing_since column on the Series row, alongside the failure word. Rejected: it is two more columns on a table every due query and every bookmark join already touches, for a state that is transient and repeatable. The column would need its own "clear on success" writer anyway — the same maintenance the row has — while permanently widening the hottest table in the system for a value that is usually absent. And the worklist's join would have to distinguish "never failed" from "currently healthy", which is exactly the sentinel problem the row avoids: an empty column means both.

A counter or last-outcome timestamp instead of (or beside) the row. Rejected: nothing in the system consumes a failure count or a last-outcome time — the worklist needs "failing and since when". A counter invites "three failures = something" thresholds that the ticket explicitly keeps out of scope, and a last-outcome timestamp conflates "the word changed" with "the run restarted", which the age is deliberately defined against. The stamp is the only number that means anything, and the row carries exactly that.

Write into poll_passes and derive the failure state from the pass stream. Rejected: a pass row is per-Lane and per-run; deriving "this Series is failing since" means scanning 14 days of outcome counts per Series and guessing at continuity across retention boundaries. The pass log answers "what did this Site's lane do recently"; the failure table answers "which Series are broken right now". Two questions, two tables — the pass log is already pruned on a fixed cutoff, which would silently reset every failure's age the moment the evidence aged out.

Refused/unreachable write nothing, but the delete happens anyway (or the upsert happens, with no delete). Rejected in both directions, above: writing condemns a library for one Site's mood; deleting claims a recovery nothing read and resets the age that makes a long failure findable. The asymmetry is the point — the two outcomes are evidence about the environment, never about a page.

Consequences

• The poller writes from the pass loop, one call after checkOne, and clears through the ordinary success path: a Forced Poll that reads the page deletes the row with no forced branch of its own, and a Forced Poll request — which only stamps the request — clears nothing.
• poll_failures is a poll-write table like poll_lanes and poll_passes: the store's two methods live next to the Lane-pass writers, and neither runs on a request path. A store failure is logged and the poll continues — a failure row is best-effort, and no single bad Series may stall a Lane.
• The due query does not join the table. A failing Series is polled at the same pace as any other, because the moment the query started pacing by failure state, the age would stop meaning what the worklist reads it as.
• Orphan removal stays a single statement: the composite foreign key's ON DELETE CASCADE is what takes the failure row with the Series.
• The table starts empty at deploy, so nothing is findable for the first twelve hours after deploy and a pre-existing breakage reads as new. Accepted; the alternative is inventing history.

Cost of reversing

The failure state is derived, not stored: a rollback drops the table and every in-progress failure age with it, leaving the pass log's outcome counts as the only trace — which is exactly the "log line nobody reads" the ticket set out to replace. Recreating the table later starts the ages over, so a reversal that is later reversed loses the evidence of the intervening failures. The failure state itself, however, is the one thing that is not lost by reversing: it is re-derived from the next pass, in the same direction the original design derives it — the row is recreated by the next failing read and deleted by the next good one.