feat(janitor): reap expired pending deletes nightly

[ajslater]

Implements P1e of tasks/followups-implementation-plan.md §4.8 — the last of the pending-delete mechanism.

Stacked on #881 → #880 → #879 → #878. Retarget as each merges.

Until this lands nothing ever really deletes a stamped row. That is a safe state, but it leaks rows indefinitely.

The window is a constant, not a setting

_PENDING_DELETE_WINDOW: Final = timedelta(hours=24)

A safety delay before an irreversible action, not a tuning knob. The precedent is nearly exact: the telemeter already has a 24-hour grace window whose purpose is "give the admin time to opt out before anything irreversible happens", it is a bare constant (_ONE_DAY), and it is documented to admins in prose while still not being configurable. The nearest neighbour in the delete path is also a commented constant pair (_MASS_DELETE_FLOOR / _MASS_DELETE_FRACTION).

An AdminFlag would cost roughly ten files (enum, title, seed default, data migration, settings/db.py helper, serializer validation, two JSON description files, a v-else-if arm, a Stats field, plus make build-choices) and would be the only configurable knob in the whole delete-safety story.

The effective window is 24h plus the time to the next nightly run, which is exactly what "24 hours or more" meant. Said so in the docstring.

Priority: index 17

Verified in place: UpdateCollectionsTask → JanitorReapPendingDeletesTask → JanitorCleanFKsTask.

• FK cleanup must follow it. While a stamped comic still exists its Publisher/Imprint/Series/Volume are not orphaned; only after the reap do they become orphans. A reaper at index 24+ leaves emptied groups visible until the next night. cleanup_fks runs a convergence loop, so it cleans the whole chain in the same pass.
• Search-index sync must follow it, or a night of dead FTS rows survives.
• Not earlier than 17. Indices 11–16 are tag-writing and import tasks; a bulk DELETE under the write lock ahead of a queued import would stall a user-initiated import behind maintenance.

Two tests pin the ordering relative to JanitorCleanFKsTask, SearchIndexSyncTask and ImportTask.

The folder guard, and the trap in it

A folder delete cascades to its comics through Comic.parent_folder and to sub-folders through Folder.parent_folder, so reaping a stamped ancestor would take live descendants — and their bookmarks — with it.

The obvious implementation is wrong, and the test caught it:

# WRONG — a folder with NO comics is NULL-extended on the LEFT OUTER
# JOIN, so this reads its absent comic as a live one and the folder
# can never be reaped.
expired.exclude(comic__missing_since__isnull=True)

Replaced with explicit ~Exists(live_comics) / ~Exists(live_subfolders) subqueries, which have no NULL-extension semantics to get wrong. Comics are reaped first, then folders, because reaping the comics is what can make a folder eligible.

Twelve registrations, not three

CLAUDE.md names three. The actual list is twelve, and omitting #8 is the silent-failure mode — get_task_priority raises ValueError: tuple.index(x): x not in tuple and the job simply never runs.

Task class · status class · JANITOR_STATII · migration · _JANITOR_STATII · _NIGHTLY_TASKS · _JANITOR_METHOD_MAP · _SCRIBE_TASK_PRIORITY · _JANITOR_NIGHTLY_STATUSES · the Jobs-tab entry · _TASK_MAP · make build-choices.

test_the_job_is_fully_registered asserts all of them.

One corrected premise: the plan warned that max_length=max_choices_len(StatusChoices) is computed from the labels, so a long title would change the column width. It is computed from the choice keys (choice[0]), which are all three characters. max_length=3 is unchanged; migration 0056 only alters choices.

"Reap now" needed no new endpoint

Registrations #10 and #11 make it POST-able through the existing POST /admin/tasks/run + librarianTask(...) store action, exactly as Poll and Force Update work from the library rows — which gets the Jobs-tab entry, the sidebar progress row and the abort plumbing for free. The job carries a confirm string, since it permanently deletes read progress.

Publishing

The job clears its own caches, re-stamps the reaped comics' collections through TimestampUpdater, and enqueues LIBRARY_CHANGED_TASK itself — the janitor has no importer finish() to do it, and cleanup_fks notifying nothing is a gap, not a precedent. Collections are gathered before the delete, since afterwards there is nothing to read them off.

It also enqueues CoverRemoveTask: #880 deliberately left covers in place so a revived row would find its own, so the reaper owns removing them.

Scheduling

Untouched. The nightly trigger stays the cron thread; commit 11b3210b4 fixed "nightly janitor running dozens of times each midnight" and nothing here adds a second wake-up.

Tests

Eight cases in TestReaper: a fresh stamp is not reaped, an expired one is, a live comic is never touched, a folder with a live comic is spared (with its comic), a folder whose comics all expired is reaped, the announcement, the twelve registrations, and the ordering.

tests/test_scribe_priority.py still passes. make build-choices run. make fix && make lint && make ty clean; makemigrations --check and django-check clean. Full make test green: 1294 pytest (+8), 579 vitest.

No new NEWS line — #881's covers the user-visible behaviour.

Known limitation, worth stating

poll_force cannot recover a stamped library — it sets stat[8] = 0.0 on every DB row and skips the stale-stat refresh, so every path reads as modified, never as revived. That matters because Force Poll is the button an admin will press. The admin surface (P1f) should say so, or the force path should run the unstamp pass.

🤖 Generated with Claude Code