athena-python-docx 0.27.0__tar.gz → 0.29.0__tar.gz

{athena_python_docx-0.27.0 → athena_python_docx-0.29.0}/.gitignore

@@ -18,6 +18,8 @@ dist/
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/
+# The live parity runner's scoreboard and exports (python-sdk/tests/live/runner.py).
+/python-sdk/out/
 
 # Editors
 .vscode/

{athena_python_docx-0.27.0 → athena_python_docx-0.29.0}/AGENTS.md

@@ -25,6 +25,13 @@ Before adding or modifying any API surface:
 
 Run `uv run pytest tests/test_python_docx_api_parity.py -v -s` to verify parity.
 
+The API ratchet sees shape only. For behaviour, `uv run --extra dev python -m
+tests.live.runner --cases <name>` runs a battery case through stock
+python-docx 1.2.0 and through the SDK against a live in-memory DOCX Studio
+and compares what each reads, field by field (`tests/fidelity/METHODOLOGY.md`
+§ L9). CI fails on a live gap `tests/live/baseline.json` does not hold, and
+on a baseline gap that is gone.
+
 ### Intentionally omitted (current SDK limitations)
 
 These standard python-docx members don't apply to a DOCX Studio-backed SDK:
@@ -33,12 +40,14 @@ These standard python-docx members don't apply to a DOCX Studio-backed SDK:
 - `Document.part`, `Paragraph.part`, `Run.part` — package part access
 - `Document.settings` — Word app settings (not surfaced by DOCX Studio)
 - `InlineShape.chart` — charts are not currently surfaced by the SDK.
