bindery-cli 0.37.0__tar.gz → 0.39.0__tar.gz

{bindery_cli-0.37.0 → bindery_cli-0.39.0}/.github/workflows/publish.yml

@@ -48,6 +48,8 @@ jobs:
     name: Build the Bindery Repair Calibre plugin zip
     needs: test
     runs-on: ubuntu-latest
+    permissions:
+      contents: write # create the release and attach the plugin zip
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5

{bindery_cli-0.37.0 → bindery_cli-0.39.0}/CLAUDE.md

@@ -29,9 +29,10 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
   * **Structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
     `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
     `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
-    `--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`;
-    transforms.py, threaded through epub.py): they alter markup structure or fabricate
-    minimal content. v0.14–v0.16 ran these unconditionally, which broke this rule;
+    `--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`,
+    `--fix-container`, `--fix-media-types`, `--fix-cover`; transforms.py, threaded
+    through epub.py):
+    they alter markup structure or fabricate minimal content. v0.14–v0.16 ran these unconditionally, which broke this rule;
     v0.17.0 restored it. `--unwrap-illegal-tags` additionally protects any illegal-tag
     name that an EPUB stylesheet styles as an element selector (`css_protected_tags`,
     book-wide, inline `<style>` blocks included). The two EPUB2-targeted fixes
@@ -56,7 +57,9 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
   the safe opt-ins (`--fix-ids`, `--add-img-alt`, `--strip-bad-attrs`,
   `--escape-unknown-entities`) plus `--encode-url-spaces`, which repair without
   altering visible markup; the "twelve structural repairs and three lossy strips"
