bindery-cli 0.45.0__tar.gz → 0.46.1__tar.gz

{bindery_cli-0.45.0 → bindery_cli-0.46.1}/.github/workflows/ci.yml

@@ -44,9 +44,10 @@ jobs:
         # The install floor (decision 63): vir-tui/cquarry are marker-gated
         # to 3.14 there, so these legs install the core (tqdm only) and run
         # exactly the test modules that never touch the gated stack: the
-        # repair core, the plugin under calibre stubs, validate, and the
-        # version/grammar pins. audit/library/CLI-stack tests stay on the
-        # 3.14 leg above.
+        # repair core, the plugin under calibre stubs, validate, the
+        # version/grammar pins, the RSC-016 comment-hyphen fix, the
+        # RepairFlags wiring pins, and the flags-driven real-core run.
+        # audit/library/CLI-stack tests stay on the 3.14 leg above.
         python-version: ["3.12", "3.13"]
     steps:
       - uses: actions/checkout@v5
@@ -59,6 +60,8 @@ jobs:
           tests.test_transforms tests.test_epub tests.test_pagination
           tests.test_watermark tests.test_reserialize tests.test_version
           tests.test_plugin tests.test_validate
+          tests.test_comment_hyphens tests.test_flags_wiring
+          tests.test_flags_real_core
   plugin-compat:
     name: Parse-check the plugin zip under the interpreters Calibre embeds
     runs-on: ubuntu-latest

{bindery_cli-0.45.0 → bindery_cli-0.46.1}/CLAUDE.md

@@ -30,21 +30,26 @@ 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: fifteen structural
-  repairs, three lossy strips, four safe opt-ins, plus `--reserialize`.
+  visible content. The canonical opt-in inventory lives in spec.md: sixteen 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`,
     `--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`; transforms.py, threaded
-    through epub.py). Since v0.44.0 `--encode-url-spaces` also RENAMES the
+    `--fix-container`, `--fix-media-types`, `--fix-cover`,
+    `--fix-comment-double-hyphen`; transforms.py, threaded
+    through epub.py). `--fix-comment-double-hyphen` (v0.46.0, the RSC-016 fatal)
+    replaces `--` inside XML comments with an en-dash: comment bodies only (text
+    nodes and CDATA never touched, the one deliberate exception to the
+    never-rewrite-comments invariant), in content documents, the NCX, and the OPF
+    alike; normal `gate` (clearing the fatal IS the measurable gain). Since v0.44.0 `--encode-url-spaces` also RENAMES the
     archive entries whose names carry raw spaces to their underscore spellings
     and rewrites every reference (OPF, NCX, content, CSS `url()`); underscore,
     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:
-    they alter markup structure or fabricate minimal content. v0.14–v0.16 ran these unconditionally, which broke this rule;
+    does not measure.
+    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`,
     book-wide, inline `<style>` blocks included). The two EPUB2-targeted fixes
