docuhand 0.1.0.dev1__py3-none-any.whl

docuhand/engine/office_app.py

@@ -0,0 +1,828 @@
+"""Office engine: probe Word/WPS via COM, failover, and inspect_document.
+
+Threading contract: every method that touches COM runs on the STA thread
+owned by :class:`~docuhand.engine.com_thread.ComWorker` (via submit).
+Only plain-attribute methods (``invalidate``) may run on other threads.
+
+Engine selection (architecture decision #6): probe order is
+``Word.Application`` → ``KWPS.Application`` by default, overridable with
+``DOCUHAND_ENGINE=word|wps``. If an engine dies mid-call (RPC crash —
+seen in production when Word drives legacy .doc on some machines) the
+engine is discarded and the next one takes over transparently.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+import win32com.client
+
+from ..errors import (
+    DocuhandError,
+    EngineUnavailableError,
+    FileNotFoundError,
+    OpenFailedError,
+    PasswordProtectedError,
+)
+from .container_guard import detect_encryption, validate_container
+from .templating import (
+    _FillOutcome,
+    _fill_open_document,
+    _final_far_east_sweep,
+    _has_cjk,
+)
+from .com_utils import (
+    _g,
+    _looks_encrypted,
+    _looks_like_arg_mismatch,
+    _short_exc,
+    file_claims_encrypted,
+)
+from .pdf_plan import parse_page_range  # noqa: F401  (re-exported for tools layer)
+from .wd_constants import (
+    WD_ALERTS_NONE,
+    WD_DO_NOT_SAVE_CHANGES,
+    WD_EXPORT_ALL_DOCUMENT,
+    WD_EXPORT_FORMAT_PDF,
+    WD_EXPORT_FROM_TO,
+)
+
+# --- pure helpers (unit-testable, zero COM) -------------------------------
+
+OLE2_MAGIC = b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1"
+ZIP_MAGIC = b"PK\x03\x04"
+FILE_ATTRIBUTE_READONLY = 0x1
+
+FRIENDLY_FORMATS = {
+    "ole2": "legacy .doc (OLE2 Compound File)",
+    "zip": "zip / OOXML (.docx family)",
+    "rtf": "RTF",
+    "html": "HTML",
+    "text": "plain text",
+    "unknown": "unknown",
+}
+
+_EXT_TO_FORMAT = {
+    ".doc": "ole2",
+    ".dot": "ole2",
+    ".docx": "zip",
+    ".dotx": "zip",
+    ".rtf": "rtf",
+    ".txt": "text",
+    ".htm": "html",
+    ".html": "html",
+}
+
+# Word constants (locale-independent numbers, not string names)
+WD_STAT_WORDS = 0
+WD_STAT_PAGES = 2
+WD_STAT_PARAGRAPHS = 4
+WD_DO_NOT_SAVE_CHANGES = 0
+WD_ALERTS_NONE = 0
+
+_PROTECTION_MODES = {
+    -1: "none",
+    -2: "comments",
+    -3: "form_fields",
+    -4: "read_only",
+    -5: "tracked_changes",
+}
+
+
+def sniff_format(head: bytes) -> str:
+    """Detect the real container format from the first bytes."""
+    if head[:8] == OLE2_MAGIC:
+        return "ole2"
+    if head[:4] == ZIP_MAGIC:
+        return "zip"
+    stripped = head.lstrip()[:512].lower()
+    if stripped.startswith(b"{\\rtf"):
+        return "rtf"
+    if b"<html" in stripped or stripped.startswith(b"<!doctype html"):
+        return "html"
+    if b"\x00" not in head[:512]:
+        try:
+            head[:512].decode("utf-8")
+            return "text"
+        except UnicodeDecodeError:
+            pass
+    return "unknown"
+
+
+def format_matches_extension(extension: str, detected: str) -> bool:
+    return _EXT_TO_FORMAT.get(extension.lower()) == detected
+
+
+def probe_writable(path: str) -> bool:
+    """Best-effort lock probe: can another writer exist right now?
+
+    A file opened in Word/WPS is held with share-write denied, so a write
+    handle fails. Note: a READONLY *attribute* also denies write handles,
+    so callers must exclude that case before calling this a "lock".
+    """
+    try:
+        with open(path, "r+b"):
+            pass
+        return True
+    except OSError:
+        return False
+
+
+def owner_lock_file(path: str) -> str | None:
+    """Word/WPS leave a '~$...' owner file next to an open document."""
+    p = Path(path)
+    try:
+        for cand in p.parent.iterdir():
+            name = cand.name.lower()
+            if not name.startswith("~$"):
+                continue
+            rest = name[2:]
+            target = p.name.lower()
+            if target[2:] == rest or target.startswith(rest):
+                return cand.name
+    except OSError:
+        pass
+    return None
+
+
+def _g(fn: Callable[[], Any], default: Any = None) -> Any:
+    """Guard a single metadata probe: one engine lacking a property must
+    never fail the whole inspection (the seed of docs/wps-vs-word.md)."""
+    try:
+        return fn()
+    except Exception:
+        return default
+
+
+def _short_exc(exc: BaseException) -> str:
+    return f"{type(exc).__name__}: {str(exc)[:200]}"
+
+
+def _looks_encrypted(exc: BaseException) -> bool:
+    text = str(exc).lower()
+    return "password" in text or "密码" in text
+
+
+def _looks_like_arg_mismatch(exc: BaseException) -> bool:
+    return isinstance(exc, TypeError) or "paramet" in str(exc).lower()
+
+
+# (Historical note: a "deliberately wrong PasswordDocument" guard passed to
+# Documents.Open kills the modal for *genuinely encrypted* files on Word —
+# but on WPS the dynamic dispatch explodes with AttributeError on the
+# unknown kwarg and takes the app object down (RPC_S_SERVER_UNAVAILABLE on
+# the next call). Not portable → not used. See docs/pitfalls.md #9.)
+
+
+def file_claims_encrypted(path: str) -> bool | None:
+    """Header sniff: can this file really be COM-password-encrypted?
+
+    True  → OLE2 with the FIB fEncrypted bit set: genuinely a password .doc.
+    False → container rules it out (plain zip can't be COM-encrypted): a
+            "password" error on it means the file is CORRUPT, not encrypted.
+    None  → OLE2 without the bit — could be a normal .doc or an encrypted
+            OOXML wrapper; treat encryption reports as genuine (safe default).
+    """
+    try:
+        with open(path, "rb") as f:
+            head = f.read(16)
+    except OSError:
+        return None
+    if head[:8] != OLE2_MAGIC:
+        return False
+    try:
+        flags = int.from_bytes(head[0x0A:0x0C], "little")
+        return bool(flags & 0x0001)
+    except Exception:
+        return None
+
+
+def engine_order_names() -> list[str]:
+    """Expose the probe order for tool payloads/tests (pure, no COM)."""
+    prefer = os.environ.get("DOCUHAND_ENGINE", "").strip().lower()
+    if prefer == "wps":
+        return ["wps", "word"]
+    return ["word", "wps"]
+
+
+# --- the engine ------------------------------------------------------------
+
+
+class OfficeEngine:
+    """Holds the hidden Word/WPS Application object — STA-only."""
+
+    def __init__(self) -> None:
+        self._app: Any = None
+        self._engine_name: str | None = None
+        self._progid: str | None = None
+        self._engine_version: str = ""  # e.g. "16.0" (Word) / "11.1.0.1" (WPS)
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def invalidate(self) -> None:
+        """Drop all engine state after its STA was abandoned (no COM calls)."""
+        self._app = None
+        self._engine_name = None
+        self._progid = None
+        self._engine_version = ""
+
+    def shutdown(self) -> None:
+        """Quit the app — must run on the engine's own STA (via submit)."""
+        app = self._app
+        self.invalidate()
+        if app is not None:
+            try:
+                app.Quit(WD_DO_NOT_SAVE_CHANGES)
+            except Exception:
+                pass
+
+    def _discard_app(self) -> None:
+        """Quit and forget after a mid-call engine failure (STA-only)."""
+        self.shutdown()
+
+    def _engine_order(self) -> list[tuple[str, str]]:
+        prefer = os.environ.get("DOCUHAND_ENGINE", "").strip().lower()
+        word_first = [("word", "Word.Application"), ("wps", "KWPS.Application")]
+        wps_first = [("wps", "KWPS.Application"), ("word", "Word.Application")]
+        if prefer == "wps":
+            return wps_first
+        if prefer == "word":
+            return word_first
+        return word_first  # default per 开工包 decision #6
+
+    def _ensure_app(self, progid: str, engine_name: str) -> Any:
+        if self._app is not None and self._engine_name == engine_name:
+            return self._app
+        self.shutdown()  # drop any previous engine's app (on this STA)
+        app = win32com.client.DispatchEx(progid)  # new hidden instance (Launch)
+        for attr, value in (("DisplayAlerts", WD_ALERTS_NONE), ("Visible", False)):
+            try:
+                setattr(app, attr, value)
+            except Exception:
+                pass  # engine differences must not block launch
+        try:
+            app.Options.ConfirmConversions = False
+        except Exception:
+            pass
+        self._app = app
+        self._engine_name = engine_name
+        self._progid = progid
+        try:
+            self._engine_version = str(app.Version)  # field diagnostics
+        except Exception:
+            self._engine_version = ""
+        return app
+
+    def inspect_document(self, path: str) -> dict[str, Any]:
+        t0 = time.perf_counter()
+        p = Path(path).expanduser()
+        if not p.exists():
+            raise FileNotFoundError(str(p))
+        if p.is_dir():
+            raise DocuhandError(
+                f"Path is a directory, not a document: {p}",
+                llm_hint="Pass the full path to a document file, not a folder.",
+                details={"path": str(p)},
+            )
+
+        size = p.stat().st_size
+        # Pre-COM gates (same rationale as convert_document): broken
+        # containers trigger a modal corrupt-file dialog; encrypted files
+        # trigger a modal password prompt — both hang a headless call.
+        ok, reason = validate_container(str(p))
+        if not ok:
+            raise OpenFailedError(str(p), "container pre-check", f"structurally invalid container: {reason}")
+        if detect_encryption(str(p)):
+            raise PasswordProtectedError(str(p), "container pre-check")
+        with open(p, "rb") as f:
+            head = f.read(1024)
+        detected = sniff_format(head)
+        extension = p.suffix.lower()
+
+        stat = p.stat()
+        readonly_attr = bool(getattr(stat, "st_file_attributes", 0) & FILE_ATTRIBUTE_READONLY)
+        writable = probe_writable(str(p))
+        is_locked = (not writable) and (not readonly_attr)
+        lockfile = owner_lock_file(str(p))
+
+        order = self._engine_order()
+        attempts: list[dict[str, str]] = []
+        launch_failures = 0
+
+        for engine_name, progid in order:
+            try:
+                app = self._ensure_app(progid, engine_name)
+            except Exception as exc:
+                launch_failures += 1
+                attempts.append({"engine": engine_name, "stage": "launch", "error": _short_exc(exc)})
+                self._discard_app()
+                continue
+            try:
+                info = self._open_and_read(app, engine_name, str(p))
+            except PasswordProtectedError:
+                raise  # failover cannot help; tell the agent immediately
+            except Exception as exc:
+                attempts.append({"engine": engine_name, "stage": "read", "error": _short_exc(exc)})
+                self._discard_app()  # engine died or refused — try the next
+                continue
+
+            info["ok"] = True
+            info["tool"] = "inspect_document"
+            info["path"] = str(p)
+            info["engine"] = engine_name
+            info["engine_version"] = self._engine_version
+            info["format"] = {
+                "extension": extension or None,
+                "detected": detected,
+                "detected_friendly": FRIENDLY_FORMATS.get(detected, detected),
+                "matches_extension": format_matches_extension(extension, detected),
+                "size_bytes": size,
+            }
+            info["is_locked"] = is_locked
+            info["readonly_attribute"] = readonly_attr
+            info["owner_lock_file_present"] = lockfile is not None
+            info["is_corrupted"] = False
+            info["duration_ms"] = round((time.perf_counter() - t0) * 1000)
+            return info
+
+        if launch_failures == len(order):
+            raise EngineUnavailableError(attempts)
+        raise OpenFailedError(str(p), "word→wps failover exhausted", "; ".join(a["error"] for a in attempts))
+
+    # -- convert_document (D3–D5) -------------------------------------------
+
+    def convert_document(self, source: str, target: str, wd_format: int) -> dict[str, Any]:
+        """Convert one file via the real engine; source is never deleted.
+
+        Same failover contract as inspect_document: try the probe order;
+        an engine that dies mid-call is discarded and the next one takes
+        over. Runs on the COM STA (via ComWorker.submit) — never call
+        directly from the event loop.
+        """
+        t0 = time.perf_counter()
+        # Absolute paths are mandatory: WPS's Documents.Open fails with
+        # "文档打开失败" on relative paths even when the server cwd is right.
+        src = Path(source).expanduser().resolve()
+        dst = Path(target).expanduser().resolve()
+
+        if not src.exists():
+            raise FileNotFoundError(str(src))
+        # Pre-COM gates: (1) structurally broken containers can pop a MODAL
+        # "file is corrupt" dialog inside Word/WPS (DisplayAlerts=0 does
+        # NOT suppress it); (2) encrypted files pop a modal password prompt
+        # that hangs a headless COM call. Both are decided here, without
+        # the engine, so the engine only ever sees files it can open.
+        ok, reason = validate_container(str(src))
+        if not ok:
+            raise OpenFailedError(
+                str(src),
+                "container pre-check",
+                f"structurally invalid container: {reason}",
+            )
+        if detect_encryption(str(src)):
+            raise PasswordProtectedError(str(src), "container pre-check")
+        if src.resolve() == dst.resolve():
+            raise DocuhandError(
+                f"Source and target are the same file: {src}",
+                llm_hint="convert_documents never overwrites its source; "
+                "this indicates an internal planning bug — report it.",
+                details={"path": str(src)},
+            )
+
+        order = self._engine_order()
+        attempts: list[dict[str, str]] = []
+        launch_failures = 0
+
+        for engine_name, progid in order:
+            try:
+                app = self._ensure_app(progid, engine_name)
+            except Exception as exc:
+                launch_failures += 1
+                attempts.append({"engine": engine_name, "stage": "launch", "error": _short_exc(exc)})
+                self._discard_app()
+                continue
+            try:
+                self._open_and_save_as(app, str(src), str(dst), wd_format)
+            except PasswordProtectedError:
+                raise
+            except Exception as exc:
+                attempts.append({"engine": engine_name, "stage": "convert", "error": _short_exc(exc)})
+                self._discard_app()
+                continue
+
+            return {
+                "ok": True,
+                "source": str(src),
+                "target": str(dst),
+                "engine": engine_name,
+                "engine_version": self._engine_version,
+                "duration_ms": round((time.perf_counter() - t0) * 1000),
+            }
+
+        if launch_failures == len(order):
+            raise EngineUnavailableError(attempts)
+        raise OpenFailedError(str(src), "word→wps failover exhausted", "; ".join(a["error"] for a in attempts))
+
+    # -- fill_document / export_pdf (D6–D8) ---------------------------------
+
+    def fill_document(
+        self,
+        template: str,
+        output: str,
+        data: dict[str, str],
+        mode: str = "auto",
+        bookmark_names: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Fill one template → one output document. Same failover contract.
+
+        Opens the template read-only (the template itself is never touched),
+        mutates the in-memory copy, applies the NameFarEast final sweep, then
+        SaveAs2 to the output path.
+        """
+        t0 = time.perf_counter()
+        src = Path(template).expanduser().resolve()
+        dst = Path(output).expanduser().resolve()
+        if not src.exists():
+            raise FileNotFoundError(str(src))
+        ok, reason = validate_container(str(src))
+        if not ok:
+            raise OpenFailedError(str(src), "container pre-check", f"structurally invalid container: {reason}")
+        if detect_encryption(str(src)):
+            raise PasswordProtectedError(str(src), "container pre-check")
+
+        order = self._engine_order()
+        attempts: list[dict[str, str]] = []
+        launch_failures = 0
+
+        for engine_name, progid in order:
+            try:
+                app = self._ensure_app(progid, engine_name)
+            except Exception as exc:
+                launch_failures += 1
+                attempts.append({"engine": engine_name, "stage": "launch", "error": _short_exc(exc)})
+                self._discard_app()
+                continue
+            try:
+                outcome = self._open_fill_save(
+                    app, str(src), str(dst), data, mode, bookmark_names or []
+                )
+            except PasswordProtectedError:
+                raise
+            except Exception as exc:
+                attempts.append({"engine": engine_name, "stage": "fill", "error": _short_exc(exc)})
+                self._discard_app()
+                continue
+
+            payload: dict[str, Any] = {
+                "ok": True,
+                "template": str(src),
+                "output": str(dst),
+                "engine": engine_name,
+                "engine_version": self._engine_version,
+                "duration_ms": round((time.perf_counter() - t0) * 1000),
+                "mode": mode,
+            }
+            payload.update(
+                {
+                    "filled_keys": sorted(set(outcome.filled)),
+                    "missing_keys": sorted(set(outcome.missing)),
+                    "content_controls_filled": sorted(set(outcome.controls_ok)),
+                    "content_controls_failed": sorted(set(outcome.controls_bad)),
+                    "leftover_placeholders": outcome.leftovers,
+                    "bookmarks_in_template": outcome.bookmarks_seen,
+                    "output_size_bytes": dst.stat().st_size if dst.exists() else None,
+                }
+            )
+            return payload
+
+        if launch_failures == len(order):
+            raise EngineUnavailableError(attempts)
+        raise OpenFailedError(str(src), "word→wps failover exhausted", "; ".join(a["error"] for a in attempts))
+
+    def export_pdf(self, path: str, output: str, page_from: int | None, page_to: int | None) -> dict[str, Any]:
+        """Export print-fidelity PDF via the real layout engine.
+
+        Uses ExportAsFixedFormat (Word ≥ 2007 SP2, WPS supports it) with a
+        SaveAs(FileFormat=17) fallback for exotic engines. Source document
+        is opened read-only and never modified.
+        """
+        t0 = time.perf_counter()
+        src = Path(path).expanduser().resolve()
+        dst = Path(output).expanduser().resolve()
+        if not src.exists():
+            raise FileNotFoundError(str(src))
+        ok, reason = validate_container(str(src))
+        if not ok:
+            raise OpenFailedError(str(src), "container pre-check", f"structurally invalid container: {reason}")
+        if detect_encryption(str(src)):
+            raise PasswordProtectedError(str(src), "container pre-check")
+
+        order = self._engine_order()
+        attempts: list[dict[str, str]] = []
+        launch_failures = 0
+
+        for engine_name, progid in order:
+            try:
+                app = self._ensure_app(progid, engine_name)
+            except Exception as exc:
+                launch_failures += 1
+                attempts.append({"engine": engine_name, "stage": "launch", "error": _short_exc(exc)})
+                self._discard_app()
+                continue
+            try:
+                self._open_export_pdf(app, str(src), str(dst), page_from, page_to)
+            except PasswordProtectedError:
+                raise
+            except Exception as exc:
+                attempts.append({"engine": engine_name, "stage": "export", "error": _short_exc(exc)})
+                self._discard_app()
+                continue
+
+            if not dst.exists():
+                raise OpenFailedError(str(src), engine_name, "export reported success but no PDF was written")
+            return {
+                "ok": True,
+                "source": str(src),
+                "output": str(dst),
+                "engine": engine_name,
+                "engine_version": self._engine_version,
+                "page_range": None if page_from is None else (str(page_from) if page_from == page_to else f"{page_from}-{page_to}"),
+                "output_size_bytes": dst.stat().st_size,
+                "pdf_verified": self._pdf_header_ok(dst),
+                "duration_ms": round((time.perf_counter() - t0) * 1000),
+            }
+
+        if launch_failures == len(order):
+            raise EngineUnavailableError(attempts)
+        raise OpenFailedError(str(src), "word→wps failover exhausted", "; ".join(a["error"] for a in attempts))
+
+    @staticmethod
+    def _pdf_header_ok(path: Path) -> bool:
+        try:
+            with open(path, "rb") as f:
+                return f.read(5) == b"%PDF-"
+        except OSError:
+            return False
+
+    def _open_export_pdf(
+        self,
+        app: Any,
+        source: str,
+        target: str,
+        page_from: int | None,
+        page_to: int | None,
+    ) -> None:
+        docs = app.Documents
+        try:
+            doc = docs.Open(
+                FileName=source,
+                ConfirmConversions=False,
+                ReadOnly=True,
+                AddToRecentFiles=False,
+                Visible=False,
+            )
+        except Exception as exc:
+            if _looks_encrypted(exc):
+                if file_claims_encrypted(source) is not False:
+                    raise PasswordProtectedError(source, getattr(app, "Name", "engine")) from None
+                raise OpenFailedError(source, "engine", _short_exc(exc)) from None
+            if not _looks_like_arg_mismatch(exc):
+                raise
+            doc = docs.Open(source)
+
+        try:
+            if page_from is not None:
+                export_range, wd_from, wd_to = WD_EXPORT_FROM_TO, page_from, page_to or page_from
+            else:
+                export_range, wd_from, wd_to = WD_EXPORT_ALL_DOCUMENT, 1, 1
+            try:
+                doc.ExportAsFixedFormat(
+                    OutputFileName=target,
+                    ExportFormat=WD_EXPORT_FORMAT_PDF,
+                    OpenAfterExport=False,
+                    OptimizeFor=0,  # wdExportOptimizeForPrint — print fidelity
+                    Range=export_range,
+                    From=wd_from,
+                    To=wd_to,
+                    Item=0,  # wdExportDocumentContent
+                    IncludeDocProps=True,
+                    KeepIRM=True,
+                    CreateBookmarks=0,
+                    DocStructureTags=True,
+                    BitmapMissingFonts=True,
+                    UseISO19005_1=False,
+                )
+            except Exception as exc:
+                if isinstance(exc, AttributeError) or _looks_like_arg_mismatch(exc):
+                    # minimal-signature fallback (old Word / WPS variants)
+                    doc.SaveAs(target, WD_EXPORT_FORMAT_PDF)  # 17 == wdFormatPDF
+                else:
+                    raise
+        finally:
+            try:
+                doc.Close(WD_DO_NOT_SAVE_CHANGES)
+            except Exception:
+                pass
+
+    # -- merge_documents (D13–D14) --------------------------------------------
+
+    def merge_one(
+        self,
+        template: str,
+        output: str,
+        data: dict[str, str],
+    ) -> dict[str, Any]:
+        """Fill one row into the template → output. Thin wrapper over the
+        fill pipeline in 'placeholders+bookmarks' auto mode; raises on
+        engine failure (the batch layer catches and isolates per row)."""
+        result = self.fill_document(template, output, data, mode="auto", bookmark_names=None)
+        problems = result.get("missing_keys") or result.get("leftover_placeholders")
+        if problems:
+            # per-row fidelity matters in a merge: report, don't hide
+            result["row_warning"] = {
+                "missing_keys": result.get("missing_keys") or [],
+                "leftover_placeholders": result.get("leftover_placeholders") or [],
+            }
+        return result
+
+    def _open_fill_save(
+        self,
+        app: Any,
+        source: str,
+        target: str,
+        data: dict[str, str],
+        mode: str,
+        bookmark_names: list[str],
+    ) -> _FillOutcome:
+        docs = app.Documents
+        try:
+            doc = docs.Open(
+                FileName=source,
+                ConfirmConversions=False,
+                ReadOnly=True,
+                AddToRecentFiles=False,
+                Visible=False,
+            )
+        except Exception as exc:
+            if _looks_encrypted(exc):
+                if file_claims_encrypted(source) is not False:
+                    raise PasswordProtectedError(source, getattr(app, "Name", "engine")) from None
+                raise OpenFailedError(source, "engine", _short_exc(exc)) from None
+            if not _looks_like_arg_mismatch(exc):
+                raise
+            doc = docs.Open(source)
+
+        try:
+            outcome = _fill_open_document(doc, data, mode, bookmark_names)
+            _final_far_east_sweep(doc)
+            # wdFormatXMLDocument = 16 for .docx, wdFormatDocument = 0 for .doc
+            wd_format = 0 if target.lower().endswith(".doc") else 16
+            try:
+                doc.SaveAs2(target, FileFormat=wd_format)
+            except Exception as exc:
+                if isinstance(exc, AttributeError) or _looks_like_arg_mismatch(exc):
+                    doc.SaveAs(target, wd_format)
+                else:
+                    raise
+            # SaveAs2 itself can reset NameFarEast on the (already-saved) doc;
+            # re-assert once more so the SAVED bytes carry correct EA fonts.
+            _final_far_east_sweep(doc)
+            try:
+                doc.Save()
+            except Exception:
+                pass  # older engines may not allow Save after SaveAs — best effort
+            return outcome
+        finally:
+            try:
+                doc.Close(WD_DO_NOT_SAVE_CHANGES)
+            except Exception:
+                pass
+
+    def _open_read_only(self, app: Any, source: str) -> Any:
+        """Open a document read-only in the given app; raise structured errors.
+
+        Shared by every engine flow. Handles the password-misclassification
+        guard and the positional-arg fallback for engines that reject named
+        arguments (docs/pitfalls.md #13 family).
+        """
+        docs = app.Documents
+        try:
+            doc = docs.Open(
+                FileName=source,
+                ConfirmConversions=False,
+                ReadOnly=True,
+                AddToRecentFiles=False,
+                Visible=False,
+            )
+        except Exception as exc:
+            if _looks_encrypted(exc):
+                if file_claims_encrypted(source) is not False:
+                    raise PasswordProtectedError(source, getattr(app, "Name", "engine")) from None
+                raise OpenFailedError(source, "engine", _short_exc(exc)) from None
+            if not _looks_like_arg_mismatch(exc):
+                raise
+            doc = docs.Open(source)  # minimal fallback for engines that reject named args
+        return doc
+
+    def _open_and_save_as(self, app: Any, source: str, target: str, wd_format: int) -> None:
+        docs = app.Documents
+        try:
+            doc = docs.Open(
+                FileName=source,
+                ConfirmConversions=False,
+                ReadOnly=True,
+                AddToRecentFiles=False,
+                Visible=False,
+            )
+        except Exception as exc:
+            if _looks_encrypted(exc):
+                # A "password" complaint is only trusted when the container
+                # can actually be COM-encrypted; otherwise it is Word's
+                # confused reaction to a corrupt file (its misclassification
+                # is what pops the password dialog we guard against).
+                if file_claims_encrypted(source) is not False:
+                    raise PasswordProtectedError(source, getattr(app, "Name", "engine")) from None
+                raise OpenFailedError(source, "engine", _short_exc(exc)) from None
+            if not _looks_like_arg_mismatch(exc):
+                raise
+            doc = docs.Open(source)  # minimal fallback for engines that reject named args
+
+        try:
+            try:
+                doc.SaveAs2(target, FileFormat=wd_format)
+            except Exception as exc:
+                # Word 2007 and older have no SaveAs2 at all: late binding
+                # raises AttributeError at attribute access (not a call
+                # TypeError) — so the net must catch AttributeError too.
+                if isinstance(exc, AttributeError) or _looks_like_arg_mismatch(exc):
+                    doc.SaveAs(target, wd_format)  # pre-2010 engines
+                else:
+                    raise
+        finally:
+            try:
+                doc.Close(WD_DO_NOT_SAVE_CHANGES)
+            except Exception:
+                pass
+
+    # -- per-engine worker (runs inside the try above) ----------------------
+
+    def _open_and_read(self, app: Any, engine_name: str, path: str) -> dict[str, Any]:
+        docs = app.Documents
+        try:
+            doc = docs.Open(
+                FileName=path,
+                ConfirmConversions=False,
+                ReadOnly=True,
+                AddToRecentFiles=False,
+                Visible=False,
+            )
+        except Exception as exc:
+            if _looks_encrypted(exc):
+                if file_claims_encrypted(path) is not False:
+                    raise PasswordProtectedError(path, engine_name) from None
+                raise OpenFailedError(path, engine_name, _short_exc(exc)) from None
+            if not _looks_like_arg_mismatch(exc):
+                raise
+            doc = docs.Open(path)  # minimal fallback for engines that reject named args
+
+        try:
+            pages = _g(lambda: doc.ComputeStatistics(WD_STAT_PAGES))
+            words = _g(lambda: doc.ComputeStatistics(WD_STAT_WORDS))
+            paragraphs = _g(lambda: doc.ComputeStatistics(WD_STAT_PARAGRAPHS))
+            protection_raw = _g(lambda: doc.ProtectionType, -1)
+            revisions = _g(lambda: doc.Revisions.Count, 0) or 0
+
+            fields_count = _g(lambda: doc.Fields.Count, 0) or 0
+            sample_codes: list[str] = []
+            for i in range(min(int(fields_count), 10)):
+                code = _g(lambda i=i: re.sub(r"\s+", " ", doc.Fields.Item(i + 1).Code.Text).strip())
+                if code:
+                    sample_codes.append(code)
+
+            bookmarks_count = _g(lambda: doc.Bookmarks.Count, 0) or 0
+            bookmark_names: list[str] = []
+            for i in range(min(int(bookmarks_count), 50)):
+                name = _g(lambda i=i: doc.Bookmarks.Item(i + 1).Name)
+                if name:
+                    bookmark_names.append(name)
+
+            protection = protection_raw if isinstance(protection_raw, int) else -1
+            return {
+                "opened_read_only": True,
+                "pages": pages,
+                "words": words,
+                "paragraphs": paragraphs,
+                "protection": _PROTECTION_MODES.get(protection, str(protection_raw)),
+                "has_unaccepted_revisions": bool(revisions),
+                "bookmarks": {"count": bookmarks_count, "names": bookmark_names},
+                "fields": {"count": fields_count, "sample_codes": sample_codes},
+            }
+        finally:
+            try:
+                doc.Close(WD_DO_NOT_SAVE_CHANGES)
+            except Exception:
+                pass