bindery-cli 0.28.0__tar.gz → 0.30.0__tar.gz

{bindery_cli-0.28.0 → bindery_cli-0.30.0}/.gitignore

@@ -14,3 +14,8 @@ testing_facility/top500candidates/*.epub
 
 # Compiled Java scratch (FastSweep harness)
 *.class
+
+# Local virtualenvs (each carries its own auto-generated inner .gitignore,
+# which is the only reason they were invisible until now)
+venv/
+.venv_ci/

{bindery_cli-0.28.0 → bindery_cli-0.30.0}/CLAUDE.md

@@ -14,13 +14,13 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 
 - **Minimal Dependencies.** Runtime deps are exactly: `tqdm` (progress/output),
   `vir-tui` (shared TUI rendering) and `cquarry` (read-only Calibre `metadata.db` access,
-  adopted in v0.16.0). `vir-tui` is PINNED to an exact commit in pyproject.toml
-  (bump deliberately); `cquarry` deliberately tracks `@main` since v0.19.0 so CI always
-  exercises the current library. `html5lib` remains the one approved
+  adopted in v0.16.0), pinned as PyPI ranges in pyproject.toml (`vir-tui>=2.2.0`,
+  `cquarry>=1.9.0`); `uv.lock` records the resolved versions. `html5lib` remains the one approved
   heavy-parsing exception (used only for the `--reserialize` fix, imported lazily so every
   other mode runs without it). Tests use the standard `unittest` framework. epubcheck is an
-  external CLI dependency, and `calibredb` is required for the `--install-to-calibre`
-  feature. Before adding any further Python package, stop and ask.
+  external CLI dependency expected on PATH; `--install-to-calibre` needs no external
+  binary, it re-registers the format through cquarry's write module (the calibredb
+  subprocess was retired in v0.24.0). Before adding any further Python package, stop and ask.
 - **Semantics-preserving transforms by default, everything else fenced behind a flag.**
   The always-on core is exactly five well-formedness fixes (prolog junk, duplicate
   `xmlns`, bare `&`, named entities, void self-closing) plus the NCX pipeline; every core
@@ -51,8 +51,10 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
   visible (they clear errors), so a run with no measurable improvement is a noop and
   nothing is applied. Changing either bar means re-running the library dry run.
 - **Library writes are sacred.** Replacement must stay atomic (temp in same dir, then
-  `os.replace`), touch only the `.epub`, preserve mode, and be dry-run by default. Calibre integrations should seamlessly swap formats using `calibredb add_format -replace`.
-  Never write to the library without `-apply`. Test every change on `/tmp` copies first.
+  `os.replace`), touch only the `.epub`, preserve mode, and be dry-run by default.
+  Calibre format installation goes through cquarry's write module (`--install-to-calibre`;
+  the calibredb subprocess was retired in v0.24.0). Never write to the library without
+  `--apply`. Test every change on `/tmp` copies first.
 
 ## Layout
 
@@ -60,11 +62,11 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets).
 - `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
 - `src/bindery/reserialize.py`: structural repair via `html5lib`.
-- `src/bindery/audit.py`: read-only body-text audits (`content`, `pagenumbers`, `emptytext`, `ocr`, and `monolithic` since v0.21.0, `--max-doc-chars N`) 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.
+- `src/bindery/audit.py`: read-only body-text audits (`content`, `pagenumbers`, `emptytext`, `ocr`, and `monolithic` since v0.21.0, `--max-doc-chars N`) 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).
 - `src/bindery/epub.py`: archive rewrite, NCX uid sync, RepairReport, mismatch detection, and the opt-in structural-repair plumbing (including the CSS precondition scan).
 - `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars.
 - `src/bindery/library.py`: Calibre walk, atomic replace, backups, and native format installation. Since v0.19.0 `CalibreIdResolver` resolves the book id from `metadata.db` through cquarry (one lazy path→id map per run; since v0.20.0 the map comes from `CalibreDB.format_path_index()`, re-normalized with `resolve().lower()` for the resolver's symlinked-directory and case-insensitive matching) — the `(id)` directory-name regex is only the no-catalog fallback. Since v0.24.0 `install_format()` places the repaired file atomically and updates the `data` row through `cquarry.write.WritableCalibreDB` (remove+add in one `batch()`; `add_format` refuses duplicates); the external `calibredb` CLI is gone. Never reintroduce directory-name guessing as the primary source: renamed/mismatched directories would replace the wrong book.
-- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`.
+- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; 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). Both take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. `library --workers N` (v0.30.0) parallelizes only the sweep's candidate pass, in windows of N consumed in order so `--limit` stays lazy; the repair phase is never parallel (shared workdir, atomic-replacement contract).
 - `tests/`: transforms, end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic, archive integrity, spine classification), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, and the version pin.
 
 ## Conventions

bindery_cli-0.28.0/README.md → bindery_cli-0.30.0/PKG-INFO

@@ -1,3 +1,25 @@
+Metadata-Version: 2.5
+Name: bindery-cli
+Version: 0.30.0
+Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
+Author: vrnvctss
+License: MIT
+License-File: LICENSE
+Keywords: calibre,ebook,epub,epubcheck,html-repair,repair,watermarks
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.14
+Requires-Dist: cquarry>=1.9.0
+Requires-Dist: tqdm
+Requires-Dist: vir-tui>=2.2.0
+Provides-Extra: reserialize
+Requires-Dist: html5lib>=1.1; extra == 'reserialize'
+Description-Content-Type: text/markdown
+
 <div align="center">
   <img src="logo.svg" width="96" height="96" alt="bindery-cli logo"/>
   <h1>bindery-cli</h1>
@@ -73,9 +95,11 @@ uv tool install "bindery-cli[reserialize]"             # incl. --reserialize
 
 ## Usage
 
-Three verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
-reports content flaws without touching anything, and `bindery library` sweeps a Calibre
-library tree (dry run by default; `--apply` replaces accepted books atomically in place).
+Four verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
+reports content flaws without touching anything, `bindery library` sweeps a Calibre
+library tree (dry run by default; `--apply` replaces accepted books atomically in place),
+and `bindery run` composes the acquisition pathway's EPUB slices (phase-1 pre-import
+vetting, phase-3 scoped post-import repair) for a calling agent.
 The sections below take each in turn.
 
 ## Auditing
@@ -115,6 +139,12 @@ cd ~/docs/Calibre\ Library && bindery audit all --id 1234,1235
 ```
 `--id` composes with `--tag`: the book is tagged only if the audit flags it.
 
+**Machine-readable reports:** `--json FILE` writes the run's verdicts in the same shape `library --json` uses: one record per book with a `status` (`clean`/`problem`/`error`) and per-analyzer verdicts (`problem`, `status`, `details`), plus the always-on archive/spine verdicts (OK when they were silent). This is the contract downstream consumers of the pre-import vetting slice read.
+```sh
+bindery audit all ~/Downloads/epubs --json vetting-report.json
+```
+With `--id`, `--json` accepts exactly one book id (each single-book run writes the file wholesale).
+
 **Spine-integrity reporting:** Both `audit` and `library` reports now classify manifest/NCX references that point to absent files. A `convention` verdict means the ToC is bloated but the present documents form a consecutive chapter span (e.g., the Wandering Inn official-build pattern, safe). A `fragment` verdict means the span itself is broken.
 
 **Archive integrity:** every audit fully reads each archive entry (CRC + decompression), so a damaged download is reported CORRUPT — with the first broken entry named — instead of being mislabeled EMPTY by `emptytext`. `library --sweep` splits its `unreadable` bucket into `not_a_zip` / `truncated` / `encrypted` / `corrupt_entry`, so the right disease is visible without leaving the sweep.
@@ -165,7 +195,8 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--only {fatals,ncx,all}` restricts the candidate set. `ncx` targets NCX-001 mismatches (detected without epubcheck); `fatals` needs `--audit`.
 - `--id <ids>` limits the sweep to a comma-separated list of Calibre book IDs, skipping the full library walk.
 - `--audit CSV` (the `fatals,errors,warnings,path` format produced by an epubcheck sweep) skips clean books so a run is fast. Paths are resolved on both sides, and a CSV that matches nothing triggers a loud warning instead of silently selecting zero books.
-- `--sweep` replaces the CSV step entirely: it runs a live epubcheck sweep for candidate selection and reuses each result as that book's before-measurement, so no book is checked twice. bindery-cli launches a transparent, persistent Java daemon (`EpubcheckDaemon`) to evaluate candidates in the background, eliminating the JVM startup penalty. This reduces validation time from ~5 seconds per book down to ~0.05 seconds, allowing `--sweep` to scan a 5,000-book library in just 10 minutes. Combine with `--only fatals` for a self-contained, lightning-fast "find and fix the broken books" run.
+- `--sweep` replaces the CSV step entirely: it runs a live epubcheck sweep for candidate selection and reuses each result as that book's before-measurement, so no book is checked twice. bindery-cli first tries a persistent Java daemon (`EpubcheckDaemon`) to eliminate the per-book JVM startup; in practice the daemon cannot boot on most installs (its classpath carries only epubcheck's launcher jar, not the `lib/` dependencies epubcheck itself puts on the classpath), and the run silently falls back to the standard per-book epubcheck subprocess at the usual seconds per book. Budget accordingly. Fixing the classpath is a recorded decision (it would also change the counts the gate measures), not a shipped behavior. Combine with `--only fatals` for a self-contained "find and fix the broken books" run.
+- `--workers N` runs the sweep's candidate pass through N concurrent epubcheck workers (default 1: serial, unchanged). The subprocess releases the GIL, so threads parallelize the oracle honestly; books are checked in windows of N consumed in order, so the candidate set matches the serial sweep and `--limit` stays lazy within one window of overshoot. The repair phase stays serial: that is where the shared workdir and the atomic-replacement contract live.
 - `--json FILE` writes a machine-readable report of the whole run (per-book status, before/after counts, applied flag, summary totals). `--manual-list FILE` writes the paths of every book that was not auto-repaired, one per line, ready for manual follow-up.
 - `--apply` is required to write; the default is a dry run. `--backup DIR` mirrors originals before replacing; `--backup-inplace` writes `.epub.bak` beside each file.
 - `--install-to-calibre` resolves the Calibre book id from `metadata.db` via cquarry (one read-only path→id map per run), so a hand-renamed `Author/Title (id)/` directory can never send the repaired file to the wrong book. The directory-name regex is only a no-catalog fallback; with neither, the file is saved atomically in place.
@@ -176,6 +207,41 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - Exit codes: 0 for a clean sweep, 1 for a usage error, 2 when any book was rejected, unreadable, or failed epubcheck (for scripts and cron).
 - `repair` refuses to overwrite an existing output file unless `--force` is given.
 
+## Run slices
+
+`bindery run` wraps the acquisition pathway's EPUB steps as verbs. They add no
+repair classes of their own: they compose the shipped audit and library runners
+in the documented order, and both speak `--json` for a calling agent.
+
+**`run phase1 DIR`** is the pre-import vetting slice for a directory of loose
+files: the audit battery (corruption sweep, content battery, monolithic) in one
+decompression pass per book, then the gated repair sweep (epubcheck, watermark
+detection, repairability) over the same directory. The verb is read-only until
+`--apply-lossy` is passed, and that flag IS the recorded lossy-strip consent;
+`--backup DIR` mirrors originals first (keep backups outside the vetted
+directory). Consent questions never block the verb: a read-only run that finds
+repairable books records an `apply_lossy` entry in the JSON's
+`decisions_needed` instead of prompting, and `--non-interactive` declares that
+contract for callers. Exit codes per the `library` contract: 0 clean, 1 usage,
+2 when any book is flagged, rejected, unreadable, or failed epubcheck (a
+consent question alone is not trouble).
+
+```sh
+bindery run phase1 ~/Downloads --json phase1-report.json               # read-only
+bindery run phase1 ~/Downloads --apply-lossy --backup /tmp/phase1-backups
+```
+
+**`run phase3 --ids IDS`** (from the library directory) is the post-import
+scoped repair sweep: exactly `library --id IDS --sweep --only all --apply --all
+--install-to-calibre` plus a pre/post epubcheck summary. It mechanically
+refuses an unscoped library-wide sweep with exit 2 (a full-library sweep is a
+dedicated hours-long task, never a verb call), and books left partial or
+unreadable surface as `decisions_needed` in the JSON.
+
+```sh
+cd ~/docs/Calibre\ Library && bindery run phase3 --ids 5071,5072 --json phase3-report.json
+```
+
 ## Companion scripts
 
 `scripts/` holds standalone, read-only utilities that are useful for EPUB maintenance but fall outside bindery-cli's repair contract (fixing what they find would be a content change, which bindery-cli makes only via the opt-in `--strip-pagination`):

bindery_cli-0.28.0/PKG-INFO → bindery_cli-0.30.0/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.5
-Name: bindery-cli
-Version: 0.28.0
-Summary: High-speed EPUB repair surgeon with a persistent Java validation daemon, safe HTML unwrapping, and native Calibre integration.
-Author: vrnvctss
-License: MIT
-License-File: LICENSE
-Keywords: calibre,ebook,epub,epubcheck,html-repair,repair,watermarks
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Environment :: Console
-Classifier: Intended Audience :: End Users/Desktop
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Utilities
-Requires-Python: >=3.14
-Requires-Dist: cquarry>=1.9.0
-Requires-Dist: tqdm
-Requires-Dist: vir-tui>=2.2.0
-Provides-Extra: reserialize
-Requires-Dist: html5lib>=1.1; extra == 'reserialize'
-Description-Content-Type: text/markdown
-
 <div align="center">
   <img src="logo.svg" width="96" height="96" alt="bindery-cli logo"/>
   <h1>bindery-cli</h1>
@@ -95,9 +73,11 @@ uv tool install "bindery-cli[reserialize]"             # incl. --reserialize
 
 ## Usage
 
-Three verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
-reports content flaws without touching anything, and `bindery library` sweeps a Calibre
-library tree (dry run by default; `--apply` replaces accepted books atomically in place).
+Four verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
+reports content flaws without touching anything, `bindery library` sweeps a Calibre
+library tree (dry run by default; `--apply` replaces accepted books atomically in place),
+and `bindery run` composes the acquisition pathway's EPUB slices (phase-1 pre-import
+vetting, phase-3 scoped post-import repair) for a calling agent.
 The sections below take each in turn.
 
 ## Auditing
@@ -137,6 +117,12 @@ cd ~/docs/Calibre\ Library && bindery audit all --id 1234,1235
 ```
 `--id` composes with `--tag`: the book is tagged only if the audit flags it.
 
+**Machine-readable reports:** `--json FILE` writes the run's verdicts in the same shape `library --json` uses: one record per book with a `status` (`clean`/`problem`/`error`) and per-analyzer verdicts (`problem`, `status`, `details`), plus the always-on archive/spine verdicts (OK when they were silent). This is the contract downstream consumers of the pre-import vetting slice read.
+```sh
+bindery audit all ~/Downloads/epubs --json vetting-report.json
+```
+With `--id`, `--json` accepts exactly one book id (each single-book run writes the file wholesale).
+
 **Spine-integrity reporting:** Both `audit` and `library` reports now classify manifest/NCX references that point to absent files. A `convention` verdict means the ToC is bloated but the present documents form a consecutive chapter span (e.g., the Wandering Inn official-build pattern, safe). A `fragment` verdict means the span itself is broken.
 
 **Archive integrity:** every audit fully reads each archive entry (CRC + decompression), so a damaged download is reported CORRUPT — with the first broken entry named — instead of being mislabeled EMPTY by `emptytext`. `library --sweep` splits its `unreadable` bucket into `not_a_zip` / `truncated` / `encrypted` / `corrupt_entry`, so the right disease is visible without leaving the sweep.
@@ -187,7 +173,8 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--only {fatals,ncx,all}` restricts the candidate set. `ncx` targets NCX-001 mismatches (detected without epubcheck); `fatals` needs `--audit`.
 - `--id <ids>` limits the sweep to a comma-separated list of Calibre book IDs, skipping the full library walk.
 - `--audit CSV` (the `fatals,errors,warnings,path` format produced by an epubcheck sweep) skips clean books so a run is fast. Paths are resolved on both sides, and a CSV that matches nothing triggers a loud warning instead of silently selecting zero books.
-- `--sweep` replaces the CSV step entirely: it runs a live epubcheck sweep for candidate selection and reuses each result as that book's before-measurement, so no book is checked twice. bindery-cli launches a transparent, persistent Java daemon (`EpubcheckDaemon`) to evaluate candidates in the background, eliminating the JVM startup penalty. This reduces validation time from ~5 seconds per book down to ~0.05 seconds, allowing `--sweep` to scan a 5,000-book library in just 10 minutes. Combine with `--only fatals` for a self-contained, lightning-fast "find and fix the broken books" run.
+- `--sweep` replaces the CSV step entirely: it runs a live epubcheck sweep for candidate selection and reuses each result as that book's before-measurement, so no book is checked twice. bindery-cli first tries a persistent Java daemon (`EpubcheckDaemon`) to eliminate the per-book JVM startup; in practice the daemon cannot boot on most installs (its classpath carries only epubcheck's launcher jar, not the `lib/` dependencies epubcheck itself puts on the classpath), and the run silently falls back to the standard per-book epubcheck subprocess at the usual seconds per book. Budget accordingly. Fixing the classpath is a recorded decision (it would also change the counts the gate measures), not a shipped behavior. Combine with `--only fatals` for a self-contained "find and fix the broken books" run.
+- `--workers N` runs the sweep's candidate pass through N concurrent epubcheck workers (default 1: serial, unchanged). The subprocess releases the GIL, so threads parallelize the oracle honestly; books are checked in windows of N consumed in order, so the candidate set matches the serial sweep and `--limit` stays lazy within one window of overshoot. The repair phase stays serial: that is where the shared workdir and the atomic-replacement contract live.
 - `--json FILE` writes a machine-readable report of the whole run (per-book status, before/after counts, applied flag, summary totals). `--manual-list FILE` writes the paths of every book that was not auto-repaired, one per line, ready for manual follow-up.
 - `--apply` is required to write; the default is a dry run. `--backup DIR` mirrors originals before replacing; `--backup-inplace` writes `.epub.bak` beside each file.
 - `--install-to-calibre` resolves the Calibre book id from `metadata.db` via cquarry (one read-only path→id map per run), so a hand-renamed `Author/Title (id)/` directory can never send the repaired file to the wrong book. The directory-name regex is only a no-catalog fallback; with neither, the file is saved atomically in place.
@@ -198,6 +185,41 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - Exit codes: 0 for a clean sweep, 1 for a usage error, 2 when any book was rejected, unreadable, or failed epubcheck (for scripts and cron).
 - `repair` refuses to overwrite an existing output file unless `--force` is given.
 
+## Run slices
+
+`bindery run` wraps the acquisition pathway's EPUB steps as verbs. They add no
+repair classes of their own: they compose the shipped audit and library runners
+in the documented order, and both speak `--json` for a calling agent.
+
+**`run phase1 DIR`** is the pre-import vetting slice for a directory of loose
+files: the audit battery (corruption sweep, content battery, monolithic) in one
+decompression pass per book, then the gated repair sweep (epubcheck, watermark
+detection, repairability) over the same directory. The verb is read-only until
+`--apply-lossy` is passed, and that flag IS the recorded lossy-strip consent;
+`--backup DIR` mirrors originals first (keep backups outside the vetted
+directory). Consent questions never block the verb: a read-only run that finds
+repairable books records an `apply_lossy` entry in the JSON's
+`decisions_needed` instead of prompting, and `--non-interactive` declares that
+contract for callers. Exit codes per the `library` contract: 0 clean, 1 usage,
+2 when any book is flagged, rejected, unreadable, or failed epubcheck (a
+consent question alone is not trouble).
+
+```sh
+bindery run phase1 ~/Downloads --json phase1-report.json               # read-only
+bindery run phase1 ~/Downloads --apply-lossy --backup /tmp/phase1-backups
+```
+
+**`run phase3 --ids IDS`** (from the library directory) is the post-import
+scoped repair sweep: exactly `library --id IDS --sweep --only all --apply --all
+--install-to-calibre` plus a pre/post epubcheck summary. It mechanically
+refuses an unscoped library-wide sweep with exit 2 (a full-library sweep is a
+dedicated hours-long task, never a verb call), and books left partial or
+unreadable surface as `decisions_needed` in the JSON.
+
+```sh
+cd ~/docs/Calibre\ Library && bindery run phase3 --ids 5071,5072 --json phase3-report.json
+```
+
 ## Companion scripts
 
 `scripts/` holds standalone, read-only utilities that are useful for EPUB maintenance but fall outside bindery-cli's repair contract (fixing what they find would be a content change, which bindery-cli makes only via the opt-in `--strip-pagination`):

{bindery_cli-0.28.0 → bindery_cli-0.30.0}/patchnotes.md

@@ -1,4 +1,73 @@
 # bindery-cli Patch Notes
+## v0.30.0 (2026-09-06)
+
+### Phase 8 stretch: concurrent sweep workers
+
+- **`library --workers N`**: the `--sweep` candidate pass runs through N
+  concurrent epubcheck workers (default 1: serial, byte-for-byte unchanged).
+  epubcheck runs in a subprocess that releases the GIL, so threads parallelize
+  the oracle honestly; this is the pass that measured ~4.4 s/book on the
+  2026-08-27 full-library walk (5,070 EPUBs ≈ 6 hours serial). Books are
+  checked in windows of N consumed in input order, so the candidate set, the
+  before-measurements, and every emitted line match the serial sweep, and
+  `--limit` stays lazy within one window of overshoot. The repair phase stays
+  serial on purpose: that is where the shared workdir and the
+  atomic-replacement contract live. Without `--sweep`, `--workers` is a
+  no-op (with a note); counts below 1 are a usage error.
+
+## v0.29.0 (2026-09-06)
+
+### Phase 13: machine-readable audit and the acquisition run slices
+
+The acquisition pathway's EPUB steps are now first-class CLI surface. Nothing
+here adds a repair class or changes an existing mode; the new verbs compose
+what already ships, in the phase-1 and phase-3 skills' documented order.
+
+- **`audit --json FILE`**: the audit subcommand writes machine-readable
+  per-file verdicts in the `library --json` shape (mode/root/summary plus one
+  record per book), from all three modes: directory, library, and single-book.
+  Records carry a status (clean/problem/error) and per-analyzer verdicts
+  (problem/status/details); the always-on archive/spine verdicts appear OK
+  when they were silent, emptytext is omitted from a record when the archive
+  verdict owns the body-text story, and a scan error becomes its own record
+  shape. `--json` with `--id` accepts exactly one book id, because each
+  single-book run writes the file wholesale. This is the contract downstream
+  consumers of the phase-1 EPUB slice read.
+- **`run phase1 DIR [--json OUT] [--apply-lossy] [--backup DIR]`**: the
+  pre-import vetting slice over a directory of loose files, in the phase-1
+  skill's documented order: the audit battery (corruption sweep, content
+  battery, monolithic), then one fused repair sweep (epubcheck, watermark
+  detection, repairability; the skill's two sweeps collapse into one
+  epubcheck pass, with watermark hits read out of the per-book fix summary).
+  Read-only until `--apply-lossy`, which IS the recorded lossy-strip consent;
+  `--backup DIR` passes through (keep backups outside the vetted directory).
+  Exit codes 0/1/2 per the library contract; a consent question alone is not
+  trouble.
+- **`run phase3 --ids CSV [--json OUT]`**: the post-import scoped repair step,
+  run from the library directory: exactly `library --id --sweep --only all
+  --apply --all --install-to-calibre` plus a pre/post epubcheck summary over
+  the swept books. The phase-3 skill's step-10 scope warning is mechanized: an
+  unscoped library-wide call is refused with exit 2, never run by accident.
+  The verb drives the shipped library runner through the real parser, so its
+  flags cannot drift from the subcommand it wraps.
+- **Non-interactive contract**: both run verbs take `--non-interactive` and
+  never prompt (nothing in bindery prompts); open questions surface in the
+  JSON as `decisions_needed` entries: the `apply_lossy` consent question in a
+  read-only phase1, `manual_repair`/`investigate` for books left partial or
+  unreadable in phase3.
+- **Skill sync**: the phase-1 and phase-3 skills name the run verbs and the
+  machine-readable contracts (the skill files live in the library directory,
+  outside this repo).
+- **Dependencies**: vir-tui 2.3.0 folded into the lock; the pyproject floor
+  stays `vir-tui>=2.2.0` (additive bump at this release).
+- **Docs and hygiene**: CLAUDE.md's last surviving `calibredb add_format`
+  line retired (it contradicted the v0.24.0 subprocess removal and carried a
+  `-apply` typo); README's `--sweep` bullet and the pyproject description no
+  longer advertise the validation daemon's speedup, which never engages
+  because the daemon's classpath omits epubcheck's `lib/` dependencies (the
+  fix is a recorded gate-behavior decision, not a drive-by); `venv/` and
+  `.venv_ci/` are gitignored. Test count: 277 → 294.
+
 ## v0.28.0 (2026-09-05)
 
 ### Phase 12: repairs for the top epubcheck error codes

{bindery_cli-0.28.0 → bindery_cli-0.30.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.28.0"
-description = "High-speed EPUB repair surgeon with a persistent Java validation daemon, safe HTML unwrapping, and native Calibre integration."
+version = "0.30.0"
+description = "Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library."
 readme = "README.md"
 classifiers = [
     "Development Status :: 5 - Production/Stable",
@@ -23,9 +23,7 @@ authors = [
 ]
 # Core dependencies are minimal. html5lib is needed only for the opt-in --reserialize structural
 # repair; it is imported lazily, so every other mode works without it installed.
-# vir-tui is PINNED to an exact commit so builds are reproducible; bump deliberately.
-# cquarry deliberately tracks @main (since v0.19.0): CI exercises current cquarry on
-# every run instead of a stale snapshot, matching CalibreQuarry's dependency policy.
+# vir-tui and cquarry are pinned as PyPI ranges; uv.lock records the resolved versions.
 dependencies = [
   "tqdm",
   "vir-tui>=2.2.0",

{bindery_cli-0.28.0 → bindery_cli-0.30.0}/roadmap.md

@@ -321,6 +321,55 @@ Three consequences worth stating, because they change existing plans:
 This is one plugin *shape* serving both tools, not one shared plugin: they are
 separate repos with separate licences and no dependency between them.
 
+**RESEARCH 2026-09-05 (against the calibre 9.14 reference clone, which matches the
+installed Calibre). The decision holds. Three corrections and a scoped spec; the
+plugin is approved to build (Brandon, 2026-09-05).**
+
+- The `on_import` contract is exactly as decided: `run(path)` returns a
+  replacement built with `temporary_file()`, Calibre swaps which path flows
+  downstream, and the original on disk is never touched. A raising plugin cannot
+  abort an import and cannot lose the file (Calibre falls back to the original),
+  but the failure is silent: tracebacks land only in Calibre's debug log. The
+  plugin therefore never raises and keeps its own log under
+  `calibre.constants.config_dir`.
+- Loader trap the decision missed: `supported_platforms` defaults to empty and
+  the loader rejects any plugin that declares no platforms. The plugin must set
+  `supported_platforms = ['linux']`, which also makes other OSes a
+  loader-enforced non-goal.
+- The hook also fires when a format is added to an existing book
+  (`db.add_format(..., run_hooks=True)`), so the plugin must be byte-idempotent.
+  The core pass already is (deterministic since v0.10.2).
+- The "both tools" wording is vacuous today: oceanstrip was absorbed at v0.12.0
+  and the standalone repo is gone. One plugin, in this repo, honoring the shape
+  claim retroactively.
+
+Scoped spec:
+
+- **Vendor slice**, generated at release from the tagged tree with a
+  byte-equality drift test: `transforms.py`, `epub.py`, `pagination.py`,
+  `watermark.py`, `reserialize.py` (~2,300 lines) plus a new plugin
+  `__init__.py`. `cli.py`/`library.py`/`audit.py`/`validate.py` stay out: they
+  carry tqdm, cquarry, vir-tui, and the epubcheck/JDK machinery, none of which
+  a plugin zip can carry (plugins cannot pip-install).
+- **Active fix set = the gate-safe default pass only**: the five well-formedness
+  transforms plus the NCX pipeline. All twelve structural repairs and the three
+  lossy strips stay CLI-only: their acceptance IS the epubcheck gate, which
+  cannot run inside Calibre (no jar, no JVM, and seconds-per-book latency).
+  Opt-in flags are never enabled by the plugin; nothing runs ungated.
+- **Behavior**: core pass on `*.epub` imports; zero fixes or any exception
+  returns the original path unchanged; the rewritten archive is re-opened and
+  `testzip()`-verified before it is handed back; one log line per book (fixed /
+  no fixes / refused / errored). Config via `site_customization` JSON
+  (`log`, `log_path`, `max_size_mb` refusal cap). No Qt config widget, no
+  `postimport` hook (that would write `metadata.db`, breaking the decision).
+- **Release**: `publish.yml` gains a job that regenerates the vendor slice from
+  the tag, runs the tests against it, zips it, and attaches
+  `BinderyRepair-v<VERSION>.zip` to the GitHub release beside the PyPI artifact.
+
+Open questions (Brandon): epubcheck-on-PATH experimental mode (default no, the
+latency ruling stands); plugin identity `Bindery Repair` / `bindery_repair`;
+size-cap default.
+
 
 ## Supplementary Phase (Based on Library Audit)
 Following a comprehensive epubcheck sweep of a 5,043-book Calibre library on 2026-08-22 (~3,228 candidates for repair), several recurring error schemas were identified; all have since shipped. (This section absorbs the one-off `BINDERY_REPORT.md`, retired in v0.17.0 — its performance notes live in the v0.13.0 patchnotes, and its findings are the checked items below.)
@@ -461,12 +510,19 @@ by hand.*
   release.
 - [x] **`audit --id` comma lists**: v0.19.0 took a single book id; support the
   same comma-separated form as the new `library --id` so the two modes match.
-- [ ] **Concurrent validation workers (stretch; not shipped)**: the 2026-08-27 full-library
+- [x] **Concurrent validation workers (stretch; not shipped)**: the 2026-08-27 full-library
   walk measured ~4.4 s/book on a single daemon (5,070 EPUBs ≈ 6 h). Gate k
   validation workers behind `--workers N`, default 1 (behavior unchanged).
   *(Un-ticked in the 2026-09-02 docs re-read (NEW-AUDIT.md Stage 0): the box was
   ticked at the v0.23.0 ship, but no `--workers` code, test, or doc line ever
-  landed. Still open as a stretch goal.)*
+  landed.)*
+  *(Shipped for real in v0.30.0: `library --workers N` runs the --sweep
+  candidate pass through N concurrent epubcheck workers, default 1 (serial,
+  unchanged). Threads parallelize the oracle honestly (the subprocess releases
+  the GIL); books are checked in windows of N consumed in input order, so the
+  candidate set matches the serial sweep and `--limit` stays lazy within one
+  window of overshoot. The repair phase stays serial, where the shared workdir
+  and the atomic-replacement contract live.)*
 
 Non-goals: no auto-trim of bloated ToCs (semantics-preserving charter); no
 content-doc synthesis; no PDF equivalent.
@@ -629,3 +685,75 @@ the underlying conditions are what the repairs target:
   gate that deserves its own decision, not a drive-by edit.
 
 Non-goals: No bulk repair of RSC-005 schema/content-model violations. With 164,302 instances, arbitrary schema repair violates the explicit non-goal in spec.md ("Fixing RSC-005 schema/content-model violations in bulk"). Restructuring arbitrary markup requires semantic human judgment; attempting to automate it risks silent content corruption, tag swallowing, or destroying valid styling. Specific, narrowly bounded RSC-005 sub-cases remain opt-in under their own flags (`--strip-epub3-attrs`, `--downgrade-epub3-tags`, `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`, `--add-img-alt`, `--fix-id-colons`); arbitrary bulk repair is rejected. No spine-item manifest pruning (missing spine documents indicate corrupt archives or broken fragments, not safe pruning candidates). No text deletion in anchor unwrapping (character conservation is absolute).
+
+## Phase 13: machine-readable audit + the acquisition run slices (proposed 2026-09-05)
+
+*Context: the acquisition pathway (`~/docs/Calibre Library/.claude/skills/`) is
+being promoted from agent-prose into first-class CLI subcommands across the lane.
+Brandon's design: `bindery run phase1` for the EPUB slice of pre-import vetting,
+`bindery run phase3` for the scoped post-import repair pass, with CalibreQuarry
+owning the orchestration (`cquarry run phase1/2/3`, its roadmap Phase 17) and the
+manifest that hands state between phases. The prerequisite on this side is a
+machine-readable audit; the run verbs wrap what already ships. No new repair
+classes, no behavior change to existing modes.*
+
+- [x] **`audit --json FILE`**: per-file analyzer verdicts in the same shape
+      `library --json` already emits (audit is console-only today; the
+      subparser has no JSON flag). This is the contract every downstream
+      consumer of the phase-1 EPUB slice reads.
+      *(Shipped in v0.29.0. All three modes write it: directory, library,
+      and single-book. The always-on archive/spine verdicts appear OK when
+      they were silent; emptytext is omitted from a record when the archive
+      verdict owns the body-text story; a scan error becomes its own record
+      shape (`status: "error"`). `--json` with `--id` accepts exactly one id,
+      because each single-book run writes the file wholesale.)*
+- [x] **`run phase1 DIR [--json OUT] [--apply-lossy] [--backup DIR]`**: the
+      EPUB slice in the phase-1 skill's documented order (corruption sweep,
+      epubcheck, content battery, monolithic, watermark dry-run,
+      repairability). Gated repair applies only under `--apply-lossy`, which is
+      the recorded lossy-strip consent; without it the verb is read-only.
+      Exit codes 0/1/2 per the `library` contract. No DRM scan, no duplicate
+      screen, no manifest assembly (CalibreQuarry's by the frontend split).
+      *(Shipped in v0.29.0. Two composed stages: the audit battery through its
+      own --json payload, then ONE fused repair sweep with the --all set — the
+      skill ran watermark detection and repairability as two sweeps, the verb
+      pays epubcheck once and reads watermark hits out of the per-book fix
+      summary. Read-only until --apply-lossy; --backup passes through (keep
+      backups outside the vetted directory). A consent question is not an
+      error: it lands in decisions_needed and the exit code stays on the
+      library contract.)*
+- [x] **`run phase3 --ids CSV [--json OUT]`**: wraps
+      `library --id ... --sweep --only all --apply --all --install-to-calibre`
+      with a pre/post summary and mechanically refuses unscoped library-wide
+      sweeps (encodes the phase-3 skill's step-10 scope warning as an exit 2
+      instead of a prose warning).
+      *(Shipped in v0.29.0. Run from the library directory (cwd-resolved like
+      audit library mode). The verb drives the shipped library runner through
+      the real parser, so its flags cannot drift from the subcommand it wraps.
+      The pre/post summary sums before/after epubcheck counts over the swept
+      books; books left partial or unreadable surface as decisions_needed.
+      The verb is the apply step by design — the batch was vetted in phase 1,
+      and the gate plus the atomic-replacement contract still govern every
+      write.)*
+- [x] **Non-interactive contract**: every `run` verb takes
+      `--non-interactive`; prompts never fire off a TTY, and open questions
+      surface in the JSON as `decisions_needed` for the calling agent or user.
+      *(Shipped in v0.29.0 with the verbs themselves. Nothing in a run verb
+      prompts (none ever did; the flag makes the orchestrator contract
+      explicit and is recorded in the payload). decisions_needed entries: the
+      apply_lossy consent question in a read-only phase1, manual_repair and
+      investigate for partial/unreadable books in phase3.)*
+- [x] **Skill sync**: the phase-1 and phase-3 skills name the run verbs once
+      shipped. Floor, not ceiling, per the standing rule.
+      *(Done for v0.29.0, 2026-09-06: the phase-1 skill's EPUB section names
+      `run phase1` as the one-verb wrapper (the fused sweep pays epubcheck
+      once; the JSON contract and `--apply-lossy` consent named) and the
+      phase-3 skill's step 10 names `run phase3` with the mechanized scope
+      refusal. The skill files live in the library directory, outside this
+      repo; per the floor rule their per-check commands still stand on their
+      own.)*
+
+Non-goals: no manifest format ownership (CalibreQuarry owns the
+`acquisition-manifest` schema and the orchestration; this repo emits reports
+and consumes id lists); no TUI beyond the existing audit rendering; no PDF/DJVU
+work (never this repo's charter).

{bindery_cli-0.28.0 → bindery_cli-0.30.0}/scripts/fast_sweep.py

@@ -47,7 +47,9 @@ def find_jar(explicit: str | None) -> Path:
     elif launcher := shutil.which("epubcheck"):
         m = _JAR_RE.search(Path(launcher).read_text())
         if not m:
-            sys.exit(f"error: cannot find a jar path in the epubcheck launcher {launcher}")
+            sys.exit(
+                f"error: cannot find a jar path in the epubcheck launcher {launcher}"
+            )
         jar = Path(os.path.expandvars(m.group(1))).expanduser()
     else:
         sys.exit("error: epubcheck not found; install it or pass --jar / EPUBCHECK_JAR")
@@ -80,9 +82,7 @@ def collect_paths(args: argparse.Namespace) -> list[str]:
         return [p.strip() for p in text.splitlines() if p.strip()]
     if not args.root.is_dir():
         sys.exit(f"error: not a directory: {args.root}")
-    return sorted(
-        str(p) for p in args.root.rglob("*") if p.suffix.lower() == ".epub"
-    )
+    return sorted(str(p) for p in args.root.rglob("*") if p.suffix.lower() == ".epub")
 
 
 def run(jar: Path, paths: list[str], mode: str) -> list[str]:
@@ -129,12 +129,21 @@ def summarize(lines: list[str]) -> None:
 
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
-    ap.add_argument("root", nargs="?", type=Path, help="directory to scan for .epub files")
+    ap.add_argument(
+        "root", nargs="?", type=Path, help="directory to scan for .epub files"
+    )
     ap.add_argument("--mode", choices=("audit", "extract"), default="audit")
     ap.add_argument("--from-file", help="read EPUB paths from this file ('-' = stdin)")
-    ap.add_argument("--jar", help="epubcheck.jar path (default: EPUBCHECK_JAR or the epubcheck launcher)")
+    ap.add_argument(
+        "--jar",
+        help="epubcheck.jar path (default: EPUBCHECK_JAR or the epubcheck launcher)",
+    )
     ap.add_argument("--out", type=Path, help="also write the raw output to this file")
-    ap.add_argument("--summary", action="store_true", help="aggregate extract-mode output into a per-code report")
+    ap.add_argument(
+        "--summary",
+        action="store_true",
+        help="aggregate extract-mode output into a per-code report",
+    )
     args = ap.parse_args()
     if not args.from_file and args.root is None:
         ap.error("a directory or --from-file is required")

{bindery_cli-0.28.0 → bindery_cli-0.30.0}/spec.md

@@ -267,6 +267,11 @@ For a Calibre library (`Author/Title (id)/Title - Author.epub`):
   reported and counted as `unreadable`; it never aborts the rest of the sweep.
 - The `library` exit code is 0 for a clean sweep, 1 for a usage error, and 2 when any
   book was rejected, unreadable, or failed epubcheck, so scripts can detect trouble.
+- With `--sweep`, `--workers N` runs the candidate-selection epubcheck pass through N
+  concurrent workers (default 1: serial, unchanged). Books are checked in windows of N
+  consumed in input order, so the candidate set and the before-measurements are identical
+  to the serial sweep; the repair phase is never parallel (the shared workdir and the
+  atomic-replacement contract live there).
 
 ### Native format installation (`--install-to-calibre`)
 Optionally, bindery-cli installs the repaired EPUB as the book's format through cquarry's write module (`WritableCalibreDB`): the file is placed atomically — an in-place replace over the catalogued file when one exists (same path, same `data.name`), or a fresh placement under the repaired file's stem otherwise — and the `data` row follows in one `batch()` transaction (`remove_format` + `add_format`, since `add_format` refuses duplicates), keeping the size truthful and queuing the book in `metadata_dirtied` so Calibre regenerates its sidecar .opf. The external `calibredb` CLI is no longer used (the v0.23.1 `--replace` crash class is gone with it). It automatically falls back to atomic filesystem replacement if a valid Calibre ID cannot be extracted, and a database failure degrades to the in-place save with a warning rather than losing the repair.
@@ -291,6 +296,38 @@ bumps `books.last_modified`, and cleans link tables before tag deletion). THIN e
 advisories stay untagged; already-tagged books are skipped; a missing file is a scan error, not a
 silent skip.
 
+`--json FILE` (v0.29.0) writes the same verdicts machine-readably, in the `library --json`
+shape: one record per file with a `status` (`clean`, `problem`, or `error`) and per-analyzer
+verdicts (`problem`, `status`, `details`); the always-on archive/spine verdicts appear OK when
+they were silent, emptytext is omitted when the archive verdict owns the book's body-text story,
+and a scan error becomes its own record (`status: "error"`, an `error` message, no verdicts).
+All three modes write it (directory, library, and single-book); `--json` with `--id` accepts
+exactly one book id, since each single-book run writes the file wholesale.
+
+## Run verbs (acquisition slices)
+
+`bindery run phase1 DIR [--json FILE] [--apply-lossy] [--backup DIR] [--non-interactive]`
+composes the shipped read-only audit battery (corruption sweep, content battery,
+monolithic) with the gated repair sweep (epubcheck, watermark detection,
+repairability) over one directory of loose files, in the phase-1 skill's
+documented order. It introduces no new repair classes: every fix, gate, and
+safety net is the shipped one. The verb is read-only until `--apply-lossy` is
+passed, and that flag is the recorded lossy-strip consent; `--backup DIR`
+mirrors originals before any replacement. Consent questions never block the
+verb: they surface as `decisions_needed` entries in the JSON (never prompts),
+and `--non-interactive` declares that contract for callers. Exit codes per the
+library contract: 0 clean, 1 usage, 2 when any book is flagged, rejected,
+unreadable, or failed epubcheck; a consent question alone is not trouble.
+
+`bindery run phase3 --ids IDS [--json FILE] [--non-interactive]` (run from the
+library directory) is exactly `library --id IDS --sweep --only all --apply
+--all --install-to-calibre` plus a pre/post epubcheck summary over the swept
+books. It is the post-import apply step by design: the batch was vetted in
+phase 1, the epubcheck gate still governs every replacement, and the atomic
+replacement contract is untouched. The scope refusal is mechanical: no `--ids`,
+no sweep, exit 2 (a library-wide sweep is a dedicated hours-long task, never a
+verb call). Books left partial or unreadable surface as `decisions_needed`.
+
 ## Out of scope (non-goals)
 
 - Fixing RSC-005 schema/content-model violations in bulk.