bindery-cli 0.63.0__tar.gz → 0.64.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/AGENTS.md +4 -3
  2. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/OBSERVE-RESEARCH.md +69 -0
  3. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/PKG-INFO +2 -1
  4. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/README.md +1 -0
  5. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/patchnotes.md +66 -0
  6. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/pyproject.toml +1 -1
  7. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/roadmap.md +5 -0
  8. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/spec.md +21 -3
  9. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/__init__.py +1 -1
  10. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/cli.py +19 -0
  11. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/epub.py +91 -0
  12. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/transforms.py +11 -2
  13. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_epub.py +119 -0
  14. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_flags_real_core.py +19 -0
  15. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_flags_wiring.py +1 -0
  16. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/uv.lock +1 -1
  17. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/.github/FUNDING.yml +0 -0
  18. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/.github/workflows/ci.yml +0 -0
  19. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/.github/workflows/publish.yml +0 -0
  20. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/.gitignore +0 -0
  21. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/LICENSE +0 -0
  22. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/docs/screenshots/library-sweep.png +0 -0
  23. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/logo.svg +0 -0
  24. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/plugin/__init__.py +0 -0
  25. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/project.done +0 -0
  26. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/run_tests.sh +0 -0
  27. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/scripts/FastSweep.java +0 -0
  28. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/scripts/build_plugin.py +0 -0
  29. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/scripts/fast_sweep.py +0 -0
  30. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/__main__.py +0 -0
  31. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/audit.py +0 -0
  32. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/library.py +0 -0
  33. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/observe.py +0 -0
  34. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/pagination.py +0 -0
  35. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/reserialize.py +0 -0
  36. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/validate.py +0 -0
  37. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/watermark.py +0 -0
  38. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_audit.py +0 -0
  39. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_cli.py +0 -0
  40. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_comment_hyphens.py +0 -0
  41. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_contamination.py +0 -0
  42. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_cover_tocdrift.py +0 -0
  43. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_help.py +0 -0
  44. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_library.py +0 -0
  45. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_matcher_hardening.py +0 -0
  46. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_observe.py +0 -0
  47. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_pagination.py +0 -0
  48. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_plugin.py +0 -0
  49. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_reserialize.py +0 -0
  50. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_space_renames.py +0 -0
  51. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_spine_guard.py +0 -0
  52. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_transforms.py +0 -0
  53. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_validate.py +0 -0
  54. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_version.py +0 -0
  55. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_watermark.py +0 -0
  56. {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_xml_hardening.py +0 -0
@@ -30,7 +30,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
30
30
  `xmlns`, bare `&`, named entities, void self-closing), the NCX pipeline, and the
31
31
  mimetype fix (added/normalized/first-stored, epub.py's archive rewrite); every core
32
32
  fix must render identically to the author's intent: never add, remove, or reorder
33
- visible content. The canonical opt-in inventory lives in spec.md: thirty-two structural
33
+ visible content. The canonical opt-in inventory lives in spec.md: thirty-three structural
34
34
  repairs, four lossy strips, five safe opt-ins, plus `--reserialize` (the
35
35
  seven v0.62.x/v0.63.0 flags -- `--fix-package-version`, `--fix-doctype`,
36
36
  `--prune-invalid-guide-refs`, `--fix-item-properties`,
@@ -47,7 +47,8 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
47
47
  `--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr`,
48
48
  `--fix-unbound-prefix`, `--fix-package-version`, `--fix-doctype`,
49
49
  `--prune-invalid-guide-refs`, `--fix-item-properties`,
50
- `--strip-presentational-attrs`, `--encode-ref-brackets`;
50
+ `--strip-presentational-attrs`, `--encode-ref-brackets`,
51
+ `--prune-dead-spine`;
51
52
  transforms.py, threaded through epub.py). The v0.47.0 five (the 2026-10-06
52
53
  issue batch): `--fix-svg-dup-ids` renames duplicate glyph ids inside
53
54
  standalone `.svg` entries (first keeps its name, references resolve to the
@@ -232,7 +233,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
232
233
  - `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets).
233
234
  - `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
234
235
  - `src/bindery/reserialize.py`: structural repair via `html5lib`.
235
- - `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, `shell` since v0.63.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).
236
+ - `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, `shell` since v0.63.0, v0.64.0 wires `--prune-dead-spine` (the shell repair, 50%-signature-gated, playOrder force re-sequence)) 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).
236
237
  - `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.59.0 (issue #23) `strip_ncx_dangling_targets` is the NCX dangling-target prune (`--prune-dangling-ncx-targets`): a balanced stack scanner over navPoint/navTarget/pageTarget tokens (quote-aware possessive regex, `_NcxTargetNode` tree, iterative post-order survival pass; header_end delimits the node's own navLabel+`<content>` so a splice removes the tags AND the dead header while the children re-home; an unbalanced walk aborts the part unchanged) and the NCX branch re-runs `fix_ncx_playorder` when it fires, alongside the anchor pass's own re-run. Since v0.58.0 (issue #18) the copy loop hands every `zout.writestr` a PRIVATE ZipInfo (`copy.copy(item)`, a fresh one on a rename) and the media-type `peek` catches `zipfile.BadZipFile` too. HAZARD: `writestr` STAMPS the ZipInfo it is handed with the DESTINATION offsets (header_offset, sizes land on it for the central directory); sharing the source's info repointed zin's own name lookups into the output file mid-loop, and one drifted probe killed whole books as "unreadable" -- 56 books "Bad magic number for file header" plus the "possible zip bomb" Development as Freedom (the drifted offset landed on a valid header whose data overlaps its neighbor), all one root cause. Since v0.58.0 (issue #21) `strip_broken_guide_fragments` gives the OPF guide the NCX fragment-strip's document-precision fallback, and the NCX branch re-runs `fix_ncx_playorder` after the anchor pass fires (the pre-strip sequence goes stale when fragments collapse onto their document). Since v0.58.0 (issue #20) `_resolve_href` decodes the five predefined XML entities plus numeric
237
238
  character references before the fragment split (attribute text arrives
238
239
  escaped; entries are raw; decoding first keeps the `#` inside `&#38;`
@@ -675,3 +675,72 @@ rejection is package-profile-driven, not DOCTYPE-driven (7 EPUB3 packages
675
675
  carrying XHTML 1.1 doctypes: zero attribute findings; every role/
676
676
  aria-hidden carrier is version="2.0"), so `package_version()` gating is
677
677
  correct as built and only the set grew (`role`, `aria-hidden`).
678
+
679
+ ## The Wandering Inn shells: documented, detected, handled manually (2026-11-04)
680
+
681
+ The two Pirateaba serial compilations (Book 18, Book 19) are the library's
682
+ RSC-001 mass: 738 and 736 of their 755/752 manifest items name files the
683
+ archive never carried (98% of the manifest; verified by content walk, NOT a
684
+ spelling mismatch — the 2026-10-25 "different spelling" hypothesis is
685
+ falsified for these two). The archive is a shell: the converter wrote the
686
+ series-wide manifest and shipped a sliver. The spine guard was CORRECT to
687
+ refuse — a repair cannot fabricate 738 files, and dropping the dead spine
688
+ positions would remove the errors from the measurement while the reader
689
+ loses nothing it ever had. Brandon's ruling: these are the best copies
690
+ available; handle manually, document the signature, detect future shells.
691
+
692
+ The detector ships as the audit battery's `shell` analyzer (v0.63.0):
693
+ spine-missing fraction at or over 50% reads `SHELL: re-source, never
694
+ repair`, advisory by contract. Live: `bindery audit all --id 8889` names
695
+ the shell. Known display quirk: the percentage divides by the RESOLVED
696
+ spine count (14), not resolved+missing (752), so shells read over 100%
697
+ — cosmetic, the verdict fires correctly. Manual handling pending:
698
+ re-source both books when a better copy surfaces.
699
+
700
+ ### The shell-repair feasibility dig (2026-11-05, facility copies)
701
+
702
+ Falsified the "different spelling" hypothesis for good: Book 19's archive
703
+ carries 14 REAL full-size chapters (0448_743 through 0461_755 — the
704
+ book's exact serial range, 118-156KB each of real prose), and Book 18
705
+ likewise (19 docs, chapters 730-742). The converter shipped the correct
706
+ chapter range but wrote the ENTIRE serial manifest: 738/755 and 736/758
707
+ manifest items name files that were never this book's chapters. The
708
+ "missing" files were never missing from anything — they belong to the
709
+ other books.
710
+
711
+ Feasibility verdict for a suite repair: PROVEN by hand-surgery on the
712
+ Book 19 copy. The recipe (NCX prune via the existing flag + drop the
713
+ dead manifest items and dangling itemrefs + playOrder re-sequence to
714
+ 1..K + the doctype/title fixes) lands the book at 0f/5e — from
715
+ 0f/742e — as a complete, coherent EPUB of its own chapters. All
716
+ deterministic. The flag design (`--prune-dead-spine`, shell-gated at
717
+ the audit's 50% signature so a lone missing chapter never fires it):
718
+ dead manifest content items + dangling itemrefs dropped, then the
719
+ existing fix_ncx_playorder coordination, then the guide-empty
720
+ coordination with prune_invalid_guide_refs.
721
+
722
+ TWO live discoveries the surgery surfaced, both suite-relevant:
723
+
724
+ 1. **The playOrder contract mismatch is REAL and base-free is wrong for
725
+ shell-shaped NCXs**: after the prune, the 14 surviving navPoints keep
726
+ playOrder 448..461 (contiguous run, base 448). The v0.62.0 base-free
727
+ contract reads that satisfied — but epubcheck 5.3 flags BOTH
728
+ "playOrder sequence has gaps" AND "the first playOrder value is not
729
+ 1" on this exact NCX. The v0.62.0 minimal matrix (offset-5-8,
730
+ singleton-2) was too minimal: epubcheck demands the 1-base once the
731
+ NCX carries findings it validates deeply (or the shape differs in a
732
+ way the matrix missed). fix_ncx_playorder returning 0 on an NCX
733
+ epubcheck flags is the mismatch, verbatim. A shell repair must
734
+ re-sequence to 1..K unconditionally (not contract-gated), and the
735
+ contract's base-free clause needs this shape added to its test
736
+ matrix.
737
+ 2. **The empty-guide coordination**: dropping dead items can empty the
738
+ guide (or prune_invalid_guide_refs can), and an empty `<guide>` is
739
+ itself an RSC-005. The flag design needs the drop-or-fill decision
740
+ for an emptied guide.
741
+
742
+ Manual handling note: both books open fine AS SHIPPED (0 fatals; the
743
+ 742/739 RSC-001s are noise to readers). The surgical recipe above is
744
+ the documented manual path; the regex-renumber experiment corrupted a
745
+ test NCX once (greedy `[^>]*` across attributes) — use bindery's own
746
+ transforms, not hand regex, for any real re-sequence.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: bindery-cli
3
- Version: 0.63.0
3
+ Version: 0.64.0
4
4
  Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
5
5
  Project-URL: Homepage, https://github.com/VirInvictus/bindery-cli
6
6
  Project-URL: Repository, https://github.com/VirInvictus/bindery-cli
@@ -91,6 +91,7 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
91
91
  - **`--strip-presentational-attrs`**: strips the deprecated presentational hints the XHTML 1.1 DTD rejects wherever they appear (`align`, `valign`, `border`, `bgcolor`, `vspace`, `hspace`, `compact`; body's `link`/`vlink`/`alink`/`text`/`background`; `type` on list elements; Amazon `data-AmznRemoved` junk). Honest caveat: these are presentational hints, and readers that honor them render differently after the strip.
92
92
  - **`--encode-ref-brackets`**: percent-encodes raw `[`/`]` in the path portion of internal references whose archive target exists with the raw brackets (RSC-020). Fragments, queries, entry names, and unresolvable/external references stay as written. Runs on content documents, the OPF, the NCX, and stylesheet `url()` tokens.
93
93
  - **`--fix-id-colons`** also renames any content-document `id` that cannot be an XML NCName (digit-led scraped ids, apostrophe-bearing calibre ids) since v0.63.0, syncing internal fragments with the same `id_` scheme as the manifest half.
94
+ - **`--prune-dead-spine`**: the shell repair — fires ONLY when half or more of the manifest's content hrefs name files the archive never carried (the audit battery's `shell` analyzer names the same shape). Drops the dead manifest items, the spine itemrefs that name them, and the dead NCX navPoints, then re-sequences the surviving playOrders to 1..K. A lone missing chapter never crosses the signature: the spine non-goal stays in force for ordinary damage. The Wandering Inn serial shells (738 and 736 of 755/752 items dead) are the design case; proven at 742e → 5e with 0 fatals.
94
95
 
95
96
  Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
96
97
 
@@ -64,6 +64,7 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
64
64
  - **`--strip-presentational-attrs`**: strips the deprecated presentational hints the XHTML 1.1 DTD rejects wherever they appear (`align`, `valign`, `border`, `bgcolor`, `vspace`, `hspace`, `compact`; body's `link`/`vlink`/`alink`/`text`/`background`; `type` on list elements; Amazon `data-AmznRemoved` junk). Honest caveat: these are presentational hints, and readers that honor them render differently after the strip.
65
65
  - **`--encode-ref-brackets`**: percent-encodes raw `[`/`]` in the path portion of internal references whose archive target exists with the raw brackets (RSC-020). Fragments, queries, entry names, and unresolvable/external references stay as written. Runs on content documents, the OPF, the NCX, and stylesheet `url()` tokens.
66
66
  - **`--fix-id-colons`** also renames any content-document `id` that cannot be an XML NCName (digit-led scraped ids, apostrophe-bearing calibre ids) since v0.63.0, syncing internal fragments with the same `id_` scheme as the manifest half.
67
+ - **`--prune-dead-spine`**: the shell repair — fires ONLY when half or more of the manifest's content hrefs name files the archive never carried (the audit battery's `shell` analyzer names the same shape). Drops the dead manifest items, the spine itemrefs that name them, and the dead NCX navPoints, then re-sequences the surviving playOrders to 1..K. A lone missing chapter never crosses the signature: the spine non-goal stays in force for ordinary damage. The Wandering Inn serial shells (738 and 736 of 755/752 items dead) are the design case; proven at 742e → 5e with 0 fatals.
67
68
 
68
69
  Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
69
70
 
@@ -1,5 +1,71 @@
1
1
  # bindery-cli Patch Notes
2
2
 
3
+ ## v0.64.0 (2026-11-05)
4
+
5
+ ### --prune-dead-spine: the shell repair
6
+
7
+ The Wandering Inn feasibility dig proved the recipe on the facility
8
+ copies (0f/742e -> 0f/5e, 0 fatals, a complete coherent book of its own
9
+ chapters); this release builds it as a flag. The diagnosis falsified the
10
+ 2026-10-25 "different spelling" hypothesis: Book 18 and Book 19 carry
11
+ their REAL, complete chapter ranges (730-742 and 743-755, full-size
12
+ prose docs) -- the converter shipped the right chapters and wrote the
13
+ ENTIRE serial manifest, so 738 and 736 of 755/752 manifest items name
14
+ files that were never this book's chapters. The books are not damaged
15
+ goods: they are complete books wrapped in another book's manifest.
16
+
17
+ `--prune-dead-spine` fires ONLY at the shell signature -- half or more
18
+ of the manifest's content hrefs name files the archive does not carry
19
+ (the audit battery's `shell` analyzer, v0.63.0, names the same shape).
20
+ At the signature it drops the dead manifest items and the spine itemrefs
21
+ that name them, prunes the dead NCX navPoints (the existing
22
+ dangling-target prune, coordinated on via a dataclasses.replace), and
23
+ re-sequences the surviving playOrders to 1..K. Below the signature --
24
+ a lone missing chapter, a broken fragment -- it never fires: the spine
25
+ non-goal ("missing spine documents mean corrupt archives or broken
26
+ fragments") stays in force for ordinary damage, now with a third,
27
+ measured exception: the wholesale shell.
28
+
29
+ Two live findings the build closed out:
30
+
31
+ - **The playOrder contract is not base-free on the shell shape.** The
32
+ v0.62.0 base-free clause was built from a minimal matrix that validated
33
+ offset runs (448..461-shaped) clean -- but epubcheck 5.3 flagged BOTH
34
+ "playOrder sequence has gaps" AND "the first playOrder value is not 1"
35
+ on the post-prune Wandering Inn NCX. The oracle rules: the shell
36
+ repair re-sequences to 1..K unconditionally (a `force` parameter on
37
+ `fix_ncx_playorder`), and the base-free clause's test matrix gains the
38
+ shell shape as a known divergence.
39
+ - **fix_ncx_playorder gains `force`**: the shell repair's playOrder
40
+ half must re-sequence even where the contract reads satisfied.
41
+
42
+ The proven end state on the facility copy: 0f/5e (from 0f/742e), a
43
+ complete readable book of its own chapters -- nothing real is lost; the
44
+ dropped positions never resolved in any reader.
45
+
46
+ Suite: 917 tests.
47
+
48
+ ## v0.63.1 (2026-11-04)
49
+
50
+ ### Two single-flag live-verification catches
51
+
52
+ Running each v0.63.0 flag alone against its real carriers caught two
53
+ wiring slips the --all-sized sweeps could never see:
54
+
55
+ - **`--encode-ref-brackets` alone was a silent no-op**: the encode reads
56
+ `present` (the archive existence set), but `present` only fills when
57
+ one of the prune/anchors/media-types/declare/prune-NCX flags asked for
58
+ it -- the new flag wasn't in that guard, so the set stayed empty, every
59
+ reference resolved to nothing, and the flag answered "no applicable
60
+ fixes" on a book whose NCX carries 59 bracket srcs (The Given Day:
61
+ `Dennis_Lehane_-_The_Given_Day_[html]_split_000.html`). The guard now
62
+ includes the flag; the live apply encodes 59 NCX srcs, zero raw left.
63
+ - **The audit CLI's `--only` choices lacked `shell`**: the analyzer
64
+ shipped in v0.63.0 but `bindery audit --only shell` died at argparse
65
+ (invalid choice). The choice is registered.
66
+
67
+ Suite: 913 tests.
68
+
3
69
  ## v0.63.0 (2026-11-04)
4
70
 
5
71
  ### The harvest census: two new flags, the id scope, and the shell detector
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "bindery-cli"
7
- version = "0.63.0"
7
+ version = "0.64.0"
8
8
  description = "Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library."
9
9
  readme = "README.md"
10
10
  classifiers = [
@@ -59,6 +59,8 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
59
59
  | 0.62.1 | `--fix-double-colon-tags`: the pseudo-tag escape for the last library fatal -- an XML name carries at most one colon, so a `::`-named pseudo-tag is never markup (fatal RSC-016; the Book of Debugging's C++ samples), and escaping both ends restores the author's text; nested templates escape inner-first, real markup is unreachable by construction; also closes the spec.md drift (the four v0.62.0 flags had not joined the inventory) | v0.62.1 |
60
60
  | 0.62.2 | The review batch (three-reviewer pass over the v0.62.x range): the item-properties insertion branch emitted malformed XML on the self-closed shape (attribute after the solidus; no test drove the branch -- every fixture pre-carried properties), now appends before the solidus with an ET-parsed pin; the missing-title empty-fill is head-scoped (an empty SVG `<title>` is visible text); the double-colon tail is bounded at 120 chars (the escaped-bracket runaway); the unverified on\* handler disjunct left the census; `_scan_doctype_span` refuses unterminated declarations; the guide-prune docstring matches the code; and the documentation inventories caught up (README's seven missing flags, spec.md's four behavioral bullets + body counts + the safe-opt-in section, AGENTS.md's inventory) | v0.62.2 |
61
61
  | 0.63 | The harvest census (the honest dig into the remaining 14,109): `--strip-presentational-attrs` (the largest attribute family; rendering-caveat approved), `--encode-ref-brackets` (the issue #19 mechanism applied to brackets without spaces; the 59-book RSC-020 lane), `--fix-id-colons` broadened to every NCName failure (digit-led scraped ids; the apostrophe charset blind spot closed), and the audit battery's `shell` analyzer (the Wandering Inn detector: spine-missing fraction at or over 50% reads SHELL, re-source never repair) | v0.63.0 |
62
+ | 0.63.1 | Two single-flag live-verification catches: `--encode-ref-brackets` alone was a silent no-op (`present` only filled under the other flags' guard -- The Given Day's 59 NCX bracket srcs encoded, zero raw left, once the guard included the flag), and the audit CLI's `--only` choices lacked `shell` | v0.63.1 |
63
+ | 0.64 | `--prune-dead-spine`: the shell repair, shell-gated at the 50% signature (drops dead manifest items + spine itemrefs, coordinates the NCX navPoint prune and an UNCONDITIONAL playOrder re-sequence to 1..K after epubcheck 5.3 flagged the non-1 base on the post-prune shape -- the base-free clause's minimal matrix missed the shell shape); proven at 742e -> 5e on the facility copy | v0.64.0 |
62
64
 
63
65
  ## Open work
64
66
 
@@ -70,6 +72,9 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
70
72
  gate refuses a book that is otherwise repaired. Needs the same
71
73
  entry-and-reference coordination as the space renames, with the
72
74
  decode-before-lookup epubcheck rule verified per character class.
75
+ *v0.63.0 narrowed this: `--encode-ref-brackets` ships the bracket
76
+ slice (the decode-before-lookup rule verified for `%5B`/`%5D`); the
77
+ comma and remaining classes stay open.*
73
78
  *(Narrowed v0.58.0: renamed references now percent-encode `[`/`]`
74
79
  (issue #19), so a book whose bracket-named entries carry spaces
75
80
  repairs cleanly. The no-rename shape remains: entries with brackets
@@ -13,7 +13,7 @@ restyle, re-compress, or restructure content, and it does not attempt to fix arb
13
13
  schema (RSC-005) violations, which are usually harmless to readers and not safely
14
14
  mechanizable.
15
15
 
16
- The deliberate exceptions to "semantics-preserving" come in opt-in groups. The thirty-two
16
+ The deliberate exceptions to "semantics-preserving" come in opt-in groups. The thirty-three
17
17
  **structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
18
18
  `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
19
19
  `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
@@ -25,7 +25,8 @@ The deliberate exceptions to "semantics-preserving" come in opt-in groups. The t
25
25
  `--fix-stray-close`, `--fix-unterminated-attr`, `--fix-unbound-prefix`,
26
26
  `--fix-unique-identifier`, `--fix-package-version`, `--fix-doctype`,
27
27
  `--prune-invalid-guide-refs`, `--fix-item-properties`,
28
- `--strip-presentational-attrs`, `--encode-ref-brackets`) alter
28
+ `--strip-presentational-attrs`, `--encode-ref-brackets`,
29
+ `--prune-dead-spine`) alter
29
30
  markup structure or fabricate minimal content; the four
30
31
  **lossy modes** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`,
31
32
  `--strip-stub-docs`) remove
@@ -534,7 +535,24 @@ leftovers whose failing OPF is a stale non-rootfile are unreachable by construct
534
535
  walk covers content documents, the OPF, the NCX, and stylesheet `url()`
535
536
  tokens.
536
537
 
537
- Twenty-nine of the thirty-two are evaluated by the normal `gate`: unlike the lossy strips,
538
+ - **`--prune-dead-spine`**: the shell repair -- fires ONLY when half or
539
+ more of the manifest's content hrefs name files the archive does not
540
+ carry (the audit battery's `shell` analyzer names the same shape; the
541
+ 2026-11-04 Wandering Inn shells: 738 and 736 of 755/752 items dead --
542
+ verified by content walk as the OTHER books' chapters, never a spelling
543
+ mismatch). Drops the dead manifest items and the spine itemrefs that
544
+ name them, prunes the dead NCX navPoints (the existing dangling-target
545
+ prune, coordinated on), and re-sequences the surviving playOrders to
546
+ 1..K UNCONDITIONALLY -- epubcheck 5.3 flagged "the first playOrder
547
+ value is not 1" on the post-prune 448..461 run even though the
548
+ base-free contract read it satisfied (the minimal matrix missed the
549
+ shell shape; the oracle rules). Nothing real is lost: the dropped
550
+ positions never resolved, and the book that remains is the complete,
551
+ coherent chapter range the archive actually carries. A lone missing
552
+ chapter never crosses the signature: the spine non-goal stays in force
553
+ for ordinary damage.
554
+
555
+ Thirty of the thirty-three are evaluated by the normal `gate`: unlike the lossy strips,
538
556
  their benefit is visible to epubcheck (they clear errors), so a run with no measurable
539
557
  improvement is a noop and nothing is applied. The three exceptions are `--fix-cover`, `--encode-url-spaces`, and
540
558
  `--fix-media-types` (whose gains sit on axes epubcheck's counts do not measure:
@@ -11,7 +11,7 @@ Calibre plugin built from this core.
11
11
  Single source of truth for the version. pyproject.toml must match VERSION below.
12
12
  """
13
13
 
14
- VERSION = "0.63.0"
14
+ VERSION = "0.64.0"
15
15
  __version__ = VERSION
16
16
 
17
17
  from .epub import RepairReport, repair_epub # noqa: E402
@@ -116,6 +116,7 @@ def _flags_from_args(args: argparse.Namespace) -> RepairFlags:
116
116
  double_colon_tags=args.fix_double_colon_tags or all_,
117
117
  presentational_attrs=args.strip_presentational_attrs or all_,
118
118
  encode_ref_brackets=args.encode_ref_brackets or all_,
119
+ prune_dead_spine=args.prune_dead_spine or all_,
119
120
  )
120
121
 
121
122
 
@@ -1831,6 +1832,23 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
1831
1832
  ),
1832
1833
  ],
1833
1834
  "structural repairs: references and resources": [
1835
+ (
1836
+ "prune_dead_spine",
1837
+ "the shell repair: drop manifest items and spine positions whose files the archive never carried",
1838
+ "fires ONLY at the shell signature -- half or more of the "
1839
+ "manifest's content hrefs name files the archive does not carry "
1840
+ "(the audit battery's `shell` analyzer names the same shape). "
1841
+ "Drops the dead manifest items, the spine itemrefs that name "
1842
+ "them, and (coordinated) the dead NCX navPoints, then "
1843
+ "re-sequences the surviving playOrders to 1..K unconditionally: "
1844
+ "epubcheck 5.3 demands the 1-base on the post-prune shape even "
1845
+ "where the base-free contract reads a contiguous offset run "
1846
+ "satisfied. A lone missing chapter NEVER crosses the signature: "
1847
+ "the spine non-goal stays in force for ordinary damage. The "
1848
+ "2026-11-04 Wandering Inn shells (738 and 736 of 755/752 items "
1849
+ "dead) are the design case; proven on the facility copy at "
1850
+ "742e -> 5e with 0 fatals.",
1851
+ ),
1834
1852
  (
1835
1853
  "encode_ref_brackets",
1836
1854
  "percent-encode raw [ ] in internal references whose target exists (RSC-020)",
@@ -2484,6 +2502,7 @@ def build_parser() -> argparse.ArgumentParser:
2484
2502
  "cover",
2485
2503
  "tocdrift",
2486
2504
  "contamination",
2505
+ "shell",
2487
2506
  "all",
2488
2507
  ),
2489
2508
  help="which audit to run",
@@ -285,6 +285,7 @@ class RepairFlags:
285
285
  double_colon_tags: bool = False
286
286
  presentational_attrs: bool = False
287
287
  encode_ref_brackets: bool = False
288
+ prune_dead_spine: bool = False
288
289
 
289
290
 
290
291
  @dataclass
@@ -522,6 +523,37 @@ def _manifest_media_type_map(opf_text: str, opf_dir: str) -> dict[str, str]:
522
523
  return out
523
524
 
524
525
 
526
+ def prune_dead_spine_items(
527
+ opf_text: str, dead_ids: frozenset[str] | set[str]
528
+ ) -> tuple[str, int]:
529
+ """Drop manifest items whose ids are in `dead_ids` (content items whose
530
+ files the archive never carried) and the spine itemrefs that name them
531
+ -- the shell repair's manifest half, gated upstream on the >= 50%
532
+ signature. Document order survives: everything not dropped passes
533
+ through byte-identical, and the `spine toc` attribute is untouched.
534
+ Returns the number of ITEMS dropped (the itemrefs follow silently)."""
535
+ count = 0
536
+
537
+ def drop_item(m: re.Match) -> str:
538
+ nonlocal count
539
+ im = _XML_ID_RE.search(m.group(0))
540
+ if im and im.group(3) in dead_ids:
541
+ count += 1
542
+ return ""
543
+ return m.group(0)
544
+
545
+ out = _ITEM_TAG_RE.sub(drop_item, opf_text)
546
+
547
+ def drop_ref(m: re.Match) -> str:
548
+ rm = _IDREF_ATTR_RE.search(m.group(0))
549
+ if rm and rm.group(3) in dead_ids:
550
+ return ""
551
+ return m.group(0)
552
+
553
+ out = _SPINE_ITEM_RE.sub(drop_ref, out)
554
+ return out, count
555
+
556
+
525
557
  def prune_invalid_guide_refs(opf_text: str, opf_dir: str) -> tuple[str, int]:
526
558
  """Remove guide ``<reference>`` elements whose target is declared but is
527
559
  not an OPS content document (OPF-032).
@@ -2531,6 +2563,8 @@ def repair_epub(
2531
2563
  or flags.fix_media_types
2532
2564
  or flags.declare_missing
2533
2565
  or flags.prune_ncx_targets
2566
+ or flags.encode_ref_brackets
2567
+ or flags.prune_dead_spine
2534
2568
  ):
2535
2569
  for n in zin.namelist():
2536
2570
  norm_to_raw.setdefault(_norm_path(space_renames.get(n, n)), n)
@@ -2543,6 +2577,40 @@ def repair_epub(
2543
2577
  undeclared: frozenset[str] = frozenset()
2544
2578
  if flags.declare_missing and opf_text is not None:
2545
2579
  undeclared = collect_undeclared_resources(zin, opf_text, opf_dir, present)
2580
+ # --prune-dead-spine: the shell signature, computed once like the
2581
+ # prune's existence set. Dead = manifest CONTENT items whose href
2582
+ # file the archive does not carry; the flag only fires at the
2583
+ # audit's shell signature (>= 50% of the content manifest missing),
2584
+ # so a lone missing chapter never crosses it and the spine
2585
+ # non-goal stays in force for ordinary damage (the 2026-11-04
2586
+ # Wandering Inn diagnosis: 738 and 736 of 755/752 items dead).
2587
+ shell_ok = False
2588
+ dead_spine_ids: frozenset[str] = frozenset()
2589
+ if flags.prune_dead_spine and opf_text is not None and present:
2590
+ total_content = 0
2591
+ dead: set[str] = set()
2592
+ for m in _ITEM_TAG_RE.finditer(opf_text):
2593
+ tag = m.group(0)
2594
+ hm = _HREF_ATTR_RE.search(tag)
2595
+ im = _XML_ID_RE.search(tag)
2596
+ if not hm or not im:
2597
+ continue
2598
+ href = hm.group(2)
2599
+ if not href.lower().endswith((".xhtml", ".html", ".htm")):
2600
+ continue
2601
+ total_content += 1
2602
+ resolved = _resolve_href(opf_dir, href)
2603
+ if resolved is None or resolved not in present:
2604
+ dead.add(im.group(3))
2605
+ if total_content and len(dead) / total_content >= 0.5:
2606
+ shell_ok = True
2607
+ dead_spine_ids = frozenset(dead)
2608
+ # the NCX half coordinates: the navPoint prune drops the
2609
+ # dead navPoints and the playOrders re-sequence to 1..K
2610
+ # (forced -- epubcheck 5.3 demands the 1-base on the
2611
+ # post-prune shape even where the minimal matrix said the
2612
+ # base was free)
2613
+ flags = replace(flags, prune_ncx_targets=True)
2546
2614
  item_props: dict[str, frozenset[str]] = {}
2547
2615
  if flags.item_properties:
2548
2616
  item_props = collect_item_properties(zin)
@@ -2812,6 +2880,18 @@ def repair_epub(
2812
2880
  counts["fix_ncx_playorder"] = (
2813
2881
  counts.get("fix_ncx_playorder", 0) + n2
2814
2882
  )
2883
+ if shell_ok:
2884
+ # The shell repair's playOrder half, UNCONDITIONAL (not
2885
+ # contract-gated): epubcheck 5.3 flagged "the first
2886
+ # playOrder value is not 1" on the post-prune 448..461
2887
+ # run -- the base-free clause reads that satisfied, but
2888
+ # on the shell shape the oracle demands the 1-base.
2889
+ # Re-sequence to 1..K in document order.
2890
+ text, n2 = fix_ncx_playorder(text, force=True)
2891
+ if n2:
2892
+ counts["fix_ncx_playorder"] = (
2893
+ counts.get("fix_ncx_playorder", 0) + n2
2894
+ )
2815
2895
  synced = False
2816
2896
  sync_uid = uid if uid else wired_uid
2817
2897
  if sync_uid:
@@ -2839,6 +2919,7 @@ def repair_epub(
2839
2919
  or flags.package_version
2840
2920
  or flags.prune_guide_refs
2841
2921
  or flags.item_properties
2922
+ or flags.prune_dead_spine
2842
2923
  ):
2843
2924
  opf_changed = False
2844
2925
  if flags.package_version:
@@ -2849,6 +2930,16 @@ def repair_epub(
2849
2930
  if n:
2850
2931
  report.add({"package_version_fixed": n})
2851
2932
  opf_changed = True
2933
+ if flags.prune_dead_spine and shell_ok and dead_spine_ids:
2934
+ # The shell repair's manifest half (gated on the >= 50%
2935
+ # signature computed above): dead content items and the
2936
+ # spine itemrefs that name them drop together. The NCX
2937
+ # half (navPoint prune + forced playOrder re-sequence)
2938
+ # runs in the NCX branch.
2939
+ text, n = prune_dead_spine_items(text, dead_spine_ids)
2940
+ if n:
2941
+ report.add({"dead_spine_items_pruned": n})
2942
+ opf_changed = True
2852
2943
  if flags.unbound_prefix:
2853
2944
  # First in the branch: the unbound prefix makes the whole
2854
2945
  # package unparseable, so the parseability scar comes off
@@ -351,10 +351,19 @@ _CONTENT_SRC_RE = re.compile(
351
351
 
352
352
 
353
353
  @_outside_protected
354
- def fix_ncx_playorder(s: str) -> tuple[str, int]:
354
+ def fix_ncx_playorder(s: str, *, force: bool = False) -> tuple[str, int]:
355
355
  """Re-sequence `playOrder` values so the NCX satisfies epubcheck's playOrder
356
356
  contract, and touch nothing when it already does.
357
357
 
358
+ `force` (v0.64.0, the shell repair's coordination) skips the
359
+ satisfied-contract early return and re-sequences to 1..K
360
+ unconditionally. The prune-dead-spine flag needs it: epubcheck 5.3
361
+ flagged "the first playOrder value is not 1" on the surviving 448..461
362
+ run of a shell NCX whose dead navPoints had just been pruned -- the
363
+ base-free clause reads that run satisfied, but on the post-prune shape
364
+ the oracle demands the 1-base (the v0.62.0 minimal matrix missed this
365
+ shape; the contract is base-free only where the oracle says so).
366
+
358
367
  Contract-gated (the 2026-10-24 whole-library surgery): the previous form
359
368
  renumbered every `<navPoint>` to document-order 1..N unconditionally, which
360
369
  rewrote VALID TOCs into violations -- navPoints whose `<content src>` share
@@ -435,7 +444,7 @@ def fix_ncx_playorder(s: str) -> tuple[str, int]:
435
444
  contract_ok = False
436
445
  break
437
446
  used |= vals
438
- if contract_ok and used and len(used) == len(groups):
447
+ if not force and contract_ok and used and len(used) == len(groups):
439
448
  lo = min(used)
440
449
  if used == set(range(lo, lo + len(used))):
441
450
  return s, 0
@@ -3806,3 +3806,122 @@ class TestEncodeRefBrackets(unittest.TestCase):
3806
3806
  )
3807
3807
  self.assertEqual(n, 1)
3808
3808
  self.assertIn("url(img%5B3%5D.png)", out)
3809
+
3810
+
3811
+ class TestPruneDeadSpine(unittest.TestCase):
3812
+ """--prune-dead-spine: the shell repair. Fires ONLY at the shell
3813
+ signature (>= 50% of the manifest's content hrefs name files the
3814
+ archive does not carry) -- a lone missing chapter never crosses it,
3815
+ so the spine non-goal stays in force for ordinary damage. Proven on
3816
+ the Wandering Inn facility copies at 742e -> 5e with 0 fatals."""
3817
+
3818
+ def _opf(self, version="2.0", items=()):
3819
+ manifest = "".join(
3820
+ f'<item id="{iid}" href="{href}" media-type="application/xhtml+xml"/>'
3821
+ for iid, href in items
3822
+ )
3823
+ spine = "".join(f'<itemref idref="{iid}"/>' for iid, _ in items)
3824
+ return (
3825
+ '<?xml version="1.0"?>'
3826
+ '<package xmlns="http://www.idpf.org/2007/opf" '
3827
+ f'version="{version}" unique-identifier="id">'
3828
+ '<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">'
3829
+ '<dc:identifier id="id">x</dc:identifier>'
3830
+ "<dc:title>t</dc:title><dc:language>en</dc:language></metadata>"
3831
+ f"<manifest>{manifest}</manifest>"
3832
+ f"<spine>{spine}</spine></package>"
3833
+ )
3834
+
3835
+ def _doc(self, title):
3836
+ return (
3837
+ '<?xml version="1.0"?><html xmlns="http://www.w3.org/1999/xhtml">'
3838
+ f"<head><title>{title}</title></head><body><p>{title}</p></body></html>"
3839
+ )
3840
+
3841
+ def _build(self, td, opf, docs):
3842
+ s = Path(td) / "in.epub"
3843
+ with zipfile.ZipFile(s, "w", zipfile.ZIP_DEFLATED) as z:
3844
+ z.writestr("mimetype", "application/epub+zip")
3845
+ z.writestr("OEBPS/content.opf", opf)
3846
+ for name, data in docs.items():
3847
+ z.writestr(name, data)
3848
+ return s
3849
+
3850
+ def test_shell_signature_prunes_items_and_refs(self):
3851
+ # 4 content items, only 1 file shipped: 75% missing = shell
3852
+ opf = self._opf(
3853
+ version="2.0",
3854
+ items=[
3855
+ ("live", "live.xhtml"),
3856
+ ("d1", "ghost1.xhtml"),
3857
+ ("d2", "ghost2.xhtml"),
3858
+ ("d3", "ghost3.xhtml"),
3859
+ ],
3860
+ )
3861
+ with tempfile.TemporaryDirectory() as td:
3862
+ s = self._build(td, opf, {"OEBPS/live.xhtml": self._doc("L")})
3863
+ d = Path(td) / "out.epub"
3864
+ report = repair_epub(s, d, RepairFlags(prune_dead_spine=True))
3865
+ self.assertGreaterEqual(report.fixes.get("dead_spine_items_pruned"), 3)
3866
+ with zipfile.ZipFile(d) as z:
3867
+ out = z.read("OEBPS/content.opf").decode()
3868
+ self.assertNotIn("ghost1.xhtml", out)
3869
+ self.assertNotIn('idref="d1"', out)
3870
+ self.assertIn('idref="live"', out)
3871
+ ET.fromstring(out)
3872
+
3873
+ def test_sub_shell_fraction_refuses(self):
3874
+ # 1 of 4 missing: 25% — a lone missing chapter never crosses the
3875
+ # signature and the spine non-goal stays in force
3876
+ opf = self._opf(
3877
+ version="2.0",
3878
+ items=[
3879
+ ("live", "live.xhtml"),
3880
+ ("b", "b.xhtml"),
3881
+ ("c", "c.xhtml"),
3882
+ ("ghost", "ghost.xhtml"),
3883
+ ],
3884
+ )
3885
+ with tempfile.TemporaryDirectory() as td:
3886
+ docs = {
3887
+ "OEBPS/live.xhtml": self._doc("L"),
3888
+ "OEBPS/b.xhtml": self._doc("B"),
3889
+ "OEBPS/c.xhtml": self._doc("C"),
3890
+ }
3891
+ s = self._build(td, opf, docs)
3892
+ d = Path(td) / "out.epub"
3893
+ report = repair_epub(s, d, RepairFlags(prune_dead_spine=True))
3894
+ self.assertNotIn("dead_spine_items_pruned", report.fixes)
3895
+ with zipfile.ZipFile(d) as z:
3896
+ out = z.read("OEBPS/content.opf").decode()
3897
+ self.assertIn("ghost.xhtml", out)
3898
+
3899
+ def test_images_and_ncx_items_are_never_dead(self):
3900
+ # the dead set is content-doc items only: the NCX/CSS/images keep
3901
+ # their manifest entries whatever their files' fate
3902
+ opf = self._opf(
3903
+ version="2.0",
3904
+ items=[
3905
+ ("live", "live.xhtml"),
3906
+ ("d1", "g1.xhtml"),
3907
+ ("d2", "g2.xhtml"),
3908
+ ("d3", "g3.xhtml"),
3909
+ ],
3910
+ )
3911
+ opf = opf.replace(
3912
+ "</manifest>",
3913
+ '<item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>'
3914
+ '<item id="css" href="s.css" media-type="text/css"/>'
3915
+ '<item id="img" href="i.jpg" media-type="image/jpeg"/>'
3916
+ "</manifest>",
3917
+ )
3918
+ with tempfile.TemporaryDirectory() as td:
3919
+ docs = {"OEBPS/live.xhtml": self._doc("L")}
3920
+ s = self._build(td, opf, docs)
3921
+ d = Path(td) / "out.epub"
3922
+ repair_epub(s, d, RepairFlags(prune_dead_spine=True))
3923
+ with zipfile.ZipFile(d) as z:
3924
+ out = z.read("OEBPS/content.opf").decode()
3925
+ self.assertIn('id="ncx"', out)
3926
+ self.assertIn('id="css"', out)
3927
+ self.assertIn('id="img"', out)
@@ -529,6 +529,20 @@ def _fixtures() -> dict:
529
529
  },
530
530
  "item_properties_added",
531
531
  ),
532
+ "--prune-dead-spine": (
533
+ {
534
+ "OEBPS/content.opf": _opf(
535
+ [
536
+ _item("live", "live.xhtml"),
537
+ _item("d1", "ghost1.xhtml"),
538
+ _item("d2", "ghost2.xhtml"),
539
+ ],
540
+ [_ref("live"), _ref("d1"), _ref("d2")],
541
+ ),
542
+ "OEBPS/live.xhtml": _doc("<p>word word word word</p>"),
543
+ },
544
+ "dead_spine_items_pruned",
545
+ ),
532
546
  "--fix-double-colon-tags": (
533
547
  {
534
548
  "OEBPS/content.opf": _opf([c1], [r1]),
@@ -772,6 +786,11 @@ class FlagEndToEndTests(unittest.TestCase):
772
786
  self._fixes_for("--fix-item-properties")["item_properties_added"], 1
773
787
  )
774
788
 
789
+ def test_prune_dead_spine(self):
790
+ self.assertGreaterEqual(
791
+ self._fixes_for("--prune-dead-spine")["dead_spine_items_pruned"], 2
792
+ )
793
+
775
794
  def test_fix_double_colon_tags(self):
776
795
  self.assertGreaterEqual(
777
796
  self._fixes_for("--fix-double-colon-tags")["double_colon_tags_escaped"],
@@ -58,6 +58,7 @@ DEST_TO_FIELD = {
58
58
  "fix_double_colon_tags": "double_colon_tags",
59
59
  "strip_presentational_attrs": "presentational_attrs",
60
60
  "encode_ref_brackets": "encode_ref_brackets",
61
+ "prune_dead_spine": "prune_dead_spine",
61
62
  "strip_pagination": "strip_pagination",
62
63
  "strip_broken_tags": "strip_brokentags",
63
64
  "strip_watermarks": "strip_watermarks",
@@ -8,7 +8,7 @@ resolution-markers = [
8
8
 
9
9
  [[package]]
10
10
  name = "bindery-cli"
11
- version = "0.63.0"
11
+ version = "0.64.0"
12
12
  source = { editable = "." }
13
13
  dependencies = [
14
14
  { name = "cquarry", marker = "python_full_version >= '3.14'" },
File without changes
File without changes
File without changes
File without changes
File without changes