openom-core 0.1.0__py3-none-any.whl

openom_core/__init__.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: MIT
+"""openOM deterministic core.
+
+Embed / read / inspect / validate machine-readable, broker-asserted payloads in
+commercial-real-estate offering-memorandum PDFs. Zero inference, ever (CLAUDE.md Rule 1).
+
+The stable public surface is re-exported here, so an integrator writes
+``from openom_core import embed, read, validate, load_schema`` (submodule paths keep working too).
+See the spec Part II §A-§E, §H-§J.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from .canonical import canonicalize, hash_bytes, payload_hash
+from .embed import ReadResult, embed, read, reembed_warnings
+from .errors import CanonicalizationError, Finding, PayloadTooLargeError, Severity
+from .images import ImageManifest, extract_images
+from .inspect import Profile, classify
+from .schema import load_schema
+from .summary import DealSummary, summarize_deal
+from .text import TextResult, extract_text
+from .types import OMPayload, RealEstateListing
+from .validate import Report, Tolerances, validate
+
+try:  # single source of truth: the installed package metadata (matches `pip show` / the wheel)
+    __version__ = _pkg_version("openom-core")
+except PackageNotFoundError:  # editable/source tree without an installed dist
+    __version__ = "0.0.0+unknown"
+
+#: The openOM spec version this library targets. Drift-locked to the schema by tests/test_types.py.
+SPEC_VERSION = "0.1"
+
+__all__ = [
+    "SPEC_VERSION",
+    "__version__",
+    # verbs
+    "embed",
+    "read",
+    "reembed_warnings",
+    "validate",
+    "classify",
+    "extract_text",
+    "extract_images",
+    "canonicalize",
+    "hash_bytes",
+    "payload_hash",
+    "load_schema",
+    "summarize_deal",
+    # result / option types
+    "ReadResult",
+    "Report",
+    "Tolerances",
+    "Profile",
+    "TextResult",
+    "ImageManifest",
+    "DealSummary",
+    "Finding",
+    "Severity",
+    "OMPayload",
+    "RealEstateListing",
+    # errors
+    "CanonicalizationError",
+    "PayloadTooLargeError",
+]

openom_core/canonical.py

@@ -0,0 +1,166 @@
+# SPDX-License-Identifier: MIT
+"""RFC 8785 JSON Canonicalization (JCS) + the openOM integrity hash (spec §C).
+
+The keystone of cross-implementation fidelity: two conformant implementations MUST produce
+byte-identical output here, and therefore the same SHA-256. RFC 8785 itself performs no
+Unicode normalization and assumes unique member names (RFC 8785 §3.1), so §C.1 mandates the
+preprocessing done here (NFC, duplicate-key rejection, number-range checks) *before* JCS.
+Serialization (key sorting, minimal escaping, ES number formatting) is delegated to the
+vetted ``rfc8785`` library.
+
+Producer vs Consumer contract (§C, §D)
+--------------------------------------
+The **producer** normalizes (NFC), canonicalizes, hashes the resulting bytes, and stores
+*those exact bytes* as the payload plus the hash in the XMP marker. The **consumer** hashes
+the stored bytes *as received* - it does NOT re-canonicalize before verifying. Verification
+is therefore a byte comparison of ``sha256(stored_bytes)`` against the marker hash; it never
+depends on the consumer re-running NFC/JCS. This asymmetry is deliberate: normalization
+happens once, at authoring time, so a consumer on a different platform/library cannot perturb
+the hash. ``canonicalize`` is the producer path; ``hash_bytes`` over stored bytes is the
+consumer path (see :func:`openom_core.embed.read`).
+"""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import math
+from collections.abc import Mapping
+from typing import Any
+from unicodedata import normalize
+
+import rfc8785
+
+from .errors import IO_BADUTF8, IO_DUPKEY, IO_NUMRANGE, IO_STRUCTURE, CanonicalizationError
+
+#: ECMAScript safe-integer limit; integers beyond this are silently rounded by the number
+#: model, which would be data corruption (§C [OM-CANON-013]).
+MAX_SAFE_INT = 2**53 - 1
+
+#: Max nesting depth (§J JSON-hardening guard) - matches the JS parser for cross-impl parity.
+MAX_DEPTH = 64
+
+
+def _prepare(obj: Any, depth: int = 0) -> Any:
+    """NFC-normalize strings + member names, reject duplicate keys and non-representable numbers.
+
+    Returns a new structure ready for RFC 8785 serialization. Mutates nothing.
+    """
+    if depth > MAX_DEPTH:
+        raise CanonicalizationError(IO_STRUCTURE, f"nesting exceeds {MAX_DEPTH}")
+    # bool is an int subclass - must be checked first.
+    if isinstance(obj, bool):
+        return obj
+    if isinstance(obj, str):
+        # A lone UTF-16 surrogate cannot be encoded as UTF-8; reject it explicitly with a
+        # stable code rather than letting the serializer raise a bare UnicodeEncodeError.
+        if any(0xD800 <= ord(ch) <= 0xDFFF for ch in obj):
+            raise CanonicalizationError(IO_BADUTF8, "string contains an unpaired surrogate")
+        return normalize("NFC", obj)
+    if isinstance(obj, Mapping):
+        out: dict[str, Any] = {}
+        for key, value in obj.items():
+            if not isinstance(key, str):
+                raise CanonicalizationError(IO_DUPKEY, f"non-string member name: {key!r}")
+            nkey = normalize("NFC", key)
+            if nkey in out:
+                raise CanonicalizationError(IO_DUPKEY, f"duplicate member name after NFC: {nkey!r}")
+            out[nkey] = _prepare(value, depth + 1)
+        return out
+    if isinstance(obj, (list, tuple)):
+        return [_prepare(item, depth + 1) for item in obj]
+    if isinstance(obj, int):
+        if abs(obj) > MAX_SAFE_INT:
+            raise CanonicalizationError(IO_NUMRANGE, f"integer exceeds 2^53-1: {obj}")
+        return obj
+    if isinstance(obj, float):
+        if not math.isfinite(obj):
+            raise CanonicalizationError(IO_NUMRANGE, f"non-finite number: {obj}")
+        if obj.is_integer() and abs(obj) > MAX_SAFE_INT:
+            raise CanonicalizationError(IO_NUMRANGE, f"float integer exceeds 2^53-1: {obj}")
+        return obj
+    if obj is None:
+        return None
+    raise CanonicalizationError(IO_NUMRANGE, f"unsupported JSON type: {type(obj).__name__}")
+
+
+def _reject_duplicate_pairs(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    """json object_pairs_hook: reject duplicate member names (after NFC) rather than last-wins.
+    Preserves the ORIGINAL keys (does not normalize) so a reader returns the payload as stored."""
+    out: dict[str, Any] = {}
+    seen: set[str] = set()
+    for key, value in pairs:
+        nkey = normalize("NFC", key)
+        if nkey in seen:
+            raise CanonicalizationError(IO_DUPKEY, f"duplicate member name after NFC: {nkey!r}")
+        seen.add(nkey)
+        out[key] = value
+    return out
+
+
+def _check_depth(obj: Any, depth: int = 0) -> None:
+    if depth > MAX_DEPTH:
+        raise CanonicalizationError(IO_STRUCTURE, f"nesting exceeds {MAX_DEPTH}")
+    if isinstance(obj, Mapping):
+        for v in obj.values():
+            _check_depth(v, depth + 1)
+    elif isinstance(obj, (list, tuple)):
+        for v in obj:
+            _check_depth(v, depth + 1)
+
+
+def parse_hardened(raw: bytes | str) -> Any:
+    """Parse an om.json payload with the §J read-side hardening the write path enforces
+    ([OM-CANON-009/010]): reject duplicate member names and over-deep nesting. Used by the reusable
+    ``read`` verb so a self-hoster calling core on untrusted PDFs gets the MCP invariants."""
+    obj = json.loads(raw, object_pairs_hook=_reject_duplicate_pairs)
+    _check_depth(obj)
+    return obj
+
+
+def canonicalize(payload: Mapping[str, Any]) -> bytes:
+    """Serialize a payload to its RFC 8785 JCS bytes (UTF-8, no BOM). Producer path.
+
+    Applies the §C.1 preprocessing (NFC, unique keys, number range) then delegates
+    serialization to ``rfc8785``. The top level MUST be a JSON object (§C.10); a bare
+    array/scalar is rejected rather than hashed.
+    """
+    if not isinstance(payload, Mapping):
+        raise CanonicalizationError(
+            IO_STRUCTURE, f"top-level value must be an object, got {type(payload).__name__}"
+        )
+    prepared = _prepare(payload)
+    try:
+        return rfc8785.dumps(prepared)
+    except CanonicalizationError:
+        raise
+    except Exception as exc:  # noqa: BLE001 - normalize any serializer failure to our code
+        raise CanonicalizationError(IO_NUMRANGE, str(exc)) from exc
+
+
+def hash_bytes(data: bytes) -> str:
+    """The openOM integrity hash of already-canonical bytes: ``sha256:<lowercase-hex>``.
+
+    Used on both the write path (over the bytes just produced) and the read/verify path
+    (over the decompressed stored bytes, as received - no re-canonicalization; §C, §D).
+    """
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def strip_signature(payload: Mapping[str, Any]) -> dict[str, Any]:
+    """Return a deep copy with ``meta.signature`` *removed* (not nulled), per [OM-CANON-003].
+
+    In 0.1 the signature is always absent/null, so this is a no-op on real payloads; it exists
+    so that adding a signature in a future version does not change the integrity hash.
+    """
+    out = copy.deepcopy(dict(payload))
+    meta = out.get("meta")
+    if isinstance(meta, dict) and "signature" in meta:
+        meta.pop("signature", None)
+    return out
+
+
+def payload_hash(payload: Mapping[str, Any]) -> str:
+    """Convenience: the integrity hash of a payload object (strip signature → JCS → sha256)."""
+    return hash_bytes(canonicalize(strip_signature(payload)))

openom_core/embed.py

@@ -0,0 +1,437 @@
+# SPDX-License-Identifier: MIT
+"""Embed / read the om.json payload in a PDF via pikepdf (spec §D).
+
+Non-destructive by construction: pikepdf appends the embedded file + XMP marker without
+touching page content. The catalog ``/AF`` array is added manually - assigning to
+``Pdf.attachments`` populates the ``/EmbeddedFiles`` name tree but NOT ``/AF`` ([OM-EMB-002]).
+The exact JCS bytes are stored verbatim ([OM-EMB-010]); the integrity hash is over those bytes.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import re
+import tempfile
+import zlib
+from dataclasses import dataclass
+from typing import Any
+
+import pikepdf
+
+from .canonical import canonicalize, hash_bytes, parse_hardened, strip_signature
+from .errors import Finding, PayloadTooLargeError, SignedEmbedError
+from .xmp import _marker_props, read_marker, render_marker_xml, write_marker
+
+#: Decompressed-payload cap (§J [OM-SEC-002]).
+MAX_PAYLOAD_BYTES = 5_000_000
+
+PAYLOAD_NAME = "om.json"
+MIME = "application/ld+json"
+SUBTYPE = pikepdf.Name("/application/ld+json")  # serialized name-escaped as /application#2Fld+json
+
+
+@dataclass
+class ReadResult:
+    """Result of reading a payload from a PDF (§I om_read shape)."""
+
+    present: bool
+    payload: dict[str, Any] | None
+    hash_valid: bool | None
+    origin_verified: None = None  # read-time origin check is a Consumer concern; null in core
+    signature_valid: None = None  # reserved (§10 layer 4)
+    source_doc_hash: str | None = None  # #5: marker sourceDocHash (provenance of the source PDF)
+
+
+def _remove_existing(pdf: pikepdf.Pdf) -> None:
+    """Remove any existing om.json attachment and its /AF reference (idempotent embed)."""
+    if PAYLOAD_NAME not in pdf.attachments:
+        return
+    old_objgen = pdf.attachments[PAYLOAD_NAME].obj.objgen
+    # Filter /AF while the referenced object is still live, then delete the attachment.
+    if "/AF" in pdf.Root:
+        kept = [f for f in pdf.Root.AF if f.objgen != old_objgen]
+        if kept:
+            pdf.Root.AF = pikepdf.Array(kept)
+        else:
+            del pdf.Root.AF
+    del pdf.attachments[PAYLOAD_NAME]
+
+
+def _ensure_af(pdf: pikepdf.Pdf, spec: pikepdf.Object) -> None:
+    """Ensure the catalog /AF array references the payload's Filespec ([OM-EMB-002])."""
+    if "/AF" not in pdf.Root:
+        pdf.Root.AF = pikepdf.Array([spec])
+        return
+    if all(f.objgen != spec.objgen for f in pdf.Root.AF):
+        pdf.Root.AF.append(spec)
+
+
+def _set_subtype(spec: pikepdf.Object) -> None:
+    """Set /Subtype application/ld+json on the embedded-file stream(s) ([OM-EMB-004])."""
+    ef = spec.EF
+    for key in ("/F", "/UF"):
+        if key in ef:
+            ef[key].Subtype = SUBTYPE
+
+
+def input_encrypted(pdf_bytes: bytes) -> bool:
+    """True if the input PDF is encrypted (permission encryption with an empty user password, which
+    pikepdf opens transparently and embed() then writes out UNENCRYPTED - a silent security-posture
+    change worth signaling to the author). A password-protected PDF raises on open and never reaches
+    here, so this is specifically the restrictions-only case (#4)."""
+    try:
+        with pikepdf.open(io.BytesIO(pdf_bytes)) as pdf:
+            return bool(pdf.is_encrypted)
+    except pikepdf.PasswordError:
+        return False
+
+
+def _is_signed(pdf: pikepdf.Pdf) -> bool:
+    """True if the PDF carries a digital signature (§10 layer 4 / #3 [OM-EMB-020]).
+
+    A full-rewrite save invalidates a byte-range signature; when this is True, embed uses an
+    incremental-update save instead, appending the payload so the signed bytes stay untouched.
+    Detects the AcroForm ``SigFlags`` "signatures exist" bit, any ``/FT /Sig`` field carrying a
+    ``/V``, or a ``/Perms`` (DocMDP/UR) entry - covering approval and certification signatures.
+    """
+    root = pdf.Root
+    if "/Perms" in root:
+        return True
+    acro = root.get("/AcroForm")
+    if acro is None:
+        return False
+    sig_flags = acro.get("/SigFlags")
+    if sig_flags is not None and int(sig_flags) & 1:
+        return True
+    fields = acro.get("/Fields")
+    if fields is None:
+        return False
+    return any(f.get("/FT") == pikepdf.Name.Sig and "/V" in f for f in fields)
+
+
+@dataclass
+class _EmbedFields:
+    data: bytes
+    payload_hash: str
+    spec_version: str
+    supersedes: str | None
+    source_doc_hash: str
+
+
+def _plan_embed(pdf: pikepdf.Pdf, pdf_bytes: bytes, payload: dict[str, Any]) -> _EmbedFields:
+    """Compute the payload bytes + marker fields (supersedes/sourceDocHash) - shared by both the
+    full-rewrite and incremental save paths so a signed OM gets identical provenance semantics."""
+    # signature excluded from the integrity preimage ([OM-CANON-003])
+    data = canonicalize(strip_signature(payload))
+    if len(data) > MAX_PAYLOAD_BYTES:
+        raise PayloadTooLargeError(len(data), MAX_PAYLOAD_BYTES)
+    payload_hash = hash_bytes(data)
+    # §D.4 re-embed semantics:
+    #  - a *different* prior payload is superseded (supersedes = prior hash);
+    #  - an *identical* re-embed carries the prior supersedes forward (no lineage wipe, no
+    #    self-supersede); a first embed has no predecessor (supersedes = None).
+    prior = read_marker(pdf)
+    prior_hash = prior.get("payloadHash") if prior else None
+    prior_supersedes = prior.get("supersedes") if prior else None
+    if prior_hash and prior_hash != payload_hash:
+        supersedes: str | None = prior_hash
+    elif prior_hash == payload_hash:
+        supersedes = prior_supersedes
+    else:
+        supersedes = None
+    # #5: sourceDocHash identifies the underlying source PDF, held STABLE across reprices - computed
+    # once (first embed) and carried forward from the prior marker on every re-embed.
+    prior_source = prior.get("sourceDocHash") if prior else None
+    source_doc_hash = prior_source or hash_bytes(pdf_bytes)
+    return _EmbedFields(
+        data=data,
+        payload_hash=payload_hash,
+        spec_version=str(payload.get("specVersion", "0.1")),
+        supersedes=supersedes,
+        source_doc_hash=source_doc_hash,
+    )
+
+
+def embed(
+    pdf_bytes: bytes, payload: dict[str, Any], *, asserted_date: str, badge: bool = False
+) -> bytes:
+    """Embed ``payload`` as om.json and return the new PDF bytes. Never mutates the input.
+
+    A *signed* input (#3 [OM-EMB-020]) is embedded via an incremental-update save - the payload is
+    appended after the signed byte range so the signature stays cryptographically intact - rather
+    than the default full-rewrite (which would invalidate it). Both paths write the identical
+    payload bytes and XMP marker, so the result reads the same regardless of the save method.
+    """
+    with pikepdf.open(io.BytesIO(pdf_bytes)) as pdf:
+        fields = _plan_embed(pdf, pdf_bytes, payload)
+        signed = _is_signed(pdf)
+
+    if signed:
+        return _embed_incremental(pdf_bytes, fields, asserted_date)
+
+    with pikepdf.open(io.BytesIO(pdf_bytes)) as pdf:
+        _remove_existing(pdf)
+        # pikepdf's stub marks description/filename/dates as required; runtime defaults them.
+        # We intentionally omit dates for determinism (§D [OM-EMB-011]).
+        filespec = pikepdf.AttachedFileSpec(pdf, fields.data, mime_type=MIME)  # type: ignore[call-arg]
+        filespec.relationship = pikepdf.Name.Data  # /AFRelationship (kwarg missing from stub)
+        pdf.attachments[PAYLOAD_NAME] = filespec
+        spec_obj = pdf.attachments[PAYLOAD_NAME].obj
+        _ensure_af(pdf, spec_obj)
+        _set_subtype(spec_obj)
+        write_marker(
+            pdf,
+            spec_version=fields.spec_version,
+            payload_filename=PAYLOAD_NAME,
+            payload_hash=fields.payload_hash,
+            asserted_date=asserted_date,
+            supersedes=fields.supersedes,
+            source_doc_hash=fields.source_doc_hash,
+        )
+        out = io.BytesIO()
+        pdf.save(out, deterministic_id=True)
+        return out.getvalue()
+
+
+def _embed_incremental(pdf_bytes: bytes, fields: _EmbedFields, asserted_date: str) -> bytes:
+    """Append the payload to a *signed* PDF via a fitz incremental-update save (#3 [OM-EMB-020]).
+
+    Builds the om.json embedded-file stream, an indirect /Filespec (/AFRelationship /Data,
+    /Subtype application/ld+json), the /EmbeddedFiles name-tree entry, the catalog /AF reference,
+    and the XMP marker - then saves incrementally so the original signed bytes are preserved as a
+    byte-exact prefix. The marker bytes come from the same ``render_marker_xml`` the full-rewrite
+    path uses, so the two producers agree. fitz's incremental save requires a real file whose bytes
+    equal the source, so the work happens in a temp file.
+    """
+    # PyMuPDF is the optional [render] extra; the signed-OM incremental path is the one embed case
+    # that needs it. Imported lazily with a clear hint so the pikepdf-only core stays MIT-clean.
+    try:
+        import pymupdf
+    except ImportError as exc:
+        raise SignedEmbedError(
+            "embedding a signed PDF needs PyMuPDF: pip install 'openom-core[render]'"
+        ) from exc
+
+    props = _marker_props(
+        spec_version=fields.spec_version,
+        payload_filename=PAYLOAD_NAME,
+        payload_hash=fields.payload_hash,
+        asserted_date=asserted_date,
+        supersedes=fields.supersedes,
+        source_doc_hash=fields.source_doc_hash,
+    )
+    # A TemporaryDirectory (vs NamedTemporaryFile + os.unlink) so cleanup can't mask the real error
+    # with a Windows "file in use" (WinError 32) in the finally block.
+    with tempfile.TemporaryDirectory(prefix="openom_signed_") as tmpdir:
+        path = os.path.join(tmpdir, "in.pdf")
+        with open(path, "wb") as fh:
+            fh.write(pdf_bytes)
+        doc = pymupdf.open(path)
+        try:
+            # If pymupdf had to REBUILD the xref to open this file, an incremental append is not a
+            # byte-exact extension of the original - the signed prefix would change and the
+            # signature break. Refuse cleanly (OM-EMB-021) rather than ship an invalid signature.
+            if getattr(doc, "is_repaired", False):
+                raise SignedEmbedError(
+                    "this signed PDF needed its cross-reference table rebuilt to open, so an "
+                    "incremental (signature-preserving) embed is not safe; embed an unsigned copy "
+                    "or re-issue the signature after embedding"
+                )
+            cat = doc.pdf_catalog()
+            # 1. embedded-file stream (verbatim JCS bytes; pikepdf read decodes the filter)
+            ef = doc.get_new_xref()
+            doc.update_object(ef, "<< /Type /EmbeddedFile /Subtype /application#2Fld+json >>")
+            doc.update_stream(ef, fields.data, compress=True)
+            # 2. indirect /Filespec ([OM-EMB-002]/[OM-EMB-004])
+            spec = doc.get_new_xref()
+            doc.update_object(
+                spec,
+                f"<< /Type /Filespec /F ({PAYLOAD_NAME}) /UF ({PAYLOAD_NAME}) "
+                f"/AFRelationship /Data /Desc (openOM payload) "
+                f"/EF << /F {ef} 0 R /UF {ef} 0 R >> >>",
+            )
+            # 3. /EmbeddedFiles name tree - drop any prior om.json, keep other attachments
+            entries = [
+                f"({nm}) {xr} 0 R"
+                for nm, xr in _name_tree_entries(doc, cat)
+                if nm != PAYLOAD_NAME
+            ]
+            entries.append(f"({PAYLOAD_NAME}) {spec} 0 R")
+            doc.xref_set_key(cat, "Names/EmbeddedFiles/Names", "[" + " ".join(entries) + "]")
+            # 4. catalog /AF - drop any prior om.json filespec ref (by resolving each ref's /F,
+            # since a re-embed's prior filespec has a different xref), append ours
+            af = [r for r in _af_refs(doc, cat) if not _is_om_filespec(doc, r)]
+            af.append(f"{spec} 0 R")
+            doc.xref_set_key(cat, "AF", "[" + " ".join(af) + "]")
+            # 5. XMP marker (identical bytes to the full-rewrite path)
+            existing = _existing_metadata_xml(doc, cat)
+            meta = doc.get_new_xref()
+            doc.update_object(meta, "<< /Type /Metadata /Subtype /XML >>")
+            marker_xml = render_marker_xml(existing, props).encode("utf-8")
+            doc.update_stream(meta, marker_xml, compress=False)
+            doc.xref_set_key(cat, "Metadata", f"{meta} 0 R")
+            try:
+                doc.saveIncr()
+            except Exception as exc:  # noqa: BLE001 - any fitz save failure -> typed refusal
+                raise SignedEmbedError(
+                    f"incremental save failed on this signed PDF: {exc}"
+                ) from exc
+        finally:
+            doc.close()
+        with open(path, "rb") as fh:
+            out = fh.read()
+    # Postcondition the whole feature promises: the original signed bytes stay a byte-exact prefix,
+    # so every byte the /ByteRange signs is unchanged. Never return a doc that broke it.
+    if not out.startswith(pdf_bytes):
+        raise SignedEmbedError("incremental embed did not preserve the signed byte prefix")
+    return out
+
+
+def _name_tree_entries(doc: Any, cat: int) -> list[tuple[str, str]]:
+    """(name, 'N 0 R') pairs already in /Names/EmbeddedFiles/Names, or [] if none."""
+    kind, val = doc.xref_get_key(cat, "Names/EmbeddedFiles/Names")
+    if kind != "array":
+        return []
+    return re.findall(r"\(([^)]*)\)\s*(\d+ 0 R)", val)
+
+
+def _af_refs(doc: Any, cat: int) -> list[str]:
+    """Existing catalog /AF indirect refs ('N 0 R'), or [] if none."""
+    kind, val = doc.xref_get_key(cat, "AF")
+    if kind != "array":
+        return []
+    return re.findall(r"\d+ 0 R", val)
+
+
+def _is_om_filespec(doc: Any, ref: str) -> bool:
+    """True if the /AF ref 'N 0 R' points to a filespec whose /F is our om.json (drop it on
+    re-embed so /AF never stacks duplicate payload references)."""
+    m = re.match(r"(\d+) 0 R", ref)
+    if not m:
+        return False
+    kind, val = doc.xref_get_key(int(m.group(1)), "F")
+    return bool(kind == "string" and val == PAYLOAD_NAME)
+
+
+def _existing_metadata_xml(doc: Any, cat: int) -> str | None:
+    """The current catalog /Metadata XML, or None - so our marker merges alongside existing XMP."""
+    kind, val = doc.xref_get_key(cat, "Metadata")
+    if kind != "xref":
+        return None
+    meta_xref = int(re.match(r"(\d+) 0 R", val).group(1))  # type: ignore[union-attr]
+    raw = doc.xref_stream(meta_xref)
+    return raw.decode("utf-8", "replace") if raw else None
+
+
+def reembed_warnings(
+    pdf_bytes: bytes, payload: dict[str, Any], *, asserted_date: str
+) -> list[Finding]:
+    """Non-blocking re-embed warnings against an existing PDF (§H). Pure; ``embed`` stays
+    bytes→bytes, so callers (CLI/MCP) compose this to surface provenance issues.
+
+    OMW-W051: the new assertedDate precedes the payload it would supersede (time going
+    backwards on a reprice). Warnings never block.
+    """
+    with pikepdf.open(io.BytesIO(pdf_bytes)) as pdf:
+        prior = read_marker(pdf)
+    if not prior:
+        return []
+    payload_hash = hash_bytes(canonicalize(strip_signature(payload)))
+    prior_hash = prior.get("payloadHash")
+    prior_date = prior.get("assertedDate")
+    out: list[Finding] = []
+    if prior_hash and prior_hash != payload_hash and prior_date and asserted_date < prior_date:
+        out.append(
+            Finding(
+                "OMW-W051",
+                "warning",
+                "/assertedDate",
+                "assertedDate precedes the superseded payload's assertedDate",
+                expected=prior_date,
+                actual=asserted_date,
+            )
+        )
+    return out
+
+
+def _find_ef_stream(pdf: pikepdf.Pdf) -> pikepdf.Object | None:
+    """Locate the om.json embedded-file stream in spec detection order ([OM-XMP-003]).
+
+    Authoritative path: catalog ``/AF`` → Filespec (``/UF`` or ``/F`` == om.json) → ``/EF``.
+    Falls back to the ``/EmbeddedFiles`` name tree for producers that populate only that.
+    """
+
+    def _ef_of(spec: pikepdf.Object) -> pikepdf.Object | None:
+        if "/EF" not in spec:
+            return None
+        ef = spec.EF
+        for key in ("/UF", "/F"):
+            if key in ef:
+                return ef[key]
+        return None
+
+    if "/AF" in pdf.Root:
+        for spec in pdf.Root.AF:
+            names = {str(spec[k]) for k in ("/UF", "/F") if k in spec}
+            if PAYLOAD_NAME in names:
+                stream = _ef_of(spec)
+                if stream is not None:
+                    return stream
+    if PAYLOAD_NAME in pdf.attachments:  # fallback: EmbeddedFiles name tree
+        return _ef_of(pdf.attachments[PAYLOAD_NAME].obj)
+    return None
+
+
+def _decoded_payload_bytes(stream: pikepdf.Object) -> bytes:
+    """Decode the EF stream to raw payload bytes, bounding size *before* full materialization.
+
+    A malicious PDF can hide a decompression bomb in a tiny compressed stream. We read the
+    stored (compressed) bytes - always bounded by the file itself - reject if already over the
+    cap, then inflate with a hard ceiling rather than decompressing unbounded into memory.
+    """
+    raw = bytes(stream.read_raw_bytes())
+    if len(raw) > MAX_PAYLOAD_BYTES:
+        raise PayloadTooLargeError(len(raw), MAX_PAYLOAD_BYTES)
+
+    filt = stream.get("/Filter")
+    names = [str(filt)] if isinstance(filt, pikepdf.Name) else [str(n) for n in (filt or [])]
+    # Plain FlateDecode (no predictor) - the common case for our writes and pdf-lib - can be
+    # inflated with a bounded zlib object. Anything exotic (predictors, other filters) defers
+    # to pikepdf's decoder, still guarded by the compressed-size cap above and a post-check.
+    if names == ["/FlateDecode"] and "/DecodeParms" not in stream and "/DP" not in stream:
+        data = _bounded_inflate(raw)
+    elif not names:
+        data = raw  # stored uncompressed
+    else:
+        data = bytes(stream.read_bytes())
+    if len(data) > MAX_PAYLOAD_BYTES:
+        raise PayloadTooLargeError(len(data), MAX_PAYLOAD_BYTES)
+    return data
+
+
+def _bounded_inflate(raw: bytes) -> bytes:
+    obj = zlib.decompressobj()
+    out = obj.decompress(raw, MAX_PAYLOAD_BYTES + 1)
+    if obj.unconsumed_tail:  # hit the ceiling before the input was exhausted
+        raise PayloadTooLargeError(MAX_PAYLOAD_BYTES + 1, MAX_PAYLOAD_BYTES)
+    return out + obj.flush()
+
+
+def read(pdf_bytes: bytes) -> ReadResult:
+    """Read + integrity-verify the om.json payload (detection order [OM-XMP-003])."""
+    with pikepdf.open(io.BytesIO(pdf_bytes)) as pdf:
+        marker = read_marker(pdf)
+        stream = _find_ef_stream(pdf)
+        if stream is None:
+            return ReadResult(present=False, payload=None, hash_valid=None)
+        raw = _decoded_payload_bytes(stream)
+        payload = parse_hardened(raw)  # §J read-side hardening: dup-key + depth guard [Mi18]
+        xmp_hash = marker.get("payloadHash") if marker else None
+        hash_valid = (hash_bytes(raw) == xmp_hash) if xmp_hash else None
+        return ReadResult(
+            present=True,
+            payload=payload,
+            hash_valid=hash_valid,
+            source_doc_hash=marker.get("sourceDocHash") if marker else None,
+        )