bindery-cli 0.51.0__tar.gz → 0.53.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 (55) hide show
  1. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/.github/workflows/ci.yml +2 -1
  2. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/AGENTS.md +11 -3
  3. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/PKG-INFO +34 -3
  4. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/README.md +33 -2
  5. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/patchnotes.md +110 -0
  6. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/pyproject.toml +1 -1
  7. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/roadmap.md +10 -0
  8. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/spec.md +65 -1
  9. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/src/bindery/__init__.py +3 -3
  10. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/src/bindery/audit.py +5 -2
  11. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/src/bindery/cli.py +82 -1
  12. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/src/bindery/epub.py +61 -7
  13. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/src/bindery/library.py +7 -2
  14. bindery_cli-0.53.0/src/bindery/observe.py +526 -0
  15. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_help.py +1 -1
  16. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_library.py +13 -0
  17. bindery_cli-0.53.0/tests/test_observe.py +358 -0
  18. bindery_cli-0.53.0/tests/test_spine_guard.py +300 -0
  19. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/uv.lock +1 -1
  20. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/.github/FUNDING.yml +0 -0
  21. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/.github/workflows/publish.yml +0 -0
  22. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/.gitignore +0 -0
  23. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/LICENSE +0 -0
  24. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/docs/screenshots/library-sweep.png +0 -0
  25. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/logo.svg +0 -0
  26. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/plugin/__init__.py +0 -0
  27. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/project.done +0 -0
  28. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/run_tests.sh +0 -0
  29. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/scripts/FastSweep.java +0 -0
  30. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/scripts/build_plugin.py +0 -0
  31. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/scripts/fast_sweep.py +0 -0
  32. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/src/bindery/__main__.py +0 -0
  33. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/src/bindery/pagination.py +0 -0
  34. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/src/bindery/reserialize.py +0 -0
  35. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/src/bindery/transforms.py +0 -0
  36. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/src/bindery/validate.py +0 -0
  37. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/src/bindery/watermark.py +0 -0
  38. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_audit.py +0 -0
  39. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_cli.py +0 -0
  40. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_comment_hyphens.py +0 -0
  41. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_contamination.py +0 -0
  42. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_cover_tocdrift.py +0 -0
  43. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_epub.py +0 -0
  44. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_flags_real_core.py +0 -0
  45. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_flags_wiring.py +0 -0
  46. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_matcher_hardening.py +0 -0
  47. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_pagination.py +0 -0
  48. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_plugin.py +0 -0
  49. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_reserialize.py +0 -0
  50. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_space_renames.py +0 -0
  51. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_transforms.py +0 -0
  52. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_validate.py +0 -0
  53. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_version.py +0 -0
  54. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_watermark.py +0 -0
  55. {bindery_cli-0.51.0 → bindery_cli-0.53.0}/tests/test_xml_hardening.py +0 -0
@@ -61,7 +61,8 @@ jobs:
61
61
  tests.test_watermark tests.test_reserialize tests.test_version
62
62
  tests.test_plugin tests.test_validate
63
63
  tests.test_comment_hyphens tests.test_flags_wiring
64
- tests.test_flags_real_core
64
+ tests.test_flags_real_core tests.test_spine_guard
65
+ tests.test_observe
65
66
  plugin-compat:
66
67
  name: Parse-check the plugin zip under the interpreters Calibre embeds
67
68
  runs-on: ubuntu-latest
@@ -115,7 +115,15 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
115
115
  `process_book` reclassifies the verdict to `partial` (a fatal package halts the
116
116
  metadata checks, so the dtb:uid comparison never ran in either measurement and the
117
117
  real sync measures as no gain); application behavior is unchanged, since still-fatal
