bindery-cli 0.27.0__tar.gz → 0.28.0__tar.gz

{bindery_cli-0.27.0 → bindery_cli-0.28.0}/.gitignore

@@ -10,3 +10,7 @@ dist/
 # Ignore actual books used for testing to prevent IP leaks
 testing_facility/books_to_fix/*
 !testing_facility/books_to_fix/.gitkeep
+testing_facility/top500candidates/*.epub
+
+# Compiled Java scratch (FastSweep harness)
+*.class

{bindery_cli-0.27.0 → bindery_cli-0.28.0}/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md (Bindery)
+# CLAUDE.md (bindery-cli)
 
 Per-project guidance. Overrides the global file where they conflict.
 
@@ -28,7 +28,8 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
   visible content. Two kinds of exceptions exist, both opt-in and off unless requested:
   * **Structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
     `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
-    `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`;
+    `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
+    `--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`;
     transforms.py, threaded through epub.py): they alter markup structure or fabricate
     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

{bindery_cli-0.27.0 → bindery_cli-0.28.0}/PKG-INFO

@@ -1,11 +1,17 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.27.0
+Version: 0.28.0
 Summary: High-speed EPUB repair surgeon with a persistent Java validation daemon, safe HTML unwrapping, and native Calibre integration.
 Author: vrnvctss
 License: MIT
 License-File: LICENSE
 Keywords: calibre,ebook,epub,epubcheck,html-repair,repair,watermarks
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+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: tqdm
@@ -15,18 +21,18 @@ Requires-Dist: html5lib>=1.1; extra == 'reserialize'
 Description-Content-Type: text/markdown
 
 <div align="center">
-  <img src="logo.svg" width="96" height="96" alt="Bindery logo"/>
-  <h1>Bindery</h1>
+  <img src="logo.svg" width="96" height="96" alt="bindery-cli logo"/>
+  <h1>bindery-cli</h1>
   <p>Audit EPUB body text and repair broken EPUBs with safe, deterministic fixes, validated by epubcheck, with optional in-place replacement in a Calibre library.</p>
 </div>
 
 <p align="center">
-  <img src="docs/screenshots/library-sweep.png" alt="Bindery's dry-run library sweep: per-book epubcheck results and a summary table ending in 'no files written'">
+  <img src="docs/screenshots/library-sweep.png" alt="bindery-cli's dry-run library sweep: per-book epubcheck results and a summary table ending in 'no files written'">
 </p>
 
 ## What it fixes
 
-Bindery makes accidentally broken markup well-formed again. It does not rewrite or reflow content. The **default pass** applies only a small set of deterministic, semantics-preserving well-formedness fixes that real-world EPUBs (especially Calibre conversions) trip over — nothing else changes without an explicit flag:
+bindery-cli makes accidentally broken markup well-formed again. It does not rewrite or reflow content. The **default pass** applies only a small set of deterministic, semantics-preserving well-formedness fixes that real-world EPUBs (especially Calibre conversions) trip over — nothing else changes without an explicit flag:
 
 - **Unclosed void elements** (`<link>`, `<br>`, `<img>`, ...) get self-closed.
 - **Undeclared named entities** (`&nbsp;`, `&deg;`, `&eacute;`, ...) become numeric character references that every XML parser understands.
@@ -54,6 +60,9 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--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.
 - **`--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:`).
+- **`--encode-url-spaces`**: percent-encodes raw spaces in `src`/`href` attribute values across the package (OPF manifest, NCX, content documents). A URL with a literal space is not a valid URL (RSC-020) and unresolvable on strict readers; the encoded form denotes the same file.
 
 
 Three opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
@@ -77,7 +86,7 @@ The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-water
 
 ## Install
 
-Python 3.14+, plus epubcheck on `PATH` for the gate. Dependencies: `tqdm` for progress output, plus the pinned VirInvictus libraries `vir-tui` (TUI rendering) and `cquarry` (read-only Calibre database access); `html5lib` remains an optional extra, needed only for `--reserialize`.
+Python 3.14+, plus epubcheck on `PATH` for the gate. Dependencies: `tqdm` for progress output, plus the VirInvictus libraries `vir-tui` (TUI rendering) and `cquarry` (read-only Calibre database access); `html5lib` remains an optional extra, needed only for `--reserialize`.
 
 ```sh
 uv tool install bindery-cli                            # core tools
@@ -93,7 +102,7 @@ The sections below take each in turn.
 
 ## Auditing
 
-Bindery includes a comprehensive auditing tool to inspect EPUB body text for non-schema flaws that epubcheck cannot catch. It extracts and analyzes the visible text to detect content issues, producing console reports that can be used to filter your library or feed into `bindery repair`.
+bindery-cli includes a comprehensive auditing tool to inspect EPUB body text for non-schema flaws that epubcheck cannot catch. It extracts and analyzes the visible text to detect content issues, producing console reports that can be used to filter your library or feed into `bindery repair`.
 
 Scan a Calibre library for specific issues:
 
@@ -178,7 +187,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--only {fatals,ncx,all}` restricts the candidate set. `ncx` targets NCX-001 mismatches (detected without epubcheck); `fatals` needs `--audit`.
 - `--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 launches a transparent, persistent Java daemon (`EpubcheckDaemon`) to evaluate candidates in the background, eliminating the JVM startup penalty. This reduces validation time from ~5 seconds per book down to ~0.05 seconds, allowing `--sweep` to scan a 5,000-book library in just 10 minutes. Combine with `--only fatals` for a self-contained, lightning-fast "find and fix the broken books" run.
+- `--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 launches a transparent, persistent Java daemon (`EpubcheckDaemon`) to evaluate candidates in the background, eliminating the JVM startup penalty. This reduces validation time from ~5 seconds per book down to ~0.05 seconds, allowing `--sweep` to scan a 5,000-book library in just 10 minutes. Combine with `--only fatals` for a self-contained, lightning-fast "find and fix the broken books" run.
 - `--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.
@@ -191,9 +200,10 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 
 ## Companion scripts
 
-`scripts/` holds standalone, read-only utilities that are useful for EPUB maintenance but fall outside Bindery's repair contract (fixing what they find would be a content change, which Bindery makes only via the opt-in `--strip-pagination`):
+`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.
 
 ## Development
 
@@ -209,7 +219,7 @@ MIT. See [LICENSE](LICENSE).
 
 ## Support
 
-If Bindery's useful to you and you'd like to chip in:
+If bindery-cli's useful to you and you'd like to chip in:
 
 - liberapay · [liberapay.com/bdkl](https://liberapay.com/bdkl/)
 - bitcoin

{bindery_cli-0.27.0 → bindery_cli-0.28.0}/README.md

@@ -1,16 +1,16 @@
 <div align="center">
-  <img src="logo.svg" width="96" height="96" alt="Bindery logo"/>
-  <h1>Bindery</h1>
+  <img src="logo.svg" width="96" height="96" alt="bindery-cli logo"/>
+  <h1>bindery-cli</h1>
   <p>Audit EPUB body text and repair broken EPUBs with safe, deterministic fixes, validated by epubcheck, with optional in-place replacement in a Calibre library.</p>
 </div>
 
 <p align="center">
-  <img src="docs/screenshots/library-sweep.png" alt="Bindery's dry-run library sweep: per-book epubcheck results and a summary table ending in 'no files written'">
+  <img src="docs/screenshots/library-sweep.png" alt="bindery-cli's dry-run library sweep: per-book epubcheck results and a summary table ending in 'no files written'">
 </p>
 
 ## What it fixes
 
-Bindery makes accidentally broken markup well-formed again. It does not rewrite or reflow content. The **default pass** applies only a small set of deterministic, semantics-preserving well-formedness fixes that real-world EPUBs (especially Calibre conversions) trip over — nothing else changes without an explicit flag:
+bindery-cli makes accidentally broken markup well-formed again. It does not rewrite or reflow content. The **default pass** applies only a small set of deterministic, semantics-preserving well-formedness fixes that real-world EPUBs (especially Calibre conversions) trip over — nothing else changes without an explicit flag:
 
 - **Unclosed void elements** (`<link>`, `<br>`, `<img>`, ...) get self-closed.
 - **Undeclared named entities** (`&nbsp;`, `&deg;`, `&eacute;`, ...) become numeric character references that every XML parser understands.
@@ -38,6 +38,9 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--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.
 - **`--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:`).
+- **`--encode-url-spaces`**: percent-encodes raw spaces in `src`/`href` attribute values across the package (OPF manifest, NCX, content documents). A URL with a literal space is not a valid URL (RSC-020) and unresolvable on strict readers; the encoded form denotes the same file.
 
 
 Three opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
@@ -61,7 +64,7 @@ The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-water
 
 ## Install
 
-Python 3.14+, plus epubcheck on `PATH` for the gate. Dependencies: `tqdm` for progress output, plus the pinned VirInvictus libraries `vir-tui` (TUI rendering) and `cquarry` (read-only Calibre database access); `html5lib` remains an optional extra, needed only for `--reserialize`.
+Python 3.14+, plus epubcheck on `PATH` for the gate. Dependencies: `tqdm` for progress output, plus the VirInvictus libraries `vir-tui` (TUI rendering) and `cquarry` (read-only Calibre database access); `html5lib` remains an optional extra, needed only for `--reserialize`.
 
 ```sh
 uv tool install bindery-cli                            # core tools
@@ -77,7 +80,7 @@ The sections below take each in turn.
 
 ## Auditing
 
-Bindery includes a comprehensive auditing tool to inspect EPUB body text for non-schema flaws that epubcheck cannot catch. It extracts and analyzes the visible text to detect content issues, producing console reports that can be used to filter your library or feed into `bindery repair`.
+bindery-cli includes a comprehensive auditing tool to inspect EPUB body text for non-schema flaws that epubcheck cannot catch. It extracts and analyzes the visible text to detect content issues, producing console reports that can be used to filter your library or feed into `bindery repair`.
 
 Scan a Calibre library for specific issues:
 
@@ -162,7 +165,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--only {fatals,ncx,all}` restricts the candidate set. `ncx` targets NCX-001 mismatches (detected without epubcheck); `fatals` needs `--audit`.
 - `--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 launches a transparent, persistent Java daemon (`EpubcheckDaemon`) to evaluate candidates in the background, eliminating the JVM startup penalty. This reduces validation time from ~5 seconds per book down to ~0.05 seconds, allowing `--sweep` to scan a 5,000-book library in just 10 minutes. Combine with `--only fatals` for a self-contained, lightning-fast "find and fix the broken books" run.
+- `--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 launches a transparent, persistent Java daemon (`EpubcheckDaemon`) to evaluate candidates in the background, eliminating the JVM startup penalty. This reduces validation time from ~5 seconds per book down to ~0.05 seconds, allowing `--sweep` to scan a 5,000-book library in just 10 minutes. Combine with `--only fatals` for a self-contained, lightning-fast "find and fix the broken books" run.
 - `--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.
@@ -175,9 +178,10 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 
 ## Companion scripts
 
-`scripts/` holds standalone, read-only utilities that are useful for EPUB maintenance but fall outside Bindery's repair contract (fixing what they find would be a content change, which Bindery makes only via the opt-in `--strip-pagination`):
+`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.
 
 ## Development
 
@@ -193,7 +197,7 @@ MIT. See [LICENSE](LICENSE).
 
 ## Support
 
-If Bindery's useful to you and you'd like to chip in:
+If bindery-cli's useful to you and you'd like to chip in:
 
 - liberapay · [liberapay.com/bdkl](https://liberapay.com/bdkl/)
 - bitcoin

{bindery_cli-0.27.0 → bindery_cli-0.28.0}/logo.svg

@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128" role="img" aria-label="Bindery logo">
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128" role="img" aria-label="bindery-cli logo">
   <rect width="128" height="128" rx="24" fill="#181616"/>
   <!-- book spine / cover being rebound -->
   <rect x="30" y="26" width="68" height="76" rx="5" fill="none" stroke="#c5c9c5" stroke-width="5"/>

{bindery_cli-0.27.0 → bindery_cli-0.28.0}/patchnotes.md

@@ -1,4 +1,93 @@
-# Bindery Patch Notes
+# bindery-cli Patch Notes
+## v0.28.0 (2026-09-05)
+
+### Phase 12: repairs for the top epubcheck error codes
+
+The 2026-09-05 full-library sweep (`testing_facility/top500candidates/REPORT.md`)
+catalogued the top recurring codes: RSC-005 (164,302), RSC-020 (8,431), PKG-010
+(4,112), RSC-007 (3,219), RSC-012 (1,940), HTM-025 (800). Bulk RSC-005 repair stays
+rejected (the spec non-goal stands); everything else gained a deterministic,
+epubcheck-gated, opt-in repair. The structural-repair set is now twelve; `--all`
+includes all three.
+
+- **`--prune-missing-resources`** (PKG-010/RSC-007) removes references to files the
+  archive does not contain: dead `<link>` elements (`dead_links_pruned`), anchors'
+  href to absent files with the text kept (`missing_file_hrefs_stripped`), absent
+  `<img>` sources replaced by their escaped alt text when they carry one
+  (`missing_imgs_unwrapped`) or dropped when they do not (`missing_imgs_pruned`), and
+  orphaned non-spine OPF manifest items (`manifest_items_pruned`). Spine documents are
+  never pruned: a missing spine document is a damaged fragment for the spine-integrity
+  report, not a pruning candidate.
+- **`--strip-broken-anchors`** (RSC-020/RSC-012, plus the HTM-025 scheme half) strips
+  href attributes that cannot resolve while keeping the anchor text byte-for-byte: a
+  `#fragment` the target document does not define (`broken_fragment_hrefs_stripped`;
+  the anchor keeps its text, NCX navTargets fall back to the document target so
+  chapter navigation survives, and the fragment is never re-pointed at a guessed
+  sibling document), and non-resolvable URI schemes (`nonfile_scheme_hrefs_stripped`;
+  fixed resolvable set: http, https, mailto). NCX counter: `ncx_fragments_stripped`.
+  The id set for fragment checks is built from the documents as they will look when
+  the pass runs (core transforms, `--reserialize`, `--fix-id-colons` applied), so an
+  id rename can never make a valid reference look broken.
+- **`--encode-url-spaces`** (the Death Masks shape: 67 RSC-020 "not a valid URL")
+  percent-encodes raw spaces in src/href attribute values across the package — OPF
+  manifest href, NCX content src, content documents (counter `url_spaces_encoded`).
+  Scope is fixed to the space character; archive entry names are untouched.
+- **HTM-025 ampersand half closed by test:** `escape_bare_amp` always covered
+  attribute values (transforms run on raw text); the URL-attribute case is now pinned
+  by an explicit test instead of an assumption.
+
+Fixture validation (all /tmp copies, gate-accepted, zero regressions):
+
+| Book | Before | After | Fixes |
+|---|---|---|---|
+| Swann's Way | 0f/31e/1w | 0f/2e/0w | dead_links_pruned:29, nonfile_scheme_hrefs_stripped:1 |
+| Sodom and Gomorrah | 0f/53e/0w | 0f/42e/0w | ncx_fragments_stripped:9, broken_fragment_hrefs_stripped:2 |
+| Death Masks | 0f/68e/34w | 0f/1e/34w | url_spaces_encoded:67 |
+
+Every surviving finding is RSC-005 (the non-goal) or the Death Masks entry-name
+warnings (see below). The full label-vs-reality findings postscript lives in
+roadmap.md Phase 12; headline: the staged "PKG-010" book has no missing resources at
+all — its 34 PKG-010s are "file name contains spaces" warnings about the zip entry
+names, which no shipped flag touches. Renaming entries and rewriting every reference
+is a possible future flag.
+
+### FastSweep: parallel JVM sweep harness (scripts/)
+
+- `scripts/FastSweep.java` now merges the audit (CSV `fatals,errors,warnings,path`,
+  the format `bindery library --audit` reads) and extract (`path ||| CODE,...`)
+  prototypes behind `--mode=audit` / `--mode=extract`, keeping the stdin +
+  `parallelStream()` shape.
+- **The prototype's extract mode never worked:** `CheckingReport` buffers every
+  message and writes nothing to its writer until `generate()` — and `generate()`
+  NPEs without a preceding `initialize()`. Every code list in the prototype's
+  `raw_errors*.txt` runs came back empty. The merged harness follows the CLI's own
+  lifecycle (`initialize` → validate → `generate`) and extracts codes from the JSON.
+  The committed REPORT.md's per-book code attributions should be treated as
+  unverified until regenerated with the fixed harness.
+- `scripts/fast_sweep.py` (stdlib-only) is the wrapper: locates the epubcheck jar
+  (`--jar` / `EPUBCHECK_JAR` / parsed from the launcher), compiles the harness once
+  with `--release 25` (cached on mtime), scans a directory or a path list, and
+  `--summary` aggregates extract output into the per-code REPORT-style table.
+  Measured on the 14 staged fixtures: ~4.5 s across all cores vs ~42 s sequential.
+- The audit CSV feeds `bindery library --audit` cleanly (smoke-tested for candidate
+  selection both ways).
+
+### Notes
+
+- epubcheck 5.3.0 surfaces disagree on counts: the human listing prints raw message
+  totals while the `--json` checker block prints deduplicated ones (Swann's Way: 31
+  vs 2 errors). bindery's gate reads the JSON surface consistently for both
+  measurements, so gate decisions are unaffected. FastSweep's audit mode carries the
+  raw CheckingReport counts; that CSV is used for candidate selection only.
+- Related, unchanged on purpose: validate.py's persistent daemon launches
+  `java -cp ".:epubcheck.jar"` without epubcheck's `lib/` dependencies, so it always
+  fails its first check and silently falls back to the subprocess JSON path on this
+  machine. Fixing the classpath would flip gate measurements from deduplicated to
+  raw counts — a gate-behavior change that gets its own decision.
+- Tests 260 → 277: transform units (encoding, protection, idempotency, HTM-025),
+  repair-level opt-in/counter/output tests for all three flags, the structural
+  default-off case list, and the CLI wiring tuples.
+
 ## v0.27.0 (2026-09-02)
 
 ### RSC-005 verdict, part two: --downgrade-epub3-tags
@@ -172,7 +261,7 @@
   directories and case-insensitive matching behave exactly as before. The
   `(123)` directory-name regex remains the documented no-catalog fallback.
   The `audit.py` raw-join swap was waived at the Phase 9 design session (its
-  three targeted joins are cheaper than whole-library hydration and Bindery
+  three targeted joins are cheaper than whole-library hydration and bindery-cli
   wants per-book maps, not row dicts); do not "improve" it into a regression.
 - **Dependency**: requires cquarry ≥ 1.8 (`format_path_index`). The `uv.lock`
   still pins the pre-1.8 `@main` commit until cquarry's 1.8.0 commits are
@@ -206,7 +295,7 @@
 - **Dependency bump (deliberate pin move).** The `vir-tui` pin moved from `d13ad0e` to `e53f17e`
   (vir-tui 2.2.0), per the repo policy of pinning exact commits and bumping deliberately. 2.2.0 is
   additive — `progress_box()`, `interactive_session()`, `prompt_float`/`prompt_path`/`confirm`,
-  `out_note`, `text_mode()`, and results-pager search — and every API Bindery uses (`ui.tqdm`,
+  `out_note`, `text_mode()`, and results-pager search — and every API bindery-cli uses (`ui.tqdm`,
   `ui.info`, `ui.print_header`) is unchanged, so no behavior change is expected; `uv.lock`
   regenerated to match the new pin.
 - **Version sync fix.** `src/bindery/__init__.py` still said `0.18.0` while `pyproject.toml` said
@@ -253,7 +342,7 @@
 - **Tagged books are queued for OPF regeneration.** The pinned cquarry bump (1.1 → 1.2) means every
   `WritableCalibreDB.add_tag()` now records the book id in Calibre's `metadata_dirtied` queue —
   the table upstream consumes to decide which sidecar `.opf`s to regenerate (and re-push to wireless
-  readers) at next startup. Previously a Bindery-applied tag would appear in the GUI but never reach
+  readers) at next startup. Previously a bindery-cli-applied tag would appear in the GUI but never reach
   OPF/wireless sync. Verified end-to-end against a synthetic library: flagged book tagged,
   `metadata_dirtied` gains exactly that id, clean books untouched.
 - **Requires `cquarry` @ e19c24c** (v1.2.0); pin bumped accordingly.
@@ -326,13 +415,13 @@ above the daemon call where it is an actual docstring. Suite: 183 -> 201 tests.
 
 ### Core Upgrades
 
-**Centralized Calibre DB Access:** Bindery has transitioned to the unified `cquarry` library for all read-only `metadata.db` accesses. The internal `bindery.audit` DB connection logic has been completely replaced with `cquarry.db.CalibreDB`. This inherits robust Calibre lock handling, database snapshotting, and ensures query logic stays perfectly synchronized with `CalibreQuarry` and `Hermitage`.
+**Centralized Calibre DB Access:** bindery-cli has transitioned to the unified `cquarry` library for all read-only `metadata.db` accesses. The internal `bindery.audit` DB connection logic has been completely replaced with `cquarry.db.CalibreDB`. This inherits robust Calibre lock handling, database snapshotting, and ensures query logic stays perfectly synchronized with `CalibreQuarry` and `Hermitage`.
 
 
 ## v0.15.0 (2026-08-23)
 
 ### Features
-- **Integrated EPUB Auditing (`bindery audit`):** Successfully absorbed the external `audit_epub` codebase directly into Bindery as a native subcommand. This transforms Bindery from a pure repair tool into a complete EPUB lifecycle toolkit (Audit -> Repair -> Validate). 
+- **Integrated EPUB Auditing (`bindery audit`):** Successfully absorbed the external `audit_epub` codebase directly into bindery-cli as a native subcommand. This transforms bindery-cli from a pure repair tool into a complete EPUB lifecycle toolkit (Audit -> Repair -> Validate). 
   - **`content`:** Identifies non-English text by sniffing the text blocks, reporting the predominant script block (e.g., Cyrillic, CJK) to catch untranslated or mis-encoded EPUBs.
   - **`pagenumbers`:** Detects books polluted with hardcoded print page numbers (using sliding window regex to find high-density sequential digits interrupting prose), seamlessly bridging into `bindery repair --strip-pagination` for the fix.
   - **`emptytext`:** Audits EPUBs to find effectively empty books or spine stubs (below configurable `--min-chars` and `--thin-chars` thresholds).
@@ -355,7 +444,7 @@ above the daemon call where it is an actual docstring. Suite: 183 -> 201 tests.
 ## v0.13.0 (2026-08-22)
 
 ### Structural Changes
-- **Epubcheck Daemon:** Radically accelerated the `bindery library` validation gate by implementing a transparent, persistent Java daemon. Bindery now automatically compiles `FastDaemon.java` in the background and pipes EPUB paths to it, eliminating the JVM startup penalty.
+- **Epubcheck Daemon:** Radically accelerated the `bindery library` validation gate by implementing a transparent, persistent Java daemon. bindery-cli now automatically compiles `FastDaemon.java` in the background and pipes EPUB paths to it, eliminating the JVM startup penalty.
 - Validation time dropped from ~5 seconds per book down to under ~0.05 seconds per book, cutting library sweeps from 6 hours to 10 minutes.
 
 ## v0.12.3 (2026-08-22)
@@ -378,10 +467,10 @@ above the daemon call where it is an actual docstring. Suite: 183 -> 201 tests.
 ## v0.12.0 (2026-08-22)
 
 ### Features
-- **Oceanstrip Merged:** Fully incorporated the `oceanstrip` standalone tool directly into Bindery's primary pipeline.
+- **Oceanstrip Merged:** Fully incorporated the `oceanstrip` standalone tool directly into bindery-cli's primary pipeline.
 - Added `--strip-watermarks` flag to systematically detect and remove producer/distributor watermarks (e.g. OceanofPDF stamps and zero-byte marker files, ABC Amber LIT Converter injections) from EPUBs.
 - This lossy transform is correctly governed by the `validate.no_worse` EPUBCheck oracle, ensuring clean structural extraction without regressing file validity.
-- The `--strip-watermarks` argument is automatically engaged when running Bindery with `--all`.
+- The `--strip-watermarks` argument is automatically engaged when running bindery-cli with `--all`.
 
 ## v0.11.0 (2026-08-21)
 
@@ -493,7 +582,7 @@ that the correct hook does not create.
 
 Two constraints recorded with the decision, because they shape what the plugin can
 be: it runs inside Calibre's bundled Python, so it must vendor its own code and
-cannot assume Bindery is installed (the minimal-dependency rule is what makes this
+cannot assume bindery-cli is installed (the minimal-dependency rule is what makes this
 practical, and the optional `html5lib` path cannot come along); and epubcheck
 cannot gate an import, being an external Java process of seconds per book, so the
 plugin does the deterministic transforms and leaves gated work to the CLI where a
@@ -643,7 +732,7 @@ round of CLI hardening and UX. Every fix ships with a unittest regression test.
 
 ## v0.5.0 (2026-06-14)
 
-**New: `--strip-pagination` (opt-in, lossy).** Removes print page numbers and running headers that a PDF/OCR conversion baked into the body text as literal paragraphs, which reflow into the middle of sentences ("where the hay cart 16 was taking him"). This is the first mode that removes visible content, so it is a deliberate, fenced-off exception to Bindery's semantics-preserving rule: off by default, and accepted by a new `no_worse` bar (no net-new fatals or errors) instead of the improvement-demanding `gate`, because a baked page number is valid markup that epubcheck cannot see.
+**New: `--strip-pagination` (opt-in, lossy).** Removes print page numbers and running headers that a PDF/OCR conversion baked into the body text as literal paragraphs, which reflow into the middle of sentences ("where the hay cart 16 was taking him"). This is the first mode that removes visible content, so it is a deliberate, fenced-off exception to bindery-cli's semantics-preserving rule: off by default, and accepted by a new `no_worse` bar (no net-new fatals or errors) instead of the improvement-demanding `gate`, because a baked page number is valid markup that epubcheck cannot see.
 
 - Removes only 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`); page-list `id` anchors are hoisted into the merged paragraph so navigation still resolves.
 - A book is treated as paginated only when it has both a dense run of standalone arabic numbers (>= 20) and several confident mid-sentence interrupts (>= 3), so a merely chapter-numbered book is never touched. Roman chapter/front-matter numerals and year-range values are preserved.

{bindery_cli-0.27.0 → bindery_cli-0.28.0}/pyproject.toml

@@ -4,9 +4,17 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.27.0"
+version = "0.28.0"
 description = "High-speed EPUB repair surgeon with a persistent Java validation daemon, safe HTML unwrapping, and native Calibre integration."
 readme = "README.md"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+]
 requires-python = ">=3.14"
 keywords = ["epub", "epubcheck", "calibre", "repair", "ebook", "html-repair", "watermarks"]
 license = { text = "MIT" }
@@ -45,3 +53,4 @@ packages = ["src/bindery"]
 # negated expression.
 select = ["E4", "E7", "E9", "F", "I", "UP", "B"]
 
+

{bindery_cli-0.27.0 → bindery_cli-0.28.0}/roadmap.md

@@ -1,4 +1,4 @@
-# Bindery roadmap
+# bindery-cli roadmap
 
 ## Phase 1: deterministic repair engine (shipped, v0.1.0)
 
@@ -303,14 +303,14 @@ enters the library, the user's original on disk is never touched, and no write t
 
 Three consequences worth stating, because they change existing plans:
 
-1. **Bindery's separate "metadata.db nudge" item is unnecessary and is dropped.**
+1. **bindery-cli's separate "metadata.db nudge" item is unnecessary and is dropped.**
    It existed so Calibre would notice a changed file size after an in-place
    replacement. Under `on_import` the file is modified *before* Calibre reads it,
    so the size it records is already correct. The nudge was solving a problem
    created by replacing files behind Calibre's back.
 2. **The plugin must carry its own code.** It runs inside Calibre's bundled
    Python, which will not have either tool pip-installed. Both being minimal-dependency
-   is what makes this practical: the module vendors into the plugin zip. Bindery's
+   is what makes this practical: the module vendors into the plugin zip. bindery-cli's
    optional `html5lib` path and its epubcheck gate cannot come along, so the
    plugin must degrade honestly rather than half-run.
 3. **epubcheck cannot gate the import.** It is an external Java process taking
@@ -339,10 +339,10 @@ never wrote — exactly the class of fix that must stay opt-in under the safety
 
 ## Phase 4: cquarry Integration (complete 2026-08-28, v0.19.0)
 
-With the transition to the `cquarry` shared library (v0.16.0), Bindery inherits the ability to perform complex search and batch resolution natively. As the `cquarry` library adds new write capabilities, Bindery is slated to adopt the following upgrades:
+With the transition to the `cquarry` shared library (v0.16.0), bindery-cli inherits the ability to perform complex search and batch resolution natively. As the `cquarry` library adds new write capabilities, bindery-cli is slated to adopt the following upgrades:
 
 - [x] **Format Path Resolution:** Transition to `cquarry.get_format_path()` to remove manual path concatenations during file discovery. *(done: v0.18.0 for library-mode audits; v0.19.0 finishes the job — `CalibreIdResolver` builds the id→EPUB-path map through `get_format_path()` so `--install-to-calibre` resolves the book id from `metadata.db` instead of the `(id)` directory fragment.)*
-- [x] **Safe Tag Application:** When `cquarry` implements safe DB writes (`add_tag`), Bindery will gain the ability to automatically tag books in the Calibre UI as "Audited" or "Flagged" when issues are found, rather than relying strictly on console output. *(done: v0.18.1 — `audit --tag` applies via `cquarry.write.WritableCalibreDB.add_tag`, OPF-resync queued through `metadata_dirtied`; v0.19.0 extends `--tag` to the new `--id` single-book mode.)*
+- [x] **Safe Tag Application:** When `cquarry` implements safe DB writes (`add_tag`), bindery-cli will gain the ability to automatically tag books in the Calibre UI as "Audited" or "Flagged" when issues are found, rather than relying strictly on console output. *(done: v0.18.1 — `audit --tag` applies via `cquarry.write.WritableCalibreDB.add_tag`, OPF-resync queued through `metadata_dirtied`; v0.19.0 extends `--tag` to the new `--id` single-book mode.)*
 - [x] **Single-Entity Fetching:** Utilize `get_book(book_id)` for faster isolated audits when analyzing a single book, avoiding the overhead of caching the entire library layout. *(done: v0.19.0 — `audit --id BOOK_ID` fetches one row via `get_book()`, resolves the EPUB via `get_format_path()`, and reports the same verdicts as directory mode.)*
 
 ## Phase 6: Code Sweep & Fixes (2026-08-23)
@@ -527,7 +527,7 @@ aside), the sweep's sub-reason split, the flipped CRC test plus
 hand-rolled zipfile sweep.
 
 ### Pending Repair Implementations
-- **Strip Invalid/Deprecated Attributes (RSC-005):** `testing_facility/books_to_fix/Lost Lambs (Madeline Cash) (z-library.sk, 1lib.sk, z-lib.sk).epub` throws `RSC-005` errors for `page-progression-direction` on `<package>`, `epub:type` on `<body>`, `aria-label` outside of allowed namespaces, and unwrapping illegal `<span>` tags. Bindery currently intercepts `<li value="..">` via `--strip-invalid-value`, but needs a broader pass to scrub these specific deprecated HTML5/EPUB3 attributes when targeting EPUB2 compliance, or just to silence strict validation errors. **DECISION 2026-09-02 (Brandon, on the NEW-AUDIT brief): Option B — the attribute scrub ships as its own opt-in flag (v0.26.0), and the element downgrade ships separately with the CSS-protection work (v0.27.0); no per-book flags, no silent tolerance.**
+- **Strip Invalid/Deprecated Attributes (RSC-005):** `testing_facility/books_to_fix/Lost Lambs (Madeline Cash) (z-library.sk, 1lib.sk, z-lib.sk).epub` throws `RSC-005` errors for `page-progression-direction` on `<package>`, `epub:type` on `<body>`, `aria-label` outside of allowed namespaces, and unwrapping illegal `<span>` tags. bindery-cli currently intercepts `<li value="..">` via `--strip-invalid-value`, but needs a broader pass to scrub these specific deprecated HTML5/EPUB3 attributes when targeting EPUB2 compliance, or just to silence strict validation errors. **DECISION 2026-09-02 (Brandon, on the NEW-AUDIT brief): Option B — the attribute scrub ships as its own opt-in flag (v0.26.0), and the element downgrade ships separately with the CSS-protection work (v0.27.0); no per-book flags, no silent tolerance.**
   *(Attribute scrub shipped in v0.26.0 as `--strip-epub3-attrs` (counter
   `epub3_attrs_stripped`): the three named attributes, fixed documented set,
   content docs and the OPF both, lookalikes survive. The illegal `<span>`
@@ -555,7 +555,7 @@ subprocess is gone, so the crash class no longer exists.)*
 
 ## Phase 11: Migrate install-to-calibre to native cquarry API (proposed 2026-08-31)
 
-*Context: `bindery library --install-to-calibre` currently shells out to the external `calibredb add_format` CLI binary. This is fragile (it crashed on 2026-08-31 due to a non-existent `--replace` flag) and bypasses the transaction and trigger-safety guarantees built into the `cquarry` library. Since Bindery already imports `cquarry` for path resolution, it should adopt the native write module.*
+*Context: `bindery library --install-to-calibre` currently shells out to the external `calibredb add_format` CLI binary. This is fragile (it crashed on 2026-08-31 due to a non-existent `--replace` flag) and bypasses the transaction and trigger-safety guarantees built into the `cquarry` library. Since bindery-cli already imports `cquarry` for path resolution, it should adopt the native write module.*
 
 - [x] **Adopt `WritableCalibreDB` for format installation:** Replace the `subprocess.run(["calibredb", ...])` call in `bindery/library.py` with `cquarry.write.WritableCalibreDB.add_format()`. This keeps all database writes safely centralized in `cquarry` and eliminates the dependency on the external Calibre CLI for structural sweeps.
   *(Shipped in v0.24.0 as `install_format()`: the file is placed atomically
@@ -570,3 +570,62 @@ subprocess is gone, so the crash class no longer exists.)*
   degrades the same way rather than losing the repair. `uv.lock` moved to
   cquarry 1.9.0 in the same release, closing NEW-AUDIT Stage 1's pending
   note. Tests 240 → 244.)*
+
+## Phase 12: Top epubcheck error resolution from full-library sweep (proposed 2026-09-05)
+
+*Context: A diagnostic sweep of the full Calibre library on 2026-09-05 (`testing_facility/top500candidates/REPORT.md`) catalogued the top recurring error codes across all candidates: RSC-005 (164,302), RSC-020 (8,431), PKG-010 (4,112), RSC-007 (3,219), RSC-012 (1,940), and HTM-025 (800). Evaluating these against spec.md establishes which are safe to automate deterministically and which must remain rejected under the safety charter.*
+
+- [x] **Opt-in missing resource pruning (`--prune-missing-resources`):**
+  - **PKG-010 (missing package resource):** When the OPF manifest lists an `<item>` whose file is absent from the archive, prune the orphaned declaration. Strictly scoped to non-spine assets (fonts, stylesheets, unused media); missing spine documents remain classified as damaged fragments and are never silently dropped.
+  - **RSC-007 (referenced resource not found):** When content documents reference absent external assets, prune dead `<link rel="stylesheet">` tags and strip `href` attributes from anchors targeting non-existent files. Missing `<img>` elements are pruned or replaced with their `alt` text under character conservation.
+  *(Shipped in v0.28.0. Fixture reality check: Swann's Way, the staged RSC-007 book, carries exactly one defect shape — 29 identical `<link rel="stylesheet" href="../page-template.xpgt">` elements for an Adobe page template the converter never copied in; all 29 prune, zero regression. Death Masks, the staged PKG-010 book, has NO missing resources at all: its 34 PKG-010s are "file name contains spaces" warnings about the zip entry names, not absent files, so nothing is prunable there — see the `--encode-url-spaces` note below. Counters: `manifest_items_pruned`, `dead_links_pruned`, `missing_file_hrefs_stripped`, `missing_imgs_unwrapped`, `missing_imgs_pruned`.)*
+- [x] **Opt-in broken anchor stripping (`--strip-broken-anchors`):**
+  - **RSC-020 (fragment identifier not defined):** When an `href` points to a non-existent `#fragment` target, remove the `href` attribute rather than fabricating an ID. Inner anchor text is preserved byte-for-byte under character conservation.
+  - **RSC-012 (fragment points to wrong element):** For content anchors targeting illegal elements, strip the invalid fragment. For NCX `<content src="doc.xhtml#bad_id"/>` references, strip the fragment to point directly to the containing document, preserving chapter navigation.
+  *(Shipped in v0.28.0. Sodom and Gomorrah, the staged RSC-012 book, is Mobipocket `filepos` drift: the converter re-split the flow and every NCX target points one file late. Per the charter the repair strips the fragment and keeps the document target — it never re-points at the guessed sibling document, because the 9th navPoint's id exists nowhere at all. Fixture run: 9 NCX fragments + 2 in-content Notes anchors stripped, 11 RSC-012 cleared, zero regression. Counters: `broken_fragment_hrefs_stripped`, `nonfile_scheme_hrefs_stripped`, `ncx_fragments_stripped`.)*
+- [x] **URI and entity normalization (HTM-025):**
+  - **Attribute ampersand escaping:** Ensure `transforms.escape_bare_amp` covers bare ampersands inside URL attributes (such as query strings `?a=1&b=2` converted to `?a=1&amp;b=2`).
+  - **Non-registered URI schemes:** Strip unresolvable proprietary or local URI schemes (e.g. `scrivcmt://`, local `file:///` paths) from anchor `href` attributes under `--strip-broken-anchors`, retaining visible prose.
+  *(Shipped in v0.28.0. The ampersand half already worked — the transforms run on raw text, so attribute values were always covered; the behavior is now pinned by an explicit test rather than an assumption. The scheme half ships inside `--strip-broken-anchors` with a fixed resolvable set (http, https, mailto); Swann's Way's single HTM-025 was a `kindle:embed:` anchor href, stripped with the anchor text kept.)*
+- [x] **Fast sweep testing harness (`FastSweep.java` JVM parallelization):**
+  - **Objective:** Integrate parallel JVM validation sweeps directly into the testing/benchmarking suite to bypass Python subprocess I/O bottlenecks during massive 7,000+ book dry-runs.
+  - **Context:** Standard `epubcheck` execution in a Python `subprocess.run` loop takes ~3 seconds per book (6.5 hours for the library). The `FastSweepExtract.java` prototype proved that instantiating `com.adobe.epubcheck.api.EpubCheck` directly and routing `CheckingReport` to a `StringWriter` within a Java `parallelStream()` reduces this to minutes by sharing the JVM startup cost and saturating all CPU cores.
+  - **Implementation Details for Future Agents:**
+    1. Expand `scripts/FastSweep.java` (or merge `FastSweepExtract.java` into it) to parse CLI flags (e.g., `--mode=audit`, `--mode=extract`).
+    2. Write an integration wrapper in `bindery-cli` that compiles the Java file (targeting `--release 25`) and invokes it against a provided directory.
+    3. **Test Fixtures:** Use the sample candidate EPUBs pre-staged in `testing_facility/top500candidates/` (which includes confirmed instances of `RSC-005`, `RSC-020`, `PKG-010`, `RSC-007`, `RSC-012`, and `HTM-025`) to verify the Java AST parsing and error-code extraction before running it across the live library.
+  *(Shipped in v0.28.0 as scripts/FastSweep.java + scripts/fast_sweep.py — see patchnotes for the full notes; the prototype's extract mode never actually worked: CheckingReport buffers its messages and writes nothing until generate(), which NPEs without a preceding initialize(); the merged harness follows the CLI's own initialize → validate → generate lifecycle and extracts codes from the JSON. The two prototypes' stdin + parallelStream shape was otherwise kept. Measured on the 14 staged fixtures: 14 books in ~4.5 s (all cores) vs ~3 s/book sequential.)*
+
+### Phase 12 findings postscript (2026-09-05)
+
+The REPORT.md code labels do not describe the actual defects in the staged fixtures;
+the underlying conditions are what the repairs target:
+
+- **Death Masks ("RSC-020 fragment not defined" + "PKG-010 resource missing"):** all 39
+  manifest items exist. The 67 RSC-020s are "not a valid URL" (literal spaces in OPF
+  hrefs and NCX srcs; fixed by `--encode-url-spaces`), and the 34 PKG-010s are
+  "file name contains spaces" WARNINGS about the zip entry names themselves. Clearing
+  those would mean renaming archive entries and rewriting every reference — a viable
+  future flag, deliberately not attempted here. After repair: 0f/1e/34w (the one error
+  is an `<img id="Picture 0">` RSC-005, out of scope).
+- **Swann's Way ("RSC-007 missing resource" + HTM-025):** 29 identical dead Adobe
+  page-template `<link>` elements plus one `kindle:embed:` anchor. After
+  `--prune-missing-resources --strip-broken-anchors`: 0f/2e/0w.
+- **Sodom and Gomorrah (RSC-012):** Mobipocket `filepos` anchors pointing one split
+  file late. After `--strip-broken-anchors`: 0f/42e/0w (the 42 survivors are RSC-005,
+  the declared non-goal).
+- **epubcheck 5.3.0 surfaces disagree on counts:** the human listing reports raw
+  message totals (Swann's Way: 31 errors) while the `--json` checker block reports
+  deduplicated ones (2). bindery's gate reads the JSON surface consistently for both
+  measurements, so gate decisions are unaffected — but audit CSVs produced by
+  FastSweep's audit mode carry the raw CheckingReport counts, which are larger than
+  the JSON surface the gate re-measures with. Candidate selection only (fatals > 0,
+  clean-book skipping), so the mixing is safe today.
+- Related discovery, unchanged on purpose: `validate.py`'s persistent daemon launches
+  `java -cp ".:epubcheck.jar"` without epubcheck's `lib/` dependencies, so on this
+  machine it has always failed its first check and silently fallen back to the
+  subprocess JSON path. Fixing the classpath would switch gate measurements from the
+  deduplicated JSON counts to raw CheckingReport counts — a behavior change to the
+  gate that deserves its own decision, not a drive-by edit.
+
+Non-goals: No bulk repair of RSC-005 schema/content-model violations. With 164,302 instances, arbitrary schema repair violates the explicit non-goal in spec.md ("Fixing RSC-005 schema/content-model violations in bulk"). Restructuring arbitrary markup requires semantic human judgment; attempting to automate it risks silent content corruption, tag swallowing, or destroying valid styling. Specific, narrowly bounded RSC-005 sub-cases remain opt-in under their own flags (`--strip-epub3-attrs`, `--downgrade-epub3-tags`, `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`, `--add-img-alt`, `--fix-id-colons`); arbitrary bulk repair is rejected. No spine-item manifest pruning (missing spine documents indicate corrupt archives or broken fragments, not safe pruning candidates). No text deletion in anchor unwrapping (character conservation is absolute).