-  phrasing elsewhere in these docs was never the complete inventory.
+  phrasing elsewhere in these docs was never the complete inventory, and the
+  Phase 16 package repairs (`--fix-container`, `--fix-media-types`, `--fix-cover`)
+  took the structural count to fifteen (v0.38.0 + v0.39.0).
 - **The gate is the safety contract.** Never apply a repair epubcheck has not accepted.
   Respect the two-mode logic in `validate.gate` (fatal-fixing tolerates error unmasking;
   error-cleanup does not). The lossy strips (`--strip-pagination`, `--strip-broken-tags`,
@@ -77,8 +80,8 @@ 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`, `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.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.
-- `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/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.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).
+- `src/bindery/epub.py`: archive rewrite, NCX uid sync, RepairReport, mismatch detection, and the opt-in structural-repair plumbing (including the CSS precondition scan). Since v0.38.0/v0.39.0 (Phase 16): `generate_container` + the `--fix-container` gateway (insert after mimetype when missing, replace in-loop when stale; constant-epoch timestamp keeps bytes deterministic), `prune_dangling_edges` (prune_missing_manifest_items returns the pruned ids and the edges that pointed at them — spine@toc, media-overlay, fallback, EPUB2 cover meta — are rewritten so pruning cannot manufacture the regression the gate rejects), and `fix_manifest_media_types` (extension map + magic-byte confirmation via a `peek` callable over the open source zip; jpg/png/gif only), and `fix_cover_meta` (the ruling's deterministic half: dangling EPUB2 cover meta re-pointed from the guide's cover reference when exactly one manifest item carries that file, removed otherwise; accepted under no_worse like the lossy strips because cover wiring is invisible to epubcheck).
 - `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars.
 - `src/bindery/library.py`: Calibre walk, atomic replace, backups, and native format installation. Since v0.19.0 `CalibreIdResolver` resolves the book id from `metadata.db` through cquarry (one lazy path→id map per run; since v0.20.0 the map comes from `CalibreDB.format_path_index()`, re-normalized with `resolve().lower()` for the resolver's symlinked-directory and case-insensitive matching); the `(id)` directory-name regex is only the no-catalog fallback. Since v0.24.0 `install_format()` places the repaired file atomically and updates the `data` row through `cquarry.write.WritableCalibreDB` (since v0.31.0 via `set_format`, cquarry 1.17's sanctioned remove+add in one transaction); the external `calibredb` CLI is gone. Since v0.32.0 a guessed id drives a row update only when metadata.db corroborates it (`_verify_guess`: books row exists, file in the book's own directory, catalogued `data.name` when a row exists); anything else saves in place and leaves the catalog untouched — never reintroduce directory-name guessing as the primary source: renamed/mismatched directories would replace the wrong book.
 - `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).

{bindery_cli-0.37.0 → bindery_cli-0.39.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.37.0
+Version: 0.39.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
@@ -60,9 +60,12 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--strip-epub3-attrs`**: scrubs the EPUB3-only attributes epubcheck rejects on an EPUB2 package: `page-progression-direction`, `epub:type`, `aria-label` (a fixed, documented set; rendering is unchanged, and lookalikes like `type` or the wider aria family survive). The edit is anchored to real start tags, so prose that merely mentions `epub:type="chapter"` is preserved.
 - **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents (`figure`/`section` to `div`, `figcaption` to `p`), keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed. Both EPUB2-targeted fixes are gated on the package version declared in the OPF: on an EPUB 3 book they do nothing, because their target defects only exist below EPUB 3.
 - **`--unwrap-illegal-tags`**: strips completely invalid or deprecated HTML tags that break EPUB3 validation (`<st>`, `<sentence>`, `<o>`, `<w>`, `<pagebreak>`) while retaining their inner text. Any of those names styled as an *element selector* by an EPUB stylesheet (`.css` entries and inline `<style>` blocks alike; class/id selectors like `.st`/`#w` don't count) is protected for the whole book, guaranteeing format preservation.
-- **`--prune-missing-resources`**: removes references to files the archive does not contain (RSC-007/PKG-010): dead `<link>` elements, anchors' `href` to absent files (anchor text preserved), absent `<img>` sources (replaced by their alt text when they carry one), and orphaned non-spine OPF manifest items. Spine documents are never pruned: a missing spine document is reported as a damaged fragment, not silently dropped.
+- **`--prune-missing-resources`**: removes references to files the archive does not contain (RSC-007/PKG-010): dead `<link>` elements, anchors' `href` to absent files (anchor text preserved), absent `<img>` sources (replaced by their alt text when they carry one), and orphaned non-spine OPF manifest items (with every package edge that pointed at them rewritten: `spine@toc`, `item@media-overlay`, `item@fallback`, and the EPUB2 cover meta). Spine documents are never pruned: a missing spine document is reported as a damaged fragment, not silently dropped.
 - **`--strip-broken-anchors`**: strips href attributes that cannot resolve, keeping the anchor text byte-for-byte: a `#fragment` the target document does not define (RSC-020/RSC-012; NCX navTargets fall back to the document target, so chapter navigation survives) and unresolvable URI schemes (`kindle:`, `file:`).
 - **`--encode-url-spaces`**: percent-encodes raw spaces in `src`/`href` attribute values across the package (OPF manifest, NCX, content documents). A URL with a literal space is not a valid URL (RSC-020) and unresolvable on strict readers; the encoded form denotes the same file.
+- **`--fix-container`**: generates `META-INF/container.xml` at the located OPF when the container is missing or names a file the archive does not contain. This is the gateway defect: epubcheck stays fatal while the OPF is unfindable, so no repair can be gate-accepted on such a book until the container exists.
+- **`--fix-media-types`**: normalizes wrong manifest media-type declarations (OPF-029, e.g. a jpg stamped `image/png` by an aggregator). Attribute-only and quote-preserving; it fires only when the file's magic bytes confirm the extension, so an honestly-declared misnamed file is never made worse.
+- **`--fix-cover`**: repairs dangling EPUB2 cover wiring. A `<meta name="cover">` whose content names no manifest item is re-pointed when the OPF guide's own cover reference names an existing item, and removed when nothing identifies it; EPUB3 `properties="cover-image"` is deliberately audit-only (guessing which image is the cover is not deterministic). Cover wiring is invisible to epubcheck, so cover-only repairs are accepted under the same no-worse bar the lossy strips use.
 
 
 Three opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:

{bindery_cli-0.37.0 → bindery_cli-0.39.0}/README.md

@@ -38,9 +38,12 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--strip-epub3-attrs`**: scrubs the EPUB3-only attributes epubcheck rejects on an EPUB2 package: `page-progression-direction`, `epub:type`, `aria-label` (a fixed, documented set; rendering is unchanged, and lookalikes like `type` or the wider aria family survive). The edit is anchored to real start tags, so prose that merely mentions `epub:type="chapter"` is preserved.
 - **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents (`figure`/`section` to `div`, `figcaption` to `p`), keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed. Both EPUB2-targeted fixes are gated on the package version declared in the OPF: on an EPUB 3 book they do nothing, because their target defects only exist below EPUB 3.
 - **`--unwrap-illegal-tags`**: strips completely invalid or deprecated HTML tags that break EPUB3 validation (`<st>`, `<sentence>`, `<o>`, `<w>`, `<pagebreak>`) while retaining their inner text. Any of those names styled as an *element selector* by an EPUB stylesheet (`.css` entries and inline `<style>` blocks alike; class/id selectors like `.st`/`#w` don't count) is protected for the whole book, guaranteeing format preservation.
-- **`--prune-missing-resources`**: removes references to files the archive does not contain (RSC-007/PKG-010): dead `<link>` elements, anchors' `href` to absent files (anchor text preserved), absent `<img>` sources (replaced by their alt text when they carry one), and orphaned non-spine OPF manifest items. Spine documents are never pruned: a missing spine document is reported as a damaged fragment, not silently dropped.
+- **`--prune-missing-resources`**: removes references to files the archive does not contain (RSC-007/PKG-010): dead `<link>` elements, anchors' `href` to absent files (anchor text preserved), absent `<img>` sources (replaced by their alt text when they carry one), and orphaned non-spine OPF manifest items (with every package edge that pointed at them rewritten: `spine@toc`, `item@media-overlay`, `item@fallback`, and the EPUB2 cover meta). Spine documents are never pruned: a missing spine document is reported as a damaged fragment, not silently dropped.
 - **`--strip-broken-anchors`**: strips href attributes that cannot resolve, keeping the anchor text byte-for-byte: a `#fragment` the target document does not define (RSC-020/RSC-012; NCX navTargets fall back to the document target, so chapter navigation survives) and unresolvable URI schemes (`kindle:`, `file:`).
 - **`--encode-url-spaces`**: percent-encodes raw spaces in `src`/`href` attribute values across the package (OPF manifest, NCX, content documents). A URL with a literal space is not a valid URL (RSC-020) and unresolvable on strict readers; the encoded form denotes the same file.
+- **`--fix-container`**: generates `META-INF/container.xml` at the located OPF when the container is missing or names a file the archive does not contain. This is the gateway defect: epubcheck stays fatal while the OPF is unfindable, so no repair can be gate-accepted on such a book until the container exists.
+- **`--fix-media-types`**: normalizes wrong manifest media-type declarations (OPF-029, e.g. a jpg stamped `image/png` by an aggregator). Attribute-only and quote-preserving; it fires only when the file's magic bytes confirm the extension, so an honestly-declared misnamed file is never made worse.
+- **`--fix-cover`**: repairs dangling EPUB2 cover wiring. A `<meta name="cover">` whose content names no manifest item is re-pointed when the OPF guide's own cover reference names an existing item, and removed when nothing identifies it; EPUB3 `properties="cover-image"` is deliberately audit-only (guessing which image is the cover is not deterministic). Cover wiring is invisible to epubcheck, so cover-only repairs are accepted under the same no-worse bar the lossy strips use.
 
 
 Three opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:

{bindery_cli-0.37.0 → bindery_cli-0.39.0}/patchnotes.md

@@ -1,4 +1,99 @@
 # bindery-cli Patch Notes
+## v0.39.0 (2026-09-12)
+
+### The cover-wiring repair (`--fix-cover`) and the executed rulings
+
+- **`--fix-cover` repairs dangling EPUB2 cover wiring.** A
+  `<meta name="cover">` whose content names no manifest item is
+  re-pointed when the OPF guide's own cover reference resolves to
+  exactly one manifest item (the producer's statement, so nothing is
+  guessed), and removed when nothing identifies the item. A meta whose
+  item exists is never touched: an absent cover file belongs to
+  `--prune-missing-resources` and its edge completion.
+- **Gate treatment:** cover wiring is invisible to epubcheck, so a
+  cover-only repair always answered 'equal' from the improvement gate.
+  Cover repairs now ride the same no_worse acceptance the lossy strips
+  use, with the partial rule intact: a regression rejects, a
+  still-fatal book stays partial and is never auto-applied. Verified
+  on a real dangling-meta book from the library: re-pointed 1,
+  accepted.
+- **Scope by ruling (the hybrid):** the EPUB3
+  `properties="cover-image"` slice stays audit-only. Choosing which
+  image is the cover from filenames is exactly the non-determinism the
+  charter forbids, and no library book is fully unwired (measured:
+  21 dangling EPUB2 metas, 3 absent cover files, 103 EPUB3 books
+  without the property, 0 with no wiring at all).
+- **The metadata-validity carve-out is ruled: routed to
+  cquarry/CalibreQuarry.** bindery's side is closed: human-facing dc:
+  metadata stays a non-goal. The cross-repo handoff (a routed box in
+  CalibreQuarry's backlog naming the 51 OPF-085 invalid-UUID warnings
+  and the thin date/language tail) is filed for the next CQ lane.
+- **The tag-policy force-push repairs are executed** on a researched
+  go: the v0.28.0 tag retargeted to the first green commit with its
+  title line restored (the historic `git tag -F` defect had stripped
+  it), the v0.33.0 tag message replaced with the corrected verbatim
+  entry, and the 10 test_facility EPUBs stripped from all history
+  (git filter-repo; main and all 14 tags force-pushed in one
+  publish.yml-disabled session; verbatim tag messages survived; PyPI
+  untouched). The roadmap's Tag policy section records the execution.
+
+## v0.38.0 (2026-09-12)
+
+### Phase 16: package-structure repairs
+
+- **`--fix-container`, the gateway repair.** A book whose
+  META-INF/container.xml is missing, unparseable, or names a file the
+  archive does not contain is locked out of every repair: epubcheck
+  stays fatal while the OPF is unfindable. The new flag generates the
+  standard container at the OPF the locator already finds by fallback
+  (a byte-deterministic template with the constant epoch timestamp).
+  Oracle-verified on a real-shaped fixture: fatal before, gate-accepted
+  after. The Phase 16 prevalence study found 0 such books in-library
+  (5,228/5,228 have valid containers); the repair ships for the
+  acquisition phase, where the class actually lives.
+- **`--prune-missing-resources` rewrites what it drops.** Removing a
+  manifest item whose file is absent used to leave every package edge
+  pointing at it dangling, manufacturing the regression the gate then
+  rejects. The prune now carries the pruned ids into a rewrite of the
+  four edge classes: `spine@toc`, `item@media-overlay`, `item@fallback`,
+  and the EPUB2 cover meta. Optional edges of dead targets are removed;
+  edges to live ids are untouched.
+- **`--fix-media-types`.** Wrong manifest media-type declarations
+  (OPF-029; 275 occurrences in 15 library books, the class being a jpg
+  stamped `image/png` by an aggregator) are normalized attribute-only,
+  preserving quote style, and only when the file's magic bytes confirm
+  the extension: a PNG renamed .jpg keeps its wrong-but-honest
+  declaration instead of a worse one. On the real Arthur sample the run
+  goes from nochange to gate-accepted with 9 declarations fixed.
+- **The audit distinguishes font obfuscation from DRM.** encryption.xml
+  entries under the obfuscation algorithms (the IDPF URI and both Adobe
+  forms, including the ns.adobe.com URI real-world files actually
+  carry, which the prevalence study caught) that read fine are the new
+  OBFUSCATED advisory: publisher font embedding, benign, problem-False,
+  exit-neutral. An unreadable obfuscation entry is CORRUPT (a broken
+  font, re-source), and only non-obfuscation algorithms give the
+  ENCRYPTED skip. 86 of the library's 5,228 books carry
+  obfuscation-only encryption.xml; the library holds no real DRM at all.
+- **Boxed, not built, with real counts.** The obfuscation-aware
+  encryption repair (the magic-byte precondition validated on 424 real
+  fonts: all genuinely scrambled, zero stale entries in-library), href
+  case/backslash resolution (1 href in 1 book; 0 backslashes), and
+  duplicate zip-entry dedupe (0 books) are recorded in the roadmap with
+  their prevalence numbers and reopen conditions. The decision-gated
+  Phase 16 C boxes (cover wiring, the metadata carve-out, the NCX<->nav
+  drift detector, CSS url() pruning) carry recorded options and wait
+  for rulings.
+
+### The prevalence study (Phase 16 A)
+
+- 5,228 library books through the FastSweep epubcheck harness plus a
+  direct zip-level pass: container.xml valid on every book; RSC-007 at
+  14,156 occurrences in 600 books and PKG-010 in 280 (the prune
+  surface, 1,538 truly-absent manifest hrefs); OPF-029 at 275 in 15;
+  case-mismatch hrefs exactly 1; encryption.xml in 86 books, all of it
+  font obfuscation. Every Phase 16 repair box now carries its real
+  count.
+
 ## v0.37.0 (2026-09-12)
 
 ### The Bindery Repair Calibre plugin (Phase 3)

{bindery_cli-0.37.0 → bindery_cli-0.39.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.37.0"
+version = "0.39.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 = [

{bindery_cli-0.37.0 → bindery_cli-0.39.0}/roadmap.md

@@ -1483,48 +1483,112 @@ an opt-in structural repair under the existing gate contract.
 
 ### B. The repairs (each: opt-in flag, dry-run default, gate-accepted)
 
-- [ ] **`--fix-container`**: generate META-INF/container.xml at the
+- [x] **`--fix-container`**: generate META-INF/container.xml at the
   located OPF (model: upstream calibre's initialize_container).
   Gateway repair, effort S, HIGH value.
+  *(shipped v0.38.0, dac7835: fires when the container is missing,
+  unparseable, or names a file the archive does not contain; the
+  generated entry carries the constant epoch so repairs stay
+  byte-deterministic. Prevalence: 0 books in-library (5,228/5,228 have
+  valid containers) — shipped anyway as the acquisition-phase gateway;
+  oracle-verified on a real-shaped fixture (fatal before, accept
+  after).)*
 - [ ] **Obfuscation-aware encryption.xml repair**: prune stale
   obfuscation entries when font magic bytes prove the fonts are
   decrypted in place; drop encryption.xml when only obfuscation entries
   remain and fonts verify. NEVER un-obfuscate. M.
-- [ ] **Audit distinction: OBFUSCATED vs DRM** in audit.py (today the
+  *(BOXED with real counts, 2026-09-12: the magic-byte validation
+  proved 424/424 readable obfuscation fonts genuinely scrambled — zero
+  stale entries in-library, so the repair has nothing to do here; its
+  precondition is validated and recognition carries both Adobe URIs.
+  The audit half of this box SHIPPED (see below). Opens only if
+  acquisition ever brings a decrypted-in-place book.)*
+- [x] **Audit distinction: OBFUSCATED vs DRM** in audit.py (today the
   ENCRYPTED verdict keys on unreadable entries and implies DRM where
   publisher obfuscation is benign). S, rides the box above.
-- [ ] **Reference-edge completion for `--prune-missing-resources`**:
+  *(shipped v0.38.0, dac7835: readable obfuscation entries are the
+  OBFUSCATED advisory (problem-False, exit-neutral; 86 library books);
+  an unreadable obfuscation entry is CORRUPT (broken font, re-source),
+  and only non-obfuscation algorithms give the ENCRYPTED skip.)*
+- [x] **Reference-edge completion for `--prune-missing-resources`**:
   rewrite `spine@toc`, `item@media-overlay`, `item@fallback`, and EPUB2
   cover-meta edges when their targets are pruned (machinery exists in
   fix_manifest_ids). Prevents manufacturing gate regressions. S/M.
-- [ ] **Manifest media-type normalization**: sniff magic bytes /
+  *(shipped v0.38.0, dac7835: prune_missing_manifest_items returns the
+  pruned ids; prune_dangling_edges removes the optional attributes and
+  a cover meta whose payload died. RSC-007 backs it at 14,156
+  occurrences in 600 books.)*
+- [x] **Manifest media-type normalization**: sniff magic bytes /
   extension map; attribute-only. S.
+  *(shipped v0.38.0, dac7835 as `--fix-media-types`: OPF-029 class,
+  275 occurrences in 15 books; jpg/png/gif only, fired only when the
+  magic bytes confirm the extension. Oracle-verified on the real
+  Arthur sample: nochange without the flag, accept with 9 normalized.)*
 - [ ] **href case/backslash resolution**: case-insensitive namemap when
   exactly one zip entry matches; backslash to slash. Kills the
   present-file RSC-007/PKG-010 slice prune cannot touch. M.
+  *(BOXED with real counts, 2026-09-12: exactly 1 case-mismatch href in
+  1 book and 0 backslash hrefs across the library — below the shipping
+  bar; reopen if acquisition changes the mix.)*
 - [ ] **Duplicate zip-entry dedupe on rewrite**: drop shadowed
   duplicates (audit already counts `dup_entries`). S.
+  *(BOXED with real counts, 2026-09-12: 0 books with duplicate entries
+  in-library.)*
 
 ### C. Decision-gated (recorded boxes; no work without a ruling)
 
-- [ ] **Cover wiring repair** (dangling `<meta name="cover">`, missing
+- [x] **Cover wiring repair** (dangling `<meta name="cover">`, missing
   `properties="cover-image"`, wrong cover media-type): narrow,
   finding-driven repair vs audit-only. Needs the scope decision. M.
+  *(RULED 2026-09-12 (Brandon, on the researched options): hybrid.
+  SHIPPED the deterministic half as `--fix-cover` (tests 96a55ad,
+  implementation 790b5f4; v0.39.0): a dangling EPUB2 cover meta is
+  re-pointed from the guide's cover reference when exactly one manifest
+  item carries that file, removed when nothing identifies the item, and
+  a meta whose item exists is left to the prune + edge-completion pair.
+  Measured class: 21 dangling metas + 3 absent files; oracle check on a
+  real book re-pointed 1 and the gate's no_worse bar accepts it (cover
+  wiring is invisible to epubcheck, so cover-only repairs ride the
+  lossy-strips acceptance path). The EPUB3 `properties="cover-image"`
+  slice stays audit-only by ruling: picking "which image is the cover"
+  from names is the guesswork the charter forbids, and 0 library books
+  are fully unwired.)*
 - [ ] **Metadata validity carve-out ruling** (non-ISO `dc:date`,
   invalid `dc:language`, missing `dcterms:modified`): bindery opt-in
   with a determinism-safe timestamp policy, or route to
   cquarry/CalibreQuarry. Needs a written charter ruling. M.
+  *(Recorded options, 2026-09-12: (a) bindery opt-in — non-ISO dates
+  and language tags are deterministic normalizations (OPF-007/OPF-012
+  class), but `dcterms:modified` needs a timestamp policy that breaks
+  byte-determinism unless pinned to the file's own zip timestamps;
+  (b) route to cquarry/CalibreQuarry — metadata quality is catalog
+  territory and the library's metadata writes already live there.
+  (b) is the cleaner charter fit; (a) only if epubcheck fatals on such
+  books show up in acquisition.)*
+  *(RULED 2026-09-12 (Brandon, on the researched options): route to
+  cquarry/CalibreQuarry. The ruling is recorded here; the cross-repo
+  handoff (a routed box in CalibreQuarry's backlog naming the class:
+  51 OPF-085 invalid-UUID warnings plus the thin date/language tail)
+  is a main-thread task for the next CQ lane. bindery's side is closed:
+  dc: metadata stays a non-goal.) *
 - [ ] **NCX<->nav drift DETECTOR** (audit-only; structural diff feeding
   `decisions_needed`; ToC synthesis stays out of charter
   permanently). L if repair is ever attempted.
 - [ ] **CSS url() pruning** as `--prune-missing-resources` scope
-  extension: only after the prevalence study says it matters. M.
+  extension: only after the prevalence study says it matters.
+  *(Prevalence read, 2026-09-12: CSS-007/CSS-008 appear at 56/30 books
+  but are selector damage, not url() pruning candidates; no url()-class
+  count surfaced in the extract codes. Stays closed until a named
+  epubcheck finding demands it.)*
 
 Ship shape: A leads; then B in value order (container, encryption,
 prune-edges, media-types); C boxes record their decisions and wait.
 Each repair ships with a fixture built from the prevalence study's
 real samples, a regression test written before the fix, and the gate
 (epubcheck) accepting the result.
+*(2026-09-12 disposition: B shipped the four boxes with real backing
+and boxed the two zero-prevalence classes with their counts; C carries
+recorded options and waits for Brandon.)*
 
 ## Tag policy (decided 2026-09-11, recorded 2026-09-12)
 
@@ -1537,9 +1601,12 @@ The release-tag backlog is settled, forward-only:
   of record (2026-09-11): no backfill tags will be cut for them. Their
   release notes live in patchnotes.md and their wheels are on PyPI; the
   missing git tags are accepted history.
-- **Two recorded-only repairs stay force-pushes, undecided:** the
-  v0.28.0 retag (the tag points at a red commit) and the v0.33.0
-  em-dash tag message (the pushed tag carries two em-dashes the
-  proofread missed; the source patchnotes entry was fixed immediately in
-  1c374c1). Either would need publish.yml disabled around the push and
-  Brandon's explicit go; neither is ever auto-executed.
+- **EXECUTED 2026-09-12 on Brandon's researched go** (one
+  publish.yml-disabled session): the v0.28.0 tag now points at the
+  first green commit (aabdd7a) and its message regains the title line
+  the historic `git tag -F` defect had stripped; the v0.33.0 tag
+  message is the corrected verbatim entry (61b16ea's entry, zero
+  em-dashes); and the 10 test_facility EPUBs (plus their scratch test
+  files) are stripped from all history via git filter-repo, main and
+  all 14 tags force-pushed. The tags' verbatim messages survived the
+  rewrite; PyPI was untouched throughout.

{bindery_cli-0.37.0 → bindery_cli-0.39.0}/spec.md

@@ -14,10 +14,11 @@ schema (RSC-005) violations, which are usually harmless to readers and not safel
 mechanizable.
 
 The deliberate exceptions to "semantics-preserving" come in two kinds, both strictly
-opt-in. The twelve **structural repairs** (`--fix-empty-body`, `--fix-missing-title`,
+opt-in. The fourteen **structural repairs** (`--fix-empty-body`, `--fix-missing-title`,
 `--fix-id-colons`, `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
 `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
-`--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`) alter
+`--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`,
+`--fix-container`, `--fix-media-types`, `--fix-cover`) alter
 markup structure or fabricate minimal content; the three
 **lossy modes** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`) remove
 content a converter injected rather than content the author wrote. The default pass runs
@@ -91,7 +92,7 @@ normal gate applies.
 
 ### Opt-in: structural repairs
 
-Twelve repairs go past well-formedness and therefore require their own flag; none is ever
+Fifteen repairs go past well-formedness and therefore require their own flag; none is ever
 part of the default pipeline:
 
 - **`--fix-empty-body`**: `&nbsp;` inside a strictly empty `<body></body>` ("body
@@ -168,7 +169,30 @@ every EPUB3 book in an `--all` sweep taking exactly that damage).
   strict readers; the encoded form denotes the same file and renders identically. Scope
   is fixed to the space character: extend only with a named epubcheck finding.
 
-All twelve are evaluated by the normal `gate`: unlike the lossy strips, their benefit is
+- **`--fix-container`**: generate `META-INF/container.xml` at the located OPF when the
+container is missing, unparseable, or names a file the archive does not contain. This is the
+gateway defect: epubcheck stays fatal while the OPF is unfindable, so no other repair can be
+gate-accepted on such a book. The generated file is byte-deterministic (a fixed template plus
+the OPF path; the entry's timestamp is the constant epoch), and a healthy container is never
+touched.
+- **`--fix-media-types`**: normalize wrong manifest `media-type` declarations (OPF-029: a
+file's bytes do not match the declared type). The expected type comes from the extension, and
+the rewrite fires only when the file's magic bytes at offset 0 confirm the extension (jpg,
+jpeg, png, gif): a PNG renamed `.jpg` keeps its wrong-but-honest declaration rather than
+gaining a worse one. Attribute-only, quote-style preserved; files absent from the archive
+belong to `--prune-missing-resources`.
+
+- **`--fix-cover`**: repair dangling EPUB2 cover wiring (the cover-wiring ruling's
+deterministic half). A `<meta name="cover" content="X">` whose `X` names no manifest id is
+re-pointed when the OPF guide's `<reference type="cover">` resolves to exactly one manifest
+item (the producer's own statement; nothing is guessed), and removed when nothing identifies
+the item. A meta whose id exists in the manifest is never touched here, even when the item's
+file is absent: that class belongs to `--prune-missing-resources` and its edge completion.
+The EPUB3 `properties="cover-image"` slice is audit-only by ruling. Cover wiring is invisible
+to epubcheck, so cover-only repairs are accepted under the `no_worse` bar the lossy strips
+use, with the `partial` rule intact.
+
+All fifteen are evaluated by the normal `gate`: unlike the lossy strips, their benefit is
 visible to epubcheck (they clear errors), so a run with no measurable improvement is a
 noop and nothing is applied. CDATA sections and comments are never rewritten, as
 everywhere else.
@@ -353,6 +377,13 @@ is fully read for CRC + decompression, reporting CORRUPT rather than EMPTY), and
 issues. Manifest/NCX references to absent files are classified as either `convention` (ToC is bloated but
 present documents form a consecutive chapter span) or `fragment` (the span itself is broken).
 
+The archive verdict distinguishes font obfuscation from DRM (Phase 16): entries
+`encryption.xml` declares under a font-obfuscation algorithm (the IDPF `2008/embedding`
+URI and both Adobe forms, including the `ns.adobe.com` URI real-world files carry) that
+read fine are the OBFUSCATED advisory — publisher embedding, benign, never a failure; an
+unreadable obfuscation entry is CORRUPT (a broken font, not a business model), and only
+non-obfuscation algorithms give the ENCRYPTED verdict with its DRM skip advice.
+
 The completeness analyzer is the phase-1 spot-check and is advisory by contract: it never
 flags a book and never moves the exit code. Per book it reports the spine doc count, the
 prose-doc count (spine docs carrying at least 400 visible characters), the opening and closing

{bindery_cli-0.37.0 → bindery_cli-0.39.0}/src/bindery/__init__.py

@@ -4,7 +4,7 @@ strip), epubcheck-gated.
 Single source of truth for the version. pyproject.toml must match VERSION below.
 """
 
-VERSION = "0.37.0"
+VERSION = "0.39.0"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402