bindery-cli 0.49.0__tar.gz → 0.51.0__tar.gz

{bindery_cli-0.49.0 → bindery_cli-0.51.0}/AGENTS.md

@@ -30,7 +30,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
   `xmlns`, bare `&`, named entities, void self-closing), the NCX pipeline, and the
   mimetype fix (added/normalized/first-stored, epub.py's archive rewrite); every core
   fix must render identically to the author's intent: never add, remove, or reorder
-  visible content. The canonical opt-in inventory lives in spec.md: twenty-one structural
+  visible content. The canonical opt-in inventory lives in spec.md: twenty-two structural
   repairs, four lossy strips, four safe opt-ins, plus `--reserialize`.
   * **Structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
     `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
@@ -38,7 +38,8 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
     `--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`,
     `--fix-container`, `--fix-media-types`, `--fix-cover`,
     `--fix-comment-double-hyphen`, `--fix-svg-dup-ids`, `--fix-cdata-terminator`,
-    `--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr`;
+    `--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr`,
+    `--fix-unbound-prefix`;
     transforms.py, threaded through epub.py). The v0.47.0 five (the 2026-10-06
     issue batch): `--fix-svg-dup-ids` renames duplicate glyph ids inside
     standalone `.svg` entries (first keeps its name, references resolve to the
@@ -60,7 +61,15 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
     never percent-encoding (epubcheck decodes references before entry lookup,
     verified against 5.3), ambiguous renames refused per entry (`space_rename_map`),
     accepted under `no_worse` because PKG-010 sits on the warning axis the gate
-    does not measure.
+    does not measure. `--fix-unbound-prefix` (v0.51.0, issue #9, the Calibre
+    embed scar) binds an attribute prefix the OPF never declares inline on the
+    element that uses it (`<dc:identifier id="ID1" ns0:scheme="calibre">`
+    whose `xmlns:ns0` sits on a sibling, out of XML scope; two RSC-016 fatals
+    plus OPF-030): URI evidence is the same prefix declared elsewhere in the
+    document (all declarations must agree) or the OPF namespace for a DC
+    element under an OPF-namespaced package, anything else refuses the whole
+    document; scope-tracked over a comment/CDATA-aware tokenizer, OPF only
+    (content docs have the `--strip-bad-attrs` drop); normal `gate`.
     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
     name that an EPUB stylesheet styles as an element selector (`css_protected_tags`,
@@ -101,7 +110,12 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
   gain IS visible, so a run with no measurable improvement is a noop and nothing is
   applied) except the two whose gains sit on axes epubcheck does not measure:
   `--fix-cover` and `--encode-url-spaces`, accepted under the same `no_worse` bar with
-  the partial rule intact. Changing either bar means re-running the library dry run.
+  the partial rule intact. One masked-axis rule (v0.51.0, issue #9): when the gate
+  answers noop but `report.ncx_uid_synced` fired on a book that started with fatals,
+  `process_book` reclassifies the verdict to `partial` (a fatal package halts the
+  metadata checks, so the dtb:uid comparison never ran in either measurement and the
+  real sync measures as no gain); application behavior is unchanged, since still-fatal
+  books are never applied. Changing either bar means re-running the library dry run.
 - **Library writes are sacred.** Replacement must stay atomic (temp in same dir, then
   `os.replace`), touch only the `.epub`, preserve mode, and be dry-run by default.
   Calibre format installation goes through cquarry's write module (`--install-to-calibre`;
@@ -114,7 +128,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - `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`, `monolithic` since v0.21.0 with `--max-doc-chars N`, and `completeness` since v0.36.0) 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). Since v0.44.0 two more advisory analyzers ride the single pass: `cover` (the EPUB3 `properties~="cover-image"` slice of the ruled hybrid: dangling EPUB2 meta, EPUB3 declaration, cover-file presence) and `tocdrift` (the NCX navMap vs EPUB3 nav toc structural diff, fragments included; audit-only, ToC synthesis out of charter permanently); the loader now exposes the parsed OPF, the NCX text, and the nav HTML on `Book`. Since v0.36.0 the completeness analyzer (Phase 15) reports the phase-1 spot-check per book: spine/prose-doc counts (prose = >= 400 visible chars), first/middle/last prose-doc opening/closing excerpts, trailing-ToC classification (`_trailing_toc`: short link lines dominate, no paragraph-length blocks), and the unreadable fraction. It is ADVISORY by contract (problem always False; ADVISORY on a trailing ToC or unreadable fraction >= 10%), never moves the exit code, and is skipped like emptytext when the archive verdict owns the book. Since v0.38.0 the archive verdict distinguishes font obfuscation from DRM (`OBFUSCATION_ALGOS`: IDPF 2008/embedding + both Adobe URIs; readable obfuscated entries are the benign OBFUSCATED advisory, an unreadable one is CORRUPT, and only non-obfuscation algorithms give ENCRYPTED). Since v0.43.0 untrusted metadata XML is parsed through `_safe_xml_parse` (DOCTYPE/ENTITY declarations refused before xml.etree sees them; the stdlib shape of defusedxml's entity protection) and single entries above `_MAX_ENTRY_BYTES` (32 MB) are refused before decompression; a refused metadata file returns the shell book. Since v0.40.0 the vir-tui console renderer loads through the module-level `_LazyUI` proxy (a plain `import vir_tui as ui` at module level would make 3.12/3.13 installs unimportable now that the stack is marker-gated; LOAD_GLOBAL never consults module `__getattr__`, so a proxy object is the lazy shape that works).
+- `src/bindery/audit.py`: read-only body-text audits (`content`, `pagenumbers`, `emptytext`, `ocr`, `monolithic` since v0.21.0 with `--max-doc-chars N`, and `completeness` since v0.36.0) 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). Since v0.44.0 two more advisory analyzers ride the single pass: `cover` (the EPUB3 `properties~="cover-image"` slice of the ruled hybrid: dangling EPUB2 meta, EPUB3 declaration, cover-file presence) and `tocdrift` (the NCX navMap vs EPUB3 nav toc structural diff, fragments included; audit-only, ToC synthesis out of charter permanently); the loader now exposes the parsed OPF, the NCX text, and the nav HTML on `Book`. Since v0.50.0 a ninth analyzer, `contamination` (issue #8, the judge-and-import class, advisory by contract like completeness/cover/tocdrift, never moves the exit code): foreign-title template stamps (head `<title>` repeats or a volume/book marker with named words in front of it, judged against the OPF's own title/creator/publisher/series with a marker-stripped comparison; a part label whose marker leads never flags), fan-bundle ad signatures (jnovels, kokoro connect, zerobooks, a light-novel plug), and review-paste fingerprints (strong flags alone, weak needs corroboration) in the first five content docs; its corpus is spine PLUS `Book.extra_docs` (the archive's non-spine html, retained by the loader in archive order under a 64 MiB cap, because a broken manifest can leave the junk entirely off the spine: Hothouse). Since v0.50.0 `run_directory`/`run_single` dispatch analyzers through `_dir_dispatch` (one entry per ALL key; the old if/elif chain's `else` ran ocr for cover/tocdrift in those modes since v0.44.0) and `tests/test_contamination.py` pins the map's key set to ALL. Since v0.36.0 the completeness analyzer (Phase 15) reports the phase-1 spot-check per book: spine/prose-doc counts (prose = >= 400 visible chars), first/middle/last prose-doc opening/closing excerpts, trailing-ToC classification (`_trailing_toc`: short link lines dominate, no paragraph-length blocks), and the unreadable fraction. It is ADVISORY by contract (problem always False; ADVISORY on a trailing ToC or unreadable fraction >= 10%), never moves the exit code, and is skipped like emptytext when the archive verdict owns the book. Since v0.38.0 the archive verdict distinguishes font obfuscation from DRM (`OBFUSCATION_ALGOS`: IDPF 2008/embedding + both Adobe URIs; readable obfuscated entries are the benign OBFUSCATED advisory, an unreadable one is CORRUPT, and only non-obfuscation algorithms give ENCRYPTED). Since v0.43.0 untrusted metadata XML is parsed through `_safe_xml_parse` (DOCTYPE/ENTITY declarations refused before xml.etree sees them; the stdlib shape of defusedxml's entity protection) and single entries above `_MAX_ENTRY_BYTES` (32 MB) are refused before decompression; a refused metadata file returns the shell book. Since v0.40.0 the vir-tui console renderer loads through the module-level `_LazyUI` proxy (a plain `import vir_tui as ui` at module level would make 3.12/3.13 installs unimportable now that the stack is marker-gated; LOAD_GLOBAL never consults module `__getattr__`, so a proxy object is the lazy shape that works).
 - `src/bindery/epub.py`: archive rewrite, NCX uid sync, RepairReport, mismatch detection, and the opt-in structural-repair plumbing (including the CSS precondition scan). Since v0.46.0 the opt-in selection is the `RepairFlags` dataclass (one field per flag, all off by default; the all-off instance IS the default pass): `repair_epub(src, dst, flags)` and `process_book(..., flags)` take one object instead of a ~25-kwarg signature, the EPUB2-targeted fixes' version gate swaps in a `dataclasses.replace` copy (never mutating the caller's instance), and the plugin's bare `repair_epub(src, dst)` call constructs exactly the all-off default pass. Since v0.38.0/v0.39.0 (Phase 16): `generate_container` + the `--fix-container` gateway (insert after mimetype when missing, replace in-loop when stale; constant-epoch timestamp keeps bytes deterministic), `prune_dangling_edges` (prune_missing_manifest_items returns the pruned ids and the edges that pointed at them (spine@toc, media-overlay, fallback, EPUB2 cover meta) are rewritten so pruning cannot manufacture the regression the gate rejects), and `fix_manifest_media_types` (extension map + magic-byte confirmation via a `peek` callable over the open source zip; jpg/png/gif only), and `fix_cover_meta` (the ruling's deterministic half: dangling EPUB2 cover meta re-pointed from the guide's cover reference when exactly one manifest item carries that file, removed otherwise; accepted under no_worse like the lossy strips because cover wiring is invisible to epubcheck).
 - `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` (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. Since 2026-09-15 `make_backup` takes the opt-in `--backup-keep N` ring: at most N backup files per book, the author original `.bak` never deleted, newest content at the highest name; default remains an unbounded rotation.
@@ -122,7 +136,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
   custom-rendered and colors itself with the CPython 3.14 argparse theme,
   gated by argparse's own _colorize detection so the levels always agree) and the repair-flag inventory is one table: `_REPAIR_FLAG_TABLE` (dest + one-line short help + long reference text) registers the compact grouped `--help` (argparse argument groups, hand-short usage line) and `--help-repairs` renders the long descriptions (a custom argparse Action, deliberately NOT store_true so the wiring test's selection count ignores it); adding a flag means adding a table row. Since v0.48.0 the metadata.db doors are enforced: `_require_closed_calibre` (pgrep fail-closed, exit 1) guards `audit --tag` and `library --apply --install-to-calibre` (run phase3 transitively), and `--help-json` (a custom argparse Action like --help-repairs, never colored) dumps the per-verb exit contract and the door list; since v0.48.1 the per-verb exit contracts tell the code's truth (repair: 0 probed/written incl. partial / 1 trouble, never 2; audit: 0/1/2 plus 3 for findings+write-failure; library and the run slices: the unified 0/2/1); since v0.49.0 the single-file verb's no-output form is a probe (the gate runs, the record's `output` is null and `applied` false, nothing is written anywhere; the old implicit `(repaired).epub` sibling was issue #7's import litter in a vetted tree, and writing now needs an explicit DST). `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). Since v0.40.0 `main()` guards the VirInvictus stack: a `ModuleNotFoundError` naming `vir_tui`/`cquarry` (marker-gated to 3.14+ on the 3.12 floor) becomes one stderr line and trouble exit 2 instead of a traceback; anything else missing still raises.
 - `plugin/__init__.py` + `scripts/build_plugin.py`: the Bindery Repair Calibre plugin (v0.37.0; identity `Bindery Repair` / `bindery_repair`, approved and built per the scoped spec in roadmap.md Phase 3). The builder vendors `transforms.py`, `epub.py`, `pagination.py`, `watermark.py`, `reserialize.py` byte-identically into the zip (the zip root is a package, so their relative imports resolve unchanged; the suite's drift test pins the equality) with the version tuple substituted from the single-source VERSION; `publish.yml` attaches `BinderyRepair-v<VERSION>.zip` to each release. The plugin runs ONLY the default pass (epubcheck cannot gate inside Calibre), never raises, is byte-idempotent (zero fixes returns the original path), testzip()-verifies its output, logs one line per book, and takes JSON config via `site_customization` (`log`, `log_path`, `max_size_mb` default 150, `max_log_mb` rotation cap default 2, `epubcheck_path` experimental validation default OFF). Load it in tests through the `tests/test_plugin.py` stubs: the calibre namespace is installed in sys.modules and the package loads with a two-dir `__path__` (plugin dir first, then src/bindery) exactly like calibre's zipplugin loader shape. **Plugin/interpreter compatibility (v0.40.0):** v0.39.0 shipped PEP 758 unparenthesized except tuples, and the plugin died with a bare SyntaxError on every released Calibre (7.x and the whole 8.x series embed Python 3.11, 9.0+ embeds 3.14; from calibre's bypy sources.json, checked against the upstream clone). The core is now grammar-pinned: parenthesized except tuples everywhere, `ruff`'s `target-version = "py312"` pin (inference from requires-python would rewrite the parens back off), `tests/test_version.py`'s parse guard, and CI's `plugin-compat` job byte-compiling the built zip under 3.11/3.12/3.13/3.14. `minimum_calibre_version` is (7, 0, 0): the oldest series whose interpreter CI covers, replacing the hollow (2, 0, 0); `supported_platforms` stays `["linux"]` (developed and tested on Linux only). Any new syntax in the vendored modules must clear the guard before it ships.
-- `tests/`: transforms, end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, the version pin and the syntax-floor grammar guard, and the Calibre plugin (build drift + run behavior under calibre stubs). Since the v0.46.0 follow-ups: `tests/test_flags_wiring.py` reflectively pins the RepairFlags inventory to the argparse dests and `_flags_from_args` mapping (a flag added without a field, a field without a flag, or a remapped line fails there), the all-off defaults, and the version gate's caller-immutability contract (test_epub's `TestVersionGateKeepsFlagsIntact`); `tests/test_comment_hyphens.py` carries the RSC-016 fix; `tests/test_flags_real_core.py` drives every repair flag from argv through the unmocked core (--no-validate; the gate itself stays pinned by the mocked-oracle tests and runs for real wherever epubcheck exists). All three ride CI's core-compat 3.12/3.13 leg; the hand-listed module list there must gain an entry for every new stack-free test module.
+- `tests/`: transforms, end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification, contamination since v0.50.0), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, the version pin and the syntax-floor grammar guard, and the Calibre plugin (build drift + run behavior under calibre stubs). Since the v0.46.0 follow-ups: `tests/test_flags_wiring.py` reflectively pins the RepairFlags inventory to the argparse dests and `_flags_from_args` mapping (a flag added without a field, a field without a flag, or a remapped line fails there), the all-off defaults, and the version gate's caller-immutability contract (test_epub's `TestVersionGateKeepsFlagsIntact`); `tests/test_comment_hyphens.py` carries the RSC-016 fix; `tests/test_flags_real_core.py` drives every repair flag from argv through the unmocked core (--no-validate; the gate itself stays pinned by the mocked-oracle tests and runs for real wherever epubcheck exists). `tests/test_contamination.py` (v0.50.0) carries the three contamination sweeps, the advisory contract, the `_dir_dispatch` key pin, and the cover-routing regression. The v0.46.0 trio (test_flags_wiring, test_comment_hyphens, test_flags_real_core) rides CI's core-compat 3.12/3.13 leg; the hand-listed module list there must gain an entry for every new stack-free test module (audit-side test modules like test_contamination stay on the 3.14 leg by convention).
 
 ## Conventions
 

