mangaBookmark/docs/adr/0015-finished-is-a-series-fact.md

# ADR-0015: Finished is a fact about the Series, not a bookmark bucket

Date: 2026-08-22
Status: accepted

## Decision

"Finished" moves from the per-Reader `bookmarks.status` bucket to a
Series-owned flag: `series.finished_at`, unix ms, zero while the Series is
still running. The Lane's gate reads the flag — a Series is polled only while
`finished_at = 0` — and `bookmarks.status` keeps exactly two values,
`reading` and `archived`.

The cutover is one-way, done by migration 0016 in three load-bearing
statements:

1. `ALTER TABLE series ADD COLUMN finished_at bigint NOT NULL DEFAULT 0`.
2. Seed it from the bookmarks: a Series is stamped finished when no bookmark
   on it is outside the `finished` bucket. This mirrors the pre-cutover due
   gate exactly — the old query skipped a Series only while
   `COUNT(*) FILTER (WHERE status <> 'finished') = 0` — so no Series changes
   polling state at the cutover.
3. Rewrite every `finished` bookmark to `archived`. The bucket is gone; the
   seed ran first because it is the only statement that can still read it.

The JSON API rejects a `finished` status with the same plain 400 as any
unknown value, and the web UI no longer offers a Finished tab, a finish
button, or a finished state badge.

## Why a future reader will find this surprising

The bucket looked Reader-shaped but described a Series fact. A Series is
finished once, and every Reader reading it is then on a finished Series —
yet the bucket carried three copies of the answer, one per Reader, free to
disagree. The disagreement is not theoretical: a second Reader who merely
kept the Series (or never read it) kept it in `reading`, so the poll gate
kept fetching a Series the first Reader had closed out, forever. Worse, the
disagreement was never resolvable — nothing in the system could say "this
Series is finished" without rewriting every bookmark, which silently edits
another Reader's progress state.

The flag is also the only memory of the bucket after the flip. `finished`
bookmarks become `archived` because a two-value status needs no third
value, and an archived row must keep meaning "shelved, but the Series is
being watched" — which is what the row says. The migration's seed is what
keeps the legacy meaning: a Series every Reader finished is stamped, so the
Lane stops polling it just as it would have pre-cutover; a Series any
Reader still reads is left alone, exactly as the old gate left it. A
Series whose every Reader only shelved (archived) continues to be polled,
because an archived bookmark is *supposed* to be polled — the cutover
changes the answer, it does not invent it. And because the flag is a series
fact, the cutover also repairs the disagreement case: the moment one Reader
has the Series open, it reads as finished to everyone.

The migration is the only writer of the flag today; the undo is writing 0,
which returns the Series to the poll. An owner-facing "mark finished" write
is deliberately not part of this change — the gate is what this ticket
rewrites, and the write can land on top of it without touching anything
here.

The userscript merge ranks `archived > reading` now. `finished` is not a
value the wire can carry, so the merge cannot un-finish a row — it cannot
even name the state it is protecting.

## Considered options

**Keep the bucket and add the flag alongside it, both live.**
Rejected: two sources of truth for one fact, with the Lane forced to
resolve "any Reader finished?" on every due query and every Reader write
still able to resurrect a finished Series. The whole point of the change is
that the finished state survives Readers.

**Stamp a Series finished when every bookmark is finished *or* archived.**
Rejected: it flips polling state at the cutover. Shelved-only Series were
polled before; making them finished stops the checks the reader knowingly
asked to keep.

**Finish as "no bookmark is reading", leaving the buckets untouched.**
Rejected for the same reason plus one: `archived` is a Reader's own state
and the flip is what makes the flag the *only* source of finished. Keeping
the `finished` value in the table would force every status validation,
merge and UI branch to keep handling a value no write can produce.

## Consequences

- `bookmarks.status` is validated to `reading | archived`, empty meaning
  "keep the stored value"; the API's 400 for `finished` is now the generic
  invalid-status rejection rather than a special case, and the web UI's own
  status control rejects it the same way.
- The Lane due query and the eligible count read `finished_at`; a Forced
  Poll (issue #146) still overrides the flag — the owner asked, so the Lane
  looks — and the pending force clears itself when the pass stamps the
  check timestamp, never by touching `finished_at`.
- The web UI has no Finished tab; finished Series render in Archived with
  their archived badge, dimmed like any shelved row.
- Migration 0016 stamps `finished_at` with the migration's own clock
  (`now()` ms), which is also the undo: write 0 and the Series returns to
  the poll.

## Cost of reversing

The finished buckets are destroyed by the flip; reversing means re-deriving
per-Reader finished state from a Series fact that now encodes the
majority-agreement snapshot plus whatever the owner reset since. The stamp
differentiates "finished at the cutover and untouched" from "finished
later", but not which Reader's choice each Series carried, and any Series
the owner has since restored is gone from the derivation entirely. The ADR
is a statement of intent to ship the one-way cutover and live with its
consequences; the per-Reader history is not kept anywhere in the schema.