athena-python-docx 0.7.0__tar.gz → 0.9.0__tar.gz

{athena_python_docx-0.7.0 → athena_python_docx-0.9.0}/CLAUDE.md

@@ -39,6 +39,18 @@ These standard python-docx members don't apply to a Superdoc-backed SDK:
   `Comment.tables` — SuperDoc models a comment as a single text body,
   not a `BlockItemContainer`. Use `Comment.text` instead. The
   paragraph/table-bearing surface raises `CommentsNotImplementedError`.
+- **`docx.oxml.*`** — the entire raw-OOXML module tree (``ns.qn``,
+  ``OxmlElement``, ``CT_*`` classes, etc.) is unavailable because the
+  SDK is HTTP-only against a SuperDoc Y.Doc; there is no local lxml
+  tree to manipulate. As of 0.8.0, ``docx.oxml`` is a real stub
+  package that raises a typed
+  :class:`docx.oxml.OxmlNotAvailableError` (subclass of
+  ``ImportError``) on any attribute access, with an inline pointer at
+  the high-level API (``Document.add_paragraph``, ``Run.bold``,
+  ``_Cell.text``, …) or the typed command surface in
+  ``docx.commands``. Pre-0.8.0 this used to fail with the stdlib's
+  generic ``ModuleNotFoundError: No module named 'docx.oxml'`` and
+  agents had to retry to discover the gap.
 
 ### Phase-3b upstream-blocked surface
 
@@ -149,13 +161,47 @@ This is a **thin HTTP client** that mimics the sync python-docx API.
   the context-manager exit drain explicitly; `docx.flush_all()` is
   the Daytona-prelude hook that flushes every live buffer in the
   process.