118
- books are never applied. Changing either bar means re-running the library dry run.
118
+ books are never applied. One structural veto rides above the counts (v0.52.0,
119
+ issue #10): `process_book` probes source and candidate with `epub.spine_dangles`
120
+ (itemref -> manifest item -> archive entry, resolved through the same helper the
121
+ repair's existence checks use) and rejects any candidate whose dangle count rises
122
+ (`(spine collapse)` in the summary) — a repair that orphans live itemrefs removes
123
+ the broken documents' errors from the measurement, so a destroyed book can read as
124
+ an error reduction. The probe needs evidence on both sides (an unreadable package
125
+ vetoes nothing); `--no-validate` skips it with the rest of the gate. Changing either
126
+ bar (or the veto) means re-running the library dry run.
119
127
  - **Library writes are sacred.** Replacement must stay atomic (temp in same dir, then
120
128
  `os.replace`), touch only the `.epub`, preserve mode, and be dry-run by default.
121
129
  Calibre format installation goes through cquarry's write module (`--install-to-calibre`;
@@ -129,10 +137,10 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
129
137
  - `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
130
138
  - `src/bindery/reserialize.py`: structural repair via `html5lib`.
131
139
  - `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).
132
- - `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).
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).
133
141
  - `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars.
134
142
  - `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.
135
- - `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. Since v0.47.1 the help is two-level (the --help-repairs reference is
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
136
144
  custom-rendered and colors itself with the CPython 3.14 argparse theme,
137
145
  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.
138
146
  - `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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: bindery-cli
3
- Version: 0.51.0
3
+ Version: 0.53.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
@@ -95,7 +95,7 @@ Every repair is gated by [epubcheck](https://github.com/w3c/epubcheck). The acce
95
95
  - If a book **had fatals**, success means **fewer fatals**. The error count may rise as previously-hidden schema warnings become visible once the file parses; that is the book going from "won't open" to "opens with nits," not a regression.
96
96
  - If a book had **no fatals**, an error increase is a real regression, so a strict error decrease is required.
97
97
 
98
- Introducing a net-new fatal is always rejected. If epubcheck itself fails to run (crash, timeout, unparsable output), the book is reported as an error and never applied; only an explicit `--no-validate` skips the gate. Originals are never modified except by an explicit, atomic in-place replace (see below), and even then only after the gate accepts the result.
98
+ Introducing a net-new fatal is always rejected. One structural veto rides above the counts: the repairer probes source and candidate with a spine-resolution check (itemref to manifest item to archive entry), and any candidate whose spine dangles more than the original's is rejected no matter what the counts say, because a repair that orphans live reading-order references can otherwise measure as an improvement. If epubcheck itself fails to run (crash, timeout, unparsable output), the book is reported as an error and never applied; only an explicit `--no-validate` skips the gate. Originals are never modified except by an explicit, atomic in-place replace (see below), and even then only after the gate accepts the result.
99
99
 
100
100
  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.
101
101
 
@@ -195,9 +195,12 @@ without a gate, and the mode costs two epubcheck runs per imported book.
195
195
 
196
196
  ## Usage
197
197
 
198
- Five verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
198
+ Six verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
199
199
  reports content flaws without touching anything, `bindery library` sweeps a Calibre
200
200
  library tree (dry run by default; `--apply` replaces accepted books atomically in place),
201
+ `bindery observe` validates every EPUB under a tree in one warm-JVM pass and writes one
202
+ versioned `.observe` census artifact (counts and error codes together, tabulated, with
203
+ the gated repair preview and `--against` trend diffing),
201
204
  `bindery run` composes the acquisition pathway's EPUB slices (phase-1 pre-import
202
205
  vetting, phase-3 scoped post-import repair) for a calling agent, and `bindery doctor`
203
206
  checks the installation (see Install).
@@ -353,6 +356,34 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
353
356
  - A `partial` book (improved but still unable to open) is reported for manual follow-up and fails the run with exit 2, in `library`, `run phase1`, and `run phase3` alike: a book that still needs a human is trouble.
354
357
  - `repair` refuses to overwrite an existing output file unless `--force` is given.
355
358
 
359
+ ## Observing a library
360
+
361
+ `bindery observe` is the whole-library census: one warm-JVM pass validates
362
+ every EPUB (counts and error codes together, clean books included), the
363
+ result is tabulated (severity histogram, dominant error-code classes, worst
364
+ offenders), and one self-describing `.observe` artifact carries the per-book
365
+ records so any later question can be answered without re-validating:
366
+
367
+ ```sh
368
+ bindery observe ~/docs/Calibre\ Library --output ~/observe/base.observe
369
+ ```
370
+
371
+ - Strictly read-only: the only file written is the artifact, and the writer
372
+ refuses to land it inside the scanned root (the default output is
373
+ `observe-<timestamp>.observe` in the current directory).
374
+ - The optional repair preview (default on, `--no-preview` skips) composes the
375
+ shipped library runner in-process as a dry-run over the default flag set:
376
+ it measures what `--apply` would write, per candidate, and never writes.
377
+ - `--against base.observe` carries a trend block in the new artifact: library
378
+ deltas, error-mass delta, and per-code changes with `new_codes` and
379
+ `resolved_codes`. Artifacts are versioned (`bindery-observe-v1`); a
380
+ schema mismatch is a usage error, never a silently incomparable trend.
381
+ - A book the JVM cannot read arrives as a sentinel record instead of being
382
+ dropped, and a run that comes back short of the input count refuses to
383
+ write a partial census. The library and audit walks skip `.caltrash`.
384
+ - Exit codes: 0 artifact written, 1 invocation problem, 2 the census harness
385
+ failed mid-run.
386
+
356
387
  ## Run slices
357
388
 
358
389
  `bindery run` wraps the acquisition pathway's EPUB steps as verbs. They add no
@@ -68,7 +68,7 @@ Every repair is gated by [epubcheck](https://github.com/w3c/epubcheck). The acce
68
68
  - If a book **had fatals**, success means **fewer fatals**. The error count may rise as previously-hidden schema warnings become visible once the file parses; that is the book going from "won't open" to "opens with nits," not a regression.
69
69
  - If a book had **no fatals**, an error increase is a real regression, so a strict error decrease is required.
70
70
 
71
- Introducing a net-new fatal is always rejected. If epubcheck itself fails to run (crash, timeout, unparsable output), the book is reported as an error and never applied; only an explicit `--no-validate` skips the gate. Originals are never modified except by an explicit, atomic in-place replace (see below), and even then only after the gate accepts the result.
71
+ Introducing a net-new fatal is always rejected. One structural veto rides above the counts: the repairer probes source and candidate with a spine-resolution check (itemref to manifest item to archive entry), and any candidate whose spine dangles more than the original's is rejected no matter what the counts say, because a repair that orphans live reading-order references can otherwise measure as an improvement. If epubcheck itself fails to run (crash, timeout, unparsable output), the book is reported as an error and never applied; only an explicit `--no-validate` skips the gate. Originals are never modified except by an explicit, atomic in-place replace (see below), and even then only after the gate accepts the result.
72
72
 
73
73
  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.
74
74
 
@@ -168,9 +168,12 @@ without a gate, and the mode costs two epubcheck runs per imported book.
168
168
 
169
169
  ## Usage
170
170
 
171
- Five verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
171
+ Six verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
172
172
  reports content flaws without touching anything, `bindery library` sweeps a Calibre
173
173
  library tree (dry run by default; `--apply` replaces accepted books atomically in place),
174
+ `bindery observe` validates every EPUB under a tree in one warm-JVM pass and writes one
175
+ versioned `.observe` census artifact (counts and error codes together, tabulated, with
176
+ the gated repair preview and `--against` trend diffing),
174
177
  `bindery run` composes the acquisition pathway's EPUB slices (phase-1 pre-import
175
178
  vetting, phase-3 scoped post-import repair) for a calling agent, and `bindery doctor`
176
179
  checks the installation (see Install).
@@ -326,6 +329,34 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
326
329
  - A `partial` book (improved but still unable to open) is reported for manual follow-up and fails the run with exit 2, in `library`, `run phase1`, and `run phase3` alike: a book that still needs a human is trouble.
327
330
  - `repair` refuses to overwrite an existing output file unless `--force` is given.
328
331
 
332
+ ## Observing a library
333
+
334
+ `bindery observe` is the whole-library census: one warm-JVM pass validates
335
+ every EPUB (counts and error codes together, clean books included), the
336
+ result is tabulated (severity histogram, dominant error-code classes, worst
337
+ offenders), and one self-describing `.observe` artifact carries the per-book
338
+ records so any later question can be answered without re-validating:
339
+
340
+ ```sh
341
+ bindery observe ~/docs/Calibre\ Library --output ~/observe/base.observe
342
+ ```
343
+
344
+ - Strictly read-only: the only file written is the artifact, and the writer
345
+ refuses to land it inside the scanned root (the default output is
346
+ `observe-<timestamp>.observe` in the current directory).
347
+ - The optional repair preview (default on, `--no-preview` skips) composes the
348
+ shipped library runner in-process as a dry-run over the default flag set:
349
+ it measures what `--apply` would write, per candidate, and never writes.
350
+ - `--against base.observe` carries a trend block in the new artifact: library
351
+ deltas, error-mass delta, and per-code changes with `new_codes` and
352
+ `resolved_codes`. Artifacts are versioned (`bindery-observe-v1`); a
353
+ schema mismatch is a usage error, never a silently incomparable trend.
354
+ - A book the JVM cannot read arrives as a sentinel record instead of being
355
+ dropped, and a run that comes back short of the input count refuses to
356
+ write a partial census. The library and audit walks skip `.caltrash`.
357
+ - Exit codes: 0 artifact written, 1 invocation problem, 2 the census harness
358
+ failed mid-run.
359
+
329
360
  ## Run slices
330
361
 
331
362
  `bindery run` wraps the acquisition pathway's EPUB steps as verbs. They add no
@@ -1,5 +1,115 @@
1
1
  # bindery-cli Patch Notes
2
2
 
3
+ ## v0.53.0 (2026-10-24)
4
+
5
+ ### `bindery observe`: the whole-library census, one artifact per run
6
+
7
+ The 2026-10-24 whole-library autopsy answered "where are we at" the hard way:
8
+ a dry-run sweep plus hand tabulation in the main thread. That session is now
9
+ a verb. `bindery observe PATH` validates every EPUB under a tree in one
10
+ warm-JVM pass, paying JVM startup once and running the parallel stream across
11
+ all cores, and writes one self-describing `.observe` artifact: the library
12
+ totals, a severity histogram (fatal books, error-count buckets, warnings-only,
13
+ unreadable, error mass), the error-code profile as occurrences and distinct
14
+ books, the worst offenders, and the per-book census rows so any later question
15
+ can be answered from the artifact without re-validating.
16
+
17
+ The harness embeds its Java like the FastDaemon does (JEP 330 single-file
18
+ launcher, no javac, in-memory compile), so the verb ships in the wheel and
19
+ the scripts/ benchmarking facility stays unshipped and untouched. Counting
20
+ matches the subprocess oracle by construction: the harness scans the JSON
21
+ document `generate()` serializes, the same document epubcheck --json emits
22
+ and the gate is calibrated on. The census answers for every input path: a
23
+ book the JVM cannot read arrives as the `-1,-1,-1` sentinel record instead of
24
+ being dropped (the scripts/ audit mode's silence is exactly why a missing-
25
+ rows warning was needed there), and a run that comes back short of the input
26
+ count refuses to write a partial census (exit 2).
27
+
28
+ The optional repair preview (default on; `--no-preview` skips) composes the
29
+ shipped library runner in-process, the `run phase1` pattern: a dry-run sweep
30
+ over the default flag set recording per-candidate status, before/after
31
+ counts, and the fix breakdown. It measures what `--apply` would write and
32
+ never writes. Artifacts are versioned (`bindery-observe-v1`); `--against
33
+ FILE` composes a trend block against a previous artifact of the same schema
34
+ (library deltas, error-mass delta, per-code book-count changes with
35
+ `new_codes`/`resolved_codes`), and a schema mismatch is a usage error rather
36
+ than a silently incomparable trend. The verb is strictly read-only: the only
37
+ file written is the artifact, and the writer refuses to land it inside the
38
+ scanned root (default output `observe-<timestamp>.observe` in the current
39
+ directory). Exit contract: 0 artifact written, 1 invocation problem, 2 census
40
+ harness failure.
41
+
42
+ ### `.caltrash` is not library content
43
+
44
+ The same session's census found two trashed books walking the tree as repair
45
+ candidates. `iter_epubs` (the library sweep's walk) and the audit directory
46
+ walk now skip anything under `.caltrash`: a deletion pending Calibre's own
47
+ cleanup is never a repair candidate, and an `--apply` could in principle have
48
+ written into the trash.
49
+
50
+ ## v0.52.0 (2026-10-21)
51
+
52
+ ### The repairer's own prune could destroy the book it was repairing (issue #10)
53
+
54
+ The 2026-10-21 re-source wave caught it live: six fan conversions (the Rihannsu
55
+ rips: My Enemy My Ally, three Ascendance rips, two The Final Reflection rips)
56
+ whose content filenames carry raw spaces (`DUANE, Diane - [Star Trek - TOS -
57
+ Rihannsu 1] - My Enemy, My Ally_split_000.htm`) and whose manifest ids carry
58
+ commas and brackets, which are invalid XML name characters. The gated sweep
59
+ accepted `0f/17e/8w -> 0f/10e/0w` and applied `manifest_items_pruned:8`: the
60
+ repair deleted every spine document's manifest item while the archive entry sat
61
+ right there under its new underscore spelling, and left a book whose spine
62
+ resolved to the title page. The gate measured fewer messages because the
63
+ destroyed documents' errors had left the measurement entirely.
64
+
65
+ Two stacked defects, both fixed:
66
+
67
+ - **The prune's existence check read the wrong layout.** With
68
+ `--encode-url-spaces` active, `prune_missing_manifest_items` ran ahead of the
69
+ reference rewrite on hrefs still carrying raw spaces, but checked them
70
+ against the archive's post-rename spellings; every raw-space href read as
71
+ missing. The check now uses the layout the OPF text is actually written in
72
+ (`present_src`, exactly what the content-document prune already did), so an
73
+ href is judged against the archive as the text sees it and the rename half
74
+ handles both sides together.
75
+ - **The spine guard described an earlier spelling of the ids.** The guard that
76
+ keeps spine documents out of the prune was snapshotted from the OPF before
77
+ `--fix-manifest-ids` renamed the item ids and spine idrefs, so by the time
78
+ the prune ran it recognized nothing. The prune now derives its spine set
79
+ from the very text it reads; the snapshot parameter is gone, and the guard
80
+ can never drift from the text again.
81
+
82
+ And the class is guarded, not just this instance: `process_book` now probes
83
+ source and candidate with `epub.spine_dangles` (itemref to manifest item to
84
+ archive entry, resolved through the same helper the repair's own existence
85
+ checks use) and vetoes any candidate whose spine dangles more than the
86
+ source's: `reject` with `(spine collapse)` in the summary, riding above the
87
+ message counts and above every fix-class promotion. A probe that cannot read a
88
+ package vetoes nothing (the veto needs evidence on both sides), and
89
+ `--no-validate` skips it with the rest of the gate.
90
+
91
+ On the issue's fixtures: The Final Reflection now repairs clean and gates
92
+ accept (`0f/30e/22w -> 0f/3e/0w`, twenty-two entries renamed, zero prunes,
93
+ spine fully resolved). My Enemy My Ally still refuses, now for an honest
94
+ reason: the fan conversion's brackets and commas are illegal URL characters
95
+ too, and once the spaces clear, epubcheck re-reports each affected link as its
96
+ own RSC-020 (`17 -> 32` aggregated), so the candidate measures as a regression
97
+ and nothing is applied. That book waits for a manual pass, or a future repair
98
+ class that percent-encodes the remaining illegal characters; refusing is the
99
+ correct outcome for a repair that cannot be made deterministically safe.
100
+
101
+ Eleven tests joined the suite (702 total): the `spine_dangles` probe unit
102
+ tests (healthy spine, the orphaned-itemref shape, the absent-file shape, and
103
+ probe-failure-is-None), the prune guard's renamed-id regression and its
104
+ non-spine prune, the end-to-end raw-space book (renames land, nothing is
105
+ pruned, every itemref walks to a file), the veto wiring in `process_book`
106
+ (collapse rejects improving counts, intact spine keeps the normal verdict,
107
+ unreadable candidate vetoes nothing), and a fixture-backed regression on the
108
+ real My Enemy My Ally pre-repair bytes (skipped where the local fixture is
109
+ absent). The stack-free module joined CI's 3.12/3.13 leg, and the full-corpus
110
+ dry run over the library (6,774 books, repaired candidates measured against
111
+ their sources) confirmed zero veto fires.
112
+
3
113
  ## v0.51.0 (2026-10-17)
4
114
 
5
115
  ### The unbound-prefix repair: the Calibre embed scar comes off the OPF (issue #9)
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "bindery-cli"
7
- version = "0.51.0"
7
+ version = "0.53.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 = [
@@ -45,9 +45,19 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
45
45
  | 0.49 | The probe form (issue #7): single-file repair without an output path runs the gate and writes nothing; writing needs an explicit DST | v0.49.0 |
46
46
  | 0.50 | The contamination analyzer (issue #8): foreign-title template stamps, fan-bundle ad signatures, review-paste front matter; advisory by contract, archive-wide corpus (`Book.extra_docs`, capped), and the `_dir_dispatch` map that fixes the v0.44.0 cover/tocdrift ocr misroute in directory/single mode | v0.50.0 |
47
47
  | 0.51 | The unbound-prefix repair (issue #9): `--fix-unbound-prefix` binds the Calibre embed scar's undeclared attribute prefix inline (evidence-based URI, scope-tracked, refuse over guess), plus the masked-ncx-gain rule that stops a real dtb:uid sync reading as no measurable gain under a fatal package | v0.51.0 |
48
+ | 0.52 | The spine guard (issue #10): the manifest prune reads the layout its hrefs are written in and derives its spine protection from the text it prunes (the raw-space wave's spine collapse), and `process_book` vetoes any candidate whose spine (itemref -> item -> archive) dangles more than the source's, above the counts and every promotion | v0.52.0 |
49
+ | 0.53 | `bindery observe` (the observatory): the whole-library census in one warm-JVM pass (counts and error codes together, sentinel-backed so no book is dropped), tabulation (severity histogram, code profile, worst offenders), the gated repair preview composed in-process, the versioned `.observe` artifact with `--against` trend diffing and the keep-root-clean output guard; the library and audit walks skip `.caltrash` | v0.53.0 |
48
50
 
49
51
  ## Open work
50
52
 
53
+ - [ ] **Percent-encode illegal URL characters in references**: the RSC-020 class
54
+ beyond spaces. Opened by issue #10's My Enemy My Ally fixture: once
55
+ `--encode-url-spaces` clears the spaces, the fan conversion's brackets and
56
+ commas re-report as 28 individual RSC-020s (previously folded into one
57
+ aggregated RSC-005), so the candidate measures as a regression and the
58
+ gate refuses a book that is otherwise repaired. Needs the same
59
+ entry-and-reference coordination as the space renames, with the
60
+ decode-before-lookup epubcheck rule verified per character class.
51
61
  - [ ] **Obfuscation-aware encryption.xml repair**: prune stale obfuscation entries
52
62
  when font magic bytes prove the fonts are decrypted in place; drop
53
63
  encryption.xml when only obfuscation entries remain and fonts verify. NEVER
@@ -178,7 +178,16 @@ every EPUB3 book in an `--all` sweep taking exactly that damage).
178
178
  (the anchor and its text stay), absent `<img>` sources (replaced by their escaped
179
179
  alt text when they carry one, dropped otherwise), and orphaned non-spine OPF manifest
180
180
  `<item>` declarations. Spine documents are never pruned: a missing spine document is
181
- a damaged fragment for the audit's spine-integrity check, never a silent drop.
181
+ a damaged fragment for the audit's spine-integrity check, never a silent drop. The
182
+ manifest existence check resolves the href the way the resolver does (unquoted,
183
+ normalized) and compares it against the layout the OPF text is written in: when
184
+ `--encode-url-spaces` is renaming entries, the prune runs ahead of the reference
185
+ rewrite and reads pre-rename hrefs, so it checks against the pre-rename archive
186
+ (a raw-space href judged against renamed spellings is how live spine documents came
187
+ to be pruned, issue #10). The spine protection is derived from the very text the
188
+ prune reads, never snapshotted earlier: `--fix-manifest-ids` may have renamed item
189
+ ids and spine idrefs ahead of it in the OPF pipeline, and a guard describing the old
190
+ spelling protects nothing.
182
191
  - **`--strip-broken-anchors`**: strip `href` attributes that cannot resolve, keeping
183
192
  the anchor text byte-for-byte. A `#fragment` the target document does not define
184
193
  (RSC-020 "fragment identifier not defined", RSC-012 "points to the wrong element") is
@@ -378,6 +387,20 @@ be run or its output cannot be parsed during a validated run, the book is an `er
378
387
  the gate has not accepted anything, so nothing is applied or written. With
379
388
  `--no-validate`, the gate is skipped and repairs are trusted on the RepairReport alone.
380
389
 
390
+ One structural veto rides above the count gate: the spine-resolution check. The
391
+ message count is not spine-aware, so a repair that orphans live itemrefs (manifest
392
+ items pruned whose files the archive still carries, idrefs rewritten to forms that
393
+ match nothing) removes the broken documents' errors from the measurement and a
394
+ destroyed book can read as an error reduction (issue #10: a raw-space fan
395
+ conversion's eight spine items pruned as "missing", gate accepted
396
+ `0f/17e/8w -> 0f/10e/0w`). `process_book` therefore probes both packages with
397
+ `spine_dangles` (itemref -> manifest item -> archive entry, resolved through the
398
+ same helper the repair's existence checks use) and vetoes any candidate whose
399
+ dangle count rises: `reject`, regardless of the counts and regardless of which
400
+ bar a fix class promotes under. The probe needs evidence on both sides — a
401
+ package it cannot read (unreadable archive, no locatable OPF) vetoes nothing —
402
+ and `--no-validate` skips it with the rest of the gate.
403
+
381
404
  The oracle itself runs two ways: the `epubcheck --json -` subprocess, or a persistent
382
405
  daemon (`_EpubcheckDaemon`, a bounded pool sized by `--workers`) that writes
383
406
  `FastDaemon.java` at runtime and launches it through Java's single-file source
@@ -549,6 +572,47 @@ the audit's trouble, so it takes the trouble slot), 2 for its own usage errors (
549
572
  path that is not a directory, a directory with no EPUBs, an unknown book id) and
550
573
  for tagging-setup failure.
551
574
 
575
+ ## Observe subcommand (read-only census)
576
+
577
+ `bindery observe PATH [--output FILE] [--against FILE] [--workers N] [--limit N]
578
+ [--no-preview]` validates every EPUB under a tree in one warm-JVM pass and
579
+ writes one self-describing `.observe` artifact. It is the whole-library
580
+ answering of "where are we at": the census measures every book (clean ones
581
+ included) for epubcheck counts AND error codes together, tabulates the result
582
+ (library totals, a severity histogram with error-mass and per-count buckets,
583
+ the error-code profile as occurrences and distinct books, the worst offenders),
584
+ and records per-book census rows so any later question can be answered from
585
+ the artifact without re-validating.
586
+
587
+ The census harness embeds its Java like the FastDaemon does (JEP 330, no
588
+ javac, in-memory compile) and always answers for every input path: a book the
589
+ JVM cannot read arrives as the `-1,-1,-1` sentinel record rather than being
590
+ dropped, and a run that comes back short of the input count refuses to write
591
+ a partial census (exit 2). Counting matches the subprocess oracle by
592
+ construction: the harness scans the JSON document `generate()` serializes,
593
+ the same document the gate is calibrated on.
594
+
595
+ The optional repair preview (default on; `--no-preview` skips) composes the
596
+ shipped library runner in-process (`run phase1`'s pattern): a dry-run sweep
597
+ over the default flag set, recording per-candidate status, before/after
598
+ counts, and the fix breakdown. The preview measures what `--apply` would
599
+ write; it never writes. `--workers N` governs the preview's sweep pass; the
600
+ census is parallel inside its own JVM.
601
+
602
+ The artifact is versioned (`schema: bindery-observe-v1`) and strictly
603
+ read-only: the only file the verb writes is the artifact itself, and the
604
+ writer refuses to land it inside the scanned root (the keep-root-clean
605
+ rule; the default output is `observe-<timestamp>.observe` in the current
606
+ directory). `--against FILE` loads a previous artifact of the same schema and
607
+ carries a `trend` block: library-total deltas, error-mass delta, and per-code
608
+ book-count changes with `new_codes`/`resolved_codes`. A schema mismatch is a
609
+ usage error, never a silently incomparable trend. Exit codes: 0 artifact
610
+ written, 1 invocation problem (no EPUBs, toolchain missing, output inside
611
+ the scanned root, `--against` schema mismatch), 2 the census harness failed
612
+ mid-run. The library and audit walks skip `.caltrash` (trash is not library
613
+ content; the 2026-10-24 census found two trashed books walking the tree
614
+ before the guard).
615
+
552
616
  ## Run verbs (acquisition slices)
553
617
 
554
618
  `bindery run phase1 DIR [--json FILE] [--apply-lossy] [--backup DIR] [--non-interactive]`
@@ -3,15 +3,15 @@
3
3
  The repair side: an always-on core of five well-formedness fixes plus the NCX
4
4
  pipeline and the mimetype fix, with the structural repairs, the four lossy
5
5
  strips (page numbers, broken tags, watermarks, stub documents), and the safe opt-ins behind
6
- explicit flags. Around it: the read-only `audit` verb (eight body-text and
7
- structural analyzers), the `library` sweep with atomic in-place replacement in a Calibre
6
+ explicit flags. Around it: the read-only `audit` verb (nine body-text and
7
+ structural analyzers), the read-only `observe` census (one warm-JVM whole-library pass writing a versioned `.observe` artifact), the `library` sweep with atomic in-place replacement in a Calibre
8
8
  library, the `run phase1`/`phase3` acquisition slices, and the Bindery Repair
9
9
  Calibre plugin built from this core.
10
10
 
11
11
  Single source of truth for the version. pyproject.toml must match VERSION below.
12
12
  """
13
13
 
14
- VERSION = "0.51.0"
14
+ VERSION = "0.53.0"
15
15
  __version__ = VERSION
16
16
 
17
17
  from .epub import RepairReport, repair_epub # noqa: E402
@@ -3243,9 +3243,12 @@ def run_directory(
3243
3243
  print(f"ERROR: {directory} is not a directory.")
3244
3244
  return 2
3245
3245
  # the is_file filter matches iter_epubs: a directory named *.epub is a
3246
- # spurious scan error, not a book
3246
+ # spurious scan error, not a book; .caltrash is excluded for the same
3247
+ # reason it is excluded there (trash is not library content)
3247
3248
  epubs = sorted(
3248
- p for p in directory.rglob("*.epub", case_sensitive=False) if p.is_file()
3249
+ p
3250
+ for p in directory.rglob("*.epub", case_sensitive=False)
3251
+ if p.is_file() and ".caltrash" not in p.parts
3249
3252
  )
3250
3253
  if not epubs:
3251
3254
  print(f"No .epub files found under {directory}")
@@ -31,7 +31,7 @@ from .audit import (
31
31
  from .audit import (
32
32
  run_library as run_audit_library,
33
33
  )
34
- from .epub import RepairFlags, ncx_uid_mismatch, repair_epub
34
+ from .epub import RepairFlags, ncx_uid_mismatch, repair_epub, spine_dangles
35
35
  from .library import (
36
36
  CalibreIdResolver,
37
37
  atomic_replace,
@@ -39,6 +39,7 @@ from .library import (
39
39
  iter_epubs,
40
40
  make_backup,
41
41
  )
42
+ from .observe import run_observe
42
43
  from .validate import (
43
44
  CheckResult,
44
45
  epubcheck_available,
@@ -214,10 +215,31 @@ def process_book(
214
215
  verdict = "partial"
215
216
  else:
216
217
  verdict = "accept"
218
+ # The spine-resolution veto (issue #10). The epubcheck count is not
219
+ # spine-aware: a repair that orphans live itemrefs (manifest items pruned
220
+ # whose files the archive still carries, idrefs rewritten to forms that
221
+ # match nothing) removes the broken documents' errors from the
222
+ # measurement, so a destroyed book can read as an error reduction. A
223
+ # spine that resolved before the repair and dangles after it is a
224
+ # regression no message count can buy back: reject, regardless of the
225
+ # counts or the bar any fix class promotes under. The probe runs on both
226
+ # real files; a probe failure (unreadable package, no locatable OPF)
227
+ # carries no evidence and vetoes nothing.
228
+ dangles_before = spine_dangles(epub)
229
+ dangles_after = spine_dangles(repaired)
230
+ spine_collapse = (
231
+ dangles_before is not None
232
+ and dangles_after is not None
233
+ and dangles_after > dangles_before
234
+ )
235
+ if spine_collapse:
236
+ verdict = "reject"
217
237
  if verdict == "reject":
218
238
  summary += " (REGRESSION)"
219
239
  elif verdict == "noop":
220
240
  summary += " (no measurable gain)"
241
+ if spine_collapse:
242
+ summary += " (spine collapse)"
221
243
  status = "equal" if verdict == "noop" else verdict
222
244
  return Outcome(
223
245
  epub,
@@ -2367,6 +2389,65 @@ def build_parser() -> argparse.ArgumentParser:
2367
2389
  _add_repair_flags(lib)
2368
2390
  lib.set_defaults(func=run_library)
2369
2391
 
2392
+ obs = sub.add_parser(
2393
+ "observe",
2394
+ help="read-only whole-library census: one versioned .observe artifact",
2395
+ usage="bindery observe [options] path",
2396
+ description="Validate every EPUB under a tree in one warm-JVM pass "
2397
+ "(epubcheck counts and error codes together), tabulate the census "
2398
+ "(severity histogram, dominant error-code classes, worst offenders), "
2399
+ "optionally compose the gated repair preview (what `bindery library "
2400
+ "--apply` would write: a dry-run over the default flag set), and "
2401
+ "write one self-describing .observe artifact for trend diffing with "
2402
+ "--against. Strictly read-only: the only file written is the "
2403
+ "artifact, and the writer refuses to land it inside the scanned "
2404
+ "root. Exit codes: 0 artifact written, 1 invocation problem (no "
2405
+ "EPUBs, toolchain missing, output inside the scanned root, --against "
2406
+ "schema mismatch), 2 the census harness failed mid-run.",
2407
+ epilog="examples:\n"
2408
+ " bindery observe ~/docs/Calibre\\ Library --output ~/observe/base.observe\n"
2409
+ " bindery observe ~/docs/Calibre\\ Library --output next.observe "
2410
+ "--against base.observe\n",
2411
+ formatter_class=argparse.RawDescriptionHelpFormatter,
2412
+ )
2413
+ obs.add_argument("path")
2414
+ og = obs.add_argument_group("output")
2415
+ og.add_argument(
2416
+ "--output",
2417
+ "-o",
2418
+ metavar="FILE",
2419
+ help="the .observe artifact path (default: observe-<timestamp>.observe "
2420
+ "in the current directory; refused inside the scanned root)",
2421
+ )
2422
+ og.add_argument(
2423
+ "--against",
2424
+ metavar="FILE",
2425
+ help="a previous .observe artifact: the new artifact carries a trend "
2426
+ "delta block (library totals, error mass, per-code changes)",
2427
+ )
2428
+ oc = obs.add_argument_group("run control")
2429
+ oc.add_argument(
2430
+ "--workers",
2431
+ type=int,
2432
+ default=1,
2433
+ metavar="N",
2434
+ help="concurrent epubcheck workers for the preview's sweep pass "
2435
+ "(default 1); the census pass is parallel inside its own JVM",
2436
+ )
2437
+ oc.add_argument(
2438
+ "--limit",
2439
+ type=int,
2440
+ metavar="N",
2441
+ help="validate at most N books (sampling)",
2442
+ )
2443
+ oc.add_argument(
2444
+ "--no-preview",
2445
+ action="store_true",
2446
+ help="skip the repair preview: census and tabulation only, a single "
2447
+ "validation pass",
2448
+ )
2449
+ obs.set_defaults(func=run_observe)
2450
+
2370
2451
  run = sub.add_parser(
2371
2452
  "run",
2372
2453
  help="the acquisition run slices: phase-1 pre-import vetting, phase-3 "