bindery-cli 0.53.1__tar.gz → 0.55.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.53.1 → bindery_cli-0.55.0}/AGENTS.md +31 -9
  2. bindery_cli-0.55.0/OBSERVE-RESEARCH.md +677 -0
  3. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/PKG-INFO +14 -4
  4. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/README.md +13 -3
  5. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/patchnotes.md +144 -0
  6. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/pyproject.toml +1 -1
  7. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/roadmap.md +2 -0
  8. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/spec.md +92 -20
  9. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/src/bindery/__init__.py +1 -1
  10. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/src/bindery/cli.py +62 -10
  11. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/src/bindery/epub.py +211 -9
  12. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/src/bindery/observe.py +113 -16
  13. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/src/bindery/transforms.py +167 -42
  14. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/src/bindery/validate.py +67 -18
  15. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_cli.py +15 -1
  16. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_epub.py +149 -6
  17. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_flags_real_core.py +33 -2
  18. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_flags_wiring.py +2 -0
  19. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_observe.py +69 -5
  20. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_transforms.py +138 -1
  21. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_validate.py +58 -2
  22. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/uv.lock +1 -1
  23. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/.github/FUNDING.yml +0 -0
  24. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/.github/workflows/ci.yml +0 -0
  25. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/.github/workflows/publish.yml +0 -0
  26. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/.gitignore +0 -0
  27. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/LICENSE +0 -0
  28. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/docs/screenshots/library-sweep.png +0 -0
  29. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/logo.svg +0 -0
  30. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/plugin/__init__.py +0 -0
  31. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/project.done +0 -0
  32. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/run_tests.sh +0 -0
  33. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/scripts/FastSweep.java +0 -0
  34. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/scripts/build_plugin.py +0 -0
  35. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/scripts/fast_sweep.py +0 -0
  36. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/src/bindery/__main__.py +0 -0
  37. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/src/bindery/audit.py +0 -0
  38. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/src/bindery/library.py +0 -0
  39. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/src/bindery/pagination.py +0 -0
  40. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/src/bindery/reserialize.py +0 -0
  41. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/src/bindery/watermark.py +0 -0
  42. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_audit.py +0 -0
  43. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_comment_hyphens.py +0 -0
  44. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_contamination.py +0 -0
  45. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_cover_tocdrift.py +0 -0
  46. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_help.py +0 -0
  47. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_library.py +0 -0
  48. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_matcher_hardening.py +0 -0
  49. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_pagination.py +0 -0
  50. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_plugin.py +0 -0
  51. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_reserialize.py +0 -0
  52. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_space_renames.py +0 -0
  53. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_spine_guard.py +0 -0
  54. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_version.py +0 -0
  55. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_watermark.py +0 -0
  56. {bindery_cli-0.53.1 → bindery_cli-0.55.0}/tests/test_xml_hardening.py +0 -0
@@ -30,14 +30,16 @@ 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: twenty-two structural
33
+ visible content. The canonical opt-in inventory lives in spec.md: twenty-four structural
34
34
  repairs, four lossy strips, four safe opt-ins, plus `--reserialize`.
35
35
  * **Structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
36
36
  `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
37
37
  `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
38
- `--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`,
38
+ `--prune-missing-resources`, `--declare-missing-items`, `--strip-broken-anchors`,
39
+ `--encode-url-spaces`,
39
40
  `--fix-container`, `--fix-media-types`, `--fix-cover`,
40
- `--fix-comment-double-hyphen`, `--fix-svg-dup-ids`, `--fix-cdata-terminator`,
41
+ `--fix-comment-double-hyphen`, `--fix-svg-dup-ids`, `--fix-duplicate-ids`,
42
+ `--fix-cdata-terminator`,
41
43
  `--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr`,
42
44
  `--fix-unbound-prefix`;