-- Other response-bearing ops without a client id (`Insert`,
-  `ListsCreate`, `ListsAttach`, `CommentsCreate`, `CommentsPatch`,
+- **Insert deferral (0.8.0+):** `Insert` was removed from the
+  response-bearing set because every in-tree caller
+  (`Paragraph._insert_run_text_segments`, `Run.add_text`, `_Cell.text`)
+  ignores the response — the Run proxy wraps a known client-side range
+  and doesn't need the server's echoed node id. Net result: a styled
+  run (one `add_run` + 6 format setters) ships as 1 HTTP request
+  instead of 2. The remaining response-bearing ops without a client id
+  (`ListsCreate`, `ListsAttach`, `CommentsCreate`, `CommentsPatch`,
   `TrackChangesDecide`) keep their eager-flush semantics so callers
   reading back ids still see real data. A `Document.add_paragraph`
   with `style="List Bullet"` flushes the queued CreateParagraph in
   the same batch as the follow-up `ListsCreate` — still one HTTP
   request per logical operation.
+- **Plain-text cell fast path (0.8.0+):** `_Cell.text = value` skips
+  the eager `doc.markdownToFragment` query when ``value`` contains no
+  markdown control characters (the dominant case for tabular data —
+  numbers, labels, currency strings). The fragment is built locally
+  and the follow-up `doc.insert` is buffered, so plain cell
+  assignments are 0 HTTP requests until the next flush. See
+  ``docx.table._is_plain_text`` for the trigger predicate.
+- **Partial-failure cascade fix (0.9.0+):** when an HTTP batch raises
+  on a 207 partial-failure (e.g. one cell-paragraph mistake mid-script),
+  the SDK now rewrites ``proxy_id_refs`` for the ``applied`` prefix
+  the server reports as successful — BEFORE re-raising. Pre-0.9.0 the
+  rewrite was inside the success-path-only branch, so every Create that
+  committed server-side left its Python proxy stuck on the client UUID;
+  the next batch shipped dead client UUIDs and the cascade restarted.
+  Preview-session ``thread_bafba02b`` turned one cell-paragraph error
+  into thirteen downstream "Block not found" failures + a
+  ``DOCUMENT_IDENTITY_CONFLICT`` before this fix. The path goes
+  ``_http_post_json`` (attaches ``applied[]`` via
+  ``DocxError.with_partial_applied``) → ``CommandBuffer.flush`` /
+  ``_eager_flush_with`` (catches ``DocxError``, drains the prefix
+  through ``_apply_proxy_id_rewrites``, re-raises). See
+  ``tests/test_partial_failure_cascade.py`` for the contract.
+- **Table-query hint (0.9.0+):** ``BlockNotFoundError`` on
+  ``TablesGet`` / ``TablesGetCells`` / etc. used to fall through with
+  no hint (the cell-paragraph workaround doesn't apply). Now carries
+  a dedicated "stale client-table-UUID" hint pointing at the actual
+  recovery (``doc.save()`` to drain pending + re-anchor proxies). See
+  ``_TABLE_CLIENT_ID_HINT`` in ``docx/_http_doc.py``.
 - The path-proxy in `_http_doc.py` is an internal translation layer:
   call sites that look like `await self._session.doc.create.paragraph(p)`
   resolve to `CommandBuffer.call(CreateParagraph(**p))`. Rewriting call

{athena_python_docx-0.7.0 → athena_python_docx-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.7.0
+Version: 0.9.0
 Summary: Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>

{athena_python_docx-0.7.0 → athena_python_docx-0.9.0}/docx/__init__.py

@@ -6,7 +6,7 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.7.0"
+__version__ = "0.9.0"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.7.0 → athena_python_docx-0.9.0}/docx/_buffer.py

@@ -35,11 +35,94 @@ from typing import TYPE_CHECKING, Any
 
 from docx import _ptc
 from docx.commands import Command, is_response_bearing, must_flush_immediately
+from docx.errors import DocxError
+
+
+def _apply_proxy_id_rewrites(
+    results: list[Any],
+    proxy_id_refs: "dict[str, list[tuple[object, str]]]",
+) -> None:
+    """Walk ``results`` and rewrite registered proxy ids from client UUIDs
+    to the real SuperDoc ids the applier echoed back.
+
+    Shared by the success path in :meth:`CommandBuffer.flush` /
+    :meth:`_eager_flush_with` AND by the **partial-failure recovery
+    path** (the SDK now reads ``DocxError.partial_applied`` on raise
+    and applies the same rewrite for the prefix that committed before
+    the server hit its first failure). Without this, every Create that
+    succeeded server-side would leave its Python proxy stuck on the
+    client UUID and the next batch would ship the dead id straight
+    back to the server — that cascade is what turned one cell-
+    paragraph mistake in preview-session ``thread_bafba02b`` into
+    thirteen downstream "Block not found" errors.
+
+    Tolerant of legacy / transitional applier results that don't
+    include ``client_node_id`` / ``real_node_id`` echoes — we simply
+    leave those proxies on their client id; the applier's per-batch
+    ``clientIdMap`` rewrite still resolves them server-side on the
+    *next* call.
+    """
+    if not proxy_id_refs:
+        return
+    for result in results:
+        if not isinstance(result, dict):
+            continue
+        for cli_key, real_key in (
+            ("client_node_id", "real_node_id"),
+            ("client_entity_id", "real_entity_id"),
+        ):
+            cli = result.get(cli_key)
+            real = result.get(real_key)
+            if not (isinstance(cli, str) and isinstance(real, str)):
+                continue
+            refs = proxy_id_refs.pop(cli, [])
+            for proxy, attr in refs:
+                try:
+                    setattr(proxy, attr, real)
+                except Exception:  # noqa: BLE001
+                    # A proxy that rejected setattr (slots without the
+                    # attr, frozen dataclass, etc.) silently keeps its
+                    # client_id — the applier's rewriter will still
+                    # resolve it correctly on the next batch.
+                    pass
+
+
+def _extract_partial_results(exc: BaseException) -> list[Any]:
+    """Pull per-command ``result`` dicts out of a partial-failure error.
+
+    The HTTP layer attaches the server's ``applied`` array to
+    :class:`DocxError` (and subclasses) as ``partial_applied``. Each
+    entry is the wire-format ``{index, type, result}`` triple. We
+    return just the ``result`` dicts so the rewrite path can share its
+    success-path code without caring whether it's running on a happy
+    batch or a salvaged prefix.
+    """
+    applied = getattr(exc, "partial_applied", None)
+    if not isinstance(applied, list):
+        return []
+    out: list[Any] = []
+    for entry in applied:
+        if isinstance(entry, dict):
+            result = entry.get("result")
+            if isinstance(result, dict):
+                out.append(result)
+    return out
 
 if TYPE_CHECKING:
     from docx._http_doc import HttpClient
 
 
+# Only commands whose class name is in this set produce PTC sub-tool-cards.
+# Every Command subclass is a candidate, but each emit is now a synchronous
+# HTTP POST to agora (see ``_ptc._send``), so emitting one card per low-level
+# mutation produces hundreds of sub-cards per script and pays full network
+# RTT on every one. The allow-list keeps the per-action signal — one card
+# per logical paragraph creation — without the spam or the cumulative
+# latency. Asset-level creation events (``CreateDocument``) are emitted
+# from ``Document.create`` directly, not through this buffer path.
+_PTC_EMIT_TOOLS: frozenset[str] = frozenset({"CreateParagraph"})
+
+
 def _ptc_emit_end_batch(cmds: list[Command], *, is_error: bool) -> None:
     """Emit a PTC ``end`` event for every cmd that received a ``begin``.
 
@@ -85,9 +168,7 @@ def _unregister(buffer: "CommandBuffer") -> None:
     """
     with _registry_lock:
         _active_buffers[:] = [
-            ref
-            for ref in _active_buffers
-            if (b := ref()) is not None and b is not buffer
+            ref for ref in _active_buffers if (b := ref()) is not None and b is not buffer
         ]
 
 
@@ -170,14 +251,10 @@ class CommandBuffer:
         # real nodeId after flush. Populated by ``add_paragraph`` /
         # ``add_heading`` / etc. when they queue a Create with a
         # client-assigned id. Drained on every flush.
-        self._proxy_id_refs: dict[
-            str, list[tuple[object, str]]
-        ] = {}
+        self._proxy_id_refs: dict[str, list[tuple[object, str]]] = {}
         _register(self)
 
-    def register_proxy_id_ref(
-        self, client_id: str, proxy: object, attr: str = "_node_id"
-    ) -> None:
+    def register_proxy_id_ref(self, client_id: str, proxy: object, attr: str = "_node_id") -> None:
         """Register that ``proxy.<attr>`` should be rewritten from
         ``client_id`` to the real node id once the queue flushes.
 
@@ -215,9 +292,7 @@ class CommandBuffer:
         ``"direct"``, ``"tracked"``, or ``None`` to clear.
         """
         if mode is not None and mode not in ("direct", "tracked"):
-            raise ValueError(
-                f"change_mode must be 'direct', 'tracked', or None; got {mode!r}"
-            )
+            raise ValueError(f"change_mode must be 'direct', 'tracked', or None; got {mode!r}")
         with self._lock:
             current = self._change_mode
         if current == mode:
@@ -269,16 +344,19 @@ class CommandBuffer:
                 f"CommandBuffer for {self._asset_id} is closed",
             )
 
-        # PTC begin: one event per user-facing method call, before any
-        # batching. Failures here can't crash the user's code path.
-        try:
-            cmd._ptc_call_id = _ptc.emit_begin(  # type: ignore[attr-defined]
-                type(cmd).__name__,
-                cmd.to_dict(),
-                asset_id=self._asset_id,
-            )
-        except Exception:  # noqa: BLE001
-            pass
+        # PTC begin: emit only for commands in the allow-list. Other
+        # commands still flow through the buffer (and through the batched
+        # HTTP POST), they just don't produce a sub-tool-card. ``emit_end``
+        # is automatically skipped because no ``_ptc_call_id`` was set.
+        if type(cmd).__name__ in _PTC_EMIT_TOOLS:
+            try:
+                cmd._ptc_call_id = _ptc.emit_begin(  # type: ignore[attr-defined]
+                    type(cmd).__name__,
+                    cmd.to_dict(),
+                    asset_id=self._asset_id,
+                )
+            except Exception:  # noqa: BLE001
+                pass
 
         if must_flush_immediately(cmd) and not self._has_client_id(cmd):
             return self._eager_flush_with(cmd)
@@ -300,12 +378,9 @@ class CommandBuffer:
         legacy callers) keep their eager-flush semantics so callers
         that read the response still see real data.
         """
-        return (
-            is_response_bearing(cmd)
-            and (
-                getattr(cmd, "client_node_id", None) is not None
-                or getattr(cmd, "client_entity_id", None) is not None
-            )
+        return is_response_bearing(cmd) and (
+            getattr(cmd, "client_node_id", None) is not None
+            or getattr(cmd, "client_entity_id", None) is not None
         )
 
     def flush(self) -> list[Any]:
@@ -339,37 +414,22 @@ class CommandBuffer:
                 change_mode=change_mode,
                 user=user,
             )
+        except DocxError as exc:
+            # Partial-failure cascade protection: even though the batch
+            # raised, the server's ``applied`` prefix tells us which
+            # commands DID commit before the failure. Rewrite the
+            # corresponding proxy ids before re-raising so the next
+            # batch ships REAL ids for the survivors (vs. dead client
+            # UUIDs that would cascade into another "Block not found").
+            # See ``_apply_proxy_id_rewrites`` for the full rationale.
+            _apply_proxy_id_rewrites(_extract_partial_results(exc), proxy_id_refs)
+            _ptc_emit_end_batch(pending, is_error=True)
+            raise
         except Exception:
             _ptc_emit_end_batch(pending, is_error=True)
             raise
         _ptc_emit_end_batch(pending, is_error=False)
-        # Rewrite registered proxies from client-side UUIDs to the real
-        # SuperDoc ids the applier echoed back. Defensive: tolerate
-        # missing fields (legacy or transitional applier without the
-        # client-id support).
-        if proxy_id_refs:
-            for result in results:
-                if not isinstance(result, dict):
-                    continue
-                for cli_key, real_key in (
-                    ("client_node_id", "real_node_id"),
-                    ("client_entity_id", "real_entity_id"),
-                ):
-                    cli = result.get(cli_key)
-                    real = result.get(real_key)
-                    if not (isinstance(cli, str) and isinstance(real, str)):
-                        continue
-                    refs = proxy_id_refs.pop(cli, [])
-                    for proxy, attr in refs:
-                        try:
-                            setattr(proxy, attr, real)
-                        except Exception:  # noqa: BLE001
-                            # A proxy that rejected setattr (slots without
-                            # the attr, frozen dataclass, etc.) silently
-                            # keeps its client_id — the rewriter in the
-                            # applier will still resolve it correctly
-                            # for the next batch.
-                            pass
+        _apply_proxy_id_rewrites(results, proxy_id_refs)
         return results
 
     def close(self) -> None:
@@ -409,30 +469,22 @@ class CommandBuffer:
                 change_mode=change_mode,
                 user=user,
             )
+        except DocxError as exc:
+            # Same partial-failure cascade protection as :meth:`flush` —
+            # rewrite proxy ids for the prefix the server reports as
+            # ``applied`` before re-raising. Critical here because the
+            # eager-flush path is hit by every query in user code (e.g.
+            # ``table.cell(0, 0)`` → ``tables.get``), so a failure on
+            # the trailing ``cmd`` would otherwise abandon every
+            # buffered Create's rewrite at once.
+            _apply_proxy_id_rewrites(_extract_partial_results(exc), proxy_id_refs)
+            _ptc_emit_end_batch(all_cmds, is_error=True)
+            raise
         except Exception:
             _ptc_emit_end_batch(all_cmds, is_error=True)
             raise
         _ptc_emit_end_batch(all_cmds, is_error=False)
-        # Apply the same proxy-rewrite pass as ``flush()`` — see comment
-        # there for the contract.
-        if proxy_id_refs:
-            for result in results:
-                if not isinstance(result, dict):
-                    continue
-                for cli_key, real_key in (
-                    ("client_node_id", "real_node_id"),
-                    ("client_entity_id", "real_entity_id"),
-                ):
-                    cli = result.get(cli_key)
-                    real = result.get(real_key)
-                    if not (isinstance(cli, str) and isinstance(real, str)):
-                        continue
-                    refs = proxy_id_refs.pop(cli, [])
-                    for proxy, attr in refs:
-                        try:
-                            setattr(proxy, attr, real)
-                        except Exception:  # noqa: BLE001
-                            pass
+        _apply_proxy_id_rewrites(results, proxy_id_refs)
         if not results:
             return {}
         return results[-1]

{athena_python_docx-0.7.0 → athena_python_docx-0.9.0}/docx/_http_doc.py

@@ -112,6 +112,7 @@ from docx.commands import (
 )
 from docx.errors import (
     AuthenticationError,
+    BlockNotFoundError,
     DocxError,
     NotFoundError,
     SessionError,
@@ -134,6 +135,124 @@ _NOT_FOUND_ERROR_NAMES: frozenset[str] = frozenset(
 )
 
 
+def _looks_like_block_not_found(err_obj: dict) -> bool:
+    """Detect SuperDoc's ``Block "<type>:<id>" was not found`` shape.
+
+    Triggers the typed :class:`BlockNotFoundError` so agent code can
+    distinguish a missing-block miss (cell-inner-paragraph addressing
+    bug, stale id from a different session) from a generic transport
+    or validation error.
+    """
+    msg = err_obj.get("message")
+    if not isinstance(msg, str):
+        return False
+    lower = msg.lower()
+    if "not found" not in lower:
+        return False
+    # Be conservative: require either ``block "`` (the SuperDoc CLI's
+    # quoted-id format) or ``block <id>`` followed by ``not found``.
+    return 'block "' in lower or ('block ' in lower and ' was not found' in lower)
+
+
+# Commands that target a paragraph block (or its inline range) and
+# therefore trip the SuperDoc 1.8.1 cell-paragraph addressing gap when
+# the target paragraph is nested inside a ``tableCell``. Used by the
+# ``BlockNotFoundError`` hint logic to decide whether to surface the
+# materialization workaround. Membership is checked against the
+# ``err_obj["type"]`` field that ``apps/api`` echoes back on partial
+# failure, so the gate covers both error-message shapes the SuperDoc
+# CLI emits:
+#
+# * ``Block "paragraph:<uuid>" was not found.`` (SetParagraph*, etc.)
+# * ``Block "<uuid>" not found.``                (Insert)
+#
+# Without this gate, the hint either fired for stale-id misses on
+# unrelated command types (Greptile #20555) or skipped the Insert form
+# entirely (preview session
+# thread_b952794f, where 3 of 4 failures were bare-UUID Inserts and
+# the agent burned 4 retries without ever seeing the workaround).
+_PARAGRAPH_TARGETING_COMMANDS: frozenset[str] = frozenset(
+    {
+        "Insert",
+        "FormatApply",
+        "SetParagraphAlignment",
+        "ClearParagraphAlignment",
+        "SetParagraphStyle",
+        "SetParagraphIndentation",
+        "ClearParagraphIndentation",
+        "SetParagraphSpacing",
+        "ClearParagraphSpacing",
+        "SetParagraphKeepOptions",
+        "SetParagraphFlowOptions",
+        "SetParagraphTabStop",
+        "ClearParagraphTabStops",
+        "Replace",
+        "InsertLineBreak",
+        "InsertTab",
+    }
+)
+
+
+_CELL_PARAGRAPH_HINT: str = (
+    "\n\nHint: SuperDoc 1.8.1 cannot format paragraphs nested inside "
+    "table cells via SetParagraphAlignment / SetParagraphStyle / "
+    "SetParagraphIndentation / SetParagraphSpacing / doc.insert with "
+    "a paragraph-block target, or any FormatApply on a cell-inner run. "
+    "The cell's inner paragraph id is returned by cell.getNodeById but "
+    "isn't a top-level addressable block. Materialize the cell's "
+    'paragraph first via ``cell.text = "value"``, then re-read '
+    "``cell.paragraphs[0]`` and apply format ops to that post-"
+    "materialization Paragraph proxy. Tracked upstream at "
+    "docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md § 'cell-inner paragraph "
+    "addressing'."
+)
+
+
+# ``tables.get`` / ``tables.getCells`` / ``tables.getProperties`` carry
+# the table id at the top-level ``nodeId`` field — and the agent code
+# that triggers them (``table.cell(0, 0)``, ``table.rows``, etc.) runs
+# *immediately* after ``doc.add_table(...)``. The first such query
+# triggers an eager flush that drains the buffered CreateTable in the
+# same HTTP batch, so the applier's per-batch ``clientIdMap`` rewrite
+# normally catches it. But when an EARLIER batch (e.g. a doomed cell-
+# paragraph mutation a few lines up in the user script) raised before
+# the SDK could rewrite ``proxy_id_refs``, the Table proxy still holds
+# the client UUID. The next batch ships the dead id straight to SuperDoc
+# and we land here. The hint points the agent at the canonical recovery
+# pattern (force a save() to reseat the proxy refs, or split the
+# offending mutation into its own execution).
+_TABLE_QUERY_COMMANDS: frozenset[str] = frozenset(
+    {
+        "TablesGet",
+        "TablesGetCells",
+        "TablesGetProperties",
+        "TablesSetStyle",
+        "TablesSetLayout",
+        "TablesSetTableOptions",
+        "TablesSetCellProperties",
+        "TablesSetColumnWidth",
+        "TablesSetRowHeight",
+        "TablesInsertRow",
+        "TablesInsertColumn",
+        "TablesMergeCells",
+    }
+)
+
+
+_TABLE_CLIENT_ID_HINT: str = (
+    "\n\nHint: this looks like a stale client-side table UUID "
+    '(``t_xxxxxxxxxxxx``). Either an earlier batch in this execution '
+    "raised before the SDK could rewrite the Table proxy's id from the "
+    "client UUID to the real SuperDoc id, OR the table belongs to a "
+    "prior execution whose state has been discarded. Recover by calling "
+    "``doc.save()`` to drain pending mutations + re-anchor live "
+    "proxies, then re-query via ``doc.tables`` to get fresh proxies "
+    "with real ids. If you saw a cell-paragraph error in the same "
+    "execution, address that first — its partial-failure is what "
+    "abandoned the rewrite."
+)
+
+
 def _looks_like_not_found(parsed: dict) -> bool:
     """Inspect a docx-studio partial-failure dict and decide whether it
     describes a "no such entity" miss (vs. a real transport / validation
@@ -280,19 +399,69 @@ def _http_post_json(
             parsed = json.loads(body) if body else {}
         except json.JSONDecodeError:
             parsed = {"raw": body}
+        # Extract the ``applied`` prefix so callers can rewrite
+        # ``proxy_id_refs`` for commands that DID succeed before the
+        # batch hit its first failure. Without this, the SDK throws
+        # away every successful Create's client-UUID → real-id mapping
+        # the moment ONE command fails, and the next batch keeps
+        # shipping dead client UUIDs. That cascade turned the preview-
+        # session thread_bafba02b's first cell-paragraph mistake into
+        # thirteen downstream "Block not found" errors and finally a
+        # ``DOCUMENT_IDENTITY_CONFLICT``. The structure is wire-shape:
+        # ``[{index, type, result: {client_node_id, real_node_id, …}}]``.
+        applied_raw = parsed.get("applied") if isinstance(parsed, dict) else None
+        partial_applied: list[dict] = []
+        if isinstance(applied_raw, list):
+            partial_applied = [a for a in applied_raw if isinstance(a, dict)]
         # If the failing command's error looks like "no such entity",
         # raise a typed :class:`NotFoundError` so speculative-read call
         # sites (``Comments.get``) can coerce it to ``None`` without
         # swallowing real transport / validation failures.
         err_obj = parsed.get("error") if isinstance(parsed, dict) else None
-        if isinstance(err_obj, dict) and _looks_like_not_found(err_obj):
-            raise NotFoundError(
-                f"docx-studio batch reported a partial failure: {parsed!r}",
-                payload=err_obj,
-            )
+        if isinstance(err_obj, dict):
+            base_msg = f"docx-studio batch reported a partial failure: {parsed!r}"
+            # ``BlockNotFoundError`` is the narrower miss — caller is most
+            # likely targeting a cell-inner paragraph or stale-session
+            # block id. Surface the typed exception plus an agent-readable
+            # workaround so the next attempt doesn't repeat the same
+            # mistake.
+            #
+            # The cell-paragraph hint applies when the failing command is
+            # a paragraph-targeting op (Insert, FormatApply, SetParagraph*,
+            # …). We can't gate on the ``paragraph:`` prefix alone — the
+            # bare-UUID ``Block "<uuid>" not found.`` shape that SuperDoc's
+            # CLI emits for ``Insert`` failures is the dominant form of
+            # this bug in practice (preview-session thread_b952794f hit
+            # it 3 of 4 times without ever seeing the workaround under the
+            # prefix-only gate).
+            if _looks_like_block_not_found(err_obj):
+                cmd_type = err_obj.get("type")
+                paragraph_targeting = (
+                    isinstance(cmd_type, str)
+                    and cmd_type in _PARAGRAPH_TARGETING_COMMANDS
+                )
+                table_query = (
+                    isinstance(cmd_type, str)
+                    and cmd_type in _TABLE_QUERY_COMMANDS
+                )
+                if paragraph_targeting:
+                    hint = _CELL_PARAGRAPH_HINT
+                elif table_query:
+                    hint = _TABLE_CLIENT_ID_HINT
+                else:
+                    hint = ""
+                raise BlockNotFoundError(
+                    base_msg + hint,
+                    payload=err_obj,
+                ).with_partial_applied(partial_applied)
+            if _looks_like_not_found(err_obj):
+                raise NotFoundError(
+                    base_msg,
+                    payload=err_obj,
+                ).with_partial_applied(partial_applied)
         raise DocxError(
             f"docx-studio batch reported a partial failure: {parsed!r}",
-        )
+        ).with_partial_applied(partial_applied)
 
     if 200 <= resp.status_code < 300:
         try: