feat: inspect EPUB colophon to resolve low-confidence mis-seeds

[vidaks]

What & why

resolve only sees a mis-seed's title + author. When Hardcover search + Haiku can't confidently pick the same work, the book is left flagged — yet the file itself usually carries the answer: the OPF dc:identifier ISBN and the colophon / copyright page.

This adds a below-threshold escalation: when the normal title+author pass lands under the confidence gate (or returns no match), inspect the book's own EPUB and re-adjudicate with two extra signals.

• OPF ISBN → deterministic heal (source=epub-opf, no LLM). A real dc:identifier ISBN that resolves to a same-author Hardcover book is healed directly at conf 0.97. ISBNs are edition-unique, so this is high-trust.
• Colophon page → folded into the Haiku prompt (source=epub-colophon). The printed print ISBN there often matches Hardcover's canonical edition better than the OPF ebook ISBN.

Only below-threshold books pay for the file I/O; the common path is untouched. Measured marginal cost of the colophon read: ~300 input tokens, ~1.3 s, well under a cent per book.

New surface:

• colophon/epub.py — stdlib-only, read-only EPUB extraction (OPF ISBNs + best-guess colophon page).
• hardcover.book_by_isbn — ISBN → book via the Typesense search (the broad Hasura editions(where:{isbn_13}) filter is 403-restricted on this key tier).
• grimmory.epub_path — read-only DB → host path, gated on the new COLOPHON_BOOKS_ROOT.

Activation (not automatic):

• Unset COLOPHON_BOOKS_ROOT ⇒ feature off (default). Set it to the host library root to enable.
• Existing cached-unresolvable mis-seeds are filtered by the skip-list before the escalation point, so they need a one-time resolve --force to get inspected; new mis-seeds get it on first encounter.

Checklist

• Discussed in an issue first — N/A (maintainer change)
• No new runtime dependencies (standard library only)
• Preserves the safety model — EPUB access is read-only; the heal / precondition path is unchanged; the OPF path is author-validated and the colophon path still validates chosen_id against the candidate set; every write still logged
• python -m compileall colophon passes (ruff not installed locally → deferred to CI)
• Updated README.md / CHANGELOG.md
• Tested against a real server with dry-run (read-only); output below

Notes / test output

Live read-only validation (real server + real files, no --apply, no writes):

# hardcover.book_by_isbn
9781466849358 -> hcid 427527 "Lock In"

# OPF deterministic short-circuit (_resolve_by_isbn)
correct author   -> propose source=epub-opf hcid=427527 isbn=9781466849358 conf=0.97
author mismatch  -> None
junk ISBN        -> None

# colophon-in-prompt path (book 589, no OPF ISBN, 136-char colophon)
epub_path resolved + file exists: True
proposal: source=epub-colophon hcid=467613 "Valkyrie" isbn=9781672360081 conf=0.95
  (reason cited "copyright year 2019 from the colophon")

Tests: python -m unittest discover -s tests -v → 27 passed (7 new epub.py, 3 new escalation-glue).

🤖 Generated with Claude Code