bindery-cli 0.55.0__tar.gz → 0.57.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/AGENTS.md +39 -12
  2. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/PKG-INFO +3 -2
  3. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/README.md +2 -1
  4. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/patchnotes.md +104 -0
  5. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/pyproject.toml +1 -1
  6. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/roadmap.md +2 -0
  7. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/spec.md +55 -22
  8. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/src/bindery/__init__.py +1 -1
  9. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/src/bindery/cli.py +63 -19
  10. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/src/bindery/epub.py +108 -22
  11. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/src/bindery/transforms.py +62 -24
  12. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_cli.py +64 -7
  13. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_epub.py +248 -0
  14. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_flags_real_core.py +46 -12
  15. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_flags_wiring.py +1 -0
  16. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_transforms.py +165 -0
  17. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/uv.lock +1 -1
  18. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/.github/FUNDING.yml +0 -0
  19. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/.github/workflows/ci.yml +0 -0
  20. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/.github/workflows/publish.yml +0 -0
  21. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/.gitignore +0 -0
  22. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/LICENSE +0 -0
  23. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/OBSERVE-RESEARCH.md +0 -0
  24. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/docs/screenshots/library-sweep.png +0 -0
  25. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/logo.svg +0 -0
  26. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/plugin/__init__.py +0 -0
  27. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/project.done +0 -0
  28. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/run_tests.sh +0 -0
  29. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/scripts/FastSweep.java +0 -0
  30. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/scripts/build_plugin.py +0 -0
  31. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/scripts/fast_sweep.py +0 -0
  32. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/src/bindery/__main__.py +0 -0
  33. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/src/bindery/audit.py +0 -0
  34. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/src/bindery/library.py +0 -0
  35. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/src/bindery/observe.py +0 -0
  36. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/src/bindery/pagination.py +0 -0
  37. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/src/bindery/reserialize.py +0 -0
  38. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/src/bindery/validate.py +0 -0
  39. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/src/bindery/watermark.py +0 -0
  40. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_audit.py +0 -0
  41. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_comment_hyphens.py +0 -0
  42. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_contamination.py +0 -0
  43. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_cover_tocdrift.py +0 -0
  44. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_help.py +0 -0
  45. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_library.py +0 -0
  46. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_matcher_hardening.py +0 -0
  47. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_observe.py +0 -0
  48. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_pagination.py +0 -0
  49. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_plugin.py +0 -0
  50. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_reserialize.py +0 -0
  51. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_space_renames.py +0 -0
  52. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_spine_guard.py +0 -0
  53. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_validate.py +0 -0
  54. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_version.py +0 -0
  55. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_watermark.py +0 -0
  56. {bindery_cli-0.55.0 → bindery_cli-0.57.0}/tests/test_xml_hardening.py +0 -0
@@ -30,7 +30,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
30
30
  `xmlns`, bare `&`, named entities, void self-closing), the NCX pipeline, and the