@@ -75,11 +80,13 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - **The gate is the safety contract.** Never apply a repair epubcheck has not accepted.
   Respect the two-mode logic in `validate.gate` (fatal-fixing tolerates error unmasking;
   error-cleanup does not). The lossy strips (`--strip-pagination`, `--strip-broken-tags`,
-  `--strip-watermarks`) are accepted by `validate.no_worse` instead (their gain is
-  invisible to epubcheck, so it only forbids a regression, never demands a measured
-  improvement). The structural opt-ins go through the normal `gate`: their gain IS
-  visible (they clear errors), so a run with no measurable improvement is a noop and
-  nothing is applied. Changing either bar means re-running the library dry run.
+  `--strip-watermarks`, `--strip-stub-docs`) are accepted by `validate.no_worse` instead
+  (their gain is invisible to epubcheck, so it only forbids a regression, never demands
+  a measured improvement). The structural opt-ins go through the normal `gate` (their
+  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.
 - **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`;
@@ -88,17 +95,17 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 
 ## Layout
 
-- `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`). Since v0.32.0: `strip_attrs_in_start_tags` anchors attribute edits on the quote-aware start-tag matcher, `_outside_protected` forwards arguments (context-carrying transforms can be decorated), `fix_id_colons` matches only the bare `id` attribute and only internal fragments (`fix_ncx_src_fragments` carries renames into the NCX), `fix_ncx_playorder` is anchored to `<navPoint>` start tags, and the css selector boundary covers namespaced and functional selector forms. HAZARD (the 0.41.0 spin): the quote-aware tag-prefix alternation (double-quoted | single-quoted | [^>]) OVERLAPS ([^>] matches quotes too), so a plain `*` re-partitions exponentially on failing candidates; every such greedy loop must carry the possessive `*+` (re 3.11+, the plugin's minimum Calibre). Since v0.42.0 the census is complete and pinned by tests/test_matcher_hardening.py: every greedy loop of this family is possessive (the three 0.41.1 rewrites plus _START_TAG_RE, _COVER_META_RE, _GUIDE_REF_RE, prune_dangling_edges' spine|item|itemref matcher, _ITEM_TAG_RE, _SPINE_ITEM_RE -- possessive is byte-identical on success because the loop is always followed by a literal `>` the [^>] branch cannot consume), and the five LAZY siblings (_VOID_RE, the transforms <img> matcher, and epub's link/a/img matchers) use the disjoint catch-all `[^>"']` instead: mutually exclusive branches cannot re-partition, and an unterminated quote inside a tag now fails to match rather than pairing across markup. NEW tag matchers: quote-aware possessive for greedy loops, the disjoint catch-all for lazy ones, and the tempered-quote idiom (["'])((?:(?!\1).)*)\1 for attribute values. Since v0.37.0: `fix_ncx_playorder` strips quotes before its already-correct comparison (regex groups carry quote characters; comparing quoted values against bare numbers counted phantom fixes on every sequential NCX and rewrote single-quoted correct attributes to double quotes).
+- `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`). Since v0.32.0: `strip_attrs_in_start_tags` anchors attribute edits on the quote-aware start-tag matcher, `_outside_protected` forwards arguments (context-carrying transforms can be decorated), `fix_id_colons` matches only the bare `id` attribute and only internal fragments (`fix_ncx_src_fragments` carries renames into the NCX), `fix_ncx_playorder` is anchored to `<navPoint>` start tags, and the css selector boundary covers namespaced and functional selector forms. HAZARD (the 0.41.0 spin): the quote-aware tag-prefix alternation (double-quoted | single-quoted | [^>]) OVERLAPS ([^>] matches quotes too), so a plain `*` re-partitions exponentially on failing candidates; every such greedy loop must carry the possessive `*+` (re 3.11+, the plugin's minimum Calibre). Since v0.42.0 the census is complete and pinned by tests/test_matcher_hardening.py: every greedy loop of this family is possessive (the three 0.41.1 rewrites plus _START_TAG_RE, _COVER_META_RE, _GUIDE_REF_RE, prune_dangling_edges' spine|item|itemref matcher, _ITEM_TAG_RE, _SPINE_ITEM_RE; possessive is byte-identical on success because the loop is always followed by a literal `>` the [^>] branch cannot consume), and the five LAZY siblings (_VOID_RE, the transforms <img> matcher, and epub's link/a/img matchers) use the disjoint catch-all `[^>"']` instead: mutually exclusive branches cannot re-partition, and an unterminated quote inside a tag now fails to match rather than pairing across markup. NEW tag matchers: quote-aware possessive for greedy loops, the disjoint catch-all for lazy ones, and the tempered-quote idiom (["'])((?:(?!\1).)*)\1 for attribute values. Since v0.37.0: `fix_ncx_playorder` strips quotes before its already-correct comparison (regex groups carry quote characters; comparing quoted values against bare numbers counted phantom fixes on every sequential NCX and rewrote single-quoted correct attributes to double quotes).
 - `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/epub.py`: archive rewrite, NCX uid sync, RepairReport, mismatch detection, and the opt-in structural-repair plumbing (including the CSS precondition scan). 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/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.
-- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; `repair --json` emits the library per-book record vocabulary (2026-09-15; since v0.45.0 every per-book record, the phase1 payload included, also carries the structured fix breakdown: the `fixes` dict plus `ncx_uid_synced`/`watermark_refusals` off the `Outcome`, and `_phase1_decisions` reads that data instead of substring-matching the rendered `summary`, which stays for human eyes; CalibreQuarry's lossy-consent mirror is the waiting consumer, floor `bindery>=0.45.0`); since v0.29.0 also the `run` verbs: `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2; since 2026-09-15 the summary sums applied/equal states only and carries rejected projections as `rejected_projection`). Plus `bindery doctor` (2026-09-15): the environment self-check that imports none of the VirInvictus stack, never raises, and always exits 0. Both run verbs take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. `library --workers N` (v0.30.0) parallelizes only the sweep's candidate pass, in windows of N consumed in order so `--limit` stays lazy; the repair phase is never parallel (shared workdir, atomic-replacement contract). 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, `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).
+- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; `repair --json` emits the library per-book record vocabulary (2026-09-15; since v0.45.0 every per-book record, the phase1 payload included, also carries the structured fix breakdown: the `fixes` dict plus `ncx_uid_synced`/`watermark_refusals` off the `Outcome`, and `_phase1_decisions` reads that data instead of substring-matching the rendered `summary`, which stays for human eyes; CalibreQuarry's lossy-consent mirror is the waiting consumer, floor `bindery>=0.45.0`); since v0.29.0 also the `run` verbs: `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2; since 2026-09-15 the summary sums applied/equal states only and carries rejected projections as `rejected_projection`). Plus `bindery doctor` (2026-09-15): the environment self-check that imports none of the VirInvictus stack, never raises, and always exits 0. Both run verbs take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. Since v0.46.0 `cli._flags_from_args(args)` is the one place the argparse names map onto `RepairFlags` fields (each `or --all`), shared by `run_library` and `run_repair`; the old per-verb ~25-kwarg blocks are gone. `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.
 
 ## Conventions
 

{bindery_cli-0.45.0 → bindery_cli-0.46.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.45.0
+Version: 0.46.1
 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
@@ -67,10 +67,11 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--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 (with every package edge that pointed at them rewritten: `spine@toc`, `item@media-overlay`, `item@fallback`, and the EPUB2 cover meta). 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.
+- **`--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. Since v0.44.0 the flag also renames archive entries whose names carry raw spaces to their underscore spellings and rewrites every reference to them (OPF, NCX, content, CSS `url()`), clearing the PKG-010 space-in-filename advisories: underscore, never percent-encoding, because epubcheck decodes references before entry lookup.
 - **`--fix-container`**: generates `META-INF/container.xml` at the located OPF when the container is missing or names a file the archive does not contain. This is the gateway defect: epubcheck stays fatal while the OPF is unfindable, so no repair can be gate-accepted on such a book until the container exists.
 - **`--fix-media-types`**: normalizes wrong manifest media-type declarations (OPF-029, e.g. a jpg stamped `image/png` by an aggregator). Attribute-only and quote-preserving; it fires only when the file's magic bytes confirm the extension, so a misnamed-but-consistent file (a PNG renamed .jpg) is never made worse.
 - **`--fix-cover`**: repairs dangling EPUB2 cover wiring. A `<meta name="cover">` whose content names no manifest item is re-pointed when the OPF guide's own cover reference names an existing item, and removed when nothing identifies it; EPUB3 `properties="cover-image"` is deliberately audit-only (guessing which image is the cover is not deterministic). Cover wiring is invisible to epubcheck, so cover-only repairs are accepted under the same no-worse bar the lossy strips use.
+- **`--fix-comment-double-hyphen`**: replaces `--` sequences inside XML comments with en-dashes. `--` is illegal inside an XML comment (epubcheck fatal RSC-016: the book opens in lenient readers but never passes epubcheck). The edit stays inside the comment bodies: text nodes and CDATA sections are never touched, and each comment's terminator is left intact.
 
 
 Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
@@ -93,7 +94,7 @@ Introducing a net-new fatal is always rejected. If epubcheck itself fails to run
 
 Under the hood, the oracle can run two ways: the usual `epubcheck --json -` subprocess, or a persistent daemon that writes `FastDaemon.java` into a temp directory at runtime, compiles it in memory with the running JVM's own compiler (Java's single-file source launcher: no javac, no javac/java version skew), and drives the warm JVM over a pipe. The daemon reports the counts it reads from the JSON document that epubcheck's own `CheckingReport` serializes, so it measures exactly what the subprocess measures, just ~15x faster. It is a pool bounded by `--workers` (serial runs use one), every roundtrip is bounded by the caller's timeout, and any failure tears it down and falls back to the subprocess for good.
 
-The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-watermarks`) are the exception to the "must improve" rule. Since they remove visible markup rather than correcting XML schema violations, epubcheck counts often remain unchanged. They are accepted when the result is **no worse** (no net-new fatals or errors), relying on strict programmatic safety nets instead.
+The lossy modes (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`, and `--strip-stub-docs`) are the exception to the "must improve" rule. Since they remove converter-injected content rather than correcting XML schema violations, epubcheck counts often remain unchanged. They are accepted when the result is **no worse** (no net-new fatals or errors), relying on strict programmatic safety nets instead.
 
 ## Install
 

{bindery_cli-0.45.0 → bindery_cli-0.46.1}/README.md

@@ -40,10 +40,11 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--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 (with every package edge that pointed at them rewritten: `spine@toc`, `item@media-overlay`, `item@fallback`, and the EPUB2 cover meta). 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.
+- **`--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. Since v0.44.0 the flag also renames archive entries whose names carry raw spaces to their underscore spellings and rewrites every reference to them (OPF, NCX, content, CSS `url()`), clearing the PKG-010 space-in-filename advisories: underscore, never percent-encoding, because epubcheck decodes references before entry lookup.
 - **`--fix-container`**: generates `META-INF/container.xml` at the located OPF when the container is missing or names a file the archive does not contain. This is the gateway defect: epubcheck stays fatal while the OPF is unfindable, so no repair can be gate-accepted on such a book until the container exists.
 - **`--fix-media-types`**: normalizes wrong manifest media-type declarations (OPF-029, e.g. a jpg stamped `image/png` by an aggregator). Attribute-only and quote-preserving; it fires only when the file's magic bytes confirm the extension, so a misnamed-but-consistent file (a PNG renamed .jpg) is never made worse.
 - **`--fix-cover`**: repairs dangling EPUB2 cover wiring. A `<meta name="cover">` whose content names no manifest item is re-pointed when the OPF guide's own cover reference names an existing item, and removed when nothing identifies it; EPUB3 `properties="cover-image"` is deliberately audit-only (guessing which image is the cover is not deterministic). Cover wiring is invisible to epubcheck, so cover-only repairs are accepted under the same no-worse bar the lossy strips use.
+- **`--fix-comment-double-hyphen`**: replaces `--` sequences inside XML comments with en-dashes. `--` is illegal inside an XML comment (epubcheck fatal RSC-016: the book opens in lenient readers but never passes epubcheck). The edit stays inside the comment bodies: text nodes and CDATA sections are never touched, and each comment's terminator is left intact.
 
 
 Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
@@ -66,7 +67,7 @@ Introducing a net-new fatal is always rejected. If epubcheck itself fails to run
 
 Under the hood, the oracle can run two ways: the usual `epubcheck --json -` subprocess, or a persistent daemon that writes `FastDaemon.java` into a temp directory at runtime, compiles it in memory with the running JVM's own compiler (Java's single-file source launcher: no javac, no javac/java version skew), and drives the warm JVM over a pipe. The daemon reports the counts it reads from the JSON document that epubcheck's own `CheckingReport` serializes, so it measures exactly what the subprocess measures, just ~15x faster. It is a pool bounded by `--workers` (serial runs use one), every roundtrip is bounded by the caller's timeout, and any failure tears it down and falls back to the subprocess for good.
 
-The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-watermarks`) are the exception to the "must improve" rule. Since they remove visible markup rather than correcting XML schema violations, epubcheck counts often remain unchanged. They are accepted when the result is **no worse** (no net-new fatals or errors), relying on strict programmatic safety nets instead.
+The lossy modes (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`, and `--strip-stub-docs`) are the exception to the "must improve" rule. Since they remove converter-injected content rather than correcting XML schema violations, epubcheck counts often remain unchanged. They are accepted when the result is **no worse** (no net-new fatals or errors), relying on strict programmatic safety nets instead.
 
 ## Install
 

