bindery-cli 0.50.0__tar.gz → 0.51.0__tar.gz

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/AGENTS.md

@@ -30,7 +30,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
   `xmlns`, bare `&`, named entities, void self-closing), the NCX pipeline, and the
   mimetype fix (added/normalized/first-stored, epub.py's archive rewrite); every core
   fix must render identically to the author's intent: never add, remove, or reorder
-  visible content. The canonical opt-in inventory lives in spec.md: twenty-one structural
+  visible content. The canonical opt-in inventory lives in spec.md: twenty-two structural
   repairs, four lossy strips, four safe opt-ins, plus `--reserialize`.
   * **Structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
     `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
@@ -38,7 +38,8 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
     `--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`,
     `--fix-container`, `--fix-media-types`, `--fix-cover`,
     `--fix-comment-double-hyphen`, `--fix-svg-dup-ids`, `--fix-cdata-terminator`,
-    `--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr`;
+    `--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr`,
+    `--fix-unbound-prefix`;
     transforms.py, threaded through epub.py). The v0.47.0 five (the 2026-10-06
     issue batch): `--fix-svg-dup-ids` renames duplicate glyph ids inside
     standalone `.svg` entries (first keeps its name, references resolve to the
@@ -60,7 +61,15 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
     never percent-encoding (epubcheck decodes references before entry lookup,
     verified against 5.3), ambiguous renames refused per entry (`space_rename_map`),
     accepted under `no_worse` because PKG-010 sits on the warning axis the gate
-    does not measure.
+    does not measure. `--fix-unbound-prefix` (v0.51.0, issue #9, the Calibre
+    embed scar) binds an attribute prefix the OPF never declares inline on the
+    element that uses it (`<dc:identifier id="ID1" ns0:scheme="calibre">`
+    whose `xmlns:ns0` sits on a sibling, out of XML scope; two RSC-016 fatals
+    plus OPF-030): URI evidence is the same prefix declared elsewhere in the
+    document (all declarations must agree) or the OPF namespace for a DC
+    element under an OPF-namespaced package, anything else refuses the whole
+    document; scope-tracked over a comment/CDATA-aware tokenizer, OPF only
+    (content docs have the `--strip-bad-attrs` drop); normal `gate`.
     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`,
@@ -101,7 +110,12 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
   gain IS visible, so a run with no measurable improvement is a noop and nothing is
   applied) except the two whose gains sit on axes epubcheck does not measure:
   `--fix-cover` and `--encode-url-spaces`, accepted under the same `no_worse` bar with
