bindery-cli 0.30.0__tar.gz → 0.32.0__tar.gz

{bindery_cli-0.30.0 → bindery_cli-0.32.0}/CLAUDE.md

@@ -34,11 +34,22 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
     minimal content. v0.14–v0.16 ran these unconditionally, which broke this rule;
     v0.17.0 restored it. `--unwrap-illegal-tags` additionally protects any illegal-tag
     name that an EPUB stylesheet styles as an element selector (`css_protected_tags`,
-    book-wide, inline `<style>` blocks included).
+    book-wide, inline `<style>` blocks included). The two EPUB2-targeted fixes
+    (`--strip-epub3-attrs`, `--downgrade-epub3-tags`) are additionally gated on the
+    package version in the OPF (`package_version()`): inert on EPUB 3 books and when
+    no version can be read, since their target defects only exist below EPUB 3; the
+    attribute scrub is anchored to real start tags via
+    `transforms.strip_attrs_in_start_tags` (prose mentioning the attributes and
+    CDATA/comment content are preserved), and `strip_invalid_value` matches the
+    attribute name with a `(?<![\w:.-])value` lookbehind so `data-value` survives.
   * **Lossy strips** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`;
     pagination.py, watermark.py): remove only what a converter injected (page numbers,
     running headers, leaked tags, watermarks), fenced behind character conservation, tag
-    balance, and the epubcheck no-regression bar.
+    balance, and the epubcheck no-regression bar. The watermark anchored pass's
+    whole-match fallback only fires when the match holds nothing but the stamp; a
+    larger match (an unclosed stamp anchor that swallowed prose) is refused, counted
+    in `RepairReport.watermark_refusals`, and surfaced as a `manual_watermark_repair`
+    decision by `run phase1` on both the read-only and apply paths.
   Do not let any NEW fix touch content without its own flag; if a candidate repair cannot
   be made deterministically safe, it does not belong here — report it for manual repair
   instead.
@@ -58,15 +69,15 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 
 ## Layout
 
-- `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`).
+- `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`). Since v0.32.0: `strip_attrs_in_start_tags` anchors attribute edits on the quote-aware start-tag matcher, `_outside_protected` forwards arguments (context-carrying transforms can be decorated), `fix_id_colons` matches only the bare `id` attribute and only internal fragments (`fix_ncx_src_fragments` carries renames into the NCX), `fix_ncx_playorder` is anchored to `<navPoint>` start tags, and the css selector boundary covers namespaced and functional selector forms.
 - `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets).
 - `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
 - `src/bindery/reserialize.py`: structural repair via `html5lib`.
 - `src/bindery/audit.py`: read-only body-text audits (`content`, `pagenumbers`, `emptytext`, `ocr`, and `monolithic` since v0.21.0, `--max-doc-chars N`) behind the `audit` subcommand (v0.15.0). Since v0.18.0 library mode resolves EPUB paths through `cquarry.get_format_path()` and can apply a tag to flagged books via `cquarry.write.WritableCalibreDB` (only with explicit `--tag`; the only sanctioned write path). Since v0.19.0 `audit --id BOOK_ID` audits a single library book through cquarry's single-entity `get_book()` fetch (no library-wide cache; supports `--tag`; incompatible with the directory argument; comma lists since v0.23.0). Since v0.22.0 every archive entry is fully read (CRC + decompression) before analysis — a damaged entry reports its own CORRUPT verdict instead of feeding emptytext — and manifest/NCX references to absent files classify as `convention` (bloated ToC, consecutive span) or `fragment` (broken span). Hazard: the scan loop reuses `tag` as its per-book display column, so the `--tag` argument is captured as `audit_tag` at function entry — do not collapse them again. Since v0.29.0 `audit --json FILE` writes per-file analyzer verdicts in the `library --json` shape (directory, library, and single-book modes; with `--id`, exactly one id; emptytext omitted from a record when the archive verdict owns the body-text story).
 - `src/bindery/epub.py`: archive rewrite, NCX uid sync, RepairReport, mismatch detection, and the opt-in structural-repair plumbing (including the CSS precondition scan).
 - `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars.