{bindery_cli-0.49.0 → bindery_cli-0.51.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.49.0
+Version: 0.51.0
 Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
 Project-URL: Homepage, https://github.com/VirInvictus/bindery-cli
 Project-URL: Repository, https://github.com/VirInvictus/bindery-cli
@@ -242,12 +242,17 @@ bindery audit completeness ~/docs/Calibre\ Library
 bindery audit cover ~/docs/Calibre\ Library
 bindery audit tocdrift ~/docs/Calibre\ Library
 
+# Fan-bundle contamination: foreign-title template stamps, ad pages, review paste
+bindery audit contamination ~/docs/Calibre\ Library
+
 # Run all audits and report to the console (--json FILE for machine output)
 cd ~/docs/Calibre\ Library && bindery audit all
 ```
 
 **Completeness spot-check:** the `completeness` audit answers the pre-import question "does this book reach its end?" It reports, per book: the prose-document count against the spine (docs with 400+ visible characters), the opening and closing text of the first/middle/last prose doc, a trailing-ToC classification of the final spine doc (a link-dense chapter list after the real back matter), and the fraction of unreadable docs. A trailing ToC is reported as an advisory, never a failure: the closing excerpt always comes from the real back matter, so a human can confirm the book ends where the author ended it.
 
+**Contamination scan:** the `contamination` audit is advisory too: fan-bundle cosmetics are the judge-and-import class. Three sweeps over the archive's content documents (spine plus the non-spine html a broken manifest can strand): another series' name where the book's own identity belongs, judged against the package's own metadata (the head-`<title>` template stamps a sloppy fan bundle leaves on every doc, a volume marker with named words in front of it, a repeated foreign running header); known fan-bundle ad signatures (jnovels, kokoro connect, zerobooks, light-novel download plugs); and pasted review-site text in the first few content docs (helpful counts, "was this review helpful", "out of 5 stars", verified purchase). Every finding is a report a human judges, never a failure.
+
 Audits can also be run on a directory of loose `.epub` files by passing the path as the second argument:
 ```sh
 bindery audit pagenumbers /path/to/loose/epubs

{bindery_cli-0.49.0 → bindery_cli-0.51.0}/README.md

@@ -215,12 +215,17 @@ bindery audit completeness ~/docs/Calibre\ Library
 bindery audit cover ~/docs/Calibre\ Library
 bindery audit tocdrift ~/docs/Calibre\ Library
 
+# Fan-bundle contamination: foreign-title template stamps, ad pages, review paste
+bindery audit contamination ~/docs/Calibre\ Library
+
 # Run all audits and report to the console (--json FILE for machine output)
 cd ~/docs/Calibre\ Library && bindery audit all
 ```
 
 **Completeness spot-check:** the `completeness` audit answers the pre-import question "does this book reach its end?" It reports, per book: the prose-document count against the spine (docs with 400+ visible characters), the opening and closing text of the first/middle/last prose doc, a trailing-ToC classification of the final spine doc (a link-dense chapter list after the real back matter), and the fraction of unreadable docs. A trailing ToC is reported as an advisory, never a failure: the closing excerpt always comes from the real back matter, so a human can confirm the book ends where the author ended it.
 
+**Contamination scan:** the `contamination` audit is advisory too: fan-bundle cosmetics are the judge-and-import class. Three sweeps over the archive's content documents (spine plus the non-spine html a broken manifest can strand): another series' name where the book's own identity belongs, judged against the package's own metadata (the head-`<title>` template stamps a sloppy fan bundle leaves on every doc, a volume marker with named words in front of it, a repeated foreign running header); known fan-bundle ad signatures (jnovels, kokoro connect, zerobooks, light-novel download plugs); and pasted review-site text in the first few content docs (helpful counts, "was this review helpful", "out of 5 stars", verified purchase). Every finding is a report a human judges, never a failure.
+
 Audits can also be run on a directory of loose `.epub` files by passing the path as the second argument:
 ```sh
 bindery audit pagenumbers /path/to/loose/epubs

{bindery_cli-0.49.0 → bindery_cli-0.51.0}/patchnotes.md

@@ -1,5 +1,106 @@
 # bindery-cli Patch Notes
 
+## v0.51.0 (2026-10-17)
+
+### The unbound-prefix repair: the Calibre embed scar comes off the OPF (issue #9)
+
+Century Rain (library book #11104) carried an OPF that repeated
+`calibredb embed_metadata` rounds had scarred: one `dc:identifier`, the package
+unique-identifier itself, carried an `ns0:scheme` attribute whose `xmlns:ns0`
+declaration sat on a sibling element, out of XML scope. epubcheck answered with
+two RSC-016 fatals (unbound prefix) plus OPF-030 (unique-identifier not found),
+and because a fatal package halts the metadata checks, the stale NCX `dtb:uid`
+was invisible to the oracle on both sides of the gate. The old probe report said
+it all: `1f/1e/0w -> 1f/1e/0w, ncx_uid_synced (no measurable gain)`, the ncx
+fix refused with the OPF half.
+
+- **`--fix-unbound-prefix`** (new structural repair, twenty-second) binds an
+  attribute prefix the OPF never declares inline on the element that uses it,
+  the exact shape the file's own healthy siblings already use. The URI is
+  evidence-based, never guessed: the same prefix declared elsewhere in the
+  document (every declaration must agree, or the document is refused), or the
+  OPF namespace for a Dublin Core element under an OPF-namespaced package (the
+  canonical EPUB 2 `opf:scheme` shape); anything else refuses the whole
+  document untouched. Scope tracking walks the document with a
+  comment/CDATA-aware tokenizer over a lenient element stack, so declarations
+  that genuinely cover a use satisfy it without an edit and clean documents
+  are byte-identical. OPF only: content documents already have the
+  invalid-attribute drop (`--strip-bad-attrs`) for this defect class. Normal
+  `gate` (clearing the fatal is the measurable gain). On the fixture:
+  `1f/1e/0w -> 0f/0e/0w`, epubcheck fully clean.
+- **The masked ncx gain** (the issue's second half) stops lying in reports:
+  when the gate answers noop but the NCX uid sync actually fired on a book
+  that started with fatals, `process_book` reclassifies the verdict to
+  `partial` instead of `equal`/`no measurable gain`. The sync is real,
+  deterministic work the oracle could not see; the still-fatal rule is intact,
+  so the library sweep still refuses to apply such a book and the single-file
+  verb still writes it under the honest PARTIAL label when given an explicit
+  destination.
+
+Twenty-seven tests joined the suite (691 total): the transform unit tests
+(scope, evidence, refusal, idempotence), the archive-level e2e, the masked-gain
+verdict rules, tokenizer spin guards beside the other matchers, and the argv
+wiring rows.
+
+## v0.50.0 (2026-10-14)
+
+### The contamination analyzer: fan-bundle cosmetics get reported (issue #8)
+
+Three fixtures from the 2026-10-14 phase-1 wave slipped past the content
+analyzer's ad-notice detection (the importknig class): two Grandmaster of
+Demonic Cultivation volumes packaged by a sloppy fan bundle, carrying
+"Full Metal Panic! Volume 5" in every content document's head `<title>` (the
+bundle template's original book) plus a whole Jnovels/Zerobooks ad page whose
+own head title names a third series; and Hothouse, whose front matter is
+pasted Amazon review text ("3 of 4 people found the following review
+helpful"). All three were approved for import regardless, so the new
+detection is advisory by contract, like completeness/cover/tocdrift: it
+never flags a book and never moves an exit code. The disposition for this
+class is judge-and-import.
+
+- **`bindery audit contamination`** (new analyzer, ninth; rides in `all`)
+  runs three sweeps over the archive's content documents:
+  - *foreign titles*: a title or series named where the book's own identity
+    belongs, judged against the package's own metadata (dc:title, creator,
+    publisher, series). Two triggers, both tuned on the fixtures: a
+    volume/book marker with named words in front of it ("Full Metal Panic!
+    Volume 5"; a part label whose marker leads, "BOOK ONE: THE RING SETS
+    OUT", never flags), or a head `<title>` repeated across the book. The
+    head-`<title>` channel matters because the MDZS stamps are invisible to
+    rendered text; a marker-stripped own-name comparison keeps a book's own
+    running headers clean when the metadata spells the volume differently.
+  - *ad signatures*: jnovels, kokoro connect, zerobooks, and a generic
+    light-novel download plug, in visible body text.
+  - *review paste*: review-site fingerprints (helpful counts, "was this
+    review helpful", "out of 5 stars", verified purchase) in the first five
+    content docs; a strong fingerprint flags a doc alone, weak ones
+    (reviewer bylines, star rows) need corroboration.
+- **The corpus is the archive's content documents, not just the spine.**
+  Hothouse's manifest is broken: 52 of its 53 content docs sit in no
+  manifest item, the spine resolves to one document, and a spine-only sweep
+  would have read the book clean. The loader now retains the archive's
+  non-spine html on `Book.extra_docs` (archive order, 64 MiB retention cap;
+  a pathological archive stops feeding the corpus there and stays the
+  corruption/completeness verdicts' business), and the contamination sweeps
+  run over spine plus extras.
+- **Directory and single-book mode actually run cover and tocdrift now.**
+  `run_directory`/`run_single` dispatched analyzers through an if/elif chain
+  whose terminal `else` ran the ocr analyzer, so since v0.44.0 an
+  `audit all` over a directory (or `audit all --id`) reported ocr verdicts
+  under the cover and tocdrift keys and never analyzed cover wiring or ToC
+  drift. Library mode was unaffected. Both modes now share a dispatch map
+  keyed on the analyzer names (`_dir_dispatch`), a missing key is a loud
+  KeyError instead of a mislabeled verdict, and `tests/test_contamination.py`
+  pins the map's key set to the analyzer list. Advisory analyzers never
+  answer problem, so `audit all` and multi-analyzer runs cannot change their
+  verdicts; the one behavioral corner is a single-key `audit cover DIR` (or
+  `--id`) run, which at HEAD actually executed the ocr analyzer and could
+  exit 1 on an ocr-damaged book under the cover key, and now runs cover
+  wiring and exits on cover's own (always-advisory) verdict.
+- CalibreQuarry-style `--json` consumers see the new analyzer's verdicts as
+  an additive `contamination` key (problem always false); nothing else in
+  the audit record shape moved.
+
 ## v0.49.0 (2026-10-13)
 
 ### The single-file repair probe writes nothing (issue #7)

{bindery_cli-0.49.0 → bindery_cli-0.51.0}/pyproject.toml

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

{bindery_cli-0.49.0 → bindery_cli-0.51.0}/roadmap.md

@@ -43,6 +43,8 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
 | 0.47 | The intake-wave batch (five open issues): the stub classifier's body-pool + image-carrier exemption, the NCName-complete `--fix-ids`, and `--fix-svg-dup-ids`, `--fix-cdata-terminator`, `--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr` | v0.47.0 |
 | 0.48 | The AI-probe batch: the enforced closed-Calibre gate on both metadata.db doors (`audit --tag`, `library --apply --install-to-calibre`), the stated contracts (exit codes, no-prompt, NCX-001, --id scoping, json envelope keys), and `--help-json` | v0.48.0 |
 | 0.49 | The probe form (issue #7): single-file repair without an output path runs the gate and writes nothing; writing needs an explicit DST | v0.49.0 |
+| 0.50 | The contamination analyzer (issue #8): foreign-title template stamps, fan-bundle ad signatures, review-paste front matter; advisory by contract, archive-wide corpus (`Book.extra_docs`, capped), and the `_dir_dispatch` map that fixes the v0.44.0 cover/tocdrift ocr misroute in directory/single mode | v0.50.0 |
+| 0.51 | The unbound-prefix repair (issue #9): `--fix-unbound-prefix` binds the Calibre embed scar's undeclared attribute prefix inline (evidence-based URI, scope-tracked, refuse over guess), plus the masked-ncx-gain rule that stops a real dtb:uid sync reading as no measurable gain under a fatal package | v0.51.0 |
 
 ## Open work
 

{bindery_cli-0.49.0 → bindery_cli-0.51.0}/spec.md

@@ -13,14 +13,14 @@ restyle, re-compress, or restructure content, and it does not attempt to fix arb
 schema (RSC-005) violations, which are usually harmless to readers and not safely
 mechanizable.
 
-The deliberate exceptions to "semantics-preserving" come in opt-in groups. The twenty-one
+The deliberate exceptions to "semantics-preserving" come in opt-in groups. The twenty-two
 **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`,
 `--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`,
 `--fix-container`, `--fix-media-types`, `--fix-cover`, `--fix-comment-double-hyphen`,
 `--fix-svg-dup-ids`, `--fix-cdata-terminator`, `--fix-misnested-inline`,
-`--fix-stray-close`, `--fix-unterminated-attr`) alter
+`--fix-stray-close`, `--fix-unterminated-attr`, `--fix-unbound-prefix`) alter
 markup structure or fabricate minimal content; the four
 **lossy modes** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`,
 `--strip-stub-docs`) remove
@@ -280,8 +280,22 @@ use, with the `partial` rule intact.
   quote before the next `<` (a real multi-line value closes quote-first), and only
   double-quoted values are judged. It runs before the other tag-shape readers, which an
   open value otherwise lies to.
-
-Nineteen of the twenty-one are evaluated by the normal `gate`: unlike the lossy strips,
+- **`--fix-unbound-prefix`**: bind an attribute prefix the OPF never declares inline on
+  the element that uses it (the Calibre embed scar, issue #9: one dc: element carries
+  `ns0:scheme` while the `xmlns:ns0` declaration sits on a sibling, out of XML scope;
+  the RSC-016 "prefix is not bound" fatals make the whole package unparseable, which
+  also costs OPF-030 on the unique-identifier and masks the NCX-001 comparison). The
+  declaration is inserted on the user, the shape the file's own healthy siblings
+  already use. The URI is evidence-based, never guessed: the same prefix declared
+  elsewhere in the document with every declaration agreeing, or the OPF namespace for
+  a Dublin Core element under an OPF-namespaced package (the canonical EPUB 2
+  `opf:scheme` shape); anything else refuses the document untouched. Scope is tracked
+  with a lenient element stack over a comment/CDATA-aware tokenizer, so declarations
+  that genuinely cover a use satisfy it without an edit and clean documents are
+  byte-identical. Runs on the OPF only: content documents have the
+  invalid-attribute drop (`--strip-bad-attrs`) for the same defect class.
+
+Twenty of the twenty-two are evaluated by the normal `gate`: unlike the lossy strips,
 their benefit is visible to epubcheck (they clear errors), so a run with no measurable
 improvement is a noop and nothing is applied. The two exceptions are `--fix-cover` and
 `--encode-url-spaces`, whose gains sit on axes epubcheck does not measure (cover
@@ -451,8 +465,8 @@ This door is lock-class: `--install-to-calibre` is REFUSED with exit 1 while Cal
 
 ## Audit subcommand (read-only)
 
-`bindery audit {content,pagenumbers,emptytext,ocr,monolithic,completeness,cover,tocdrift,all} [PATH] [--max-doc-chars N]
-[--tag TAG] [--id IDs]` (v0.15.0, `audit.py`; `--tag` since v0.18.0; `monolithic` since v0.21.0, `--max-doc-chars N`; `--id` since v0.19.0, comma-lists in v0.23.0; `completeness` since v0.36.0; `cover` and `tocdrift` since v0.44.0) inspects
+`bindery audit {content,pagenumbers,emptytext,ocr,monolithic,completeness,cover,tocdrift,contamination,all} [PATH] [--max-doc-chars N]
+[--tag TAG] [--id IDs]` (v0.15.0, `audit.py`; `--tag` since v0.18.0; `monolithic` since v0.21.0, `--max-doc-chars N`; `--id` since v0.19.0, comma-lists in v0.23.0; `completeness` since v0.36.0; `cover` and `tocdrift` since v0.44.0; `contamination` since v0.50.0) inspects
 EPUB body text for flaws epubcheck cannot see: non-English script blocks, baked-in page-number
 layers (sliding-window density heuristics), empty or thin books, systemic OCR damage, and
 single oversized content documents (one spine doc at or above 300k characters: readers refuse
@@ -477,6 +491,28 @@ entries each side is missing and labels that disagree; it feeds decisions, never
 rewrite (ToC synthesis is out of the repair charter permanently). Both never flag a
 book and never move the exit code.
 
+The contamination analyzer (v0.50.0, issue #8) is advisory by the same contract:
+fan-bundle cosmetics are the judge-and-import class, so it never flags a book and
+never moves an exit code. Three sweeps run over the archive's content documents
+(the spine plus the non-spine html the loader retains on `Book.extra_docs`,
+archive order, 64 MiB retention cap): *foreign titles* name a title or series that
+matches none of the package's own metadata (dc:title, creator, publisher, series),
+flagged either by a volume/book marker with named words in front of it or by a
+head `<title>` repeated across the book (a part label whose marker leads, "BOOK
+ONE: ...", never flags; the comparison also runs on the volume-marker-stripped
+form so a book's own running headers stay clean); *ad signatures* (jnovels,
+kokoro connect, zerobooks, a generic light-novel download plug) are searched in
+visible body text, with a signature that matches the book's own metadata
+skipped outright (a legitimate Kokoro Connect volume names its own series on
+every doc); *review paste* (helpful counts, review-helpful prompts,
+"out of 5 stars", verified purchase, with reviewer bylines and star rows as
+corroborating-only weak fingerprints) is scoped to the first five content docs.
+The archive-wide corpus exists because fan-bundle junk is package furniture a
+broken manifest can leave entirely off the spine (Hothouse: 52 of 53 content
+docs in no manifest item, a resolved spine of one). On a shell book (no package
+metadata) the analyzer reports nothing: there is no "own" to judge foreignness
+against.
+
 The completeness analyzer is the phase-1 spot-check and is advisory by contract: it never
 flags a book and never moves the exit code. Per book it reports the spine doc count, the
 prose-doc count (spine docs carrying at least 400 visible characters), the opening and closing

{bindery_cli-0.49.0 → bindery_cli-0.51.0}/src/bindery/__init__.py

@@ -11,7 +11,7 @@ Calibre plugin built from this core.
 Single source of truth for the version. pyproject.toml must match VERSION below.
 """
 
-VERSION = "0.49.0"
+VERSION = "0.51.0"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402