31
31
  mimetype fix (added/normalized/first-stored, epub.py's archive rewrite); every core
32
32
  fix must render identically to the author's intent: never add, remove, or reorder
33
- visible content. The canonical opt-in inventory lives in spec.md: twenty-four structural
33
+ visible content. The canonical opt-in inventory lives in spec.md: twenty-five structural
34
34
  repairs, four lossy strips, four safe opt-ins, plus `--reserialize`.
35
35
  * **Structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
36
36
  `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
@@ -64,12 +64,20 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
64
64
  verified against 5.3), ambiguous renames refused per entry (`space_rename_map`),
65
65
  accepted under `no_worse` because PKG-010 sits on the warning axis the gate
66
66
  does not measure. `--fix-unbound-prefix` (v0.51.0, issue #9, the Calibre
67
- embed scar) binds an attribute prefix the OPF never declares inline on the
68
- element that uses it (`<dc:identifier id="ID1" ns0:scheme="calibre">`
67
+ embed scar; element half v0.57.0, issue #22) binds a prefix the OPF
68
+ never declares in scope inline on the element that uses it: the
69
+ attribute half (`<dc:identifier id="ID1" ns0:scheme="calibre">`
69
70
  whose `xmlns:ns0` sits on a sibling, out of XML scope; two RSC-016 fatals
70
- plus OPF-030): URI evidence is the same prefix declared elsewhere in the
71
- document (all declarations must agree) or the OPF namespace for a DC
72
- element under an OPF-namespaced package, anything else refuses the whole
71
+ plus OPF-030) and, since v0.57.0, the element half (the Calibre 9.7.0
72
+ writer self-declares `xmlns:dc` on every dc: element but one, so that
73
+ element's own name dies with `FATAL(RSC-016): The prefix "dc" for
74
+ element "dc:date" is not bound`; the scope walk now checks each start
75
+ tag's own name and binds it on the element): URI evidence is the same
76
+ prefix declared elsewhere in the
77
+ document (all declarations must agree) or the use site's own namespace
78
+ for a Dublin Core site under an OPF-namespaced package (the OPF
79
+ namespace for a DC element's attributes, the DC namespace for a literal
80
+ `dc:` element name), anything else refuses the whole
73
81
  document; scope-tracked over a comment/CDATA-aware tokenizer, OPF only
74
82
  (content docs have the `--strip-bad-attrs` drop); normal `gate`.
75
83
  The v0.55.0 two (the 2026-10-25 issue batch): `--declare-missing-items`
@@ -87,6 +95,19 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
87
95
  different spelling (the spine guard correctly refuses; the mass carrier
88
96
  is `--encode-url-spaces` territory), so the prune's coverage boundary is
89
97
  documented, not widened.
98
+ The v0.56.0 one (the boxed OPF-030 recipe, built same-day on Brandon's
99
+ call): `--fix-unique-identifier` wires the package's dangling
100
+ unique-identifier id onto the first `dc:identifier` start tag
101
+ (`unique_identifier_wired`), with the masked-NCX coordination: the uid
102
+ sync predicts the post-wiring uid before the loop (the same pure
103
+ function on the same input region, never a snapshot of a different
104
+ layout), so one run both wires the OPF and aligns the NCX dtb:uid the
105
+ broken wiring was masking. Refusals: absent/empty attribute, non-NCName
106
+ id, already-wired, no dc:identifier, first-identifier-has-id; normal
107
+ `gate`. The CSS-007 font half shipped the same release inside
108
+ `--fix-media-types` (font/* blessed on both package versions, magic
109
+ confirmed, `.eot` never touched) with the flag accepted under `no_worse`
110
+ (its gain sits on the INFO axis).
90
111
  They alter markup structure or fabricate minimal content. v0.14–v0.16 ran these unconditionally, which broke this rule;
91
112
  v0.17.0 restored it. `--unwrap-illegal-tags` additionally protects any illegal-tag
92
113
  name that an EPUB stylesheet styles as an element selector (`css_protected_tags`,
@@ -132,12 +153,18 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
132
153
  gain IS visible, so a run with no measurable improvement is a noop and nothing is
133
154
  applied) except the two whose gains sit on axes epubcheck does not measure:
134
155
  `--fix-cover` and `--encode-url-spaces`, accepted under the same `no_worse` bar with
135
- the partial rule intact. One masked-axis rule (v0.51.0, issue #9): when the gate
136
- answers noop but `report.ncx_uid_synced` fired on a book that started with fatals,
137
- `process_book` reclassifies the verdict to `partial` (a fatal package halts the
138
- metadata checks, so the dtb:uid comparison never ran in either measurement and the
139
- real sync measures as no gain); application behavior is unchanged, since still-fatal
140
- books are never applied. One structural veto rides above the counts (v0.52.0,
156
+ the partial rule intact. One masked-axis rule (v0.51.0, issue #9, for the
157
+ NCX sync; generalized v0.57.0, issue #22, to every fired fix): when the gate
158
+ answers noop on a book that started AND stayed fatal, `process_book`
159
+ reclassifies the verdict to `partial` (a still-fatal package keeps
160
+ epubcheck's per-file halt, so whatever the fix cleared below the halt --
161
+ the dtb:uid comparison, an error axis, a second latent fatal unmasked by the
162
+ fix that cleared the first: `unbound_prefixes_bound:1`, 1f/1e -> 1f/0e,
163
+ fatals read 1 -> 1 -- measures as no gain, and a silent `equal` buries a
164
+ book that still will not open instead of landing it on the manual list);
165
+ application behavior is unchanged, since still-fatal
166
+ books are never applied, and clean books are untouched (no fatals on both
167
+ sides, no reclassification). One structural veto rides above the counts (v0.52.0,
141
168
  issue #10): `process_book` probes source and candidate with `epub.spine_dangles`
142
169
  (itemref -> manifest item -> archive entry, resolved through the same helper the
143
170
  repair's existence checks use) and rejects any candidate whose dangle count rises
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: bindery-cli
3
- Version: 0.55.0
3
+ Version: 0.57.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
@@ -66,11 +66,12 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
66
66
  - **`--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.
67
67
  - **`--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.
68
68
  - **`--declare-missing-items`**: the RSC-008 inverse of the prune: adds the manifest `<item>` declarations the OPF never wrote for files the archive carries and the book references (content `<img src>`/`<link href>` targets, CSS `url()` resources, OPF guide references). Deterministic ids, media types from a blessed extension map only, and no `<itemref>` is ever written: the spine is untouched.
69
+ - **`--fix-unique-identifier`**: wires the dangling OPF unique-identifier (OPF-030): adds the id the package names to the first `dc:identifier` when no element carries it, and aligns the NCX `dtb:uid` the broken wiring was masking in the same run. The `dc:` values are never touched; ambiguous shapes refuse.
69
70
  - **`--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.
70
71
  - **`--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:`).
71
72
  - **`--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. Since v0.44.0 the flag also renames archive entries whose names carry raw spaces to their underscore spellings and rewrites every reference to them (OPF, NCX, content, CSS `url()`), clearing the PKG-010 space-in-filename advisories: underscore, never percent-encoding, because epubcheck decodes references before entry lookup.
72
73
  - **`--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.