-  the partial rule intact. Changing either bar means re-running the library dry run.
+  the partial rule intact. One masked-axis rule (v0.51.0, issue #9): when the gate
+  answers noop but `report.ncx_uid_synced` fired on a book that started with fatals,
+  `process_book` reclassifies the verdict to `partial` (a fatal package halts the
+  metadata checks, so the dtb:uid comparison never ran in either measurement and the
+  real sync measures as no gain); application behavior is unchanged, since still-fatal
+  books are never 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 format installation goes through cquarry's write module (`--install-to-calibre`;

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.50.0
+Version: 0.51.0
 Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
 Project-URL: Homepage, https://github.com/VirInvictus/bindery-cli
 Project-URL: Repository, https://github.com/VirInvictus/bindery-cli

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/patchnotes.md

@@ -1,5 +1,47 @@
 # bindery-cli Patch Notes
 
+## v0.51.0 (2026-10-17)
+
+### The unbound-prefix repair: the Calibre embed scar comes off the OPF (issue #9)
+
+Century Rain (library book #11104) carried an OPF that repeated
+`calibredb embed_metadata` rounds had scarred: one `dc:identifier`, the package
+unique-identifier itself, carried an `ns0:scheme` attribute whose `xmlns:ns0`
+declaration sat on a sibling element, out of XML scope. epubcheck answered with
+two RSC-016 fatals (unbound prefix) plus OPF-030 (unique-identifier not found),
+and because a fatal package halts the metadata checks, the stale NCX `dtb:uid`
+was invisible to the oracle on both sides of the gate. The old probe report said
+it all: `1f/1e/0w -> 1f/1e/0w, ncx_uid_synced (no measurable gain)`, the ncx
+fix refused with the OPF half.
+
+- **`--fix-unbound-prefix`** (new structural repair, twenty-second) binds an
+  attribute prefix the OPF never declares inline on the element that uses it,
+  the exact shape the file's own healthy siblings already use. The URI is
+  evidence-based, never guessed: the same prefix declared elsewhere in the
+  document (every declaration must agree, or the document is refused), or the
+  OPF namespace for a Dublin Core element under an OPF-namespaced package (the
+  canonical EPUB 2 `opf:scheme` shape); anything else refuses the whole
+  document untouched. Scope tracking walks the document with a
+  comment/CDATA-aware tokenizer over a lenient element stack, so declarations
+  that genuinely cover a use satisfy it without an edit and clean documents
+  are byte-identical. OPF only: content documents already have the
+  invalid-attribute drop (`--strip-bad-attrs`) for this defect class. Normal
+  `gate` (clearing the fatal is the measurable gain). On the fixture:
+  `1f/1e/0w -> 0f/0e/0w`, epubcheck fully clean.
+- **The masked ncx gain** (the issue's second half) stops lying in reports:
+  when the gate answers noop but the NCX uid sync actually fired on a book
+  that started with fatals, `process_book` reclassifies the verdict to
+  `partial` instead of `equal`/`no measurable gain`. The sync is real,
+  deterministic work the oracle could not see; the still-fatal rule is intact,
+  so the library sweep still refuses to apply such a book and the single-file
+  verb still writes it under the honest PARTIAL label when given an explicit
+  destination.
+
+Twenty-seven tests joined the suite (691 total): the transform unit tests
+(scope, evidence, refusal, idempotence), the archive-level e2e, the masked-gain
+verdict rules, tokenizer spin guards beside the other matchers, and the argv
+wiring rows.
+
 ## v0.50.0 (2026-10-14)
 
 ### The contamination analyzer: fan-bundle cosmetics get reported (issue #8)

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.50.0"
+version = "0.51.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.50.0 → bindery_cli-0.51.0}/roadmap.md

@@ -44,6 +44,7 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
 | 0.48 | The AI-probe batch: the enforced closed-Calibre gate on both metadata.db doors (`audit --tag`, `library --apply --install-to-calibre`), the stated contracts (exit codes, no-prompt, NCX-001, --id scoping, json envelope keys), and `--help-json` | v0.48.0 |
 | 0.49 | The probe form (issue #7): single-file repair without an output path runs the gate and writes nothing; writing needs an explicit DST | v0.49.0 |
 | 0.50 | The contamination analyzer (issue #8): foreign-title template stamps, fan-bundle ad signatures, review-paste front matter; advisory by contract, archive-wide corpus (`Book.extra_docs`, capped), and the `_dir_dispatch` map that fixes the v0.44.0 cover/tocdrift ocr misroute in directory/single mode | v0.50.0 |
+| 0.51 | The unbound-prefix repair (issue #9): `--fix-unbound-prefix` binds the Calibre embed scar's undeclared attribute prefix inline (evidence-based URI, scope-tracked, refuse over guess), plus the masked-ncx-gain rule that stops a real dtb:uid sync reading as no measurable gain under a fatal package | v0.51.0 |
 
 ## Open work
 

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/spec.md

@@ -13,14 +13,14 @@ restyle, re-compress, or restructure content, and it does not attempt to fix arb
 schema (RSC-005) violations, which are usually harmless to readers and not safely
 mechanizable.
 
-The deliberate exceptions to "semantics-preserving" come in opt-in groups. The twenty-one
+The deliberate exceptions to "semantics-preserving" come in opt-in groups. The twenty-two
 **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`,
 `--fix-container`, `--fix-media-types`, `--fix-cover`, `--fix-comment-double-hyphen`,
 `--fix-svg-dup-ids`, `--fix-cdata-terminator`, `--fix-misnested-inline`,
-`--fix-stray-close`, `--fix-unterminated-attr`) alter
+`--fix-stray-close`, `--fix-unterminated-attr`, `--fix-unbound-prefix`) alter
 markup structure or fabricate minimal content; the four
 **lossy modes** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`,
 `--strip-stub-docs`) remove
@@ -280,8 +280,22 @@ use, with the `partial` rule intact.
   quote before the next `<` (a real multi-line value closes quote-first), and only
   double-quoted values are judged. It runs before the other tag-shape readers, which an
   open value otherwise lies to.
-
-Nineteen of the twenty-one are evaluated by the normal `gate`: unlike the lossy strips,
+- **`--fix-unbound-prefix`**: bind an attribute prefix the OPF never declares inline on
+  the element that uses it (the Calibre embed scar, issue #9: one dc: element carries
+  `ns0:scheme` while the `xmlns:ns0` declaration sits on a sibling, out of XML scope;
+  the RSC-016 "prefix is not bound" fatals make the whole package unparseable, which
+  also costs OPF-030 on the unique-identifier and masks the NCX-001 comparison). The
+  declaration is inserted on the user, the shape the file's own healthy siblings
+  already use. The URI is evidence-based, never guessed: the same prefix declared
+  elsewhere in the document with every declaration agreeing, or the OPF namespace for
+  a Dublin Core element under an OPF-namespaced package (the canonical EPUB 2
+  `opf:scheme` shape); anything else refuses the document untouched. Scope is tracked
+  with a lenient element stack over a comment/CDATA-aware tokenizer, so declarations
+  that genuinely cover a use satisfy it without an edit and clean documents are
+  byte-identical. Runs on the OPF only: content documents have the
+  invalid-attribute drop (`--strip-bad-attrs`) for the same defect class.
+
+Twenty of the twenty-two 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. The two exceptions are `--fix-cover` and
 `--encode-url-spaces`, whose gains sit on axes epubcheck does not measure (cover

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/src/bindery/__init__.py

@@ -11,7 +11,7 @@ Calibre plugin built from this core.
 Single source of truth for the version. pyproject.toml must match VERSION below.
 """
 
-VERSION = "0.50.0"
+VERSION = "0.51.0"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/src/bindery/cli.py

@@ -102,6 +102,7 @@ def _flags_from_args(args: argparse.Namespace) -> RepairFlags:
         misnested_inline=args.fix_misnested_inline or all_,
         stray_close=args.fix_stray_close or all_,
         unterminated_attr=args.fix_unterminated_attr or all_,
+        unbound_prefix=args.fix_unbound_prefix or all_,
     )
 
 
@@ -159,6 +160,16 @@ def process_book(
             watermark_refusals=report.watermark_refusals,
         )
     verdict = gate(before, after)
+    if verdict == "noop" and report.ncx_uid_synced and before.fatals > 0:
+        # The NCX-001 axis was masked in both measurements (issue #9): a fatal
+        # in the package halts the metadata checks, so epubcheck never compared
+        # dtb:uid to the unique-identifier, and the sync that really fixed it
+        # measures as no gain. The sync is semantics-preserving by construction
+        # (it writes only a differing dtb:uid content value), so the verdict
+        # stops calling real work gainless: partial, with the still-fatal rule
+        # intact (the library sweep still refuses to apply it; the single-file
+        # verb still writes it under the PARTIAL label when given a DST).
+        verdict = "partial"
     if (
         report.fixes.get("stripped_pagination")
         or report.fixes.get("stripped_broken_tags")
@@ -1136,7 +1147,9 @@ def _phase1_decisions(books: list[dict], apply: bool) -> list[dict]:
                         f"{len(pending)} book(s) have gate-accepted repairs "
                         f"pending ({len(watermarked)} watermarked); this run "
                         "was read-only. Re-run with --apply-lossy to record "
-                        "the lossy-strip consent and apply."
+                        "the lossy-strip consent and apply. A book still "
+                        "carrying fatals stays unapplied until its fatal is "
+                        "fixed: the sweep never applies a still-fatal book."
                     ),
                     "books": sorted(set(pending + watermarked)),
                 }
@@ -1777,6 +1790,21 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
             "stays inside the comment bodies: text nodes and CDATA sections are "
             "never touched, and each comment's terminator is left intact.",
         ),
+        (
+            "fix_unbound_prefix",
+            "bind an undeclared attribute prefix inline (Calibre embed scar)",
+            "bind an attribute prefix the OPF never declares inline on the "
+            "element that uses it (RSC-016 'prefix is not bound'): calibre's "
+            "embed_metadata writer can leave one dc: element carrying "
+            "ns0:scheme while the xmlns declaration sits on a sibling, out of "
+            "XML scope, which fatals the whole package (plus OPF-030 on the "
+            "unique-identifier). The URI is evidence-based, never guessed: "
+            "the same prefix declared elsewhere in the document, or the OPF "
+            "namespace for a Dublin Core element under an OPF-namespaced "
+            "package; anything else refuses the document untouched. Content "
+            "documents are not touched (their unbound prefixes have the "
+            "--strip-bad-attrs drop).",
+        ),
     ],
     "lossy strips (these delete converter-injected content; accepted on a no-worse bar)": [
         (

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/src/bindery/epub.py

@@ -44,6 +44,7 @@ from .transforms import (
     fix_ncx_src_fragments,
     fix_stray_close,
     fix_svg_dup_ids,
+    fix_unbound_prefixes,
     fix_unterminated_attr,
     outside_protected_map,
     strip_attrs_in_start_tags,
@@ -284,6 +285,7 @@ class RepairFlags:
     misnested_inline: bool = False
     stray_close: bool = False
     unterminated_attr: bool = False
+    unbound_prefix: bool = False
 
 
 @dataclass
@@ -1478,6 +1480,15 @@ def repair_epub(
     own `>` (`<p class="footnote>` -> `<p class="footnote">`; the RSC-016
     'must not contain the < character' fatal). It runs before the tag-shape
     readers, which an open value otherwise lies to.
+    With `unbound_prefix`, bind an attribute prefix the OPF never declares
+    inline on the element that uses it (the Calibre embed scar: one dc:
+    element carries `ns0:scheme` while the xmlns declaration sits on a
+    sibling, out of scope; two RSC-016 fatals plus OPF-030 on the
+    unique-identifier). The URI is evidence-based: the same prefix declared
+    elsewhere in the document, or the OPF namespace for a Dublin Core element
+    under an OPF-namespaced package; anything else refuses the whole
+    document. Content documents are not touched (their unbound prefixes have
+    the --strip-bad-attrs drop).
     With `strip_stub_docs` (lossy, the no_worse bar), drop spine documents whose
     entire visible text is one identical short placeholder repeated across the
     spine (the Bookmate/DRM-sample export whose chapters are all the same
@@ -1835,8 +1846,17 @@ def repair_epub(
                 or flags.fix_cover
                 or flags.comment_double_hyphens
                 or flags.strip_stub_docs
+                or flags.unbound_prefix
             ):
                 opf_changed = False
+                if flags.unbound_prefix:
+                    # First in the branch: the unbound prefix makes the whole
+                    # package unparseable, so the parseability scar comes off
+                    # before the readers that match against the text.
+                    text, n = fix_unbound_prefixes(text)
+                    if n:
+                        report.add({"unbound_prefixes_bound": n})
+                        opf_changed = True
                 if flags.fix_ids:
                     text, n = fix_manifest_ids(text)
                     if n:

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/src/bindery/transforms.py

@@ -991,6 +991,166 @@ def fix_unterminated_attr(s: str) -> tuple[str, int]:
     return _UNTERMINATED_ATTR_RE.sub(repl, s), count
 
 
+# --fix-unbound-prefix (issue #9). One tokenizer walks the whole document so
+# prefix scope can be tracked: comments, CDATA sections, PIs, and doctypes are
+# consumed as opaque tokens (markup-looking text inside them must never touch
+# the element stack), end tags and start tags carry their names. The
+# quote-aware loops are possessive per the house convention: the three
+# branches are mutually exclusive, so a failing candidate fails linearly.
+_OPF_TOKEN_RE = re.compile(
+    r"""<!--(?:(?!-->).)*+-->"""
+    r"""|<!\[CDATA\[(?:(?!\]\]>).)*+\]\]>"""
+    r"""|<\?(?:(?!\?>).)*+\?>"""
+    r"""|<![^>]*+>"""
+    r"""|</([A-Za-z_][\w.:-]*)((?:"[^"]*+"|'[^']*+'|[^>"'])*+)>"""
+    r"""|<([A-Za-z_][\w.:-]*)((?:"[^"]*+"|'[^']*+'|[^>"'])*+)>"""
+)
+# Any quoted attribute (declarations and uses alike); group 3 is the value
+# exactly as spelled in the document, re-emitted verbatim when binding.
+_OPF_ATTR_RE = re.compile(r"""([A-Za-z_][\w.:-]*)\s*=\s*(["'])((?:(?!\2).)*+)\2""")
+_OPF_NS = "http://www.idpf.org/2007/opf"
+_DC_NS = "http://purl.org/dc/elements/1.1/"
+# Pre-bound in every XML document; never candidates for binding.
+_PREBOUND_PREFIXES = frozenset({"xml", "xmlns"})
+
+
+def _unescape_attr(v: str) -> str:
+    """The five predefined XML entities, the only escapes a namespace URI
+    could legitimately carry."""
+    for ent, ch in (("&lt;", "<"), ("&gt;", ">"), ("&quot;", '"'), ("&apos;", "'")):
+        v = v.replace(ent, ch)
+    return v.replace("&amp;", "&")
+
+
+def fix_unbound_prefixes(opf: str) -> tuple[str, int]:
+    """Bind an undeclared namespace prefix inline on each element that uses it.
+
+    Calibre's embed_metadata writer has been observed to leave one dc: element
+    carrying an attribute prefix (``ns0:scheme``) whose xmlns declaration never
+    made it into the document: the declaration sits on a sibling, and XML scope
+    ends at the sibling's end tag. The unparseable package costs every
+    downstream check (two RSC-016 fatals plus OPF-030 on the
+    unique-identifier). The repair is the shape the file's own healthy
+    siblings already use: declare the prefix on the element that uses it.
+
+    The URI is evidence-based, never guessed: (1) the same prefix declared
+    elsewhere in the document, every declaration agreeing on one URI; (2) the
+    prefix declared nowhere, but the carrying element is Dublin Core (its
+    element prefix resolves to the DC namespace, or the literal ``dc:``
+    spelling when that is itself unbound) and the package element declares the
+    OPF namespace, the canonical EPUB 2 ``opf:scheme``/``opf:role`` shape
+    calibre's writer emits; (3) anything else refuses the whole document (an
+    invented URI would be a guess, and a half-bound package is still fatal, so
+    a partial fix would buy nothing). Declarations scoped to an ancestor (or
+    to the element itself) satisfy the check without an edit, so clean
+    documents are byte-identical.
+
+    Opt-in (--fix-unbound-prefix). Runs on the OPF only: content documents
+    have the invalid-attribute drop (--strip-bad-attrs) for the same defect
+    class.
+    """
+    # Document-wide declaration evidence, prefix -> the URIs it is bound to.
+    # Scanned over start-tag tokens only: a raw scan would also read
+    # commented-out or prose-mentioned xmlns spellings, and a junk URI that
+    # exists only inside a comment must never become binding evidence (nor
+    # poison the agreement check against a real declaration).
+    decl_uris: dict[str, set[str]] = {}
+    for m in _OPF_TOKEN_RE.finditer(opf):
+        if m.group(3) is None:
+            continue
+        for am in _OPF_ATTR_RE.finditer(m.group(4)):
+            name = am.group(1)
+            if name.startswith("xmlns:"):
+                decl_uris.setdefault(name[len("xmlns:") :], set()).add(am.group(3))
+
+    scope: list[tuple[str, dict[str, str]]] = []
+    edits: list[tuple[int, str]] = []
+    count = 0
+    pkg_ns = False
+    pkg_seen = False
+
+    for m in _OPF_TOKEN_RE.finditer(opf):
+        if m.group(3) is None:
+            if m.group(1) is None:
+                continue  # comment / CDATA / PI / doctype: opaque
+            # End tag: pop to the matching start; a stray end tag with no
+            # open element pops nothing. Mismatched nesting pops through
+            # intermediate levels, which can only ever cause a redundant
+            # inline re-declaration of a prefix that was still in scope,
+            # never a semantic change: the evidence URI is document-wide,
+            # so it equals whatever the dropped scope held.
+            ename = m.group(1)
+            for i in range(len(scope) - 1, -1, -1):
+                if scope[i][0] == ename:
+                    del scope[i:]
+                    break
+            continue
+
+        name, body = m.group(3), m.group(4)
+        # The possessive body loop always swallows a self-closing slash (the
+        # [^>"'] catch-all is disjoint from `>` but not from `/`), so
+        # self-closing is read off the body, never a group.
+        slash = body.rstrip().endswith("/")
+        decls: dict[str, str] = {}
+        attr_names: list[str] = []
+        default_uri = None
+        for am in _OPF_ATTR_RE.finditer(body):
+            aname = am.group(1)
+            if aname == "xmlns":
+                default_uri = am.group(3)
+            elif aname.startswith("xmlns:"):
+                decls[aname[len("xmlns:") :]] = am.group(3)
+            else:
+                attr_names.append(aname)
+        if not pkg_seen and name.split(":")[-1] == "package":
+            pkg_seen = True
+            pkg_ns = any(
+                u == _OPF_NS or _unescape_attr(u) == _OPF_NS
+                for u in (default_uri, *decls.values())
+                if u
+            )
+        # Push before the attribute check: the element's own declarations
+        # apply to its own attributes.
+        scope.append((name, decls))
+        binds: list[str] = []
+        for aname in attr_names:
+            prefix, sep, _ = aname.partition(":")
+            if not sep or prefix in _PREBOUND_PREFIXES:
+                continue
+            if any(prefix in d for _, d in scope):
+                continue
+            uris = decl_uris.get(prefix)
+            if uris is not None:
+                if len(uris) != 1:
+                    return opf, 0  # one prefix, two URIs: intent unreadable
+                uri = next(iter(uris))
+            else:
+                elem_prefix, _, _ = name.partition(":")
+                elem_ns = None
+                for _, d in reversed(scope):
+                    if elem_prefix in d:
+                        elem_ns = d[elem_prefix]
+                        break
+                if pkg_ns and (
+                    elem_ns == _DC_NS or (elem_ns is None and elem_prefix == "dc")
+                ):
+                    uri = _OPF_NS
+                else:
+                    return opf, 0  # no evidence: refuse the whole document
+            binds.append(f' xmlns:{prefix}="{uri}"')
+        if binds:
+            # Insert directly after the element name, the position the
+            # file's own healthy inline declarations occupy.
+            edits.append((m.start(4), "".join(binds)))
+            count += len(binds)
+        if slash:
+            scope.pop()
+
+    for at, text in reversed(edits):
+        opf = opf[:at] + text + opf[at:]
+    return opf, count
+
+
 # The always-on core for full (X)HTML content documents, in order: prolog and
 # root-tag fixes first, then ampersand/entity normalization, then void
 # self-closing. Exactly the five semantics-preserving well-formedness fixes the

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/tests/test_cli.py

@@ -1868,6 +1868,48 @@ class TestStripStubDocsGate(unittest.TestCase):
         self.assertEqual(o.status, "reject")
 
 
+class TestMaskedNcxUidGain(unittest.TestCase):
+    """Issue #9, the gate's masked axis: a fatal package halts the metadata
+    checks, so epubcheck never compares dtb:uid to the unique-identifier and
+    a real NCX uid sync measures as no gain. A noop verdict that carries a
+    sync on a book that started with fatals is reclassified partial: real
+    work the oracle could not see, still-fatal rules intact."""
+
+    def _verdict(self, before, after, report):
+        with (
+            mock.patch("bindery.cli.repair_epub", return_value=report),
+            mock.patch("bindery.cli.run_epubcheck", side_effect=[before, after]),
+        ):
+            return process_book(Path("x.epub"), Path("."), validate=True)
+
+    def test_masked_sync_is_partial_not_equal(self):
+        report = RepairReport(ncx_uid_synced=True)
+        o = self._verdict(CheckResult(2, 1, 0), CheckResult(2, 1, 0), report)
+        self.assertEqual(o.status, "partial")
+        self.assertNotIn("no measurable gain", o.summary)
+        self.assertIn("ncx_uid_synced", o.summary)
+
+    def test_sync_without_fatals_stays_gate_measured(self):
+        # A parseable package lets epubcheck see the NCX axis; a noop there
+        # means the sync bought nothing epubcheck measures.
+        report = RepairReport(ncx_uid_synced=True)
+        o = self._verdict(CheckResult(0, 0, 0), CheckResult(0, 0, 0), report)
+        self.assertEqual(o.status, "equal")
+        self.assertIn("no measurable gain", o.summary)
+
+    def test_masked_sync_fatals_reduced_stays_partial(self):
+        # The gate itself answers partial when fatals merely dropped; the
+        # reclassification must not downgrade a better verdict.
+        report = RepairReport(ncx_uid_synced=True)
+        o = self._verdict(CheckResult(2, 1, 0), CheckResult(1, 1, 0), report)
+        self.assertEqual(o.status, "partial")
+
+    def test_reject_never_reclassified(self):
+        report = RepairReport(ncx_uid_synced=True)
+        o = self._verdict(CheckResult(1, 0, 0), CheckResult(2, 0, 0), report)
+        self.assertEqual(o.status, "reject")
+
+
 class TestHelpLayout(unittest.TestCase):
     """The two-level help contract (the 2026-10-06 restructure): the compact
     --help is grouped with one-line flags and a short usage line, and

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/tests/test_epub.py

@@ -1970,3 +1970,66 @@ class TestStripStubDocs(unittest.TestCase):
             dst = Path(td) / "out.epub"
             report = repair_epub(src, dst, RepairFlags(strip_stub_docs=True))
         self.assertNotIn("stub_docs_dropped", report.fixes)
+
+
+SCARRED_OPF = (
+    '<?xml version="1.0" encoding="UTF-8"?>'
+    '<package xmlns="http://www.idpf.org/2007/opf" unique-identifier="ID1" '
+    'version="2.0">'
+    '<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">'
+    "<dc:title>Century Rain</dc:title>"
+    '<dc:creator xmlns:ns0="http://www.idpf.org/2007/opf" ns0:role="aut">'
+    "Alastair Reynolds</dc:creator>"
+    '<dc:identifier id="ID1" ns0:scheme="calibre">'
+    "fccddb12-6dd3-4896-ab23-c676558ca98b</dc:identifier>"
+    "</metadata>"
+    '<manifest><item id="c1" href="c1.xhtml" '
+    'media-type="application/xhtml+xml"/><item id="ncx" href="toc.ncx" '
+    'media-type="application/x-dtbncx+xml"/></manifest>'
+    '<spine toc="ncx"><itemref idref="c1"/></spine></package>'
+)
+
+
+class TestUnboundPrefix(unittest.TestCase):
+    """Issue #9: the Calibre embed scar. One dc: element carries an
+    ns0:-prefixed attribute whose declaration sits on a sibling, out of XML
+    scope: two RSC-016 fatals plus OPF-030 on the unique-identifier, and the
+    NCX uid sync measures as no gain while the package is unparseable."""
+
+    def _build(self, td: str) -> tuple[Path, Path]:
+        src, dst = Path(td) / "in.epub", Path(td) / "out.epub"
+        with zipfile.ZipFile(src, "w") as z:
+            z.writestr("mimetype", "application/epub+zip")
+            z.writestr("OEBPS/c1.xhtml", CONTENT)
+            z.writestr("OEBPS/toc.ncx", NCX_BAD)
+            z.writestr("OEBPS/content.opf", SCARRED_OPF)
+        return src, dst
+
+    def test_off_by_default(self):
+        with tempfile.TemporaryDirectory() as td:
+            src, dst = self._build(td)
+            report = repair_epub(src, dst)
+        self.assertNotIn("unbound_prefixes_bound", report.fixes)
+
+    def test_scarred_opf_bound_and_ncx_synced(self):
+        with tempfile.TemporaryDirectory() as td:
+            src, dst = self._build(td)
+            self.assertTrue(ncx_uid_mismatch(src))
+            report = repair_epub(src, dst, RepairFlags(unbound_prefix=True))
+            self.assertEqual(report.fixes.get("unbound_prefixes_bound"), 1)
+            self.assertTrue(report.ncx_uid_synced)
+            with zipfile.ZipFile(dst) as z:
+                opf = z.read("OEBPS/content.opf").decode()
+            self.assertIn(
+                '<dc:identifier xmlns:ns0="http://www.idpf.org/2007/opf" '
+                'id="ID1" ns0:scheme="calibre">',
+                opf,
+            )
+            # the healthy sibling is untouched
+            self.assertIn(
+                '<dc:creator xmlns:ns0="http://www.idpf.org/2007/opf" ns0:role="aut">',
+                opf,
+            )
+            # the bound package parses and its unique-identifier resolves
+            ET.fromstring(opf)
+            self.assertFalse(ncx_uid_mismatch(dst))

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/tests/test_flags_real_core.py

@@ -378,6 +378,23 @@ def _fixtures() -> dict:
             },
             "fix_unterminated_attr",
         ),
+        "--fix-unbound-prefix": (
+            {
+                "OEBPS/content.opf": _opf(
+                    [c1],
+                    [r1],
+                    # The Calibre embed scar: ns0 declared on the sibling
+                    # creator only, so the identifier's ns0:scheme is unbound.
+                    meta=(
+                        '<dc:creator xmlns:ns0="http://www.idpf.org/2007/opf" '
+                        'ns0:role="aut">A</dc:creator>'
+                        '<dc:identifier id="id" ns0:scheme="calibre">uuid-x</dc:identifier>'
+                    ),
+                ),
+                "OEBPS/c1.xhtml": plain,
+            },
+            "unbound_prefixes_bound",
+        ),
     }
 
 
@@ -558,6 +575,11 @@ class FlagEndToEndTests(unittest.TestCase):
             self._fixes_for("--fix-unterminated-attr")["fix_unterminated_attr"], 1
         )
 
+    def test_fix_unbound_prefix(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--fix-unbound-prefix")["unbound_prefixes_bound"], 1
+        )
+
 
 if __name__ == "__main__":
     unittest.main()

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/tests/test_flags_wiring.py

@@ -46,6 +46,7 @@ DEST_TO_FIELD = {
     "fix_misnested_inline": "misnested_inline",
     "fix_stray_close": "stray_close",
     "fix_unterminated_attr": "unterminated_attr",
+    "fix_unbound_prefix": "unbound_prefix",
     "strip_pagination": "strip_pagination",
     "strip_broken_tags": "strip_brokentags",
     "strip_watermarks": "strip_watermarks",

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/tests/test_matcher_hardening.py

@@ -120,6 +120,63 @@ class OpfTagMatchersSpin(unittest.TestCase):
         self.assertLess(elapsed, 5.0)
 
 
+class UnboundPrefixTokenizerSpin(unittest.TestCase):
+    """fix_unbound_prefixes' tokenizer (issue #9) walks every OPF it runs
+    on: a scarred document that ends inside an unterminated tag or comment
+    must fail linearly, and its success shapes must carve at real tag
+    boundaries."""
+
+    def test_unterminated_tag_spin_shape(self):
+        from bindery.transforms import fix_unbound_prefixes
+
+        opf = "<package><metadata><dc:identifier ns0:scheme='" + _apostrophe_run(500)
+        signal.alarm(20)
+        try:
+            t0 = time.perf_counter()
+            fix_unbound_prefixes(opf)
+            elapsed = time.perf_counter() - t0
+        finally:
+            signal.alarm(0)
+        self.assertLess(elapsed, 5.0)
+
+    def test_unterminated_comment_spin_shape(self):
+        from bindery.transforms import fix_unbound_prefixes
+
+        opf = "<package><metadata><!-- " + _apostrophe_run(500)
+        signal.alarm(20)
+        try:
+            t0 = time.perf_counter()
+            fix_unbound_prefixes(opf)
+            elapsed = time.perf_counter() - t0
+        finally:
+            signal.alarm(0)
+        self.assertLess(elapsed, 5.0)
+
+    def test_tokenizer_success_shapes(self):
+        tok = transforms._OPF_TOKEN_RE
+        m = tok.search('<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">')
+        self.assertIsNotNone(m)
+        self.assertEqual(m.group(3), "metadata")
+        # a bare attribute-less tag keeps its full name (a mandatory-one-char
+        # body loop would steal the final name character and orphan the
+        # end-tag match)
+        m = tok.search("<metadata>")
+        self.assertEqual((m.group(3), m.group(4)), ("metadata", ""))
+        m = tok.search("</dc:identifier>")
+        self.assertEqual(m.group(1), "dc:identifier")
+        # a `>` inside a quoted attribute stays attribute content; the
+        # self-closing slash lands in the body (the catch-all is disjoint
+        # from `>` but not from `/`), where the transform reads it
+        m = tok.search('<item href="a>b.xhtml"/>')
+        self.assertIsNotNone(m)
+        self.assertTrue(m.group(4).rstrip().endswith("/"))
+        # comments and CDATA are opaque tokens with no tag groups
+        m = tok.search("<!-- <dc:x ns1:y='z'></dc:x> -->")
+        self.assertIsNotNone(m)
+        self.assertIsNone(m.group(1))
+        self.assertIsNone(m.group(3))
+
+
 class LazyMatcherDisjointBranch(unittest.TestCase):
     """The lazy matchers (_VOID_RE, the img/link/a tag matchers) now use a
     disjoint branch 3 ([^>"']): an unterminated quote inside a tag can no

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/tests/test_transforms.py

@@ -24,6 +24,7 @@ from bindery.transforms import (
     fix_ncx_src_fragments,
     fix_stray_close,
     fix_svg_dup_ids,
+    fix_unbound_prefixes,
     fix_unterminated_attr,
     self_close_void,
     strip_broken_tags,
@@ -834,6 +835,189 @@ class TestFixUnterminatedAttr(unittest.TestCase):
         self.assertEqual((twice, n2), (once, 0))
 
 
+def _scarred_opf(scar: str, healthy: str = "") -> str:
+    """The Century Rain shape (issue #9): an EPUB2 package whose OPF
+    namespace is the DEFAULT namespace, a healthy sibling declaring ns0
+    inline, and one scarred element."""
+    return (
+        '<?xml version="1.0" encoding="UTF-8"?>\n'
+        '<package xmlns="http://www.idpf.org/2007/opf" unique-identifier="ID1" '
+        'version="2.0">\n'
+        '  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">\n'
+        f"    {healthy}\n"
+        f"    {scar}\n"
+        "  </metadata>\n"
+        "</package>"
+    )
+
+
+class TestFixUnboundPrefixes(unittest.TestCase):
+    SCAR = '<dc:identifier id="ID1" ns0:scheme="calibre">uuid-x</dc:identifier>'
+    HEALTHY = (
+        '<dc:creator xmlns:ns0="http://www.idpf.org/2007/opf" '
+        'ns0:role="aut">A</dc:creator>'
+    )
+
+    def test_sibling_declaration_bound_inline(self):
+        # The fixture shape: ns0 is declared on the sibling creator, out of
+        # scope for the identifier; the fix declares it on the user.
+        doc = _scarred_opf(self.SCAR, self.HEALTHY)
+        out, n = fix_unbound_prefixes(doc)
+        self.assertEqual(n, 1)
+        self.assertIn(
+            '<dc:identifier xmlns:ns0="http://www.idpf.org/2007/opf" id="ID1" '
+            'ns0:scheme="calibre">',
+            out,
+        )
+        ET.fromstring(out)
+
+    def test_clean_document_byte_identical(self):
+        doc = _scarred_opf(
+            '<dc:identifier id="ID1">uuid-x</dc:identifier>',
+            self.HEALTHY,
+        )
+        out, n = fix_unbound_prefixes(doc)
+        self.assertEqual((out, n), (doc, 0))
+
+    def test_own_declaration_satisfies(self):
+        # An element declaring and using the prefix on itself is legal XML.
+        doc = _scarred_opf(
+            '<dc:identifier id="ID1" xmlns:ns0="http://www.idpf.org/2007/opf" '
+            'ns0:scheme="calibre">u</dc:identifier>',
+            self.HEALTHY,
+        )
+        self.assertEqual(fix_unbound_prefixes(doc), (doc, 0))
+
+    def test_ancestor_declaration_satisfies(self):
+        doc = _scarred_opf(
+            '<dc:identifier id="ID1" opf:scheme="calibre">u</dc:identifier>'
+        ).replace(
+            '<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">',
+            '<metadata xmlns:dc="http://purl.org/dc/elements/1.1/" '
+            'xmlns:opf="http://www.idpf.org/2007/opf">',
+        )
+        self.assertEqual(fix_unbound_prefixes(doc), (doc, 0))
+
+    def test_child_of_declarator_in_scope(self):
+        doc = _scarred_opf(
+            '<wrapper xmlns:ns7="http://www.idpf.org/2007/opf">'
+            '<dc:identifier id="ID1" ns7:scheme="calibre">u</dc:identifier>'
+            "</wrapper>"
+        )
+        self.assertEqual(fix_unbound_prefixes(doc), (doc, 0))
+
+    def test_commented_declaration_is_not_evidence(self):
+        # A commented-out xmlns spelling must never become binding evidence
+        # (the code-reviewer bug): with the only ns0 inside a comment, the
+        # prefix is declared nowhere, so rule 2 binds the OPF namespace on
+        # this DC element, not the junk URI from the comment.
+        doc = _scarred_opf(
+            self.SCAR,
+            '<!-- <dc:creator xmlns:ns0="http://comment.example/ns">X</dc:creator> -->',
+        )
+        out, n = fix_unbound_prefixes(doc)
+        self.assertEqual(n, 1)
+        self.assertIn(
+            '<dc:identifier xmlns:ns0="http://www.idpf.org/2007/opf" id="ID1"',
+            out,
+        )
+        # the comment itself is untouched
+        self.assertIn("comment.example", out)
+
+    def test_comment_conflict_does_not_poison_agreement(self):
+        # The inverse: a comment's conflicting URI must not flip the
+        # agreement check into refusing a fixable document.
+        doc = _scarred_opf(
+            self.SCAR,
+            self.HEALTHY
+            + '<!-- <dc:publisher xmlns:ns0="http://other.example/ns">P</dc:publisher> -->',
+        )
+        out, n = fix_unbound_prefixes(doc)
+        self.assertEqual(n, 1)
+        self.assertIn('xmlns:ns0="http://www.idpf.org/2007/opf"', out)
+
+    def test_foreign_dc_binding_refuses_rule2_fallback(self):
+        # The literal dc: fallback fires only when the dc prefix is itself
+        # unbound; a dc bound to a foreign namespace is not Dublin Core, and
+        # the document is refused untouched.
+        doc = _scarred_opf(
+            '<dc:identifier id="ID1" ns0:scheme="calibre">u</dc:identifier>'
+        ).replace(
+            'xmlns:dc="http://purl.org/dc/elements/1.1/"',
+            'xmlns:dc="http://foreign.example/not-dc"',
+        )
+        self.assertEqual(fix_unbound_prefixes(doc), (doc, 0))
+
+    def test_ambiguous_prefix_refuses_whole_document(self):
+        doc = _scarred_opf(
+            '<dc:identifier id="ID1" ns0:scheme="calibre">u</dc:identifier>',
+            '<dc:creator xmlns:ns0="http://www.idpf.org/2007/opf">A</dc:creator>'
+            '<dc:publisher xmlns:ns0="http://other.example/ns">P</dc:publisher>',
+        )
+        self.assertEqual(fix_unbound_prefixes(doc), (doc, 0))
+
+    def test_no_evidence_not_dc_refuses(self):
+        # An unbound prefix on a non-DC element with no document evidence:
+        # no deterministic URI, so the document is refused untouched.
+        doc = _scarred_opf('<meta ns9:thing="x" name="cover" content="c"/>')
+        self.assertEqual(fix_unbound_prefixes(doc), (doc, 0))
+
+    def test_never_declared_dc_element_gets_opf_ns(self):
+        # Rule 2: the scar with no surviving declaration at all; a Dublin
+        # Core element under an OPF-namespaced package binds the OPF
+        # namespace, the canonical EPUB 2 opf:scheme shape.
+        doc = _scarred_opf(
+            '<dc:identifier id="ID1" ns0:scheme="calibre">u</dc:identifier>'
+        )
+        out, n = fix_unbound_prefixes(doc)
+        self.assertEqual(n, 1)
+        self.assertIn('<dc:identifier xmlns:ns0="http://www.idpf.org/2007/opf"', out)
+        ET.fromstring(out)
+
+    def test_never_declared_without_opf_package_refuses(self):
+        # Rule 2 needs the package itself to carry the OPF namespace.
+        doc = _scarred_opf(
+            '<dc:identifier id="ID1" ns0:scheme="calibre">u</dc:identifier>'
+        ).replace('xmlns="http://www.idpf.org/2007/opf" ', "")
+        self.assertEqual(fix_unbound_prefixes(doc), (doc, 0))
+
+    def test_xml_prefix_never_flagged(self):
+        doc = _scarred_opf('<dc:identifier id="ID1" xml:lang="en">u</dc:identifier>')
+        self.assertEqual(fix_unbound_prefixes(doc), (doc, 0))
+
+    def test_self_closing_element_bound(self):
+        doc = _scarred_opf(f'<dc:rights ns0:r="x"/>{self.SCAR}', self.HEALTHY)
+        out, n = fix_unbound_prefixes(doc)
+        self.assertEqual(n, 2)
+        self.assertIn('xmlns:ns0="http://www.idpf.org/2007/opf"', out)
+        ET.fromstring(out)
+
+    def test_comment_markup_never_touched(self):
+        doc = _scarred_opf(
+            f"{self.SCAR}",
+            self.HEALTHY + '<!-- <dc:x ns1:scheme="nope"></dc:x> -->',
+        )
+        out, n = fix_unbound_prefixes(doc)
+        self.assertEqual(n, 1)
+        self.assertNotIn('xmlns:ns1="http://www.idpf.org/2007/opf" ', out)
+        ET.fromstring(out)
+
+    def test_single_quoted_evidence(self):
+        doc = _scarred_opf(
+            self.SCAR,
+            "<dc:creator xmlns:ns0='http://www.idpf.org/2007/opf'>A</dc:creator>",
+        )
+        out, n = fix_unbound_prefixes(doc)
+        self.assertEqual(n, 1)
+        ET.fromstring(out)
+
+    def test_idempotent(self):
+        doc = _scarred_opf(self.SCAR, self.HEALTHY)
+        once, _ = fix_unbound_prefixes(doc)
+        twice, n2 = fix_unbound_prefixes(once)
+        self.assertEqual((twice, n2), (once, 0))
+
+
 class TestCssProtectedTags(unittest.TestCase):
     def test_element_selector_protects(self):
         self.assertIn("st", css_protected_tags("st { color: red }"))

{bindery_cli-0.50.0 → bindery_cli-0.51.0}/uv.lock

@@ -8,7 +8,7 @@ resolution-markers = [
 
 [[package]]
 name = "bindery-cli"
-version = "0.50.0"
+version = "0.51.0"
 source = { editable = "." }
 dependencies = [
     { name = "cquarry", marker = "python_full_version >= '3.14'" },