-- `Comment.add_paragraph` / `Comment.add_table` /
-  `Comment.iter_inner_content` / `Comment.paragraphs` /
-  `Comment.tables` — DOCX Studio models a comment as a single text body.
-  `Comment` is a `docx.blkcntnr.BlockItemContainer`, as `_Cell` and the
-  header/footer proxies are, but its paragraph/table-bearing surface raises
-  `CommentsNotImplementedError`. Use `Comment.text` instead.
+- `Comment.add_table` / `Comment.tables` — a DOCX Studio comment holds
+  paragraphs only. `Comment` is a `docx.blkcntnr.BlockItemContainer`, as
+  `_Cell` and the header/footer proxies are: `paragraphs`,
+  `add_paragraph`, `iter_inner_content` and `text` work as in python-docx
+  1.2.0 (the paragraphs list the comment's story, `blocks.list` with
+  `in: {storyType: "comment"}`, and `add_paragraph` sends
+  `CommentsParagraphAppend`), while `tables` is empty and `add_table`
+  raises `CommentsNotImplementedError`.
 - **`_Cell.add_table(rows, cols)`** — surface preserved for parity
   (signature matches python-docx, no `width` kwarg) but raises
   :class:`docx.errors.NestedTableNotSupportedError` (subclass of
@@ -181,22 +190,33 @@ not file-backed. Each is documented in the relevant docstring.
   on the other studios: `Workbook.workbook_id` (xlsx) and
   `Presentation.deck_id` (pptx).
 
-- **`Document.save(path_or_stream=None)`** — argument is optional and,
-  when supplied, raises
-  :class:`docx.errors.LocalSaveTargetNotSupportedError`. Stock
-  python-docx requires it and `TypeError`s on no-arg, but in an
-  asset-backed SDK there is no local file to write — writes are always
-  in-place against the Y.Doc. Forcing the upstream signature broke
-  every agent invocation that reflexively called `doc.save()` (a
-  near-universal Python pattern), so the no-arg form is supported.
-  When a path or stream IS supplied, the SDK cannot fulfill the
-  implied "write bytes to this target" contract, so the call raises
-  loudly rather than silently flushing — agents must use Olympus's
-  Export DOCX (which goes through the DOCX Studio session that already
-  has the bytes) instead of expecting a local file.
-
-- **`Document.track_revisions: bool`** — when `True`, all subsequent
-  mutations are recorded as tracked revisions instead of direct edits.
+- **`Document.save(path_or_stream=None)`** — the argument is optional.
+  Stock python-docx requires it and `TypeError`s on no-arg, but writes
+  are always in place against the Y.Doc, and forcing the upstream
+  signature broke every agent invocation that reflexively called
+  `doc.save()`, so the no-arg form flushes and writes no file. With a
+  path (`str` or `os.PathLike`) or a binary stream, `save` also writes
+  the document's `.docx` there, as python-docx does, through
+  `export_docx` (0.29.0+; earlier versions raised
+  `LocalSaveTargetNotSupportedError`, which stays importable).
+
+- **`Document.track_revisions: bool`** — when `True`, subsequent batches
+  are sent with `changeMode: "tracked"`, and docx-studio records their text
+  edits as Word revisions (`w:ins` / `w:del`): run and paragraph text,
+  `find_replace` in the body, new paragraphs and headings (an inserted
+  paragraph mark), tabs and line breaks, run formatting (`w:rPrChange`) and
+  `paragraph_format` properties (`w:pPrChange`). The replaced text stays, deleted,
+  and the new text follows it, so the SDK keeps its paragraph lengths and
+  run ranges that way (`docx/_tracked.py`): a tracked `run.text = value`
+  leaves the run over `value`, after its deleted text, and the paragraph
+  grows by `len(value)`. Every batch says so to docx-studio
+  (`client.capabilities: ["trackedAuthoring"]`); a docx-studio refuses a
+  tracked edit from an SDK that does not. A batch holding an edit it cannot
+  record yet (paragraph styles, tables, pictures, lists, sections, notes,
+  page breaks, header/footer/comment text) is refused (HTTP 422,
+  `TrackedChangesUnsupported`) and applies nothing; reads, exports,
+  comments and `TrackChangesDecide` run either way
+  (`DOCX_STUDIO_LIMITATIONS.md` § 32).
   python-docx upstream has no top-level toggle (the closest is
   hand-edited `<w:trackChanges/>` on `Document.settings.element`).
   We expose this as a Document-level property because every DOCX Studio
@@ -212,10 +232,12 @@ not file-backed. Each is documented in the relevant docstring.
   because the upstream package has no track-changes API at all.
 
 - **`Document.user_name: str | None` / `Document.user_email: str |
-  None`** — author identity threaded through to DOCX Studio on session-
-  open for tracked-change attribution; DOCX Studio bakes them into the
-  change records. Separate from `Document.core_properties.last_modified_by`,
-  the `docProps/core.xml` metadata the SDK reads and writes as python-docx
+  None`** — the name sent with each batch, which DOCX Studio uses as the
+  author of a comment that names none. It is not a tracked change's author:
+  DOCX Studio stamps those with the signed-in user agora's access check
+  names, so a script cannot choose who a redline's changes are by.
+  Separate from `Document.core_properties.last_modified_by`, the
+  `docProps/core.xml` metadata the SDK reads and writes as python-docx
   does.
 
 - **`Document.revisions: Revisions`** — collection of tracked changes
@@ -271,9 +293,10 @@ Issue numbers reference `python-openxml/python-docx`.
   `"FILENAME"`, `"NUMWORDS"`, `"REF"`, `"SEQ"`, `"TOC"`, and the
   generic `"FIELD"` escape hatch. python-docx has no field API
   whatsoever; issue #498 (page numbers) and #31 (23 comments) demand
-  this. `Fields` is sequence-like; `Fields.refresh_all(scope?)`
-  forces a recompute. Routes through `CreateField` / `FieldsRefresh`
-  / `FieldsList`.
+  this. `Fields` is sequence-like; `Fields.refresh_all(scope?)` updates
+  every unlocked REF and SEQ result as Word's F9 does (PAGE, PAGEREF
+  and TOC results depend on pages and stay). Routes through
+  `CreateField` / `FieldsRefresh` / `FieldsList`.
 
 - **`Document.bookmarks: Bookmarks`** + **`Paragraph.add_bookmark
   (name)`** + **`Document.add_bookmark(name, *, paragraph=None,
@@ -291,7 +314,9 @@ Issue numbers reference `python-openxml/python-docx`.
   `FootnotesGet` / `FootnotesPatch` / `FootnotesDelete`. The
   parallel **`Document.endnotes: Endnotes`** + **`Run.add_endnote
   (text, *, custom_mark=None)`** mirrors the same machinery for
-  end-of-section notes.
+  end-of-section notes. Both list the notes a reference reaches, as
+  Word and the export do: a note whose reference was deleted in the
+  editor stays in the package for undo, and is not listed.
 
 - **`Document.add_toc(*, levels=(1, 3), style_id=None,
   include_hyperlinks=True, title=None, tab_leader="dot", at=None)
@@ -418,6 +443,8 @@ Issue numbers reference `python-openxml/python-docx`.
   inspection. Use this when an agent needs to sample or inspect runs
   without issuing one ``getNodeById`` query per paragraph through
   ``doc.paragraphs`` + ``paragraph.runs``. Routes through `IterRuns`.
+  These three see a footnote or endnote only while a reference reaches
+  it, as `Document.footnotes` / `Document.endnotes` list them.
 
 - **`Paragraph.list_id` / `Paragraph.list_level` /
   `Paragraph.list_format` / `Paragraph.list_number`** — list-item
@@ -600,12 +627,10 @@ Issue numbers reference `python-openxml/python-docx`.
 
 - **`Document.export_docx(path=None, *, include_revisions=False)
   -> bytes`** (0.11.4+) — export the document's current state as
-  ``.docx`` bytes, optionally writing to ``path``. Closes the gap
-  left by ``Document.save(path)`` raising
-  ``LocalSaveTargetNotSupportedError`` in this SDK: parity test
-  harnesses and CI workflows need a programmatic .docx export to
-  diff against ``python-docx`` output that doesn't require a
-  human-driven Olympus UI action. Routes through ``ExportDocx`` →
+  ``.docx`` bytes, optionally writing to ``path``; ``Document.save(path_or_stream)``
+  writes its file through it. Parity test harnesses and CI workflows
+  use it to diff against ``python-docx`` output without a human-driven
+  Olympus UI action. Routes through ``ExportDocx`` →
   apps/api's backend export path. apps/api
   writes the session state to a temp ``.docx``, reads bytes back,
   base64-encodes for the wire, and unlinks the temp in a
@@ -614,6 +639,26 @@ Issue numbers reference `python-openxml/python-docx`.
   the current backend export path has no ``includeRevisions`` support,
   so honoring the flag isn't possible yet.
 
+  ``export_docx(path=None, *, include_revisions=False, clean=False,
+  clear_title=False)`` (0.29.0+): called with ``clean=True`` it returns a
+  clean copy for sending outside the firm instead, from
+  ``GET /docs/:id/export.docx?clean=1`` (VIEW gate): docx-studio imports
+  the export into an in-memory room, accepts every tracked change and
+  deletes every comment through the command runner, exports that room and
+  leaves out the author, last-modified-by, revision, company, manager,
+  template, editing-time and hyperlink-base properties, rsids, document
+  variables, custom properties, Custom XML (a content control bound to it
+  keeps its content, not its binding), the attached template and the
+  thumbnail; ``clear_title=True`` drops the title too. The live document is
+  not changed. The SDK refuses (``DocxUnsupportedCommandError``) an answer
+  without ``X-Docx-Clean-Copy: 1``, the plain export an older docx-studio
+  sends, and raises ``DocxError`` with docx-studio's reason when a header,
+  footer or note still holds a tracked change (the engine accepts the
+  body's only; ``DOCX_STUDIO_LIMITATIONS.md`` § 31). The in-process
+  post-export rewrites are applied to a clean copy as to a plain export,
+  and the copy is refused (``DocxError``) if they put revision, comment or
+  rsid markup back into ``word/document.xml``.
+
   Template seeding: ``Document.create()`` (no ``docx=``) already
   produces an exportable asset because ``POST /docs/empty`` seeds
   from the default Athena template, so ``export_docx`` works
@@ -904,6 +949,18 @@ architecture or a DOCX Studio constraint:
   but DOCX Studio's ProseMirror table node can't represent one; the SDK
   raises eagerly rather than failing opaquely on the wire.
 
+- **`Document.add_table` writes Athena's brand table.** Owner decision
+  (2026-10-12): keep the brand defaults. The table's layout is fixed, so
+  `Table.autofit` reads `False` (python-docx leaves autofit on); its columns
+  share 9,360 twips, where python-docx shares the section's text width; and
+  in the fixed layout a column width the script sets sizes the column's
+  cells too, where python-docx sets the `w:gridCol` alone. It also draws
+  borders and a zebra fill, which no python-docx read sees. Recorded as
+  `live_deviations` for the script cases' `tables.autofit`, `tables.widths`
+  and `tables.cell_format` in `tests/parity/intentional_deviations.json`;
+  an imported table's gaps stay gaps, and so do the two cases whose
+  `cell_format` also differs for another cause (`except`).
+
 - **`_Cell.merge` raises `InvalidSpanError` for every span that would cut
   through a merged cell.** It merges what python-docx merges and refuses
   what python-docx refuses (an L- or T-shaped pair of corners), but where
@@ -942,6 +999,18 @@ architecture or a DOCX Studio constraint:
   Keryx attributes the edit to the signed-in user (and agent), and
   nothing reads a comment's author as identity.
 
+- **A comment's paragraphs are in Word's comment style, which the export
+  defines.** python-docx 1.2.0's `add_comment` and `Comment.add_paragraph`
+  write `w:pStyle CommentText` (Word's built-in "annotation text", Comment
+  Text in Word's UI) without defining the style in `styles.xml`, so
+  python-docx reads those paragraphs as Normal. docx-studio writes the same
+  `w:pStyle` and defines the style as Word does: `Comment.paragraphs[i].style`
+  reads `Comment Text` (a built-in the document lacks reads back as that
+  built-in, as above), and the export adds Word's definition of the style and
+  of its linked `Comment Text Char` to `styles.xml`, so python-docx reads the
+  exported paragraph as `annotation text`. Owner decision, 2026-10-12.
+  Recorded in `tests/parity/intentional_deviations.json` (`live_deviations`).
+
 - **`ParagraphFormat.line_spacing_rule = None` warns-and-preserves on a
   clear** rather than raising (upstream accepts `None` to clear, but DOCX
   Studio's merging mutation ops have no single-attribute clear). It emits a
@@ -959,7 +1028,24 @@ architecture or a DOCX Studio constraint:
   given. `Run.add_tab()` and `Run.add_break()` take the run's formatting, as
   upstream appends them to the run's `w:r`; `Run.add_break(WD_BREAK.COLUMN)`
   sends a column break (`breakType: "column"`), which docx-studio writes after
-  the paragraph's content. `DOCX_STUDIO_LIMITATIONS.md` §26.
+  the paragraph's content. `DOCX_STUDIO_LIMITATIONS.md` §26. `Run.text` and
+  `Paragraph.text` leave a ruby's base text out (`w:ruby`, a phonetic guide
+  over its base text), as upstream reads only a run's own text elements, while
+  the base text keeps its room in the text-address space (`ruby` spans on the
+  read's run; `tests/test_ruby_reads_python_docx_parity.py`). That holds while
+  the paragraph's runs are as its records hold them, in the body, a table cell,
+  a header, a footer or a comment; a paragraph with a link or a tracked change
+  reads its runs from their marks, the base text included. A write to the run
+  (its text, an append, its formatting) makes the base text ordinary text,
+  which then reads as text: docx-studio keeps no guide through an edit, where
+  upstream keeps the `w:ruby` through all but a text write.
+
+- **`CoreProperties.modified` is the time of the last save.** The asset is a
+  live Word document, and docx-studio stamps `dcterms:modified` when it saves
+  a change to the package: a section, style or property write, and the export
+  of a changed document. Word stamps it on every save; upstream leaves the
+  value it read until the script sets it. Owner decision, 2026-10-12. Recorded
+  in `tests/parity/intentional_deviations.json` (`live_deviations`).
 
 - **Tracked changes read as Word's final view.** `Paragraph.text`, `runs`,
   `iter_inner_content()`, `Hyperlink.text` / `runs` and `_Cell.text` include
@@ -973,23 +1059,45 @@ architecture or a DOCX Studio constraint:
   Markup) show insertions and hide deletions, as these reads do.
   `doc.revisions` lists every change (`tests/test_run_text_python_docx.py`).
 
+- **A citation link Athena added reads as its text, as the export writes it**
+  (owner decision #40122). Athena's citation flow stamps the links it writes
+  with the `Athena citation` tooltip. These links only navigate inside Athena,
+  so the export leaves them out and keeps their text: no `w:hyperlink`, and no
+  citation highlight on that text.
+  - **The reads match the export.** The run reads with no `hyperlink` and no
+    highlight in `Paragraph.runs`, `Paragraph.hyperlinks`, a cell's paragraphs
+    and docx-studio's markdown read.
+  - **Where upstream differs.** Upstream reads the room's `w:hyperlink` as a
+    link.
+  - **Which links are Athena's** is decided by the room's provenance, not by
+    the tooltip alone. A link with the tooltip that came in the uploaded file
+    (the room's source package holds it) is a link everywhere, as Word keeps
+    it.
+  - **Tests:** `applier.test.ts` › `applier — citations`.
+
 - **A field's runs read as python-docx reads them; some writes to them
   differ.** `Paragraph.text` includes a complex field's displayed result and
   `Paragraph.runs` holds its begin, field code, separate, result and end runs
   (each with its own formatting), as python-docx reads the `w:r` children of
-  a `w:p`; a simple field (`w:fldSimple`) reads as nothing, and a field in a
-  link is the link's, as in python-docx. Each paragraph of a field that spans
+  a `w:p`; a simple field (`w:fldSimple`) reads as nothing (one in a tracked
+  change, which the export writes as a complex field, reads that field's
+  runs), a result run of a note reference reads `""`, and a field in a link
+  is the link's, as in python-docx. Each paragraph of a field that spans
   paragraphs (a table of contents) holds the field character runs it has
   (`tests/test_field_reads_python_docx_parity.py`, against stock python-docx
   on the same `.docx`; `DOCX_STUDIO_LIMITATIONS.md` § 27). A field takes no
   room in the text-address space, so its runs stand at one offset. Writes:
   - setting a result run's `.text` changes the field's displayed result,
-    as in python-docx (`Replace` with a `field` target), but the export
-    writes a changed result of several runs as one run, in the first run's
-    formatting, and a result run read before the field's result changed
-    (through another read's run, or by a collaborator) raises
-    `FieldRunWriteError` rather than write over that change, where
-    python-docx's run is live;
+    as in python-docx (`Replace` with a `field` target): the export keeps
+    the result's runs where the new text allows (text still there stays in
+    its run, new text goes in the run whose text it replaced; another result
+    run's tab or Word character stays as the source wrote it, and a note
+    reference stays where it is, where python-docx's write of its run would
+    delete it), but writes no result run left with no text, where
+    python-docx keeps an empty `w:r`, and a result run read before the
+    field's result changed (through another read's run, or by a
+    collaborator) raises `FieldRunWriteError` rather than write over that
+    change, where python-docx's run is live;
   - formatting a result run formats the field's whole result (`FormatApply`
     with a `field` target), from its source formatting, where python-docx
     formats that run alone;
@@ -1006,10 +1114,22 @@ architecture or a DOCX Studio constraint:
     `add_footnote`, `add_endnote`, `add_math` and `add_cross_reference` on
     any of a field's runs raise `FieldRunWriteError`; python-docx appends to
     that `w:r`.
-  A field that `Run.add_field` adds is a simple field, so it reads as no
-  runs and no text, though docx-studio's export writes it as a complex field.
-  Against a docx-studio that predates `fieldRun` reads, a field reads as no
-  runs and no text, as before (`tests/test_field_runs.py`).
+  A field that `Run.add_field` adds is a complex field, as Word's Insert
+  Field writes one, so its paragraph reads its runs, as python-docx reads the
+  exported file. Against a docx-studio that predates `fieldRun` reads, a
+  field reads as no runs and no text, as before (`tests/test_field_runs.py`).
+
+- **`Font.name = "…"` also clears the theme fonts of the two slots it
+  sets.** python-docx writes the name to `w:rFonts`' `w:ascii` and `w:hAnsi`
+  and leaves a `w:asciiTheme` / `w:hAnsiTheme` beside them; Word reads a
+  theme font over the name in its slot (ISO/IEC 29500-1 §17.3.2.26), so
+  after python-docx's write Word still shows the theme font. The SDK sets the
+  same two slots and docx-studio drops their theme fonts with them, so Word
+  shows the font that was set. The run's other slots (`w:eastAsia`, `w:cs`
+  and their theme fonts) and its `w:hint` stay as they were, as in
+  python-docx. The export writes exactly the slots the run's fonts hold
+  (#42248). Recorded in `tests/parity/intentional_deviations.json`
+  (`_comment_behavioral_deviations`).
 
 ### If you need a deviation
 
@@ -1052,6 +1172,15 @@ This is a **thin HTTP client** that mimics the sync python-docx API.
   the context-manager exit drain explicitly; `docx.flush_all()` is
   the executor-postamble hook that flushes every live buffer in the
   process.
+- A flush of more than 500 commands (`MAX_BATCH_COMMANDS`,
+  docx-studio's request cap) goes out as consecutive requests, and
+  docx-studio applies each all or nothing: when one fails, the requests
+  before it are saved and it and every later one are not. The
+  `DocxError` (0.29.0+) says how many of the flush's commands were
+  applied and names the failed one by its flush index; it carries
+  `unapplied_commands` and `failed_command`, and `partial_applied`
+  holds the saved requests' results. A retry re-applies the unapplied
+  edits, never the whole flush.
 - Execution scope: executor sandboxes may keep Python globals
   between tool calls so imports, constants, and helper functions can be
   reused. Live SDK objects are different. The executor calls

{athena_python_docx-0.27.0 → athena_python_docx-0.29.0}/PKG-INFO

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

{athena_python_docx-0.27.0 → athena_python_docx-0.29.0}/docx/__init__.py

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

athena_python_docx-0.29.0/docx/_batching.py

@@ -0,0 +1,137 @@
+"""Sync→async bridge. Runs a single event loop in a background thread
+and dispatches coroutines from sync callers.
+
+This is the only place in the SDK that uses threading.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import contextvars
+import threading
+from typing import Any, Coroutine, TypeVar
+
+from docx._timeouts import DEFAULT_OP_TIMEOUT_SECONDS
+from docx.errors import OperationTimeoutError
+
+T = TypeVar("T")
+
+_loop: asyncio.AbstractEventLoop | None = None
+_thread: threading.Thread | None = None
+_lock = threading.Lock()
+
+
+class _Progress:
+    """What the thread waiting on a call (:func:`run_sync`) and the call share:
+    the steps the call has finished, and whether the waiter gave up."""
+
+    __slots__ = ("abandoned", "steps")
+
+    def __init__(self) -> None:
+        self.steps = 0
+        self.abandoned = False
+
+
+_progress: contextvars.ContextVar[_Progress | None] = contextvars.ContextVar(
+    "docx_sdk_call_progress", default=None
+)
+
+
+def note_progress() -> None:
+    """A step of the running call finished: one batch of a flush that goes
+    out in several (``HttpClient.execute_batch``). :func:`run_sync` gives the
+    call its ``timeout`` again, so each batch has the budget its request has."""
+    progress = _progress.get()
+    if progress is not None:
+        progress.steps += 1
+
+
+def call_abandoned() -> bool:
+    """True once the caller of the running call timed out
+    (:class:`OperationTimeoutError`): a call of several steps starts no more."""
+    progress = _progress.get()
+    return progress is not None and progress.abandoned
+
+
+def _ensure_loop() -> asyncio.AbstractEventLoop:
+    """Return the persistent background event loop. Starts it lazily."""
+    global _loop, _thread
+
+    with _lock:
+        if _loop is not None and _loop.is_running():
+            return _loop
+
+        loop = asyncio.new_event_loop()
+        loop_ready = threading.Event()
+
+        def _run() -> None:
+            asyncio.set_event_loop(loop)
+            loop_ready.set()
+            loop.run_forever()
+
+        thread = threading.Thread(
+            target=_run,
+            name="docx-sdk-loop",
+            daemon=True,
+        )
+        thread.start()
+        loop_ready.wait(timeout=5)
+        _loop = loop
+        _thread = thread
+        return loop
+
+
+def run_sync(
+    coro: Coroutine[Any, Any, T],
+    *,
+    timeout: float | None = DEFAULT_OP_TIMEOUT_SECONDS,
+) -> T:
+    """Run a coroutine on the background loop and block until it returns.
+
+    Args:
+        coro: The coroutine to execute.
+        timeout: Maximum seconds to wait, counted again whenever the call
+            finishes a step (:func:`note_progress`). ``None`` blocks
+            indefinitely (use sparingly — prefer the default so stalls
+            surface early).
+
+    Raises:
+        OperationTimeoutError: if the coroutine neither completes nor
+            finishes a step within `timeout` seconds. The call then starts
+            no further step (:func:`call_abandoned`).
+        The coroutine's exception, re-raised in the calling thread.
+    """
+    loop = _ensure_loop()
+    progress = _Progress()
+    # The call runs in a copy of this thread's context (call_soon_threadsafe
+    # and the task each copy the current one), so it finds `progress`.
+    token = _progress.set(progress)
+    try:
+        future = asyncio.run_coroutine_threadsafe(coro, loop)
+    finally:
+        _progress.reset(token)
+    seen = 0
+    while True:
+        try:
+            return future.result(timeout=timeout)
+        except concurrent.futures.TimeoutError as exc:
+            if progress.steps > seen:
+                seen = progress.steps
+                continue
+            progress.abandoned = True
+            future.cancel()
+            raise OperationTimeoutError(timeout_seconds=timeout) from exc
+
+
+def shutdown() -> None:
+    """Stop the background event loop. For test teardown."""
+    global _loop, _thread
+    with _lock:
+        if _loop is None:
+            return
+        _loop.call_soon_threadsafe(_loop.stop)
+        if _thread is not None:
+            _thread.join(timeout=5)
+        _loop = None
+        _thread = None