43
45
  transforms.py, threaded through epub.py). The v0.47.0 five (the 2026-10-06
@@ -70,6 +72,21 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
70
72
  element under an OPF-namespaced package, anything else refuses the whole
71
73
  document; scope-tracked over a comment/CDATA-aware tokenizer, OPF only
72
74
  (content docs have the `--strip-bad-attrs` drop); normal `gate`.
75
+ The v0.55.0 two (the 2026-10-25 issue batch): `--declare-missing-items`
76
+ (issue #16) is the RSC-008 inverse of the prune -- it ADDS manifest
77
+ `<item>` declarations for files the archive carries and the book
78
+ references (content img/link, CSS url(), OPF guide refs) but the OPF
79
+ never declared; deterministic sorted-order `bindery-dN` ids, blessed
80
+ extension-map media types only, no itemref ever written (the spine is
81
+ untouched; an itemref with no manifest item stays unrepaired -- which
82
+ file it meant is underdetermined); normal `gate`. `--fix-duplicate-ids`
83
+ (issue #14) is the content-doc half of the SVG duplicate-id rename:
84
+ same first-keeps-name rule, references resolve to the first definition
85
+ and are never rewritten; normal `gate`. The same lane's RSC-001 verdict:
86
+ 95.3% of its mass is spine documents whose files exist under a
87
+ different spelling (the spine guard correctly refuses; the mass carrier
88
+ is `--encode-url-spaces` territory), so the prune's coverage boundary is
89
+ documented, not widened.
73
90
  They alter markup structure or fabricate minimal content. v0.14–v0.16 ran these unconditionally, which broke this rule;
74
91
  v0.17.0 restored it. `--unwrap-illegal-tags` additionally protects any illegal-tag
75
92
  name that an EPUB stylesheet styles as an element selector (`css_protected_tags`,
@@ -79,7 +96,12 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
79
96
  no version can be read, since their target defects only exist below EPUB 3; the
80
97
  attribute scrub is anchored to real start tags via
81
98
  `transforms.strip_attrs_in_start_tags` (prose mentioning the attributes and
82
- CDATA/comment content are preserved), and `strip_invalid_value` matches the
99
+ CDATA/comment content are preserved); since v0.55.0 (issue #11) the set also
100
+ covers `role` and `aria-hidden` (the 2026-10-25 census: the dominant
101
+ EPUB3-semantics-on-legacy-package family, DPUB-ARIA doc-* values only; the
102
+ package-version gate stays, verified aligned with epubcheck's profile-driven
103
+ rejection; `hidden` deliberately NOT covered, stripping it would reveal
104
+ hidden content), and `strip_invalid_value` matches the
83
105
  attribute name with a `(?<![\w:.-])value` lookbehind so `data-value` survives.
84
106
  * **Lossy strips** (`--strip-pagination`, `--strip-broken-tags`,
85
107
  `--strip-watermarks`; pagination.py, watermark.py; `--strip-stub-docs`,
@@ -132,19 +154,19 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
132
154
 
133
155
  ## Layout
134
156
 
135
- - `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).
157
+ - `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`). Since v0.55.0 `fix_svg_dup_ids` and `fix_duplicate_ids` share `_rename_duplicate_ids` (first-keeps-name, `_2`/`_3` suffixes, references never rewritten); the SVG flag owns standalone `.svg` entries, the content-doc flag owns `.xhtml`/`.html`/`.htm`/`.xml`. 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). Since v0.54.0 (the 2026-10-24 surgery): `fix_ncx_playorder` is CONTRACT-GATED -- it tokenizes navPoint/navTarget/pageTarget start tags plus their `<content src>` targets, returns unchanged when the NCX already satisfies epubcheck's playOrder contract (same target shares one value, distinct targets distinct values, values contiguous 1..K), and re-sequences by first-appearance target order only on a violation; the old unconditional 1..N renumbering rewrote valid TOCs into violations (211 of 579 firings gate-rejected, 17 real fixes, 347 no-ops). The same fix extends `_PROTECTED_RE` with the Calibre `/*<![CDATA[*/ ... /*]]>*/` wrapper as one protected unit (the bare CDATA alternative ends inside the closing `/*]]>`, which exposed the trailing `*/` to strip_prolog_junk's amputation: 111 phantom-fix rejections).
136
158
  - `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets).
137
159
  - `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
138
160
  - `src/bindery/reserialize.py`: structural repair via `html5lib`.
139
161
  - `src/bindery/audit.py`: read-only body-text audits (`content`, `pagenumbers`, `emptytext`, `ocr`, `monolithic` since v0.21.0 with `--max-doc-chars N`, and `completeness` since v0.36.0) behind the `audit` subcommand (v0.15.0). Since v0.18.0 library mode resolves EPUB paths through `cquarry.get_format_path()` and can apply a tag to flagged books via `cquarry.write.WritableCalibreDB` (only with explicit `--tag`; the only sanctioned write path). Since v0.19.0 `audit --id BOOK_ID` audits a single library book through cquarry's single-entity `get_book()` fetch (no library-wide cache; supports `--tag`; incompatible with the directory argument; comma lists since v0.23.0). Since v0.22.0 every archive entry is fully read (CRC + decompression) before analysis (a damaged entry reports its own CORRUPT verdict instead of feeding emptytext) and manifest/NCX references to absent files classify as `convention` (bloated ToC, consecutive span) or `fragment` (broken span). Hazard: the scan loop reuses `tag` as its per-book display column, so the `--tag` argument is captured as `audit_tag` at function entry; do not collapse them again. Since v0.29.0 `audit --json FILE` writes per-file analyzer verdicts in the `library --json` shape (directory, library, and single-book modes; with `--id`, exactly one id; emptytext omitted from a record when the archive verdict owns the body-text story). Since v0.44.0 two more advisory analyzers ride the single pass: `cover` (the EPUB3 `properties~="cover-image"` slice of the ruled hybrid: dangling EPUB2 meta, EPUB3 declaration, cover-file presence) and `tocdrift` (the NCX navMap vs EPUB3 nav toc structural diff, fragments included; audit-only, ToC synthesis out of charter permanently); the loader now exposes the parsed OPF, the NCX text, and the nav HTML on `Book`. Since v0.50.0 a ninth analyzer, `contamination` (issue #8, the judge-and-import class, advisory by contract like completeness/cover/tocdrift, never moves the exit code): foreign-title template stamps (head `<title>` repeats or a volume/book marker with named words in front of it, judged against the OPF's own title/creator/publisher/series with a marker-stripped comparison; a part label whose marker leads never flags), fan-bundle ad signatures (jnovels, kokoro connect, zerobooks, a light-novel plug), and review-paste fingerprints (strong flags alone, weak needs corroboration) in the first five content docs; its corpus is spine PLUS `Book.extra_docs` (the archive's non-spine html, retained by the loader in archive order under a 64 MiB cap, because a broken manifest can leave the junk entirely off the spine: Hothouse). Since v0.50.0 `run_directory`/`run_single` dispatch analyzers through `_dir_dispatch` (one entry per ALL key; the old if/elif chain's `else` ran ocr for cover/tocdrift in those modes since v0.44.0) and `tests/test_contamination.py` pins the map's key set to ALL. Since v0.36.0 the completeness analyzer (Phase 15) reports the phase-1 spot-check per book: spine/prose-doc counts (prose = >= 400 visible chars), first/middle/last prose-doc opening/closing excerpts, trailing-ToC classification (`_trailing_toc`: short link lines dominate, no paragraph-length blocks), and the unreadable fraction. It is ADVISORY by contract (problem always False; ADVISORY on a trailing ToC or unreadable fraction >= 10%), never moves the exit code, and is skipped like emptytext when the archive verdict owns the book. Since v0.38.0 the archive verdict distinguishes font obfuscation from DRM (`OBFUSCATION_ALGOS`: IDPF 2008/embedding + both Adobe URIs; readable obfuscated entries are the benign OBFUSCATED advisory, an unreadable one is CORRUPT, and only non-obfuscation algorithms give ENCRYPTED). Since v0.43.0 untrusted metadata XML is parsed through `_safe_xml_parse` (DOCTYPE/ENTITY declarations refused before xml.etree sees them; the stdlib shape of defusedxml's entity protection) and single entries above `_MAX_ENTRY_BYTES` (32 MB) are refused before decompression; a refused metadata file returns the shell book. Since v0.40.0 the vir-tui console renderer loads through the module-level `_LazyUI` proxy (a plain `import vir_tui as ui` at module level would make 3.12/3.13 installs unimportable now that the stack is marker-gated; LOAD_GLOBAL never consults module `__getattr__`, so a proxy object is the lazy shape that works).
140
- - `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.52.0 (issue #10): `spine_dangles(src)` walks itemref -> manifest item -> archive entry through `_resolve_href`+`_norm_path` (None on an unreadable package: the veto needs evidence, never fires on a probe failure), and `prune_missing_manifest_items` derives its spine protection from the text it prunes (no snapshot parameter: fix_manifest_ids renames ids ahead of it, and the existence set it checks against must be the layout its hrefs are written in — `present_src` when space renames are active, matching the content-doc prune). 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).
141
- - `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars.
162
+ - `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.52.0 (issue #10): `spine_dangles(src)` walks itemref -> manifest item -> archive entry through `_resolve_href`+`_norm_path` (None on an unreadable package: the veto needs evidence, never fires on a probe failure), and `prune_missing_manifest_items` derives its spine protection from the text it prunes (no snapshot parameter: fix_manifest_ids renames ids ahead of it, and the existence set it checks against must be the layout its hrefs are written in — `present_src` when space renames are active, matching the content-doc prune). 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.55.0 (issue #16) the RSC-008 half lives beside the prune: `collect_undeclared_resources` (one whole-book census: content img/link, inline `<style>` url(), stylesheet url(), OPF guide refs) + `declare_missing_manifest_items` (sorted `bindery-dN` items before `</manifest>`, `_DECLARE_MEDIA_TYPES` blessed extensions only), gated and threaded through `RepairFlags.declare_missing`. 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).
163
+ - `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars. Since v0.55.0 (issue #15) the default oracle budget is size-scaled (`oracle_timeout_for`: 300s at or under 10 MB, +60s per started 10 MB above, 1800s cap), one subprocess retry follows a timed-out attempt (the daemon path's subprocess fallback is that attempt), and only a double timeout raises `OracleTimeout`, which the gate surfaces as `(epubcheck timeout)` instead of `(epubcheck failed)` (the sweep selectors catch it and keep the book a candidate).
142
164
  - `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.
143
- - `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; since v0.52.0 `process_book` carries the spine-resolution veto (issue #10) above every verdict path, promotions included: a candidate whose spine dangles more than the source's is `reject` with `(spine collapse)` appended to the summary, whatever the counts say. `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. Since v0.47.1 the help is two-level (the --help-repairs reference is
165
+ - `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; since v0.52.0 `process_book` carries the spine-resolution veto (issue #10) above every verdict path, promotions included: a candidate whose spine dangles more than the source's is `reject` with `(spine collapse)` appended to the summary, whatever the counts say. `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. The `observe` verb (v0.53.0) writes schema v2 artifacts since v0.55.0 (issue #13): `codes.messages` (renamed from the mislabeled `occurrences`) counts aggregated epubcheck JSON message entries, `codes.occurrences` now carries the true per-site scale (summed `locations`), a `counting` block states both scales in the artifact, and `--against` accepts v1 or v2 (the trend keys exist in both). 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. Since v0.47.1 the help is two-level (the --help-repairs reference is
144
166
  custom-rendered and colors itself with the CPython 3.14 argparse theme,
145
167
  gated by argparse's own _colorize detection so the levels always agree) and the repair-flag inventory is one table: `_REPAIR_FLAG_TABLE` (dest + one-line short help + long reference text) registers the compact grouped `--help` (argparse argument groups, hand-short usage line) and `--help-repairs` renders the long descriptions (a custom argparse Action, deliberately NOT store_true so the wiring test's selection count ignores it); adding a flag means adding a table row. Since v0.48.0 the metadata.db doors are enforced: `_require_closed_calibre` (pgrep fail-closed, exit 1) guards `audit --tag` and `library --apply --install-to-calibre` (run phase3 transitively), and `--help-json` (a custom argparse Action like --help-repairs, never colored) dumps the per-verb exit contract and the door list; since v0.48.1 the per-verb exit contracts tell the code's truth (repair: 0 probed/written incl. partial / 1 trouble, never 2; audit: 0/1/2 plus 3 for findings+write-failure; library and the run slices: the unified 0/2/1); since v0.49.0 the single-file verb's no-output form is a probe (the gate runs, the record's `output` is null and `applied` false, nothing is written anywhere; the old implicit `(repaired).epub` sibling was issue #7's import litter in a vetted tree, and writing now needs an explicit DST). `library --workers N` (v0.30.0) parallelizes only the sweep's candidate pass, in windows of N consumed in order so `--limit` stays lazy; the repair phase is never parallel (shared workdir, atomic-replacement contract). Since v0.40.0 `main()` guards the VirInvictus stack: a `ModuleNotFoundError` naming `vir_tui`/`cquarry` (marker-gated to 3.14+ on the 3.12 floor) becomes one stderr line and trouble exit 2 instead of a traceback; anything else missing still raises.
146
168
  - `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.
147
- - `tests/`: transforms, end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification, contamination since v0.50.0), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, the version pin and the syntax-floor grammar guard, and the Calibre plugin (build drift + run behavior under calibre stubs). Since the v0.46.0 follow-ups: `tests/test_flags_wiring.py` reflectively pins the RepairFlags inventory to the argparse dests and `_flags_from_args` mapping (a flag added without a field, a field without a flag, or a remapped line fails there), the all-off defaults, and the version gate's caller-immutability contract (test_epub's `TestVersionGateKeepsFlagsIntact`); `tests/test_comment_hyphens.py` carries the RSC-016 fix; `tests/test_flags_real_core.py` drives every repair flag from argv through the unmocked core (--no-validate; the gate itself stays pinned by the mocked-oracle tests and runs for real wherever epubcheck exists). `tests/test_contamination.py` (v0.50.0) carries the three contamination sweeps, the advisory contract, the `_dir_dispatch` key pin, and the cover-routing regression. The v0.46.0 trio (test_flags_wiring, test_comment_hyphens, test_flags_real_core) rides CI's core-compat 3.12/3.13 leg; the hand-listed module list there must gain an entry for every new stack-free test module (audit-side test modules like test_contamination stay on the 3.14 leg by convention).
169
+ - `tests/`: transforms (including the shared duplicate-id rename), end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification, contamination since v0.50.0), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, the version pin and the syntax-floor grammar guard, and the Calibre plugin (build drift + run behavior under calibre stubs). Since the v0.46.0 follow-ups: `tests/test_flags_wiring.py` reflectively pins the RepairFlags inventory to the argparse dests and `_flags_from_args` mapping (a flag added without a field, a field without a flag, or a remapped line fails there), the all-off defaults, and the version gate's caller-immutability contract (test_epub's `TestVersionGateKeepsFlagsIntact`); `tests/test_comment_hyphens.py` carries the RSC-016 fix; `tests/test_flags_real_core.py` drives every repair flag from argv through the unmocked core (--no-validate; the gate itself stays pinned by the mocked-oracle tests and runs for real wherever epubcheck exists). `tests/test_contamination.py` (v0.50.0) carries the three contamination sweeps, the advisory contract, the `_dir_dispatch` key pin, and the cover-routing regression. The v0.46.0 trio (test_flags_wiring, test_comment_hyphens, test_flags_real_core) rides CI's core-compat 3.12/3.13 leg; the hand-listed module list there must gain an entry for every new stack-free test module (audit-side test modules like test_contamination stay on the 3.14 leg by convention). The v0.55.0 batch (issues #11-#16): `tests/test_validate.py` pins the size-scaled timeout and the retry-then-OracleTimeout contract, `tests/test_observe.py` the v2 line format (`CODE:messages:occurrences`), the renamed codes block, the counting envelope, and v1 `--against` acceptance, `tests/test_epub.py::TestDeclareMissingItems` the RSC-008 declarer (sorted deterministic items, blessed media types only, id collisions prefixed, schemes/fragments/spaces/declared skipped), `tests/test_transforms.py::TestFixDuplicateIds` the content-doc rename, and `tests/test_flags_real_core.py` drives `--fix-duplicate-ids`, `--declare-missing-items`, and the extended `--strip-epub3-attrs` set through the real argv-to-fix path.
148
170
 
149
171
  ## Conventions
150
172