{bindery_cli-0.45.0 → bindery_cli-0.46.1}/patchnotes.md

@@ -1,4 +1,39 @@
 # bindery-cli Patch Notes
+## v0.46.1 (2026-10-02)
+
+### The closing sweep: documentation truth after the 0.46 line
+
+The 2026-10-02 verification of the four-lane run left four documentation
+findings against the v0.46.0 tree; all four land here as text plus one
+plugin string. No surface change beyond the plugin's help text.
+
+* The safety contract's lossy enumeration names all four modes: the
+  paragraph listed three and omitted `--strip-stub-docs` (shipped
+  v0.41.0), while the mode list twenty lines up, spec.md, and CLAUDE.md
+  all carry four. Its rationale sentence now says converter-injected
+  content rather than visible markup, true of the document-dropping stub
+  mode too.
+* CLAUDE.md's tests bullet loses its em-dash: the one straggler in the
+  v0.45.0..HEAD markdown delta, recast with a semicolon.
+* ci.yml's core-compat comment describes every module its list runs: the
+  v0.46.0 follow-ups added comment-hyphens, flags-wiring, and
+  flags-real-core to the module list without touching the enumeration
+  above it, so a reader reconciling comment against list found three
+  orphans.
+* The plugin's `customization_help` names `max_log_mb`: the rotation cap
+  is documented in the README and honored by the log writer, but the
+  in-Calibre customization dialog never mentioned the key. Rides the
+  release-attached plugin zip.
+* Suite: 544 -> 575 tests since v0.46.0 (the two follow-up wiring-test
+  commits, unpinned in that entry's count), all green on this text-only
+  sweep.
+## v0.46.0 (2026-10-02)
+
+### The last open repair class closes: RSC-016, plus the RepairFlags refactor
+
+* **`--fix-comment-double-hyphen` (new structural repair, in the `--all` set)**: a `--` inside an XML comment is illegal XML (epubcheck fatal RSC-016, "The string \"--\" is not permitted within comments"), so such a book parses in lenient readers and never passes epubcheck. The fix replaces each `--` with an en-dash inside comment bodies only: text nodes are never touched (a `--` in character data is legal XML), CDATA sections stay protected, and every comment's `-->` terminator stays intact (the span ends there, so the replacement cannot reach it). It applies to content documents, the NCX, and the OPF alike, and each replaced sequence is counted under the `fixes` key `fix_comment_double_hyphen` (an additive key; CalibreQuarry's lossy-consent mirror reads the dict with `.get()` over its fixed lossy-marker tuple, so the new key is tolerated as structural, verified in `cquarry_cli/run.py`). It is the sixteenth structural repair, built exactly to the 2026-09-16 classics-wave box's recorded design: the Theaetetus hand-rescue's en-dash half, now native. The normal `gate` accepts it (clearing the fatal IS the measurable gain; verified against epubcheck 5.x on a synthetic book: 1f/1e -> 0f/1e), and the never-rewrite-comments invariant gains its one documented exception in spec.md.
+* **`RepairFlags` (internal)**: the opt-in selection that used to be a ~25-kwarg signature triplicated across `repair_epub`, `process_book`, and the CLI's per-verb call sites is now one dataclass (`epub.RepairFlags`, one field per flag, all off by default; the all-off instance IS the default pass). `cli._flags_from_args` is the single argparse-to-fields mapping, shared by `library` and `repair`; the EPUB2-targeted fixes' package-version gate swaps in a `dataclasses.replace` copy, so a caller's instance is never mutated. No surface change: the CLI flags, the gate, and the JSON records are untouched (end-to-end and byte-determinism verified against real epubcheck). One API note for in-repo consumers: `bindery.epub.repair_epub` and `bindery.cli.process_book` now take `flags=RepairFlags(...)` instead of keyword flags; the plugin's bare `repair_epub(src, dst)` call constructs exactly the default pass.
+* Suite: 524 -> 544 tests (`tests/test_comment_hyphens.py`: transform units, end-to-end over content/NCX/OPF, and the gate on both sides; the flag-wiring tuples pin the new flag).
 ## v0.45.0 (2026-09-21)
 
 ### The structured fix breakdown in the JSON records