73
- - **`--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 a misnamed-but-consistent file (a PNG renamed .jpg) is never made worse.
74
+ - **`--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 a misnamed-but-consistent file (a PNG renamed .jpg) is never made worse. Since v0.56.0 it also covers the CSS-007 font slice (a `ttf`/`otf`/`woff`/`woff2` declared outside epubcheck's blessed font set is rewritten to its `font/*` spelling when the magic bytes confirm; `.eot` is never touched), and the flag is accepted under the no-worse bar because that half's gain sits on the INFO axis.
74
75
  - **`--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.
75
76
  - **`--fix-comment-double-hyphen`**: replaces `--` sequences inside XML comments with en-dashes. `--` is illegal inside an XML comment (epubcheck fatal RSC-016: the book opens in lenient readers but never passes epubcheck). The edit stays inside the comment bodies: text nodes and CDATA sections are never touched, and each comment's terminator is left intact.
76
77
  - **`--fix-svg-dup-ids`**: renames duplicate `id` values inside standalone `.svg` entries (old calibre SVG page renders repeat glyph ids within one document; the intake wave that found this carried 445 to 1,339 'Duplicate "glNNNN"' errors per book). The first occurrence keeps its name, later ones gain `_2`/`_3`, and internal references are deliberately untouched: they already resolve to the first definition under every reader's first-match lookup.
@@ -39,11 +39,12 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
39
39
  - **`--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.
40
40
  - **`--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.
41
41
  - **`--declare-missing-items`**: the RSC-008 inverse of the prune: adds the manifest `<item>` declarations the OPF never wrote for files the archive carries and the book references (content `<img src>`/`<link href>` targets, CSS `url()` resources, OPF guide references). Deterministic ids, media types from a blessed extension map only, and no `<itemref>` is ever written: the spine is untouched.
42
+ - **`--fix-unique-identifier`**: wires the dangling OPF unique-identifier (OPF-030): adds the id the package names to the first `dc:identifier` when no element carries it, and aligns the NCX `dtb:uid` the broken wiring was masking in the same run. The `dc:` values are never touched; ambiguous shapes refuse.
42
43
  - **`--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.
43
44
  - **`--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:`).
44
45
  - **`--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. Since v0.44.0 the flag also renames archive entries whose names carry raw spaces to their underscore spellings and rewrites every reference to them (OPF, NCX, content, CSS `url()`), clearing the PKG-010 space-in-filename advisories: underscore, never percent-encoding, because epubcheck decodes references before entry lookup.
45
46
  - **`--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.
