[developer-ainative]

Cross-cutting infrastructure fix, not a numbered backlog story — same category as the scheduled-job runner. ZeroDBClient had no delete_file, and three separately merged stories each had to document "cleanup cannot remove uploaded file objects" as an honest limitation instead of actually cleaning up: 9.1 (campaign sites), 5.4 (bill text), 9.2 (debates/questionnaires). Story 5.4's verify script leaked H.R. 1's 2.8 MB public-law text on every single run. Built once, here, rather than a fourth time.

The endpoint, measured rather than assumed

The /database/files vs /files split is exactly the one that caused the upload bug in PR #157 (metadata row written, no bytes stored), so this was verified live against the real project before committing to a shape. Both DELETE routes exist:

Route	Response
DELETE /projects/{id}/database/files/{file_id}	{message, file_name}
DELETE /projects/{id}/files/{file_id}	{success, file_id, deleted_from_storage, message}

Both genuinely remove the MinIO object. That is not inferred from the 200 — a presigned URL minted before the delete, still inside its signature window afterwards, was fetched straight from object storage and answered NoSuchKey for either route.

delete_file uses /files/{file_id} because it is the only one whose contract names storage, which is what makes the trap below refusable instead of invisible.

Two live findings that shaped the method

?delete_from_storage=false is a byte leak with a friendly name. It returns 200, drops the metadata row, and leaves the object in MinIO addressable by nothing — every delete route addresses a row that no longer exists. Recovering one takes re-uploading under the identical file_key and deleting that properly (confirmed; that is how the one I created while probing was reclaimed). The method sends the parameter never and exposes no argument for it.

deleted_from_storage is not proof. It reads true even for a metadata-only row that never had an object, so it means "attempted", not "removed". Nothing treats it as proof; the verify scripts prove removal with a failed download_file instead.

Unlike delete_memory, a second delete answers a clean 404, not a 500 wrapping a 404 — so no reinterpret hook is needed and no retry is burned. A cleanup path can treat already-gone as done.

The one judgment call

delete_file refuses a row whose bytes were never stored unless the caller passes allow_missing_content=True. Those rows are datamodel.md's unmendable citations — story 9.1's three promise_sources archives whose pages have since changed, so the bytes are provably unrecoverable by anyone. Retiring them is a deliberate human decision, not something a cleanup sweep does on its way past, and the opt-in is the gate that keeps it deliberate. Live-verified in both directions: the guard fires, and the opt-in works.

Verified live

• A file uploaded, downloaded, deleted, then: object 404s from the raw store on a still-valid presigned URL; get_file, download_file and a second delete_file all raise ZeroDBNotFoundError.
• verify_bill_text_live.py — all live checks passed, 2 bills, 4 provenance_log rows and 2 archived files deleted, each re-checked. No more 2.8 MB leak per run.
• verify_debates_questionnaires_live.py --cleanup — VERIFICATION PASSED, all 10 stored files (5 captures × document + text) deleted and each confirmed unreadable.
• Both of story 5.4's documented orphans cleaned up for real: 583d2231… (4,233 bytes) and 0cebf653… (2,787,974 bytes), each first confirmed matching its documented name/size and unreferenced by any bills row, then deleted and confirmed unreadable. 2.79 MB reclaimed.

Scope note

verify_campaign_sites_live.py (9.1) is deliberately not changed — it has no cleanup path by design; its own output says "These are REAL captures … Do NOT clean these up." Adding deletion there would be wrong. The 9.1-era limitation note lives in repair_unretrievable_archives.py, whose conclusion still stands but whose stated blocker was half plumbing that now exists; it now says so accurately.

Tests

Red first, confirmed failing for the right reason ('ZeroDBClient' object has no attribute 'delete_file'), committed, then green. Five unit tests against FakeZeroDBTransport, consistent with every other client method; the fake serves the route with the same semantics, including the unconditional deleted_from_storage so no caller can come to rely on it. No Gherkin — internal infrastructure with no user-facing behaviour, following this session's scheduled-job-runner precedent.

Full backend suite: 3918 passed, 4 xfailed, 0 failed. ruff check and ruff format --check clean.

🤖 Generated with Claude Code