@@ -19,7 +54,7 @@
 
 * **`--encode-url-spaces` gained its rename half**, the biggest real-prevalence repair class left (PKG-010: 8,237 occurrences in 284 books at the 2026-09-17 refresh). Archive entries whose names carry raw spaces are renamed to their underscore spellings and every reference is rewritten (OPF, NCX, content `src`/`href`, stylesheet `url()`). The design was decided by experiment, not by the roadmap box's plan: epubcheck 5.3 DECODES references before entry lookup, so percent-encoded entries are unfindable by the encoded references pointing at them (all four raw/percent/underscore combinations built and checked); underscore on both sides resolves and clears PKG-010. Ambiguous renames are refused per entry (a target that already exists, two names converging, a duplicated archive name), a book with any non-UTF-8 document refuses all of its renames, a renamed OPF regenerates a stale container, and the acceptance rides `no_worse` because the gain sits on the warning axis the improvement gate does not measure (same bar as `--fix-cover`).
 * **The matcher fix that explains Theaetetus** (the 2026-09-16 hand-rescue): the encode pass's value class `[^"']` stopped at apostrophes inside double-quoted hrefs, so the 270 raw-space OPF hrefs never matched and the fatal survived. The matcher now takes the tempered-quote idiom (possessive, house style), and an apostrophe in a double-quoted filename is ordinary.
-* **`bindery audit cover`** (advisory, the EPUB3 half of the ruled hybrid): dangling EPUB2 `<meta name="cover">` (the `--fix-cover` class), the EPUB3 `properties~="cover-image"` declaration, and whether the named cover file exists. **`bindery audit tocdrift`**: the structural diff between the NCX navMap and the EPUB3 nav toc, keyed on the full target including fragments -- entries each side is missing plus label mismatches. Both never flag a book and never move the exit code; ToC synthesis stays out of the repair charter permanently. The loader exposes the parsed OPF, the NCX text, and the nav HTML on `Book`.
+* **`bindery audit cover`** (advisory, the EPUB3 half of the ruled hybrid): dangling EPUB2 `<meta name="cover">` (the `--fix-cover` class), the EPUB3 `properties~="cover-image"` declaration, and whether the named cover file exists. **`bindery audit tocdrift`**: the structural diff between the NCX navMap and the EPUB3 nav toc, keyed on the full target including fragments: entries each side is missing plus label mismatches. Both never flag a book and never move the exit code; ToC synthesis stays out of the repair charter permanently. The loader exposes the parsed OPF, the NCX text, and the nav HTML on `Book`.
 * **The audit-refresh deep-dive ran** (read-only FastSweep extract over the full 5,228-book library; raw report in the facility): RSC-005 164,302 -> 13,782 occurrences, RSC-007 3,219 -> 14,162 in 604 books (the classics-wave imports), RSC-020 9,953 in 337 books, PKG-010 8,237 in 284 books (population flat: the rename class was still live, hence this ship).
 * **The roman grammar is one copy again**: pagination.py is the canonical home (it vendors into the plugin; audit does not), audit.py imports `ROMAN_RE`/`ROMAN_MAX`/`roman_value`, and the two byte-identical copies cannot drift. The RepairFlags dataclass refactor stays boxed with its reason (pure churn on the signatures this release touched).
 * Suite: 497 -> 521 tests (tests/test_space_renames.py, tests/test_cover_tocdrift.py, and the updated `--encode-url-spaces` end-to-end pins).
@@ -28,13 +63,13 @@
 
 ### The stdlib XML hardening: untrusted metadata is bounded and entity-refused, no dependency
 
-* **`--audit` and every `load_book` caller no longer decompress blind.** Two protections, both stdlib-only (the defusedxml dependency stays declined): single entries whose declared size exceeds `_MAX_ENTRY_BYTES` (32 MB) are refused before decompression -- a bomb entry in a tiny zip cannot be downloaded into memory -- and the untrusted metadata files (container.xml, OPF, encryption.xml) parse through `_safe_xml_parse`, which refuses DOCTYPE/ENTITY declarations before xml.etree sees them. A refused or unparseable metadata file returns the shell book (the archive verdict is the book's whole story), never a hang or a traceback.
+* **`--audit` and every `load_book` caller no longer decompress blind.** Two protections, both stdlib-only (the defusedxml dependency stays declined): single entries whose declared size exceeds `_MAX_ENTRY_BYTES` (32 MB) are refused before decompression (a bomb entry in a tiny zip cannot be downloaded into memory), and the untrusted metadata files (container.xml, OPF, encryption.xml) parse through `_safe_xml_parse`, which refuses DOCTYPE/ENTITY declarations before xml.etree sees them. A refused or unparseable metadata file returns the shell book (the archive verdict is the book's whole story), never a hang or a traceback.
 * Pinned by `tests/test_xml_hardening.py` (entity-bomb container returns the shell book; clean XML parses; the entry cap is sane). The defusedxml dependency ask is closed as declined with the stdlib shape delivered.
 
 ## v0.42.0 (2026-09-16)
 
 ### The matcher audit executed: every quote-aware tag matcher hardened
-The follow-up box the 0.41.1 hotfix opened is closed with a full per-matcher census, and the audit found the box's own enumeration incomplete. Six GREEDY patterns of the exponential overlap class were unhardened -- `_START_TAG_RE` (the quote-aware start-tag matcher anchoring `--strip-epub3-attrs` and `--strip-bad-attrs`, running under `repair --all` on every content doc; not even named in the box), `_COVER_META_RE`, `_GUIDE_REF_RE`, `prune_dangling_edges`' spine|item|itemref matcher, `_ITEM_TAG_RE`, and `_SPINE_ITEM_RE`. All six are possessive-bounded now: byte-identical on every successful match (the loop is always followed by a literal `>` that the `[^>]` branch cannot consume, so backtracking only ever happened on failure) and linear on failure. Five LAZY patterns of the quadratic class (`_VOID_RE`, the transforms `<img>` matcher, and epub's link/anchor/img matchers) took the disjoint catch-all `[^>"']` instead of a blind possessive swap: mutually exclusive branches cannot re-partition, so any quantifier is linear, and an unterminated quote inside a tag now fails to match instead of pairing with a distant quote and matching across markup. Every well-formed shape is byte-identical. The epub `_IMG_TAG_RE` is renamed `_PRUNE_IMG_TAG_RE` (it collided with the transforms matcher of the same name). Everything else in the package audited safe by construction: tempered-quote value matchers, two-branch quote alternations, `[^>]*` single-class prefixes (linear, not quote-aware -- accepted, documented), lazy paired-delimiter spans, and the analyzer tokenizers.
+The follow-up box the 0.41.1 hotfix opened is closed with a full per-matcher census, and the audit found the box's own enumeration incomplete. Six GREEDY patterns of the exponential overlap class were unhardened: `_START_TAG_RE` (the quote-aware start-tag matcher anchoring `--strip-epub3-attrs` and `--strip-bad-attrs`, running under `repair --all` on every content doc; not even named in the box), `_COVER_META_RE`, `_GUIDE_REF_RE`, `prune_dangling_edges`' spine|item|itemref matcher, `_ITEM_TAG_RE`, and `_SPINE_ITEM_RE`. All six are possessive-bounded now: byte-identical on every successful match (the loop is always followed by a literal `>` that the `[^>]` branch cannot consume, so backtracking only ever happened on failure) and linear on failure. Five LAZY patterns of the quadratic class (`_VOID_RE`, the transforms `<img>` matcher, and epub's link/anchor/img matchers) took the disjoint catch-all `[^>"']` instead of a blind possessive swap: mutually exclusive branches cannot re-partition, so any quantifier is linear, and an unterminated quote inside a tag now fails to match instead of pairing with a distant quote and matching across markup. Every well-formed shape is byte-identical. The epub `_IMG_TAG_RE` is renamed `_PRUNE_IMG_TAG_RE` (it collided with the transforms matcher of the same name). Everything else in the package audited safe by construction: tempered-quote value matchers, two-branch quote alternations, `[^>]*` single-class prefixes (linear, not quote-aware; accepted, documented), lazy paired-delimiter spans, and the analyzer tokenizers.
 
 Pinned by `tests/test_matcher_hardening.py` (15 tests): alarm-guarded spin shapes per greedy site (OPF flavor, the truncated-OPF prune shape), unterminated-quote skips, and well-formed byte-identity. `CLAUDE.md`'s hazard note now carries the census and the rule for new matchers. The full suite is 491 tests.
 

{bindery_cli-0.45.0 → bindery_cli-0.46.1}/plugin/__init__.py

@@ -270,7 +270,9 @@ class BinderyRepair(FileTypePlugin):
     def customization_help(self, gui=False):
         return (
             'Enter a JSON object: {"log": true, "log_path": ..., '
-            '"max_size_mb": 150, "epubcheck_path": null}. '
-            "epubcheck_path enables the experimental post-repair validation "
-            "with the epubcheck binary (slow; off by default)."
+            '"max_size_mb": 150, "max_log_mb": 2, "epubcheck_path": null}. '
+            "max_log_mb is the log rotation cap in MB (default 2, one .old "
+            "generation kept, 0 disables). epubcheck_path enables the "
+            "experimental post-repair validation with the epubcheck binary "
+            "(slow; off by default)."
         )

{bindery_cli-0.45.0 → bindery_cli-0.46.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.45.0"
+version = "0.46.1"
 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.46.1/roadmap.md

@@ -0,0 +1,212 @@
+# bindery-cli roadmap
+
+*Phase numbers are historical identifiers, not an order: the campaign added phases
+non-monotonically and two distinct efforts both carry "Phase 4". Cross-repo notes
+cite them, so the ledger keeps the identifiers.*
+
+**Minimized 2026-09-29 (the cquarry precedent).** Phases 1-16, the supplementary
+audit section, the bug-report waves, and every audit block are shipped; their full
+text is preserved in git at the tree of commit 157afc9 (the last full roadmap) and
+the release-by-release record is `patchnotes.md`. This file keeps the ledger, the
+open work, the records that live nowhere else, and the parity dispositions.
+
+Standing rules: `spec.md` is the contract (deterministic, semantics-preserving,
+epubcheck-gated repairs; opt-in lossy lane; dry-run default; atomic replacement).
+The plugin vendors the core and never gates (the epubcheck latency ruling).
+`tests/test_version.py` pins the version carriers.
+
+## Completed phases (ledger)
+
+| Phase | Scope | Shipped |
+|---|---|---|
+| 1 | Deterministic repair engine: transforms, NCX-001, mimetype repair, the two-mode epubcheck gate, `repair`/`library` modes, atomic in-place replacement with backups, dry-run default | v0.1.0 |
+| 2 | The long tail: unclosed non-void elements (`--reserialize`), unbound namespaces (`--strip-bad-attrs`), digit-led/colon ids (`--fix-ids`), JSON reports + `--manual-list`, `--sweep` re-audit integration | v0.2.0-v0.7.0 |
+| 4 (lossy) | `--strip-pagination`: the fenced lossy lane's first member (confident interrupts, character conservation, `no_worse`) | v0.5.0 |
+| 5 | Audit fixes and hardening: the partial-classification bug, per-book exception isolation, id-anchor preservation, html5lib as an extra, the epubcheck locale/JSON hardening (5.2; cited by tests/test_validate.py), UX batch (progress, warnings, exit codes, `--limit`), mimetype/unknown-entity/NCX-ids/`--add-img-alt` additions, the void-end-tag spec gap | v0.6.0-v0.10.0 |
+| 3 | Calibre plugin ("Bindery Repair", `FileTypePlugin` `on_import`): the decided shape (see Records kept), scoped vendor slice, byte-idempotence, per-release zip attachment | v0.37.0 |
+| Suppl. | Library-audit schemas: `--fix-id-colons`, `--fix-empty-body`, `--fix-missing-title`, `--unwrap-block-in-inline`, `fix_ncx_playorder`, `--strip-invalid-value` (all opt-in since v0.17.0; `--add-img-alt` deliberately never defaulted) | v0.14.0 |
+| 4 (cquarry) | cquarry integration: `get_format_path()` resolution, the `--tag` write path, `audit --id` single-book mode | v0.18.0-v0.19.0 |
+| 6 | Code sweep: the content-loss fix, `--replace` crash, dead method, java pin removal, regex bounds, opt-in decoupling, CSS-aware unwrapping | v0.16.3-v0.19.0 |
+| 7 | `monolithic` analyzer + the version-sync pin (`tests/test_version.py`) | v0.21.0 / v0.19.2 |
+| 8 | `library --id` batch scoping, spine-integrity classification (convention vs fragment), `audit --id` comma lists; `--workers` made real in v0.30.0, the daemon pool in v0.35.0 | v0.23.0 |
+| 9 | Archive integrity: the CRC sweep with its own CORRUPT verdict (never mislabeled EMPTY), the unreadable sub-reason split | v0.22.0 |
+| 10 | OPF/NCX edges: `--fix-page-map`; the RSC-005 EPUB3 scrubs (`--strip-epub3-attrs`, `--downgrade-epub3-tags`), ruled Option B | v0.25.0-v0.27.0 |
+| 11 | install-to-calibre on the native cquarry write module (`install_format`/`set_format`; the calibredb subprocess retired) | v0.24.0 |
+| 12 | Top-error repairs: `--prune-missing-resources`, `--strip-broken-anchors`, the HTM-025 half, the FastSweep harness; bulk RSC-005 rejected (see Records kept) | v0.28.0 |
+| 13 | Machine-readable audit (`audit --json`) + the `run phase1`/`run phase3` acquisition slices + the non-interactive contract | v0.29.0 |
+| 14 | Hardening from the 2026-09-08 sweep: anchored/quote-aware regexes, `fix_id_colons` honesty + NCX follow, CDATA/comment protection everywhere, strict UTF-8, `--reserialize` html-root scoping, the watermark/roman/install/EPUB3-gate bug fixes, audit ToC accounting inside the open zip, the "unify on trouble" exit ruling, backup rotation + out-of-tree refusal, the daemon pool, docs reconciliation, the test-suite cleanups | v0.32.0-v0.35.0 |
+| 15 | `audit completeness` spot-check analyzer (trailing-ToC, prose sampling), fixtures from the Redwall run | v0.36.0 |
+| 16 | Package-structure repairs: the prevalence study, `--fix-container`, the OBFUSCATED vs DRM verdict split, prune edge completion, `--fix-media-types`, `--fix-cover` (the ruled hybrid), the boxed classes below | v0.38.0-v0.39.0 |
+| Waves 15 + blitz | The plugin PEP-758 HIGH + the 3.11-3.14 interpreter matrix, analyzer robustness, the per-matcher census (possessive bounding; cited by tests/test_matcher_hardening.py), stdlib XML hardening, FastDaemon v2 (reconcile-not-retire), `--strip-stub-docs`, `bindery doctor` + `repair --json`, `--encode-url-spaces` entry renames, the cover + tocdrift analyzers, the privacy/GitHub/docs/comment/hygiene batches, requires-python 3.12 with markers, the em-dash sweep | v0.40.0-v0.44.0 |
+| 0.45 | Structured fix records (`fixes`, `ncx_uid_synced`, `watermark_refusals`) in every JSON payload; CalibreQuarry consumes them with the 0.45.0 floor | v0.45.0 |
+| 0.46 | RSC-016 `--fix-comment-double-hyphen` (the last open repair class) and the RepairFlags dataclass | v0.46.0 |
+
+## Open work
+
+- [ ] **Obfuscation-aware encryption.xml repair**: prune stale obfuscation entries
+      when font magic bytes prove the fonts are decrypted in place; drop
+      encryption.xml when only obfuscation entries remain and fonts verify. NEVER
+      un-obfuscate. *(BOXED with real counts, 2026-09-12: 424/424 readable
+      obfuscation fonts genuinely scrambled, zero stale entries in-library; the
+      precondition is validated and recognition carries both Adobe URI spellings.
+      The audit half SHIPPED v0.38.0 as the OBFUSCATED verdict. Opens only if
+      acquisition ever brings a decrypted-in-place book.)*
+- [ ] **href case/backslash resolution**: case-insensitive namemap when exactly one
+      zip entry matches; backslash to slash. Kills the present-file
+      RSC-007/PKG-010 slice prune cannot touch. *(BOXED with real counts,
+      2026-09-12: exactly 1 case-mismatch href in 1 book and 0 backslash hrefs
+      across the library; reopen if acquisition changes the mix.)*
+- [ ] **Duplicate zip-entry dedupe on rewrite**: drop shadowed duplicates (audit
+      already counts `dup_entries`). *(BOXED with real counts, 2026-09-12: 0 books
+      with duplicate entries in-library.)*
+- [ ] **CSS url() pruning** as a `--prune-missing-resources` scope extension:
+      stays closed until a named epubcheck finding demands it (the 2026-09-12
+      prevalence read found selector damage, not url() candidates).
+- [x] **Candidate transform: `--` inside XML comments (RSC-016 fatal)**. A
+      `fix_comment_double_hyphen` transform (comment nodes only, `--` -> en-dash,
+      byte-counted) would make the always-on core able to parse such books at all;
+      until then the book parses in lenient readers but never passes epubcheck.
+      Low frequency (one book in the classics wave); the fixture reference is in
+      git history. *(SHIPPED v0.46.0 as the opt-in `--fix-comment-double-hyphen`
+      structural repair: comment bodies only in content documents, the NCX, and
+      the OPF; the `-->` terminators stay intact; normal `gate`. Not a core
+      transform: it edits comment content, which everything else protects.)*
+- [x] **RepairFlags dataclass** for the triplicated ~25-kwarg
+      process_book/repair_epub signature. Deferred with reason: pure churn on that
+      surface immediately after the v0.44 batch touched exactly those signatures;
+      do it as a standalone lane with the full suite and the plugin byte-compat
+      job green at every step, not as a rider. (The roman/arabic half of its parent
+      box resolved to UNIFY at pagination.py, v0.44.0.) *(SHIPPED v0.46.0 as its
+      own commit, exactly by that method: dataclass in epub.py, repair_epub, then
+      process_book, then `cli._flags_from_args` collapsing the per-verb kwarg
+      blocks, suite green at every step; the plugin's bare repair_epub call and
+      byte-compat unchanged.)*
+- [ ] **MobileRead listing for the Bindery Repair plugin** (Brandon's manual
+      step): post the listing with name/identity, the release-attached zip,
+      minimum Calibre 7.0, Linux platform note. Posting is outward-facing under
+      his name.
+- [ ] **README screenshot regeneration** (Brandon's call pending): rebuild
+      docs/screenshots/library-sweep.png against a synthetic testing_facility
+      library (invented titles, real dry-run output); the current PNG shows 16
+      real rows. Asked 2026-09-15, unanswered.
+- [x] **The 2026-10-02 closing sweep** (the four-lane verification's doc
+      findings against the v0.46.0 tree): the safety contract's lossy
+      enumeration names all four modes, the core-compat em-dash is gone,
+      ci.yml's module comment covers all eleven stack-free modules, and the
+      plugin's `customization_help` names `max_log_mb`. *(SHIPPED v0.46.1:
+      text plus the one plugin string; no surface change.)*
+
+## The repair domain in the ecosystem parity program (recorded 2026-09-29)
+
+Brandon opened the ecosystem Calibre-parity program on 2026-09-29 (cquarry roadmap.md,
+"The parity program"; parity counts native coverage plus orchestration of Calibre's own
+headless tools, and excludes process-bound and declined surface with recorded reasons).
+bindery-cli's lane is the repair/acceptance domain, where this repo is already past
+parity with Calibre's own tooling: ebook-polish has no acceptance oracle, no determinism
+contract, and no atomic library replacement; bindery has all three, plus native
+metadata.db registration and the Calibre plugin. Dispositions recorded under the program:
+
+- **Conversion stays out, permanently** (spec.md:10-14): Calibre's conversion engine
+  (~45 input / ~20 output formats) is orchestration-lane territory (CalibreQuarry
+  `run convert`); bindery never grows one, and no parity claim depends on it.
+- **The ebook-polish content-improving actions bindery lacks stay declined**:
+  embed/subset fonts, jacket, smarten punctuation, remove-unused-css, compress-images,
+  upgrade-book, download-external-resources, the --opf rewrite, --cover. They are
+  content-improving rather than repair, and dc: metadata editing is out of charter
+  (spec.md:597). Recorded here so the parity ledger's bindery row names them declined,
+  not missing.
+- **The `data`-row waiver note**: bindery has updated `data` rows through
+  `WritableCalibreDB.set_format` since v0.24.0 (the sanctioned install path);
+  cquarry's conditional write-back waiver was reworded 2026-09-29 to name what it
+  actually guards: a bindery-side book-metadata write-back convenience, still declined.
+- **Parity-relevant accepted gaps**: RSC-016 (`--` inside XML comments) SHIPPED
+  v0.46.0 as `--fix-comment-double-hyphen` (the candidate box above), so no open
+  repair class blocks epubcheck acceptance on prevalence anymore; the
+  prevalence-gated classes (encryption.xml, href case/backslash,
+  zip dedupe, CSS url()) reopen only on acquisition mix. The RepairFlags refactor shipped
+  v0.46.0 (the ticked box above).
+- **Brandon-parked items are unchanged**: the MobileRead plugin listing and the README
+  screenshot regeneration stay his; the program does not schedule them.
+
+## Records kept (decisions and counts that live only here)
+
+- **The plugin shape decision** (2026-08-09, researched against the Calibre source;
+  corrected 2026-09-05; shipped v0.37.0): `FileTypePlugin` with `on_import`:
+  `run(path)` returns a `temporary_file()` replacement before the file lands, so the
+  original on disk is never touched and metadata.db is never written. A raising plugin
+  cannot abort an import and cannot lose the file, but the failure is silent, so the
+  plugin never raises and keeps its own log under the Calibre config dir.
+  `supported_platforms = ['linux']` (the loader rejects an empty declaration). The hook
+  also fires on `add_format`, so the plugin is byte-idempotent. The vendor slice
+  (transforms/epub/pagination/watermark/reserialize + a plugin `__init__`) is
+  generated at release from the tagged tree with a byte-equality drift test. Active
+  set = the gate-safe default pass only: every structural repair and the four
+  lossy strips stay CLI-only, because epubcheck cannot gate inside Calibre (no jar/JVM
+  and seconds-per-book latency). Config via `site_customization` JSON (`log`,
+  `log_path`, `max_size_mb`, recorded default 150MB); `publish.yml` attaches
+  `BinderyRepair-v<VERSION>.zip` to each release.
+- **The metadata-validity carve-out ruling** (Brandon, 2026-09-12): route to
+  cquarry/CalibreQuarry; bindery's side is closed and dc: metadata stays a non-goal.
+  The routed half (51 OPF-085 invalid-UUID warnings plus the thin date/language tail)
+  is CalibreQuarry's lane (recorded in its roadmap; its 3.41/3.42 audit rows found the
+  classes clean at the DB level, the warnings file-side).
+- **Prevalence baselines** (2026-09-12 study over 5,228 books; 2026-09-17 refresh):
+  RSC-005 164,302 -> 13,782 occurrences; RSC-007 14,156 in 600 books; RSC-020 9,953
+  in 337; PKG-010 8,237 in 284 (population flat, the rename class stayed live, hence
+  v0.44.0); container.xml valid 5,228/5,228; case-mismatch hrefs 1 in 1 book;
+  backslash hrefs 0; duplicate zip entries 0 books; encryption.xml in 86 books (426
+  Adobe + 3 IDPF obfuscation entries; 424/424 readable obfuscated fonts genuinely
+  scrambled at offset 0; the wild Adobe URI is `http://ns.adobe.com/pdf/enc#RC`, and
+  recognition carries both spellings); NO real-DRM algorithm anywhere in the library.
+- **The exit-code contracts:** argparse-level misuse exits 2 before the tool's
+  validation; the tool's own usage errors exit 1; trouble (rejected + errors +
+  unreadable + partial books) exits 2 in all three layers by the 2026-09-10 "unify on
+  trouble" ruling (option A of the recorded pair).
+- **The daemon decision** (2026-09-10): RECONCILE, not retire. The counting divergence
+  ran deeper than the daemon (the human summary counts message occurrences, epubcheck's
+  JSON counts aggregated messages, and the gate has always measured the aggregated
+  scale), so FastDaemon v2 reads the JSON epubcheck itself serializes and measures the
+  subprocess oracle's numbers exactly; the launch is Java's single-file source launcher
+  (no javac, no version skew); warm throughput ~0.27s/book vs ~4.2s/book subprocess.
+  Shipped v0.35.0.
+- **requires-python ~3.12** (decision 63, executed v0.40.0): every cquarry/vir-tui on
+  PyPI declares >=3.14, so the VirInvictus pins carry
+  `; python_version >= '3.14'` markers (3.14 installs byte-identical); 3.12/3.13
+  installs run the stack-free repair core; the CLI dispatch guard turns a missing
+  stack into one stderr line + exit 2; CI byte-compiles the plugin zip under
+  3.11/3.12/3.13/3.14; `minimum_calibre_version` is (7, 0, 0).
+- **Tag policy** (decided 2026-09-11, recorded 2026-09-12): v0.35.0 is the anchor;
+  every release from v0.36.0 on is tagged at its release commit under auto-tag
+  promotion. The nine untagged 0.18.0-0.26.0 entries are exempted by decision of
+  record (no backfill tags; patchnotes and PyPI carry them). Executed 2026-09-12: the
+  v0.28.0 tag re-pointed at its first green commit with its title line restored, the
+  v0.33.0 tag message corrected verbatim, and the 10 test_facility EPUBs stripped from
+  all history via git filter-repo (main + 14 tags force-pushed; PyPI untouched).
+- **Privacy record:** top500candidates/REPORT.md is untracked forward-only (Brandon's
+  ruling, no history strip); the file stays on disk as the fast_sweep `--summary`
+  target. Reopen condition: the history-strip recipe (rewrite 16 release tags,
+  publish.yml disabled around the push) if the reachable copy is ever judged
+  unacceptable (also in project.done).
+- **The matcher census** (v0.42.0; cited by tests/test_matcher_hardening.py): six
+  greedy exponential-class sites possessive-bounded (`_START_TAG_RE`, `_COVER_META_RE`,
+  `_GUIDE_REF_RE`, the prune spine matcher, `_ITEM_TAG_RE`, `_SPINE_ITEM_RE`); five
+  lazy quadratic-class sites took the disjoint `[^>"']` catch-all (`_VOID_RE`, the
+  transforms `<img>` matcher, epub's link/a/img matchers); everything else audited
+  safe by construction. Never a third grammar copy: pagination.py is the canonical
+  roman/number home (it vendors into the plugin; audit imports from it), and any
+  future divergence is a decision at pagination.
+- **Non-goals kept with reasons:** ToC synthesis is out of the repair charter
+  permanently (tocdrift is detector-only); conversion is out permanently (the parity
+  section above); dc: metadata editing is out (spec); bulk RSC-005 rejected (164,302
+  instances; narrowly bounded sub-cases stay opt-in under their own flags); no
+  spine-item manifest pruning (missing spine documents mean corrupt archives or broken
+  fragments); no text deletion in anchor unwrapping (character conservation is
+  absolute); no auto-split of monolithic docs and no auto-trim of bloated ToCs (flag
+  and re-source); no repair of corrupt archive entries (re-source, never repair); no
+  PDF/DJVU work (never this repo's charter); `--add-img-alt` stays opt-in
+  (`alt=""` asserts "decorative" to screen readers); defusedxml stays declined (the
+  stdlib `_safe_xml_parse` delivers the entity protection and the vendored-plugin cost
+  was the real objection; the full-parser swap is Brandon-gated on a real 3.12/3.13
+  stranger audience); the plugin never gates on epubcheck (the latency ruling); no
+  manifest format ownership (CalibreQuarry owns `acquisition-manifest` and the
+  orchestration).