46
- - **`--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 a misnamed-but-consistent file (a PNG renamed .jpg) is never made worse.
47
+ - **`--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 a misnamed-but-consistent file (a PNG renamed .jpg) is never made worse. Since v0.56.0 it also covers the CSS-007 font slice (a `ttf`/`otf`/`woff`/`woff2` declared outside epubcheck's blessed font set is rewritten to its `font/*` spelling when the magic bytes confirm; `.eot` is never touched), and the flag is accepted under the no-worse bar because that half's gain sits on the INFO axis.
47
48
  - **`--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.
48
49
  - **`--fix-comment-double-hyphen`**: replaces `--` sequences inside XML comments with en-dashes. `--` is illegal inside an XML comment (epubcheck fatal RSC-016: the book opens in lenient readers but never passes epubcheck). The edit stays inside the comment bodies: text nodes and CDATA sections are never touched, and each comment's terminator is left intact.
49
50
  - **`--fix-svg-dup-ids`**: renames duplicate `id` values inside standalone `.svg` entries (old calibre SVG page renders repeat glyph ids within one document; the intake wave that found this carried 445 to 1,339 'Duplicate "glNNNN"' errors per book). The first occurrence keeps its name, later ones gain `_2`/`_3`, and internal references are deliberately untouched: they already resolve to the first definition under every reader's first-match lookup.
@@ -1,5 +1,109 @@
1
1
  # bindery-cli Patch Notes
2
2
 
3
+ ## v0.57.0 (2026-10-25)
4
+
5
+ ### Issue #22: the embed scar's element half, and the end of the silent equal
6
+
7
+ The reconcile-embed fallout's last scar shape, plus the reporting gap its
8
+ investigation exposed.
9
+
10
+ **`--fix-unbound-prefix` binds element prefixes (shape 1).** Calibre
11
+ 9.7.0's `embed_metadata` self-declares `xmlns:dc` on every dc: element it
12
+ writes but one, leaving that element's own ELEMENT prefix unbound:
13
+ `FATAL(RSC-016): The prefix "dc" for element "dc:date" is not bound`. The
14
+ v0.51.0 repair covered attribute prefixes only (`ns0:scheme`); the element
15
+ name is a different use site and nothing in the inventory touched it, so
16
+ the specimen chain sat one fatal apart from clean with no repair left to
17
+ run. The same scope-tracking walk now checks each start tag's own name:
18
+ an unbound element prefix is bound inline on the element, the exact shape
19
+ the file's healthy siblings already use. The evidence rules carry over
20
+ with one addition: rule 1 is unchanged (the prefix declared elsewhere in
21
+ the document, every declaration agreeing), and rule 2 for a literal `dc:`
22
+ element under an OPF-namespaced package resolves to the DC namespace
23
+ itself (the attribute half's rule 2 names the OPF namespace because
24
+ `opf:scheme` rides on DC elements; a `dc:` element IS the Dublin Core
25
+ element). Ambiguous or unevidenced prefixes still refuse the whole
26
+ document, clean documents stay byte-identical, and the each-use-site
27
+ counting contract holds (nested unbound elements each get their own
28
+ declaration, mirroring the attribute half). One start tag never carries
29
+ two declarations for one prefix (XML forbids the duplicate attribute;
30
+ the code-review pass caught the collision between an unbound element
31
+ prefix and an unbound same-prefix attribute on one tag, and fixed the
32
+ attribute-vs-attribute variant the attribute half had always carried).
33
+ Live gate on the specimen
34
+ (Hackers, the issue's own chain): the scarred original went
35
+ `1f/1e -> 0f/1e` with `unbound_prefixes_bound:2` (attribute + element in
36
+ one run), and the half-repaired intermediate that v0.56.0 refused as
37
+ `equal` now repairs (`1f/0e -> 0f/1e`, the element bind alone). The
38
+ residual error on the specimen is NCX-001, not embed damage: its 2010-era
39
+ NCX spells every element with the `ncx:` prefix, which the always-on
40
+ dtb:uid sync's `<meta\b` matcher does not read; that sync gap is recorded
41
+ on the issue and left unrepaired here.
42
+
43
+ **Still-fatal noops reclassify as partial (shape 2).** The same
44
+ investigation caught the gate answering `equal (no measurable gain)` on a
45
+ book whose fix had cleared one fatal and unmasked a latent second:
46
+ `unbound_prefixes_bound:1` fired, `1f/1e -> 1f/0e`, fatals read 1 -> 1,
47
+ and the silent skip buried a book that still will not open. The v0.51.0
48
+ masked-ncx-gain rule already reclassified exactly this shape for the uid
49
+ sync; it is now general (the gate's noop on any book that started and
50
+ stayed fatal means the fix's real axis lives below epubcheck's per-file
51
+ halt, whatever the fix was): the verdict is `partial`, the book lands on
52
+ the manual list (`still_fatal`), and the still-fatal rule is untouched
53
+ (partial candidates were never auto-applied). Clean books are unaffected:
54
+ the rule cannot fire without fatals on both sides, and the gate's own
55
+ partial and reject answers never enter it.
56
+
57
+ Twenty-five structural repairs. Suite: 789 tests.
58
+
59
+
60
+ ## v0.56.0 (2026-10-25)
61
+
62
+ ### The two boxed recipes, built: the OPF-030 wiring and the CSS-007 font half
63
+
64
+ The v0.55.0 census lanes left two deterministic-but-marginal candidates
65
+ recorded as recipes; both shipped the same day on the follow-up call.
66
+
67
+ **`--fix-unique-identifier` (the OPF-030 recipe).** The dominant family:
68
+ the package names an id (`bookid`, `uuid_id`, ISBN shapes) but no
69
+ `dc:identifier` carries any id attribute at all. The repair writes the id
70
+ the package itself names onto the first `dc:identifier` start tag; the
71
+ dc: values are never touched. It refuses to guess every ambiguous shape:
72
+ an absent or empty `unique-identifier` attribute, a non-NCName id, an
73
+ already-wired OPF, no `dc:identifier` element, or a first identifier that
74
+ already carries an id. The live gate on the census specimen (The Eagle Has
75
+ Landed) surfaced a masking twist: the broken wiring was hiding a real
76
+ NCX-001 (epubcheck cannot compare `dtb:uid` to an unresolvable
77
+ identifier), and the default pass's uid sync skipped because the source
78
+ had no resolvable uid. The repair now predicts the post-wiring uid (the
79
+ same pure transformation the OPF branch applies; never a snapshot of a
80
+ different layout, the issue #10 lesson) so one run wires the OPF AND
81
+ aligns the NCX: the specimen went from 2 errors (OPF-030 + a masked
82
+ latent) to 1 (a pre-existing out-of-scope OPF-032), accept, with
83
+ `unique_identifier_wired:1` and the NCX sync fired. The multi-OPF merge
84
+ leftovers whose failing OPF is a stale non-rootfile are unreachable by
85
+ construction (only the located rootfile is repaired).
86
+
87
+ **The CSS-007 font half of `--fix-media-types`.** The census found the
88
+ INFO-severity family: `@font-face` srcs whose OPF declaration sits
89
+ outside epubcheck's version-specific blessed font set (`text/plain`
90
+ fonts, `application/xfont+otf`, `octet-stream` woff2). The map gains
91
+ `ttf`/`otf`/`woff`/`woff2` with their magic bytes; the `font/*`
92
+ spellings are blessed on BOTH package versions (EPUB2 blesses the prefix,
93
+ EPUB3's exact list carries them), so no version gate is needed, and the
94
+ existing magic-byte confirmation rule is unchanged (a font is rewritten
95
+ only when its bytes name the format the extension does; `.eot` is never
96
+ touched -- epubcheck rejects EOT as a font src however it is declared, so
97
+ correcting it can only churn). Because CSS-007 is INFO, the error counts
98
+ do not see the gain, so the flag is now accepted under the `no_worse` bar
99
+ (the cover-wiring ruling's shape): the OPF-029 error slice still measures
100
+ its real decrease through the normal gate, and a font-only repair no
101
+ longer reads as gainless. Live gate on Brave New World (8 `text/plain`
102
+ fonts): `media_types_normalized:8`, accept, CSS-007 fully cleared.
103
+
104
+ Twenty-five structural repairs. Suite: 768 tests.
105
+
106
+
3
107
  ## v0.55.0 (2026-10-25)
4
108
 
5
109
  ### The issue batch: the 2026-10-24 surgery's follow-ups, #11 through #16
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "bindery-cli"
7
- version = "0.55.0"
7
+ version = "0.57.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 = [
@@ -49,6 +49,8 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
49
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-v0.53.1 |
50
50
  | 0.54 | The surgery fixes: `fix_ncx_playorder` is contract-gated (epubcheck's playOrder contract: same-target sharing, distinct-target distinctness, contiguous 1..K across navTarget/pageTarget; the old unconditional 1..N renumbering rewrote valid TOCs into violations, 211 of 579 firings gate-rejected vs 17 real fixes) and `_PROTECTED_RE` protects the Calibre `/*<![CDATA[*/ ... /*]]>*/` wrapper as one unit (the bare CDATA span exposed the trailing `*/` to strip_prolog_junk's amputation, 111 phantom-fix rejections); verified by the 2026-10-24 error-code surgery (OBSERVE-RESEARCH.md) | v0.54.0 |
51
51
  | 0.55 | The issue-batch release (issues #11-#16, the 2026-10-24 surgery's follow-ups): `--strip-epub3-attrs` extended with `role` + `aria-hidden` (the census killed the DOCTYPE-gate concern: epubcheck is profile-driven; #11), `--fix-duplicate-ids` for content docs (#14), `--declare-missing-items` for RSC-008 (#16, with the prune's RSC-001 boundary documented), the size-scaled epubcheck timeout with one retry and the distinct `OracleTimeout` (#15), observe schema v2 (`codes.messages` rename, true `codes.occurrences`, the `counting` block, v1 `--against` accepted; #13), the #12 content-model ruling (measured, not repaired: the wrap changes layout), and the #17 census lanes (RSC-012/OPF-029 dispositions on existing flags; OPF-030/CSS-007/RSC-004 recorded leave-measured with recipes) | v0.55.0 |
52
+ | 0.56 | The boxed recipes, built same-day on the follow-up call: `--fix-unique-identifier` (the OPF-030 recipe: wire the package's named id onto the first dc:identifier, refuses every ambiguous shape, and predicts the post-wiring uid so the NCX sync the broken wiring was masking fires in the same run -- eagle 2e -> 1e accept) and the CSS-007 font half inside `--fix-media-types` (font/* blessed on both package versions, magic confirmed, .eot never touched; accepted under no_worse because the gain sits on the INFO axis -- Brave New World 8 fonts normalized, CSS-007 cleared) | v0.56.0 |
53
+ | 0.57 | The embed scar's element half and the end of the silent equal (issue #22): `--fix-unbound-prefix` now binds an unbound ELEMENT prefix inline (the 9.7.0 writer self-declares xmlns:dc on every dc: element but one; rule 2 for a literal dc: element resolves to the DC namespace itself; Hackers 1f/1e -> 0f/1e with both binds in one run, and the half-repaired intermediate that read equal now repairs), and the masked-axis reclassification generalizes from the v0.51.0 NCX sync to every fired fix: a gate noop on a book that started and stayed fatal reads partial (the manual list) instead of a silent equal; the ncx:-prefixed dtb:uid sync gap found on the specimen is recorded, not repaired | v0.57.0 |
52
54
 
53
55
  ## Open work
54
56
 
@@ -13,7 +13,7 @@ restyle, re-compress, or restructure content, and it does not attempt to fix arb
13
13
  schema (RSC-005) violations, which are usually harmless to readers and not safely
14
14
  mechanizable.
15
15
 
16
- The deliberate exceptions to "semantics-preserving" come in opt-in groups. The twenty-four
16
+ The deliberate exceptions to "semantics-preserving" come in opt-in groups. The twenty-five
17
17
  **structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
18
18
  `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
19
19
  `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
@@ -22,7 +22,8 @@ The deliberate exceptions to "semantics-preserving" come in opt-in groups. The t
22
22
  `--fix-container`, `--fix-media-types`, `--fix-cover`, `--fix-comment-double-hyphen`,
23
23
  `--fix-svg-dup-ids`, `--fix-duplicate-ids`, `--fix-cdata-terminator`,
24
24
  `--fix-misnested-inline`,
25
- `--fix-stray-close`, `--fix-unterminated-attr`, `--fix-unbound-prefix`) alter
25
+ `--fix-stray-close`, `--fix-unterminated-attr`, `--fix-unbound-prefix`,
26
+ `--fix-unique-identifier`) alter
26
27
  markup structure or fabricate minimal content; the four
27
28
  **lossy modes** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`,
28
29
  `--strip-stub-docs`) remove