-- `src/bindery/library.py`: Calibre walk, atomic replace, backups, and native format installation. Since v0.19.0 `CalibreIdResolver` resolves the book id from `metadata.db` through cquarry (one lazy path→id map per run; since v0.20.0 the map comes from `CalibreDB.format_path_index()`, re-normalized with `resolve().lower()` for the resolver's symlinked-directory and case-insensitive matching) — the `(id)` directory-name regex is only the no-catalog fallback. Since v0.24.0 `install_format()` places the repaired file atomically and updates the `data` row through `cquarry.write.WritableCalibreDB` (remove+add in one `batch()`; `add_format` refuses duplicates); the external `calibredb` CLI is gone. Never reintroduce directory-name guessing as the primary source: renamed/mismatched directories would replace the wrong book.
-- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; since v0.29.0 also the `run` verbs — `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2). Both take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. `library --workers N` (v0.30.0) parallelizes only the sweep's candidate pass, in windows of N consumed in order so `--limit` stays lazy; the repair phase is never parallel (shared workdir, atomic-replacement contract).
+- `src/bindery/library.py`: Calibre walk, atomic replace, backups, and native format installation. Since v0.19.0 `CalibreIdResolver` resolves the book id from `metadata.db` through cquarry (one lazy path→id map per run; since v0.20.0 the map comes from `CalibreDB.format_path_index()`, re-normalized with `resolve().lower()` for the resolver's symlinked-directory and case-insensitive matching) — the `(id)` directory-name regex is only the no-catalog fallback. Since v0.24.0 `install_format()` places the repaired file atomically and updates the `data` row through `cquarry.write.WritableCalibreDB` (since v0.31.0 via `set_format`, cquarry 1.17's sanctioned remove+add in one transaction); the external `calibredb` CLI is gone. Since v0.32.0 a guessed id drives a row update only when metadata.db corroborates it (`_verify_guess`: books row exists, file in the book's own directory, catalogued `data.name` when a row exists); anything else saves in place and leaves the catalog untouched — never reintroduce directory-name guessing as the primary source: renamed/mismatched directories would replace the wrong book.
+- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; since v0.29.0 also the `run` verbs: `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2). Both take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. `library --workers N` (v0.30.0) parallelizes only the sweep's candidate pass, in windows of N consumed in order so `--limit` stays lazy; the repair phase is never parallel (shared workdir, atomic-replacement contract).
 - `tests/`: transforms, end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic, archive integrity, spine classification), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, and the version pin.
 
 ## Conventions

