bindery-cli 0.31.0__tar.gz → 0.33.0__tar.gz

{bindery_cli-0.31.0 → bindery_cli-0.33.0}/.gitignore

@@ -12,6 +12,11 @@ testing_facility/books_to_fix/*
 !testing_facility/books_to_fix/.gitkeep
 testing_facility/top500candidates/*.epub
 
+# test_facility EPUBs stopped being tracked in v0.33.0 (forward-only; 9 of
+# the 10 books are commercial and one untracked leak on a public repo is
+# one too many). Files stay on disk, out of git.
+test_facility/*.epub
+
 # Compiled Java scratch (FastSweep harness)
 *.class
 

{bindery_cli-0.31.0 → bindery_cli-0.33.0}/CLAUDE.md

@@ -34,14 +34,29 @@ 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.
+  instead. A fourth, smaller group sits beside the structural repairs and lossy strips:
+  the safe opt-ins (`--fix-ids`, `--add-img-alt`, `--strip-bad-attrs`,
+  `--escape-unknown-entities`) plus `--encode-url-spaces`, which repair without
+  altering visible markup; the "twelve structural repairs and three lossy strips"
+  phrasing elsewhere in these docs was never the complete inventory.
 - **The gate is the safety contract.** Never apply a repair epubcheck has not accepted.
   Respect the two-mode logic in `validate.gate` (fatal-fixing tolerates error unmasking;
   error-cleanup does not). The lossy strips (`--strip-pagination`, `--strip-broken-tags`,
@@ -58,14 +73,14 @@ 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/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.
 

{bindery_cli-0.31.0 → bindery_cli-0.33.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.31.0
+Version: 0.33.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
@@ -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.
 
@@ -82,6 +82,8 @@ Every repair is gated by [epubcheck](https://github.com/w3c/epubcheck). The acce
 
 Introducing a net-new fatal is always rejected. If epubcheck itself fails to run (crash, timeout, unparsable output), the book is reported as an error and never applied; only an explicit `--no-validate` skips the gate. Originals are never modified except by an explicit, atomic in-place replace (see below), and even then only after the gate accepts the result.
 
+Under the hood, the oracle can run two ways: the usual `epubcheck --json -` subprocess, or a small in-process daemon that compiles `FastDaemon.java` into a temp directory at runtime and drives a warm JVM over a pipe. The daemon is a pool bounded by `--workers` (serial runs use one), its every roundtrip is bounded by the caller's timeout, and any failure tears it down and falls back to the subprocess for good — the two paths must never disagree about a book, and the subprocess oracle is the fallback by design. The daemon is also the scariest under-tested code in the repo and depends on a matched javac/java pair; its status is recorded in the roadmap's Phase 12 postscript and Phase 14 backlog.
+
 The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-watermarks`) are the exception to the "must improve" rule. Since they remove visible markup rather than correcting XML schema violations, epubcheck counts often remain unchanged. They are accepted when the result is **no worse** (no net-new fatals or errors), relying on strict programmatic safety nets instead.
 
 ## Install
@@ -192,19 +194,22 @@ Apply all safe and lossy repairs directly into the Calibre database natively:
 bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-calibre
 ```
 
-- `--only {fatals,ncx,all}` restricts the candidate set. `ncx` targets NCX-001 mismatches (detected without epubcheck); `fatals` needs `--audit`.
+- `--only {fatals,ncx,all}` restricts the candidate set. `ncx` targets NCX-001 mismatches (detected without epubcheck); `fatals` needs `--audit` or `--sweep`.
 - `--id <ids>` limits the sweep to a comma-separated list of Calibre book IDs, skipping the full library walk.
 - `--audit CSV` (the `fatals,errors,warnings,path` format produced by an epubcheck sweep) skips clean books so a run is fast. Paths are resolved on both sides, and a CSV that matches nothing triggers a loud warning instead of silently selecting zero books.
-- `--sweep` replaces the CSV step entirely: it runs a live epubcheck sweep for candidate selection and reuses each result as that book's before-measurement, so no book is checked twice. bindery-cli first tries a persistent Java daemon (`EpubcheckDaemon`) to eliminate the per-book JVM startup; in practice the daemon cannot boot on most installs (its classpath carries only epubcheck's launcher jar, not the `lib/` dependencies epubcheck itself puts on the classpath), and the run silently falls back to the standard per-book epubcheck subprocess at the usual seconds per book. Budget accordingly. Fixing the classpath is a recorded decision (it would also change the counts the gate measures), not a shipped behavior. Combine with `--only fatals` for a self-contained "find and fix the broken books" run.
+- `--limit N` processes at most N candidates and stops opening archives after them (lazy within one worker window). A value below 1 is a usage error.
+- `--min-chars N` and `--thin-chars N` are the audit's EMPTY and THIN body-text thresholds (defaults 2000 and 20000); `--min-chars` above `--thin-chars` is a usage error. `--max-doc-chars N` is the audit monolithic-document flag threshold (default 300,000).
+- `--sweep` replaces the CSV step entirely: it runs a live epubcheck sweep for candidate selection and reuses each result as that book's before-measurement, so no book is checked twice. bindery-cli may serve checks from a small persistent Java daemon (see the gate section above for how it is bounded and how it fails safe); wherever the daemon cannot serve, the run falls back to the standard per-book epubcheck subprocess at the usual seconds per book. Combine with `--only fatals` for a self-contained "find and fix the broken books" run.
 - `--workers N` runs the sweep's candidate pass through N concurrent epubcheck workers (default 1: serial, unchanged). The subprocess releases the GIL, so threads parallelize the oracle honestly; books are checked in windows of N consumed in order, so the candidate set matches the serial sweep and `--limit` stays lazy within one window of overshoot. The repair phase stays serial: that is where the shared workdir and the atomic-replacement contract live.
 - `--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.
-- Exit codes: 0 for a clean sweep, 1 for a usage error, 2 when any book was rejected, unreadable, or failed epubcheck (for scripts and cron).
+- Exit codes: 0 for a clean sweep, 1 for a usage error, 2 when any book was rejected, unreadable, or failed epubcheck (for scripts and cron). Note that argparse-level misuse (an unknown flag or a malformed argument) exits with 2 before any validation runs; the tool's own usage validations exit 1.
+- A `partial` book (improved but still unable to open) is reported for manual follow-up and does not fail a `library` run; `run phase1` counts it as trouble and exits 2.
 - `repair` refuses to overwrite an existing output file unless `--force` is given.
 
 ## Run slices
@@ -246,15 +251,22 @@ cd ~/docs/Calibre\ Library && bindery run phase3 --ids 5071,5072 --json phase3-r
 
 `scripts/` holds standalone, read-only utilities that are useful for EPUB maintenance but fall outside bindery-cli's repair contract (fixing what they find would be a content change, which bindery-cli makes only via the opt-in `--strip-pagination`):
 
-- `find_missing_images.py`: scans a library tree and reports every book whose `<img>` tags point at files that do not exist inside the archive (a common defect in converted EPUBs). Reads the archives in place; nothing is unpacked or written. The library path is set at the bottom of the script.
 - `fast_sweep.py`: compiles and drives `FastSweep.java`, a parallel JVM epubcheck sweep that pays JVM startup once instead of per book (a 7,000-book dry-run sweep drops from hours to minutes). `--mode=audit` emits the `fatals,errors,warnings,path` CSV that `bindery library --audit` reads; `--mode=extract` emits per-book error codes for aggregation (`--summary` prints the per-code report). The epubcheck jar is located from the `epubcheck` launcher or `EPUBCHECK_JAR`; the harness compiles once (`--release 25`) and is cached on mtime.
 
+The older `find_*.py` detection wedges and the `sweep.sh`/`FastSweepExtract.java` prototypes were removed: every detection they performed is now a shipped, tested flag (missing images are `--prune-missing-resources`, and the rest of the RSC-005/PKG-010 family shipped through Phases 6-12), and keeping two copies meant future behavior changes landed in only one of them. Git history preserves them.
+
 ## Development
 
 ```sh
-./run_tests.sh        # unittest suite
+./run_tests.sh        # ruff (CI's pin) + unittest suite
 ```
 
+The suite builds its own synthetic EPUBs in temporary directories. `testing_facility/`
+holds staged real-book copies for manual dry runs (gitignored); `test_facility/` holds
+loose local books that stay on disk but out of git (untracked since v0.33.0,
+forward-only, because 9 of the 10 are commercial and one untracked leak on a public
+repo is one too many).
+
 See [spec.md](spec.md) for the full contract and [roadmap.md](roadmap.md) for what is planned.
 
 ## License

{bindery_cli-0.31.0 → bindery_cli-0.33.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.
 
@@ -60,6 +60,8 @@ Every repair is gated by [epubcheck](https://github.com/w3c/epubcheck). The acce
 
 Introducing a net-new fatal is always rejected. If epubcheck itself fails to run (crash, timeout, unparsable output), the book is reported as an error and never applied; only an explicit `--no-validate` skips the gate. Originals are never modified except by an explicit, atomic in-place replace (see below), and even then only after the gate accepts the result.
 
+Under the hood, the oracle can run two ways: the usual `epubcheck --json -` subprocess, or a small in-process daemon that compiles `FastDaemon.java` into a temp directory at runtime and drives a warm JVM over a pipe. The daemon is a pool bounded by `--workers` (serial runs use one), its every roundtrip is bounded by the caller's timeout, and any failure tears it down and falls back to the subprocess for good — the two paths must never disagree about a book, and the subprocess oracle is the fallback by design. The daemon is also the scariest under-tested code in the repo and depends on a matched javac/java pair; its status is recorded in the roadmap's Phase 12 postscript and Phase 14 backlog.
+
 The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-watermarks`) are the exception to the "must improve" rule. Since they remove visible markup rather than correcting XML schema violations, epubcheck counts often remain unchanged. They are accepted when the result is **no worse** (no net-new fatals or errors), relying on strict programmatic safety nets instead.
 
 ## Install
@@ -170,19 +172,22 @@ Apply all safe and lossy repairs directly into the Calibre database natively:
 bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-calibre
 ```
 
-- `--only {fatals,ncx,all}` restricts the candidate set. `ncx` targets NCX-001 mismatches (detected without epubcheck); `fatals` needs `--audit`.
+- `--only {fatals,ncx,all}` restricts the candidate set. `ncx` targets NCX-001 mismatches (detected without epubcheck); `fatals` needs `--audit` or `--sweep`.
 - `--id <ids>` limits the sweep to a comma-separated list of Calibre book IDs, skipping the full library walk.
 - `--audit CSV` (the `fatals,errors,warnings,path` format produced by an epubcheck sweep) skips clean books so a run is fast. Paths are resolved on both sides, and a CSV that matches nothing triggers a loud warning instead of silently selecting zero books.
-- `--sweep` replaces the CSV step entirely: it runs a live epubcheck sweep for candidate selection and reuses each result as that book's before-measurement, so no book is checked twice. bindery-cli first tries a persistent Java daemon (`EpubcheckDaemon`) to eliminate the per-book JVM startup; in practice the daemon cannot boot on most installs (its classpath carries only epubcheck's launcher jar, not the `lib/` dependencies epubcheck itself puts on the classpath), and the run silently falls back to the standard per-book epubcheck subprocess at the usual seconds per book. Budget accordingly. Fixing the classpath is a recorded decision (it would also change the counts the gate measures), not a shipped behavior. Combine with `--only fatals` for a self-contained "find and fix the broken books" run.
+- `--limit N` processes at most N candidates and stops opening archives after them (lazy within one worker window). A value below 1 is a usage error.
+- `--min-chars N` and `--thin-chars N` are the audit's EMPTY and THIN body-text thresholds (defaults 2000 and 20000); `--min-chars` above `--thin-chars` is a usage error. `--max-doc-chars N` is the audit monolithic-document flag threshold (default 300,000).
+- `--sweep` replaces the CSV step entirely: it runs a live epubcheck sweep for candidate selection and reuses each result as that book's before-measurement, so no book is checked twice. bindery-cli may serve checks from a small persistent Java daemon (see the gate section above for how it is bounded and how it fails safe); wherever the daemon cannot serve, the run falls back to the standard per-book epubcheck subprocess at the usual seconds per book. Combine with `--only fatals` for a self-contained "find and fix the broken books" run.
 - `--workers N` runs the sweep's candidate pass through N concurrent epubcheck workers (default 1: serial, unchanged). The subprocess releases the GIL, so threads parallelize the oracle honestly; books are checked in windows of N consumed in order, so the candidate set matches the serial sweep and `--limit` stays lazy within one window of overshoot. The repair phase stays serial: that is where the shared workdir and the atomic-replacement contract live.
 - `--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.
-- Exit codes: 0 for a clean sweep, 1 for a usage error, 2 when any book was rejected, unreadable, or failed epubcheck (for scripts and cron).
+- Exit codes: 0 for a clean sweep, 1 for a usage error, 2 when any book was rejected, unreadable, or failed epubcheck (for scripts and cron). Note that argparse-level misuse (an unknown flag or a malformed argument) exits with 2 before any validation runs; the tool's own usage validations exit 1.
+- A `partial` book (improved but still unable to open) is reported for manual follow-up and does not fail a `library` run; `run phase1` counts it as trouble and exits 2.
 - `repair` refuses to overwrite an existing output file unless `--force` is given.
 
 ## Run slices
@@ -224,15 +229,22 @@ cd ~/docs/Calibre\ Library && bindery run phase3 --ids 5071,5072 --json phase3-r
 
 `scripts/` holds standalone, read-only utilities that are useful for EPUB maintenance but fall outside bindery-cli's repair contract (fixing what they find would be a content change, which bindery-cli makes only via the opt-in `--strip-pagination`):
 
-- `find_missing_images.py`: scans a library tree and reports every book whose `<img>` tags point at files that do not exist inside the archive (a common defect in converted EPUBs). Reads the archives in place; nothing is unpacked or written. The library path is set at the bottom of the script.
 - `fast_sweep.py`: compiles and drives `FastSweep.java`, a parallel JVM epubcheck sweep that pays JVM startup once instead of per book (a 7,000-book dry-run sweep drops from hours to minutes). `--mode=audit` emits the `fatals,errors,warnings,path` CSV that `bindery library --audit` reads; `--mode=extract` emits per-book error codes for aggregation (`--summary` prints the per-code report). The epubcheck jar is located from the `epubcheck` launcher or `EPUBCHECK_JAR`; the harness compiles once (`--release 25`) and is cached on mtime.
 
+The older `find_*.py` detection wedges and the `sweep.sh`/`FastSweepExtract.java` prototypes were removed: every detection they performed is now a shipped, tested flag (missing images are `--prune-missing-resources`, and the rest of the RSC-005/PKG-010 family shipped through Phases 6-12), and keeping two copies meant future behavior changes landed in only one of them. Git history preserves them.
+
 ## Development
 
 ```sh
-./run_tests.sh        # unittest suite
+./run_tests.sh        # ruff (CI's pin) + unittest suite
 ```
 
+The suite builds its own synthetic EPUBs in temporary directories. `testing_facility/`
+holds staged real-book copies for manual dry runs (gitignored); `test_facility/` holds
+loose local books that stay on disk but out of git (untracked since v0.33.0,
+forward-only, because 9 of the 10 are commercial and one untracked leak on a public
+repo is one too many).
+
 See [spec.md](spec.md) for the full contract and [roadmap.md](roadmap.md) for what is planned.
 
 ## License

{bindery_cli-0.31.0 → bindery_cli-0.33.0}/patchnotes.md

@@ -1,4 +1,210 @@
 # bindery-cli Patch Notes
+## v0.33.0 (2026-09-10)
+
+### Phase 14 hardening: the apply path, the audit, and the safety contract's tests
+
+The rest of the 2026-09-08 audit sweep's backlog, in the same shape as
+v0.32.0: every fix confirmed against current code first, each with its
+regression test.
+
+**Apply-path and oracle safety**
+
+- **A failed write can no longer abort a sweep raw.** The backup,
+  replace, and install calls sat bare in the loop, so an ENOSPC or
+  EACCES partway through a multi-hour run died with a traceback and no
+  record. Failures are now error Outcomes; the summary and JSON always
+  land, and exit 2 says scripts should look.
+- **Backups rotate and stay out of the candidate set.** A second
+  `--apply` used to clobber the first backup (the only copy of the
+  author original); backups now rotate (`book.epub.bak2`, `.bak3`, ...).
+  A `--backup` directory inside the library root is refused (its copies
+  would be swept as candidates on the next run).
+- **`--workers N` parallelism is real.** With epubcheck present, every
+  worker serialized behind the daemon's one pipe. The daemon is now a
+  bounded pool sized by `--workers` (default 1: the old behavior), a
+  busy pool falls back to subprocesses instead of blocking, every
+  roundtrip is bounded by the caller's timeout, and a daemon that dies
+  or wedges is torn down and never retried — one failed attempt exhausts
+  the pool so the sweep degrades to pure subprocess checks instead of
+  respawning a JVM per book. Measured: 8 books, 4 workers, two ~10s
+  waves. The evidence for the recorded daemon-classpath decision grew:
+  this machine's javac (27-ea) and java (25) cannot load each other's
+  classes, so the daemon has never served a count here, and when forced
+  to run its counts diverge from the CLI JSON oracle (243 vs 4 on one
+  book) — enabling it would change gate outcomes.
+- **Smaller apply papercuts:** `--limit < 1` and a missing `--audit`
+  file are usage errors, not tracebacks; the fresh-format install
+  registers the catalogued file's own name instead of `repaired`; and
+  phase1 notes the dry-run `--backup` no-op instead of ignoring it.
+
+**audit.py correctness**
+
+- **ToC accounting reads inside the open zip,** a declared-but-absent
+  nav/NCX no longer poisons `Book.corrupt` (a healthy book with a
+  leftover `toc.ncx` entry is not a damaged archive), NCX `content src`
+  resolves against the NCX's own directory (a nested NCX counted every
+  target absent), and ToC hrefs are entity-decoded before comparison.
+- **Archive and spine verdicts are first-class in library mode.** Their
+  sections were dead code in the library report loop: a CRC-corrupt book
+  printed `emptytext CLEAN` and exited 0 there while directory mode said
+  CORRUPT and exited 1. Both modes now agree.
+- **The record pipeline's edges hold:** a failed `--json` write becomes a
+  trouble exit instead of a post-scan traceback; `--tag` skips
+  expected-foreign content findings; an unresolvable spine itemref is
+  counted into the emptytext detail instead of silently reading EMPTY;
+  DRM-encrypted entries get their own ENCRYPTED verdict
+  ("not repairable, skip") instead of CORRUPT re-source; and
+  part1a/part1b/part2-style spines no longer read as a broken span.
+- **Dead surfaces removed** (a duplicate argparse CLI, an unreachable
+  analyzer, duplicated imports) and directory mode catches uppercase
+  `.EPUB` like the library walk always did.
+- **Seven audit papercuts** closed: the block-stack pop now matches the
+  closing tag, the nav property matches whole tokens (`data-nav` is not
+  the nav), exit 3 is documented, the JSON analyzers list includes the
+  always-on verdicts, the console problem counter counts books like
+  `summary.problems`, `--min-chars` above `--thin-chars` is a usage
+  error, and duplicate archive entries are counted instead of resolving
+  last-wins in silence.
+
+**Tests, hygiene, and docs**
+
+- **Direct tests for the safety contract:** gate()/no_worse() including
+  the error-unmasking branch, the watermark gated-apply path,
+  atomic_replace failure injection (temp cleaned, target untouched,
+  re-raise), `--install-to-calibre` wiring, and library-mode `--tag` end
+  to end through cquarry's write path. Suite grew 342 → 381.
+- **The weak two percent cleaned:** mid-file `__main__` blocks,
+  constant-assertion tests, and module aliases gone; the
+  non-interactive wiring is asserted through the real runner's JSON.
+- **run_tests.sh runs CI's exact ruff pins** before the suite, so the
+  local loop fails where CI fails.
+- **Repo hygiene:** the ten subsumed `scripts/find_*.py` wedges plus
+  `sweep.sh` and `FastSweepExtract.java` are retired (git keeps them);
+  the ten commercial EPUBs in `test_facility/` are untracked
+  (forward-only, files stay on disk) and the dead never-run suite there
+  is deleted.
+- **Docs:** the daemon is admitted to exist (README gate section, spec
+  gate section) with its bounding and fail-safe fallback; README's
+  `--sweep` bullet stopped describing the fixed classpath bug as current;
+  the exit-code contract documents argparse's own exit 2 and the partial
+  book divergence; CLAUDE.md's exception taxonomy names the safe
+  opt-ins group.
+
+**Recorded for Brandon (unchanged, evidence sharpened):** the daemon
+classpath decision, the exit-code-from-partial-books decision (both
+options written into its roadmap box; unifying on "trouble" is the
+recommendation), and the spec.md reconciliation draft (the non-goals
+vs. the shipped opt-ins, ready to apply on a go).
+
+## 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

{bindery_cli-0.31.0 → bindery_cli-0.33.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.31.0"
+version = "0.33.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 = [