@@ -141,7 +142,7 @@ byte-for-byte. The normal gate applies.
141
142
 
142
143
  ### Opt-in: structural repairs
143
144
 
144
- Twenty-four repairs go past well-formedness and therefore require their own flag; none is ever
145
+ Twenty-five repairs go past well-formedness and therefore require their own flag; none is ever
145
146
  part of the default pipeline:
146
147
 
147
148
  - **`--fix-empty-body`**: `&nbsp;` inside a strictly empty `<body></body>` ("body
@@ -263,9 +264,15 @@ touched.
263
264
  - **`--fix-media-types`**: normalize wrong manifest `media-type` declarations (OPF-029: a
264
265
  file's bytes do not match the declared type). The expected type comes from the extension, and
265
266
  the rewrite fires only when the file's magic bytes at offset 0 confirm the extension (jpg,
266
- jpeg, png, gif): a PNG renamed `.jpg` keeps its wrong-but-consistent declaration rather than
267
- gaining a worse one. Attribute-only, quote-style preserved; files absent from the archive
268
- belong to `--prune-missing-resources`.
267
+ jpeg, png, gif; since v0.56.0 also the CSS-007 font slice: `ttf`/`otf`/`woff`/`woff2`
268
+ declared outside epubcheck's blessed font set are rewritten to their `font/*` spellings
269
+ when the magic bytes confirm the extension -- `font/*` is blessed on both package
270
+ versions, so no version gate is needed; `.eot` is never touched, epubcheck rejects EOT
271
+ as a font src however it is declared): a PNG renamed `.jpg` keeps its
272
+ wrong-but-consistent declaration rather than gaining a worse one. Attribute-only,
273
+ quote-style preserved; files absent from the archive belong to
274
+ `--prune-missing-resources`. The font half's gain sits on the INFO axis the counts do
275
+ not measure, so the flag is accepted under the `no_worse` bar (v0.56.0).
269
276
 