{bindery_cli-0.30.0 → bindery_cli-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.30.0
+Version: 0.32.0
 Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
 Author: vrnvctss
 License: MIT
@@ -13,7 +13,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Utilities
 Requires-Python: >=3.14
-Requires-Dist: cquarry>=1.9.0
+Requires-Dist: cquarry>=1.17.0
 Requires-Dist: tqdm
 Requires-Dist: vir-tui>=2.2.0
 Provides-Extra: reserialize
@@ -51,14 +51,14 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--reserialize`**: rebuild content documents that are still malformed by re-parsing them with html5lib and re-emitting XHTML, closing unclosed `<p>`/`<div>`/`<span>`/`<blockquote>` that the regex transforms cannot. Runs only on documents that are not already well-formed, so good files are untouched.
 - **`--strip-bad-attrs`**: drop attributes that are invalid XML (a name starting with a digit, or a namespaced name whose prefix is never declared, like Office VML `v:shapes`). Surgical and a no-op on well-formed files.
 - **`--escape-unknown-entities`**: escape entity names that are not in the HTML5 table (`&foo;` becomes `&amp;foo;`), which renders exactly as browsers already render an unknown entity. Documents whose DOCTYPE carries an internal subset are skipped wholesale, since a subset can declare custom entities.
-- **`--fix-id-colons`**: translates illegal colons in `id="X:Y"` and their matching `#X:Y` fragment references to valid underscores.
+- **`--fix-id-colons`**: translates illegal colons in `id="X:Y"` and their matching internal `#X:Y` fragment references to valid underscores. External URL fragments are left verbatim (they name positions in other documents), `data-id` values are never touched, and the NCX's `content src` fragments follow the rename so the table of contents never dangles against the ids it references.
 - **`--fix-empty-body`**: appends a non-breaking space `&nbsp;` to strictly empty body tags to satisfy parser requirements.
 - **`--fix-missing-title`**: injects a `<title>Unknown</title>` fallback in the `<head>` if missing, handling both empty `<title/>` self-closing tags and entirely absent tags.
 - **`--unwrap-block-in-inline`**: safely unwraps `<span>` tags that illegally contain a block-level element (e.g. `<div>` or `<p>`), leaving the block element intact.
 - **`--strip-invalid-value`**: systematically strips invalid `value="..."` attributes from elements like `<div>`, `<span>`, `<p>`, etc.
 - **`--fix-page-map`**: normalizes legacy page-map markup — drops the non-standard `page-map="..."` attribute from the OPF `<spine>` and adds `class="pages"` to classless NCX `<pageList>` elements (epubcheck rejects both on older HarperCollins / Anna's Archive conversions).
-- **`--strip-epub3-attrs`**: scrubs the EPUB3-only attributes epubcheck rejects on an EPUB2 package — `page-progression-direction`, `epub:type`, `aria-label` (a fixed, documented set; rendering is unchanged, and lookalikes like `type` or the wider aria family survive).
-- **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents — `figure`/`section` to `div`, `figcaption` to `p` — keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed.
+- **`--strip-epub3-attrs`**: scrubs the EPUB3-only attributes epubcheck rejects on an EPUB2 package — `page-progression-direction`, `epub:type`, `aria-label` (a fixed, documented set; rendering is unchanged, and lookalikes like `type` or the wider aria family survive). The edit is anchored to real start tags, so prose that merely mentions `epub:type="chapter"` is preserved.
+- **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents — `figure`/`section` to `div`, `figcaption` to `p` — keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed. Both EPUB2-targeted fixes are gated on the package version declared in the OPF: on an EPUB 3 book they do nothing, because their target defects only exist below EPUB 3.
 - **`--unwrap-illegal-tags`**: strips completely invalid or deprecated HTML tags that break EPUB3 validation (`<st>`, `<sentence>`, `<o>`, `<w>`, `<pagebreak>`) while retaining their inner text. Any of those names styled as an *element selector* by an EPUB stylesheet (`.css` entries and inline `<style>` blocks alike; class/id selectors like `.st`/`#w` don't count) is protected for the whole book, guaranteeing format preservation.
 - **`--prune-missing-resources`**: removes references to files the archive does not contain (RSC-007/PKG-010): dead `<link>` elements, anchors' `href` to absent files (anchor text preserved), absent `<img>` sources (replaced by their alt text when they carry one), and orphaned non-spine OPF manifest items. Spine documents are never pruned: a missing spine document is reported as a damaged fragment, not silently dropped.
 - **`--strip-broken-anchors`**: strips href attributes that cannot resolve, keeping the anchor text byte-for-byte: a `#fragment` the target document does not define (RSC-020/RSC-012; NCX navTargets fall back to the document target, so chapter navigation survives) and unresolvable URI schemes (`kindle:`, `file:`).
@@ -67,9 +67,9 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 
 Three opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
 
-- **`--strip-pagination`**: remove print page numbers and running headers that a PDF/OCR conversion baked into the body text as literal paragraphs (so they reflow into the middle of a sentence: "where the hay cart **16** was taking him"). It removes only that injected furniture, never the author's prose: where a number split a sentence it rejoins the two paragraphs (closing up a word split like `compli-` / `mentary`), and it preserves roman chapter numbers, page-list nav anchors, and years. A book is only treated as paginated when it has both a dense run of arabic numbers and several confident mid-sentence interrupts, so a merely chapter-numbered book is left alone. Three safety nets guard every edit (character conservation, tag balance, and an epubcheck no-regression check); any failure leaves the document untouched.
+- **`--strip-pagination`**: remove print page numbers and running headers that a PDF/OCR conversion baked into the body text as literal paragraphs (so they reflow into the middle of a sentence: "where the hay cart **16** was taking him"). It removes only that injected furniture, never the author's prose: where a number split a sentence it rejoins the two paragraphs (closing up a word split like `compli-` / `mentary`), and it preserves roman chapter numbers, page-list nav anchors, and years. A roman numeral counts as a page number only when it is well-formed and under 100, so ordinary words (`mid`, `mix`, `civil`) are never mistaken for pages. A book is only treated as paginated when it has both a dense run of arabic numbers and several confident mid-sentence interrupts, so a merely chapter-numbered book is left alone. Three safety nets guard every edit (character conservation, tag balance, and an epubcheck no-regression check); any failure leaves the document untouched.
 - **`--strip-broken-tags`**: remove leaked HTML closing tags missing their open brackets (e.g. `</p>`) that render as raw text.
-- **`--strip-watermarks`**: remove known producer and distributor watermarks (e.g. OceanofPDF, ABC Amber LIT Converter) and stray marker files. It locates the stamp and deletes the outermost wrapper whose entire visible text is the watermark, ensuring prose that merely mentions the URL is preserved.
+- **`--strip-watermarks`**: remove known producer and distributor watermarks (e.g. OceanofPDF, ABC Amber LIT Converter) and stray marker files. It locates the stamp and deletes the outermost wrapper whose entire visible text is the watermark, ensuring prose that merely mentions the URL is preserved. An inline stamp link is deleted only when it holds nothing but the stamp; a match too large to be safe (an unclosed stamp anchor that swallowed prose) is refused and reported for manual repair rather than deleted.
 
 All lossy edits are invisible to epubcheck, so they are accepted when the result is *no worse* rather than measurably better.
 
@@ -200,7 +200,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--json FILE` writes a machine-readable report of the whole run (per-book status, before/after counts, applied flag, summary totals). `--manual-list FILE` writes the paths of every book that was not auto-repaired, one per line, ready for manual follow-up.
 - `--apply` is required to write; the default is a dry run. `--backup DIR` mirrors originals before replacing; `--backup-inplace` writes `.epub.bak` beside each file.
 - `--install-to-calibre` resolves the Calibre book id from `metadata.db` via cquarry (one read-only path→id map per run), so a hand-renamed `Author/Title (id)/` directory can never send the repaired file to the wrong book. The directory-name regex is only a no-catalog fallback; with neither, the file is saved atomically in place.
-- `--install-to-calibre` installs the repaired EPUB through cquarry's write module: the file is placed atomically at the catalogued path (same filename, Calibre's layout never changes) and the format row is re-registered in one transaction, so the stored size stays truthful and the book lands in `metadata_dirtied` — Calibre regenerates its sidecar .opf on next start. No external `calibredb` call is involved. It falls back to atomic file replacement if the Calibre database ID cannot be resolved, and a database failure degrades to the in-place save with a warning.
+- `--install-to-calibre` installs the repaired EPUB through cquarry's write module: the file is placed atomically at the catalogued path (same filename, Calibre's layout never changes) and the format row is re-registered in one transaction, so the stored size stays truthful and the book lands in `metadata_dirtied` — Calibre regenerates its sidecar .opf on next start. No external `calibredb` call is involved. It falls back to atomic file replacement if the Calibre database ID cannot be resolved, and a database failure degrades to the in-place save with a warning. A directory-name-guessed id is trusted only when `metadata.db` corroborates it (the book exists and the file is that book's catalogued EPUB); an uncatalogued stray file inside a book directory is saved in place and the catalog row is left untouched.
 - `--all` automatically turns on all opt-in non-fatal fixes and lossy strips (pagination, watermarks, bad attributes, unknown entities, image alt tags, etc.) in a single run.
 - Only the `.epub` is replaced. `metadata.opf`, `cover.jpg`, and `metadata.db` are left for Calibre's Quality Check sync to reconcile.
 - A per-book progress line goes to stderr (stdout stays a clean report); `--quiet` suppresses it. A corrupt or unreadable book is reported and skipped, never aborting the sweep.

{bindery_cli-0.30.0 → bindery_cli-0.32.0}/README.md

@@ -29,14 +29,14 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--reserialize`**: rebuild content documents that are still malformed by re-parsing them with html5lib and re-emitting XHTML, closing unclosed `<p>`/`<div>`/`<span>`/`<blockquote>` that the regex transforms cannot. Runs only on documents that are not already well-formed, so good files are untouched.
 - **`--strip-bad-attrs`**: drop attributes that are invalid XML (a name starting with a digit, or a namespaced name whose prefix is never declared, like Office VML `v:shapes`). Surgical and a no-op on well-formed files.
 - **`--escape-unknown-entities`**: escape entity names that are not in the HTML5 table (`&foo;` becomes `&amp;foo;`), which renders exactly as browsers already render an unknown entity. Documents whose DOCTYPE carries an internal subset are skipped wholesale, since a subset can declare custom entities.
-- **`--fix-id-colons`**: translates illegal colons in `id="X:Y"` and their matching `#X:Y` fragment references to valid underscores.
+- **`--fix-id-colons`**: translates illegal colons in `id="X:Y"` and their matching internal `#X:Y` fragment references to valid underscores. External URL fragments are left verbatim (they name positions in other documents), `data-id` values are never touched, and the NCX's `content src` fragments follow the rename so the table of contents never dangles against the ids it references.
 - **`--fix-empty-body`**: appends a non-breaking space `&nbsp;` to strictly empty body tags to satisfy parser requirements.
 - **`--fix-missing-title`**: injects a `<title>Unknown</title>` fallback in the `<head>` if missing, handling both empty `<title/>` self-closing tags and entirely absent tags.
 - **`--unwrap-block-in-inline`**: safely unwraps `<span>` tags that illegally contain a block-level element (e.g. `<div>` or `<p>`), leaving the block element intact.
 - **`--strip-invalid-value`**: systematically strips invalid `value="..."` attributes from elements like `<div>`, `<span>`, `<p>`, etc.
 - **`--fix-page-map`**: normalizes legacy page-map markup — drops the non-standard `page-map="..."` attribute from the OPF `<spine>` and adds `class="pages"` to classless NCX `<pageList>` elements (epubcheck rejects both on older HarperCollins / Anna's Archive conversions).
-- **`--strip-epub3-attrs`**: scrubs the EPUB3-only attributes epubcheck rejects on an EPUB2 package — `page-progression-direction`, `epub:type`, `aria-label` (a fixed, documented set; rendering is unchanged, and lookalikes like `type` or the wider aria family survive).
-- **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents — `figure`/`section` to `div`, `figcaption` to `p` — keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed.
+- **`--strip-epub3-attrs`**: scrubs the EPUB3-only attributes epubcheck rejects on an EPUB2 package — `page-progression-direction`, `epub:type`, `aria-label` (a fixed, documented set; rendering is unchanged, and lookalikes like `type` or the wider aria family survive). The edit is anchored to real start tags, so prose that merely mentions `epub:type="chapter"` is preserved.
+- **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents — `figure`/`section` to `div`, `figcaption` to `p` — keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed. Both EPUB2-targeted fixes are gated on the package version declared in the OPF: on an EPUB 3 book they do nothing, because their target defects only exist below EPUB 3.
 - **`--unwrap-illegal-tags`**: strips completely invalid or deprecated HTML tags that break EPUB3 validation (`<st>`, `<sentence>`, `<o>`, `<w>`, `<pagebreak>`) while retaining their inner text. Any of those names styled as an *element selector* by an EPUB stylesheet (`.css` entries and inline `<style>` blocks alike; class/id selectors like `.st`/`#w` don't count) is protected for the whole book, guaranteeing format preservation.
 - **`--prune-missing-resources`**: removes references to files the archive does not contain (RSC-007/PKG-010): dead `<link>` elements, anchors' `href` to absent files (anchor text preserved), absent `<img>` sources (replaced by their alt text when they carry one), and orphaned non-spine OPF manifest items. Spine documents are never pruned: a missing spine document is reported as a damaged fragment, not silently dropped.
 - **`--strip-broken-anchors`**: strips href attributes that cannot resolve, keeping the anchor text byte-for-byte: a `#fragment` the target document does not define (RSC-020/RSC-012; NCX navTargets fall back to the document target, so chapter navigation survives) and unresolvable URI schemes (`kindle:`, `file:`).
@@ -45,9 +45,9 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 
 Three opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
 
-- **`--strip-pagination`**: remove print page numbers and running headers that a PDF/OCR conversion baked into the body text as literal paragraphs (so they reflow into the middle of a sentence: "where the hay cart **16** was taking him"). It removes only that injected furniture, never the author's prose: where a number split a sentence it rejoins the two paragraphs (closing up a word split like `compli-` / `mentary`), and it preserves roman chapter numbers, page-list nav anchors, and years. A book is only treated as paginated when it has both a dense run of arabic numbers and several confident mid-sentence interrupts, so a merely chapter-numbered book is left alone. Three safety nets guard every edit (character conservation, tag balance, and an epubcheck no-regression check); any failure leaves the document untouched.
+- **`--strip-pagination`**: remove print page numbers and running headers that a PDF/OCR conversion baked into the body text as literal paragraphs (so they reflow into the middle of a sentence: "where the hay cart **16** was taking him"). It removes only that injected furniture, never the author's prose: where a number split a sentence it rejoins the two paragraphs (closing up a word split like `compli-` / `mentary`), and it preserves roman chapter numbers, page-list nav anchors, and years. A roman numeral counts as a page number only when it is well-formed and under 100, so ordinary words (`mid`, `mix`, `civil`) are never mistaken for pages. A book is only treated as paginated when it has both a dense run of arabic numbers and several confident mid-sentence interrupts, so a merely chapter-numbered book is left alone. Three safety nets guard every edit (character conservation, tag balance, and an epubcheck no-regression check); any failure leaves the document untouched.
 - **`--strip-broken-tags`**: remove leaked HTML closing tags missing their open brackets (e.g. `</p>`) that render as raw text.
-- **`--strip-watermarks`**: remove known producer and distributor watermarks (e.g. OceanofPDF, ABC Amber LIT Converter) and stray marker files. It locates the stamp and deletes the outermost wrapper whose entire visible text is the watermark, ensuring prose that merely mentions the URL is preserved.
+- **`--strip-watermarks`**: remove known producer and distributor watermarks (e.g. OceanofPDF, ABC Amber LIT Converter) and stray marker files. It locates the stamp and deletes the outermost wrapper whose entire visible text is the watermark, ensuring prose that merely mentions the URL is preserved. An inline stamp link is deleted only when it holds nothing but the stamp; a match too large to be safe (an unclosed stamp anchor that swallowed prose) is refused and reported for manual repair rather than deleted.
 
 All lossy edits are invisible to epubcheck, so they are accepted when the result is *no worse* rather than measurably better.
 
@@ -178,7 +178,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--json FILE` writes a machine-readable report of the whole run (per-book status, before/after counts, applied flag, summary totals). `--manual-list FILE` writes the paths of every book that was not auto-repaired, one per line, ready for manual follow-up.
 - `--apply` is required to write; the default is a dry run. `--backup DIR` mirrors originals before replacing; `--backup-inplace` writes `.epub.bak` beside each file.
 - `--install-to-calibre` resolves the Calibre book id from `metadata.db` via cquarry (one read-only path→id map per run), so a hand-renamed `Author/Title (id)/` directory can never send the repaired file to the wrong book. The directory-name regex is only a no-catalog fallback; with neither, the file is saved atomically in place.
-- `--install-to-calibre` installs the repaired EPUB through cquarry's write module: the file is placed atomically at the catalogued path (same filename, Calibre's layout never changes) and the format row is re-registered in one transaction, so the stored size stays truthful and the book lands in `metadata_dirtied` — Calibre regenerates its sidecar .opf on next start. No external `calibredb` call is involved. It falls back to atomic file replacement if the Calibre database ID cannot be resolved, and a database failure degrades to the in-place save with a warning.
+- `--install-to-calibre` installs the repaired EPUB through cquarry's write module: the file is placed atomically at the catalogued path (same filename, Calibre's layout never changes) and the format row is re-registered in one transaction, so the stored size stays truthful and the book lands in `metadata_dirtied` — Calibre regenerates its sidecar .opf on next start. No external `calibredb` call is involved. It falls back to atomic file replacement if the Calibre database ID cannot be resolved, and a database failure degrades to the in-place save with a warning. A directory-name-guessed id is trusted only when `metadata.db` corroborates it (the book exists and the file is that book's catalogued EPUB); an uncatalogued stray file inside a book directory is saved in place and the catalog row is left untouched.
 - `--all` automatically turns on all opt-in non-fatal fixes and lossy strips (pagination, watermarks, bad attributes, unknown entities, image alt tags, etc.) in a single run.
 - Only the `.epub` is replaced. `metadata.opf`, `cover.jpg`, and `metadata.db` are left for Calibre's Quality Check sync to reconcile.
 - A per-book progress line goes to stderr (stdout stays a clean report); `--quiet` suppresses it. A corrupt or unreadable book is reported and skipped, never aborting the sweep.

{bindery_cli-0.30.0 → bindery_cli-0.32.0}/patchnotes.md

@@ -1,4 +1,126 @@
 # bindery-cli Patch Notes
+## v0.32.0 (2026-09-10)
+
+### The four Bug Reports fixes (2026-09-08 sweep) and the anchored-attribute cluster
+
+- **`--strip-watermarks` refuses anchored matches larger than the stamp**
+  (the sweep demonstrated two paragraphs of real prose vanishing with
+  count 1). The anchored stamp regex is DOTALL with no tag budget, so an
+  unclosed stamp `<a>` matched through real prose to the next unrelated
+  `</a>`, and the whole-match fallback deleted everything in between;
+  epubcheck cannot see deleted text, so the no-regression bar accepted the
+  loss. The fallback now fires only when the match demonstrably holds
+  nothing but the stamp (a tag-free body within stamp length, or visible
+  text exactly the watermark), a second `<a>` opening inside the match
+  refuses it outright, and anything larger stays in place, counted in the
+  new `RepairReport.watermark_refusals` and surfaced by `run phase1` as a
+  `manual_watermark_repair` decision on both the read-only and apply paths.
+  Safe shapes (pure wrappers, inline stamp-only links) are byte-identical
+  to before.
+- **Roman page-number detection reads well-formed numerals only**, in both
+  `--strip-pagination` and the audit pagenumbers analyzer. The old
+  `[ivxlcdm]{2,7}` character set read ordinary English words as page
+  numbers (`mid` = 1499), and a standalone `<p>mid</p>` before a
+  lowercase-starting paragraph is exactly the confident interrupt shape,
+  so real words were deleted and merged away. A roman counts only when
+  well-formed (explicit subtractive pairs) and valued under 100, where
+  front-matter page numbers live and words do not (`mix` = M+IX = 1009).
+  Lowercase front-matter romans keep working; the audit copy's deliberately
+  different year handling is untouched.
+- **`install_format` verifies directory-guessed ids against metadata.db.**
+  In directory mode, an uncatalogued stray `.epub` inside a book directory
+  made the `(id)` directory guess fire, and the row update re-registered
+  the catalogued format name with the stray file's size: the catalogued
+  999-byte file untouched on disk while `data` recorded 8123 bytes. A
+  stale `(N)` directory for a deleted book crashed the sweep instead. A
+  guessed id now drives a row update only when metadata.db corroborates it
+  (the books row exists, the file sits in that book's own directory, and
+  when an EPUB row exists it carries the row's stored name); anything else
+  saves the repair in place with a warning and leaves the catalog
+  untouched. The resolver path needs no verification: its id comes from
+  the catalog's own path map.
+- **The EPUB2-targeted fixes are gated on the package version.** Neither
+  `--strip-epub3-attrs` nor `--downgrade-epub3-tags` checked what the
+  package declared, so under `--all` every EPUB3 book in a sweep took the
+  EPUB2 cure: a repairable EPUB3 book gained a net-new error from a
+  stripped nav `epub:type` (whole repair rejected), and a legal
+  `epub:type="chapter"` was silently removed because the gate only sees
+  epubcheck counts. Both fixes now fire only on EPUB 2 packages (major
+  version 1 or 2) and are inert on EPUB 3 packages and when no version can
+  be read, where their target defects do not exist.
+- **The anchored-attribute regex cluster closes with the gate** (the same
+  sweep's sharpest repair-pipeline finding): the attribute scrub runs
+  anchored on real start tags through the new
+  `transforms.strip_attrs_in_start_tags`, with CDATA sections and comments
+  protected, so prose mentioning `epub:type="chapter"` is no longer
+  deleted down to `Use here`; `strip_invalid_value` matches its attribute
+  name behind a `(?<![\w:.-])value` lookbehind, so `data-value="42"`
+  survives instead of becoming a malformed `<span  data->`.
+
+### Repair-pipeline correctness (Phase 14, the 2026-09-08 sweep's backlog)
+
+- **`--fix-id-colons` is consistent and honest.** Only the bare `id`
+  attribute is in scope (a lookbehind keeps `data-id` and `xml:id` values
+  untouched), the fragment of an external URL survives verbatim (it names a
+  position in another document), the NCX's `content src` fragments follow
+  the rename through the new `fix_ncx_src_fragments` so a ToC never dangles
+  against the ids it references, and only actual colons replaced are
+  counted (byte-identical reruns report 0 and no longer trigger the
+  re-encode the untouched-file guard exists to prevent).
+- **The anchor pass runs last.** `strip_broken_anchors`' id snapshot used
+  to predate the unwrap fixes, so an id they deleted still counted as
+  present and fragments pointing at it survived dangling. The anchor pass
+  now runs after every content fix, against a snapshot that replicates
+  each id-moving fix ahead of it.
+- **CDATA sections and comments are protected everywhere.**
+  `strip_broken_tags` and `unwrap_illegal_tags` joined the module's
+  protected-span machinery (the wrapper now forwards arguments, so the
+  protected_tags-carrying unwrap could be decorated); a leaked-looking tag
+  inside either is literal rendered text, not markup.
+- **Non-UTF-8 documents are skipped verbatim.** A fix firing on a
+  windows-1252 or UTF-16 document used to decode with U+FFFD substitutes
+  and re-encode UTF-8 under a declaration still naming the old encoding:
+  usually well-formed, so the gate could not see the corruption. The write
+  loop strict-decodes first; failures are copied byte-for-byte, counted in
+  the new `non_utf8_docs_skipped` entry, and left for manual repair.
+- **`--reserialize` requires an html root.** A broken non-HTML `.xml`
+  sidecar used to come back html/body-wrapped with `ns0:` prefixes,
+  structurally rewritten while staying well-formed; it is now returned
+  untouched.
+- **Seven papercuts.** `fix_ncx_playorder` is anchored to `<navPoint>`
+  start tags (nav-label text is untouchable); mimetype fixes increment
+  `files_changed`; `fix_manifest_ids` and its reference rewrites are
+  quote-agnostic (a single-quoting OPF used to be a silent count-0 no-op;
+  the two shadowed `_IDREF_ATTR_RE` definitions collapsed into one);
+  the css selector boundary recognizes `svg|st`, `:is(st, w)`, and
+  `:where(...)` forms and the stylesheet scan collects `.xpgt` page
+  templates, so styled tags keep their unwrap protection; watermark
+  normalization decodes entities (`OceanofPDF.com&nbsp;` stamps now
+  match); the prolog and duplicate-xmlns fixes run under the
+  protected-span wrapper; and the archive comment field rides the rewrite.
+
+Dry-run validation for this release: the 14 staged top500candidates plus
+the 3 books_to_fix fixtures swept clean (9 accepted, 2 gate-refused
+regressions, 0 errors), and a 200-candidate sample of the real library
+(5,228 EPUBs) under `--all --workers 4` matched the documented verdict
+mix (94 accepted, 84 equal, 16 gate-refused, 0 partial, 0 epubcheck
+errors, 0 unreadable) with zero crashes. Read-only throughout; the
+gate-refused books are the safety contract declining marginal repairs,
+left untouched for manual work.
+
+## v0.31.0 (2026-09-09)
+
+### Cascade: install through cquarry 1.17's set_format
+
+- **`--install-to-calibre` replaces the format row through
+  `WritableCalibreDB.set_format`** (cquarry 1.17's sanctioned remove+add
+  in one transaction) instead of composing `remove_format` + `add_format`
+  in a `batch()` by hand. Same contract as before: same `data.name`,
+  truthful size, OPF-resync queue, and a database failure still degrades
+  to the in-place save with a warning. The cquarry floor moves from
+  >=1.9.0 to **>=1.17.0** (`uv.lock` re-resolved), and the failure-mode
+  test now injects through `set_format`.
+
 ## v0.30.0 (2026-09-06)
 
 ### Phase 8 stretch: concurrent sweep workers

{bindery_cli-0.30.0 → bindery_cli-0.32.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.30.0"
+version = "0.32.0"
 description = "Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library."
 readme = "README.md"
 classifiers = [
@@ -27,7 +27,7 @@ authors = [
 dependencies = [
   "tqdm",
   "vir-tui>=2.2.0",
-  "cquarry>=1.9.0",
+  "cquarry>=1.17.0",
 ]
 
 [project.optional-dependencies]