270
277
  - **`--fix-cover`**: repair dangling EPUB2 cover wiring (the cover-wiring ruling's
271
278
  deterministic half). A `<meta name="cover" content="X">` whose `X` names no manifest id is
@@ -276,6 +283,17 @@ file is absent: that class belongs to `--prune-missing-resources` and its edge c
276
283
  The EPUB3 `properties="cover-image"` slice is audit-only by ruling. Cover wiring is invisible
277
284
  to epubcheck, so cover-only repairs are accepted under the `no_worse` bar the lossy strips
278
285
  use, with the `partial` rule intact.
286
+ - **`--fix-unique-identifier`**: wire the OPF-030 dangling unique-identifier (v0.56.0, the
287
+ census lane's recipe): when `<package unique-identifier="X">` names an id no element
288
+ carries (the dominant family: identifiers that lost their id attributes wholesale), the id
289
+ X is written onto the first `dc:identifier` start tag. The dc: values are never touched,
290
+ and the repair predicts the post-wiring uid for the always-on NCX sync (the broken wiring
291
+ was masking the dtb:uid comparison; one run wires the OPF and aligns the NCX instead of
292
+ surfacing NCX-001 for a second run -- the issue #9 masking pattern, unmasked direction).
293
+ Refuses to guess: an absent or empty attribute, a non-NCName id, an already-wired OPF, no
294
+ `dc:identifier` element, or a first identifier that already carries an id. The multi-OPF
295
+ leftovers whose failing OPF is a stale non-rootfile are unreachable by construction
296
+ (only the located rootfile is repaired).
279
297
  - **`--fix-comment-double-hyphen`**: replace `--` inside XML comments with an en-dash
280
298
  (RSC-016: "The string `--` is not permitted within comments", a fatal: the book parses in
281
299
  lenient readers and never passes epubcheck). The edit is confined to comment bodies:
@@ -340,28 +358,32 @@ use, with the `partial` rule intact.
340
358
  quote before the next `<` (a real multi-line value closes quote-first), and only
341
359
  double-quoted values are judged. It runs before the other tag-shape readers, which an
342
360
  open value otherwise lies to.
343
- - **`--fix-unbound-prefix`**: bind an attribute prefix the OPF never declares inline on
344
- the element that uses it (the Calibre embed scar, issue #9: one dc: element carries
345
- `ns0:scheme` while the `xmlns:ns0` declaration sits on a sibling, out of XML scope;
346
- the RSC-016 "prefix is not bound" fatals make the whole package unparseable, which
347
- also costs OPF-030 on the unique-identifier and masks the NCX-001 comparison). The
348
- declaration is inserted on the user, the shape the file's own healthy siblings
349
- already use. The URI is evidence-based, never guessed: the same prefix declared
350
- elsewhere in the document with every declaration agreeing, or the OPF namespace for
351
- a Dublin Core element under an OPF-namespaced package (the canonical EPUB 2
352
- `opf:scheme` shape); anything else refuses the document untouched. Scope is tracked
361
+ - **`--fix-unbound-prefix`**: bind a prefix the OPF never declares in scope inline on
362
+ the element that uses it (the Calibre embed scar: issue #9's attribute half, one dc:
363
+ element carrying `ns0:scheme` while the `xmlns:ns0` declaration sits on a sibling, out
364
+ of XML scope; and issue #22's element half, a later writer build self-declaring
365
+ `xmlns:dc` on every dc: element but one, so that element's own name dies with the
366
+ RSC-016 "prefix is not bound" fatal). Either scar makes the whole package
367
+ unparseable, which also costs OPF-030 on the unique-identifier and masks the NCX-001
368
+ comparison. The declaration is inserted on the user (element name or attribute
369
+ alike), the shape the file's own healthy siblings already use. The URI is
370
+ evidence-based, never guessed: the same prefix declared elsewhere in the document
371
+ with every declaration agreeing, or the use site's own namespace under an
372
+ OPF-namespaced package (the OPF namespace for a Dublin Core element's attributes,
373
+ the canonical EPUB 2 `opf:scheme` shape; the DC namespace for a literal `dc:` element
374
+ name); anything else refuses the document untouched. Scope is tracked
353
375
  with a lenient element stack over a comment/CDATA-aware tokenizer, so declarations
354
376
  that genuinely cover a use satisfy it without an edit and clean documents are
355
377
  byte-identical. Runs on the OPF only: content documents have the
356
378
  invalid-attribute drop (`--strip-bad-attrs`) for the same defect class.
357
379
 
358
- Twenty-two of the twenty-four are evaluated by the normal `gate`: unlike the lossy strips,
380
+ Twenty-three of the twenty-five are evaluated by the normal `gate`: unlike the lossy strips,
359
381
  their benefit is visible to epubcheck (they clear errors), so a run with no measurable
360
- improvement is a noop and nothing is applied. The two exceptions are `--fix-cover` and
361
- `--encode-url-spaces`, whose gains sit on axes epubcheck does not measure (cover
362
- wiring is not a schema finding; the rename half's PKG-010 gain sits on the warning
363
- axis): both are accepted under the same `no_worse` bar the lossy strips use, with
364
- the partial rule intact. CDATA sections are never rewritten
382
+ improvement is a noop and nothing is applied. The three exceptions are `--fix-cover`, `--encode-url-spaces`, and
383
+ `--fix-media-types` (whose gains sit on axes epubcheck's counts do not measure:
384
+ cover wiring is not a schema finding; the rename half's PKG-010 gain sits on the
385
+ warning axis; the font half's CSS-007 gain sits on the INFO axis): all are accepted
386
+ under the same `no_worse` bar the lossy strips use, with the partial rule intact. CDATA sections are never rewritten
365
387
  anywhere; comment bodies only by the double-hyphen fix above, and nothing else inside
366
388
  them.
367
389
 
@@ -438,6 +460,17 @@ be run or its output cannot be parsed during a validated run, the book is an `er
438
460
  the gate has not accepted anything, so nothing is applied or written. With
439
461
  `--no-validate`, the gate is skipped and repairs are trusted on the RepairReport alone.
440
462
 
463
+ One reporting rule rides on the noop verdict: the masked-axis reclassification. A
464
+ `noop` on a book that started fatal means the fix fired and the count did not move,
465
+ and with fatals still standing epubcheck's per-file halt hides whatever the fix
466
+ actually cleared below the halt: the dtb:uid comparison (issue #9, where the rule
467
+ was first scoped to the NCX sync), a cleared error axis, or a second latent fatal
468
+ unmasked by the fix that cleared the first (issue #22's embed scar:
469
+ `unbound_prefixes_bound` fired, `1f/1e -> 1f/0e`, fatals read 1 -> 1). Real,
470
+ unmeasurable work on a book that still will not open is `partial`, never a silent
471
+ `equal`: partial lands the book on the manual list. Application behavior is
472
+ unchanged (still-fatal candidates are never auto-applied).
473
+
441
474
  One structural veto rides above the count gate: the spine-resolution check. The
442
475
  message count is not spine-aware, so a repair that orphans live itemrefs (manifest
443
476
  items pruned whose files the archive still carries, idrefs rewritten to forms that
@@ -11,7 +11,7 @@ Calibre plugin built from this core.
11
11
  Single source of truth for the version. pyproject.toml must match VERSION below.
12
12
  """
13
13
 
14
- VERSION = "0.55.0"
14
+ VERSION = "0.57.0"
15
15
  __version__ = VERSION
16
16
 
17
17
  from .epub import RepairReport, repair_epub # noqa: E402
@@ -107,6 +107,7 @@ def _flags_from_args(args: argparse.Namespace) -> RepairFlags:
107
107
  stray_close=args.fix_stray_close or all_,
108
108
  unterminated_attr=args.fix_unterminated_attr or all_,
109
109
  unbound_prefix=args.fix_unbound_prefix or all_,
110
+ unique_identifier=args.fix_unique_identifier or all_,
110
111
  )
111
112
 
112
113
 
@@ -176,15 +177,21 @@ def process_book(
176
177
  watermark_refusals=report.watermark_refusals,
177
178
  )
178
179
  verdict = gate(before, after)
179
- if verdict == "noop" and report.ncx_uid_synced and before.fatals > 0:
180
- # The NCX-001 axis was masked in both measurements (issue #9): a fatal
181
- # in the package halts the metadata checks, so epubcheck never compared
182
- # dtb:uid to the unique-identifier, and the sync that really fixed it
183
- # measures as no gain. The sync is semantics-preserving by construction
184
- # (it writes only a differing dtb:uid content value), so the verdict
185
- # stops calling real work gainless: partial, with the still-fatal rule
186
- # intact (the library sweep still refuses to apply it; the single-file
187
- # verb still writes it under the PARTIAL label when given a DST).
180
+ if verdict == "noop" and before.fatals > 0:
181
+ # The masked-axis rule. v0.51.0 (issue #9) named it for the NCX uid
182
+ # sync; v0.57.0 (issue #22) generalizes it to every fired fix. A
183
+ # still-fatal package keeps epubcheck's per-file halt, so any gain
184
+ # living below the halt — the dtb:uid comparison, a cleared error
185
+ # axis, a second latent fatal unmasked by the fix that cleared the
186
+ # first (the Hackers dc:date scar: unbound_prefixes_bound fired,
187
+ # 1f/1e -> 1f/0e, fatals read 1 -> 1) — measures as no gain. The
188
+ # honest verdict for real, unmeasurable work on a book that still
189
+ # will not open is partial, never equal: partial lands the book on
190
+ # the manual list (the sweep's still_fatal set) instead of vanishing
191
+ # into a silent skip. Application behavior is unchanged: still-fatal
192
+ # books are never auto-applied, and the gate's own partial/reject
193
+ # answers (fatals reduced, or a regression) never enter this branch
194
+ # (gate noop with fatals before implies fatals after).
188
195
  verdict = "partial"
189
196
  if (
190
197
  report.fixes.get("stripped_pagination")
@@ -217,6 +224,21 @@ def process_book(
217
224
  verdict = "partial"
218
225
  else:
219
226
  verdict = "accept"
227
+ if report.fixes.get("media_types_normalized"):
228
+ # v0.56.0: the font half of --fix-media-types clears CSS-007, an INFO
229
+ # finding the error/warning counts do not measure, so a font-only
230
+ # repair answers 'equal' from the improvement gate. The
231
+ # magic-byte-confirmed normalization is worth having regardless (the
232
+ # cover-wiring ruling's shape): same no_worse bar, partial rule
233
+ # intact. The OPF-029 error slice still measures a real decrease and
234
+ # accepts through the normal gate; this promotion only stops an
235
+ # INFO-only or mixed-equal repair from reading as gainless.
236
+ if not no_worse(before, after):
237
+ verdict = "reject"
238
+ elif after.fatals > 0:
239
+ verdict = "partial"
240
+ else:
241
+ verdict = "accept"
220
242
  if report.fixes.get("entries_renamed"):
221
243
  # The rename half's gain sits on epubcheck's WARNING axis
222
244
  # (PKG-010 space-in-filename advisories), which the improvement
@@ -1826,10 +1848,16 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
1826
1848
  "fix_media_types",
1827
1849
  "normalize wrong manifest media-types (magic-byte confirmed)",
1828
1850
  "normalize wrong manifest media-type declarations (OPF-029, e.g. a "
1829
- "jpg stamped image/png by an aggregator). Attribute-only and "
1851
+ "jpg stamped image/png by an aggregator; since v0.56.0 also the "
1852
+ "CSS-007 font slice: a ttf/otf/woff/woff2 declared outside "
1853
+ "epubcheck's blessed font set, rewritten to its font/* spelling "
1854
+ "when the magic bytes confirm the extension). Attribute-only and "
1830
1855
  "quote-preserving; it fires only when the file's magic bytes "
1831
1856
  "confirm the extension, so a misnamed-but-consistent file is never "
1832
- "made worse.",
1857
+ "made worse (.eot is never touched: epubcheck rejects EOT as a "
1858
+ "font src however it is declared). Accepted under the no-worse "
1859
+ "bar: the font half's gain sits on the INFO axis the counts do "
1860
+ "not measure.",
1833
1861
  ),
1834
1862
  (
1835
1863
  "declare_missing_items",
@@ -1843,6 +1871,18 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
1843
1871
  "An itemref with no manifest item is deliberately not repaired: "
1844
1872
  "which file it meant is underdetermined.",
1845
1873
  ),
1874
+ (
1875
+ "fix_unique_identifier",
1876
+ "wire the dangling OPF unique-identifier onto the first dc:identifier (OPF-030)",
1877
+ "add the id the package's unique-identifier attribute names to the "
1878
+ "first dc:identifier start tag when no element carries it (OPF-030 "
1879
+ "'The unique-identifier X was not found'; the census's dominant "
1880
+ "family is identifiers that lost their id attributes wholesale). "
1881
+ "Writes only the id the package itself names; the dc: values are "
1882
+ "never touched. Refuses to guess: an absent or empty attribute, a "
1883
+ "non-NCName id, an already-wired OPF, no dc:identifier element, or "
1884
+ "a first identifier that already carries an id.",
1885
+ ),
1846
1886
  (
1847
1887
  "fix_cover",
1848
1888
  "re-point or remove a dangling EPUB2 cover meta (no-worse bar)",
@@ -1866,18 +1906,22 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
1866
1906
  ),
1867
1907
  (
1868
1908
  "fix_unbound_prefix",
1869
- "bind an undeclared attribute prefix inline (Calibre embed scar)",
1870
- "bind an attribute prefix the OPF never declares inline on the "
1909
+ "bind an undeclared namespace prefix inline (Calibre embed scar)",
1910
+ "bind a prefix the OPF never declares in scope inline on the "
1871
1911
  "element that uses it (RSC-016 'prefix is not bound'): calibre's "
1872
1912
  "embed_metadata writer can leave one dc: element carrying "
1873
1913
  "ns0:scheme while the xmlns declaration sits on a sibling, out of "
1874
- "XML scope, which fatals the whole package (plus OPF-030 on the "
1914
+ "XML scope, and a later writer build leaves one dc: element's own "
1915
+ "name unbound the same way (every dc: element self-declares "
1916
+ "xmlns:dc except one, so <dc:date> dies with RSC-016); either "
1917
+ "scar fatals the whole package (plus OPF-030 on the "
1875
1918
  "unique-identifier). The URI is evidence-based, never guessed: "
1876
- "the same prefix declared elsewhere in the document, or the OPF "
1877
- "namespace for a Dublin Core element under an OPF-namespaced "
1878
- "package; anything else refuses the document untouched. Content "
1879
- "documents are not touched (their unbound prefixes have the "
1880
- "--strip-bad-attrs drop).",
1919
+ "the same prefix declared elsewhere in the document, or the use "
1920
+ "site's own namespace under an OPF-namespaced package (the OPF "
1921
+ "namespace for a Dublin Core element's attributes, the DC "
1922
+ "namespace for a dc: element name); anything else refuses the "
1923
+ "document untouched. Content documents are not touched (their "
1924
+ "unbound prefixes have the --strip-bad-attrs drop).",
1881
1925
  ),
1882
1926
  ],
1883
1927
  "lossy strips (these delete converter-injected content; accepted on a no-worse bar)": [