changex-core 0.1.0__tar.gz

changex_core-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+
+# Node / Tauri
+node_modules/
+packages/viewer/dist/
+packages/viewer/src-tauri/target/
+
+# OS
+.DS_Store
+
+# Local editor/agent settings
+.claude/settings.local.json
+
+# ChangeX working artifacts
+*.changex.tmp
+examples/out/
+
+# stray sample journals (regenerate via make demo)
+examples/*.changex
+
+# Tauri generated icons (regenerated by `tauri icon` / the desktop workflow)
+packages/viewer/src-tauri/icons/32x32.png
+packages/viewer/src-tauri/icons/128x128.png
+packages/viewer/src-tauri/icons/128x128@2x.png
+packages/viewer/src-tauri/icons/icon.icns
+packages/viewer/src-tauri/icons/icon.ico
+packages/viewer/src-tauri/icons/Square*.png
+packages/viewer/src-tauri/icons/StoreLogo.png
+packages/viewer/src-tauri/icons/_source.png

changex_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ario Moniri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

changex_core-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: changex-core
+Version: 0.1.0
+Summary: ChangeX core: canonical document model, append-only provenance journal, and the docx native-revisions adapter (M0 spine).
+Author: ChangeX
+License: MIT
+License-File: LICENSE
+Keywords: csv,docx,event-sourcing,ooxml,pptx,provenance,track-changes,xlsx
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Office Suites
+Requires-Python: >=3.11
+Requires-Dist: lxml>=4.9.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: python-docx>=1.1.0
+Requires-Dist: python-pptx>=0.6.21
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# changex-core
+
+Core of **ChangeX** — the provenance-first edit-tracking spine (roadmap M0).
+
+This package contains, with **no network access** and **no MCP dependency**:
+
+- **`changex_core.model`** — a canonical, addressable document-node tree whose
+  `node_id` is an *opaque, edit-invariant* identifier (NOT a content hash). For
+  docx paragraphs it reuses Word's native `w14:paraId`; for nodes lacking a native
+  id it mints a monotonic per-session counter. A content+position fingerprint is
+  demoted to a *fallback rebind anchor* used only for fuzzy re-resolution.
+- **`changex_core.ops`** — the frozen **v0.1 op vocabulary** (docx-only):
+  `text.insert`, `text.delete`, `text.replace`, `node.insert`, `node.delete`,
+  `style.change`. Offsets are *node-relative* and *seq-ordered*; `before` substrings
+  are validated against current node content.
+- **`changex_core.journal`** — the append-only JSONL `.changex` journal with an
+  RFC 8785 (JCS) canonicalized **sha256 hash chain**, plus `append`, `read`,
+  `replay`, `verify`, and `revert`.
+- **`changex_core.adapters`** — the `DocumentAdapter` contract and the **docx
+  adapter** that loads a `.docx`, applies the v0.1 ops, and renders **native Word
+  revisions** (`<w:ins>` / `<w:del>` / `<w:delText>` / `<w:pPrChange>`) with
+  centrally-allocated unique `w:id`, `w:author = <model name>`, and `w:date`.
+- **`changex_core.render`** — an HTML/markdown redline projection of the journal.
+- **`changex_core.baseline`** — a baseline snapshot + out-of-band mismatch warning.
+- **`changex_core.cli`** — a thin CLI (`changex track / review / verify`) that
+  exercises the spine for the M0 script-based acceptance test.
+
+## Threat model (hash chain)
+
+The hash chain gives **tamper-evidence** for accidental corruption and naive
+tampering only. An attacker who controls the `.changex` can recompute the whole
+chain. Adversarial integrity requires out-of-band storage or signing (deferred to
+M6).

changex_core-0.1.0/README.md

@@ -0,0 +1,33 @@
+# changex-core
+
+Core of **ChangeX** — the provenance-first edit-tracking spine (roadmap M0).
+
+This package contains, with **no network access** and **no MCP dependency**:
+
+- **`changex_core.model`** — a canonical, addressable document-node tree whose
+  `node_id` is an *opaque, edit-invariant* identifier (NOT a content hash). For
+  docx paragraphs it reuses Word's native `w14:paraId`; for nodes lacking a native
+  id it mints a monotonic per-session counter. A content+position fingerprint is
+  demoted to a *fallback rebind anchor* used only for fuzzy re-resolution.
+- **`changex_core.ops`** — the frozen **v0.1 op vocabulary** (docx-only):
+  `text.insert`, `text.delete`, `text.replace`, `node.insert`, `node.delete`,
+  `style.change`. Offsets are *node-relative* and *seq-ordered*; `before` substrings
+  are validated against current node content.
+- **`changex_core.journal`** — the append-only JSONL `.changex` journal with an
+  RFC 8785 (JCS) canonicalized **sha256 hash chain**, plus `append`, `read`,
+  `replay`, `verify`, and `revert`.
+- **`changex_core.adapters`** — the `DocumentAdapter` contract and the **docx
+  adapter** that loads a `.docx`, applies the v0.1 ops, and renders **native Word
+  revisions** (`<w:ins>` / `<w:del>` / `<w:delText>` / `<w:pPrChange>`) with
+  centrally-allocated unique `w:id`, `w:author = <model name>`, and `w:date`.
+- **`changex_core.render`** — an HTML/markdown redline projection of the journal.
+- **`changex_core.baseline`** — a baseline snapshot + out-of-band mismatch warning.
+- **`changex_core.cli`** — a thin CLI (`changex track / review / verify`) that
+  exercises the spine for the M0 script-based acceptance test.
+
+## Threat model (hash chain)
+
+The hash chain gives **tamper-evidence** for accidental corruption and naive
+tampering only. An attacker who controls the `.changex` can recompute the whole
+chain. Adversarial integrity requires out-of-band storage or signing (deferred to
+M6).

changex_core-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "changex-core"
+version = "0.1.0"
+description = "ChangeX core: canonical document model, append-only provenance journal, and the docx native-revisions adapter (M0 spine)."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "ChangeX" }]
+keywords = ["docx", "xlsx", "pptx", "csv", "track-changes", "provenance", "ooxml", "event-sourcing"]
+classifiers = [
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Office/Business :: Office Suites",
+]
+dependencies = [
+    "python-docx>=1.1.0",
+    "lxml>=4.9.0",
+    # v0.2 format adapters (phase-2): xlsx/csv use openpyxl, pptx uses python-pptx.
+    # Declared here so the phase-2 adapter agents never need to touch pyproject.
+    "openpyxl>=3.1.0",
+    "python-pptx>=0.6.21",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.1",
+    "mypy>=1.5",
+]
+
+[project.scripts]
+changex = "changex_core.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/changex_core"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/changex_core", "README.md"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_ignores = true
+ignore_missing_imports = true

changex_core-0.1.0/src/changex_core/__init__.py

@@ -0,0 +1,177 @@
+"""ChangeX core (M0 spine): canonical model, provenance journal, docx adapter.
+
+Public API (the surface other packages — ``changex-mcp``, the CLI — code against):
+
+Model
+    ``Node``, ``NodeKind``, ``NodeIdAllocator``, ``AnchorFingerprint``,
+    ``rebind`` — addressable nodes with opaque, edit-invariant ids.
+
+Ops (frozen v0.2)
+    docx: ``TextInsert``, ``TextDelete``, ``TextReplace``, ``NodeInsert``,
+    ``NodeDelete``, ``StyleChange``. xlsx/csv: ``CellSet``, ``FormulaSet``,
+    ``RowInsert``, ``RowDelete``. pptx: ``SlideInsert``, ``SlideDelete``,
+    ``ShapeEdit``. Plus ``op_from_dict`` / ``op_to_dict`` and ``validate_op``.
+    (``format.run`` / ``node.move`` remain reserved.)
+
+Journal
+    ``Journal`` (append / read / replay / verify / revert), ``Header``,
+    ``Event``, ``Provenance``, ``Target``, ``VerifyResult``, and the
+    canonicalization primitives ``canonicalize`` / ``chain_hash``.
+
+Adapters
+    ``DocumentAdapter`` (the contract), ``DocxAdapter`` (native Word
+    revisions), and ``load_adapter`` (the extension-keyed factory that lazily
+    imports the right adapter for ``.docx`` / ``.xlsx`` / ``.csv`` / ``.pptx``),
+    plus the boundary errors ``BeforeMismatchError`` / ``OversizedOpError``.
+
+Render / baseline
+    ``render_html`` / ``render_markdown`` and ``snapshot`` /
+    ``check_out_of_band``.
+"""
+
+from __future__ import annotations
+
+from changex_core.adapters import load_adapter
+from changex_core.adapters.base import (
+    AdapterError,
+    BeforeMismatchError,
+    DocumentAdapter,
+    NodeNotFoundError,
+    OversizedOpError,
+    UnsupportedFormatError,
+)
+from changex_core.adapters.docx_adapter import DocxAdapter
+from changex_core.baseline import (
+    Baseline,
+    OutOfBandWarning,
+    check_out_of_band,
+    snapshot,
+)
+from changex_core.journal.canonical import canonicalize, chain_hash, sha256_hex
+from changex_core.journal.events import Event, Header, Provenance, Target
+from changex_core.journal.journal import Journal, JournalError, VerifyResult
+from changex_core.model.addressing import (
+    AnchorFingerprint,
+    NodeIdAllocator,
+    RebindResult,
+    rebind,
+)
+from changex_core.model.nodes import Node, NodeKind
+from changex_core.ops.vocabulary import (
+    OP_SCHEMA_VERSION,
+    CellSet,
+    FormulaSet,
+    NodeDelete,
+    NodeInsert,
+    Op,
+    ReservedOpError,
+    RowDelete,
+    RowInsert,
+    ShapeEdit,
+    SlideDelete,
+    SlideInsert,
+    StyleChange,
+    TextDelete,
+    TextInsert,
+    TextReplace,
+    UnknownOpError,
+    op_from_dict,
+    op_to_dict,
+    target_node_id,
+)
+from changex_core.diff.text_diff import (
+    ParagraphSpec,
+    ReconstructedOp,
+    diff_paragraphs,
+    reconstruct_ops,
+)
+from changex_core.ops.validation import SchemaValidationError, validate_op
+from changex_core.passive import (
+    OpenResult,
+    SealResult,
+    open_passive,
+    seal_passive,
+)
+from changex_core.render.document import render_document_html
+from changex_core.render.html import render_html, render_markdown
+from changex_core.render.save import save_active, save_active_from_path
+from changex_core.render.server import build_server, serve
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # model
+    "Node",
+    "NodeKind",
+    "NodeIdAllocator",
+    "AnchorFingerprint",
+    "RebindResult",
+    "rebind",
+    # ops (docx, v0.1)
+    "Op",
+    "TextInsert",
+    "TextDelete",
+    "TextReplace",
+    "NodeInsert",
+    "NodeDelete",
+    "StyleChange",
+    # ops (xlsx/csv + pptx, v0.2)
+    "CellSet",
+    "FormulaSet",
+    "RowInsert",
+    "RowDelete",
+    "SlideInsert",
+    "SlideDelete",
+    "ShapeEdit",
+    "OP_SCHEMA_VERSION",
+    "op_from_dict",
+    "op_to_dict",
+    "target_node_id",
+    "validate_op",
+    "SchemaValidationError",
+    "ReservedOpError",
+    "UnknownOpError",
+    # journal
+    "Journal",
+    "JournalError",
+    "VerifyResult",
+    "Header",
+    "Event",
+    "Provenance",
+    "Target",
+    "canonicalize",
+    "chain_hash",
+    "sha256_hex",
+    # adapters
+    "DocumentAdapter",
+    "DocxAdapter",
+    "load_adapter",
+    "AdapterError",
+    "BeforeMismatchError",
+    "OversizedOpError",
+    "NodeNotFoundError",
+    "UnsupportedFormatError",
+    # render / baseline
+    "render_html",
+    "render_markdown",
+    "render_document_html",
+    "Baseline",
+    "OutOfBandWarning",
+    "snapshot",
+    "check_out_of_band",
+    # render: journal-aware save + interactive review server
+    "save_active",
+    "save_active_from_path",
+    "build_server",
+    "serve",
+    # passive ("native to any model") capture + diff reconstruction
+    "open_passive",
+    "seal_passive",
+    "OpenResult",
+    "SealResult",
+    "ParagraphSpec",
+    "ReconstructedOp",
+    "diff_paragraphs",
+    "reconstruct_ops",
+]

changex_core-0.1.0/src/changex_core/adapters/__init__.py

@@ -0,0 +1,156 @@
+"""Document adapters: the contract, the docx implementation, and the registry.
+
+The :class:`~changex_core.adapters.base.DocumentAdapter` ABC is the anti-drift
+contract every format adapter implements. This package also owns the **format
+registry + factory** (:func:`load_adapter`) that resolves a file path to the
+adapter that handles its extension.
+
+Lazy import is load-bearing
+---------------------------
+The registry maps an extension to a ``"module:ClassName"`` target string and
+imports the module **only when that format is actually loaded**. Concretely the
+xlsx/csv/pptx adapter modules are created by phase-2 agents and may not exist (or
+may pull heavy third-party deps like ``openpyxl`` / ``python-pptx``) when this
+package is imported. Importing them eagerly here would (a) crash ``import
+changex_core`` before phase-2 lands and (b) force every consumer to install every
+format's dependencies. So this module **must not** import the adapter
+implementations at top level — only ``base`` and the already-shipping
+``docx_adapter`` are imported eagerly.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from changex_core.adapters.base import (
+    AdapterError,
+    BeforeMismatchError,
+    DocumentAdapter,
+    NodeNotFoundError,
+    OversizedOpError,
+    UnsupportedFormatError,
+)
+from changex_core.adapters.docx_adapter import DocxAdapter
+from changex_core.paths import safe_path
+
+# --------------------------------------------------------------------------- #
+# Format registry.
+#
+# Maps a lowercased file extension to a ``"<module>:<ClassName>"`` target. The
+# class is resolved by a LAZY import (see ``_resolve``) so the adapter module is
+# only imported when a file of that format is loaded — phase-2 modules
+# (xlsx_adapter, csv_adapter, pptx_adapter) therefore need not exist at import
+# time, and their third-party deps stay opt-in.
+# --------------------------------------------------------------------------- #
+_REGISTRY: dict[str, str] = {
+    ".docx": "changex_core.adapters.docx_adapter:DocxAdapter",
+    ".xlsx": "changex_core.adapters.xlsx_adapter:XlsxAdapter",
+    ".csv": "changex_core.adapters.csv_adapter:CsvAdapter",
+    ".pptx": "changex_core.adapters.pptx_adapter:PptxAdapter",
+}
+
+# The suffixes ``load_adapter`` will accept (used as the ``allow_suffixes`` guard
+# at the path boundary so an unknown extension is rejected before any import).
+SUPPORTED_SUFFIXES: tuple[str, ...] = tuple(_REGISTRY)
+
+
+def supported_suffixes() -> tuple[str, ...]:
+    """Return the file extensions the registry knows how to load."""
+    return SUPPORTED_SUFFIXES
+
+
+def _resolve(target: str) -> type[DocumentAdapter]:
+    """Lazily import ``"module:ClassName"`` and return the adapter class.
+
+    Raises:
+        UnsupportedFormatError: if the module/class cannot be imported (e.g. a
+            phase-2 adapter that has not been created yet, or its third-party
+            dependency is missing). The original cause is chained for debugging.
+    """
+    import importlib
+
+    module_name, _, class_name = target.partition(":")
+    try:
+        module = importlib.import_module(module_name)
+        cls = getattr(module, class_name)
+    except (ImportError, AttributeError) as exc:  # adapter not yet implemented
+        raise UnsupportedFormatError(
+            f"adapter {target!r} is not available: {exc}"
+        ) from exc
+    if not (isinstance(cls, type) and issubclass(cls, DocumentAdapter)):
+        raise UnsupportedFormatError(
+            f"{target!r} does not resolve to a DocumentAdapter subclass"
+        )
+    return cls
+
+
+def adapter_class_for(path: str) -> type[DocumentAdapter]:
+    """Return the adapter **class** registered for ``path``'s extension.
+
+    The path is sanitized (suffix-guarded against :data:`SUPPORTED_SUFFIXES`) and
+    the matching adapter class is lazily imported. The file need not exist — this
+    is a pure type lookup, used by callers that want to construct the adapter
+    themselves. Use :func:`load_adapter` to also load the document.
+
+    Raises:
+        UnsupportedFormatError: if the extension is not registered or the adapter
+            module/class cannot be imported.
+        UnsafePathError: if the path fails sanitization.
+    """
+    resolved = safe_path(path, allow_suffixes=SUPPORTED_SUFFIXES)
+    suffix = resolved.suffix.lower()
+    target = _REGISTRY.get(suffix)
+    if target is None:  # pragma: no cover - safe_path already guards the suffix
+        raise UnsupportedFormatError(
+            f"no adapter registered for {suffix!r}; supported: {SUPPORTED_SUFFIXES}"
+        )
+    return _resolve(target)
+
+
+def load_adapter(path: str, **kwargs: object) -> DocumentAdapter:
+    """Load ``path`` with the adapter registered for its file extension.
+
+    This is the format-aware entry point the CLI and MCP server use instead of
+    hard-coding :class:`DocxAdapter`. It dispatches by **extension** (``.docx`` ->
+    :class:`DocxAdapter`, ``.xlsx`` -> ``XlsxAdapter``, ``.csv`` -> ``CsvAdapter``,
+    ``.pptx`` -> ``PptxAdapter``), lazily importing the adapter module so unused
+    formats never pull their third-party deps.
+
+    ``path`` is sanitized (must exist, suffix-guarded). Extra ``kwargs`` (e.g.
+    ``author=`` / ``date=`` for docx) are forwarded to the adapter's ``load``
+    classmethod; adapters should accept the kwargs they understand.
+
+    Args:
+        path: The document to load. Extension selects the adapter.
+        **kwargs: Forwarded to ``<Adapter>.load`` (adapter-specific).
+
+    Returns:
+        A loaded :class:`DocumentAdapter` for the file.
+
+    Raises:
+        UnsupportedFormatError: if the extension is not registered or the adapter
+            is not yet available.
+        UnsafePathError: if the path fails sanitization or does not exist.
+    """
+    resolved = safe_path(path, must_exist=True, allow_suffixes=SUPPORTED_SUFFIXES)
+    cls = adapter_class_for(str(resolved))
+    loader: Callable[..., DocumentAdapter] = cls.load  # type: ignore[assignment]
+    return loader(str(resolved), **kwargs)
+
+
+__all__ = [
+    # contract + errors
+    "DocumentAdapter",
+    "AdapterError",
+    "BeforeMismatchError",
+    "OversizedOpError",
+    "NodeNotFoundError",
+    "UnsupportedFormatError",
+    # docx implementation (shipping)
+    "DocxAdapter",
+    # registry / factory
+    "load_adapter",
+    "adapter_class_for",
+    "supported_suffixes",
+    "SUPPORTED_SUFFIXES",
+]

changex_core-0.1.0/src/changex_core/adapters/base.py

@@ -0,0 +1,109 @@
+"""The ``DocumentAdapter`` contract every format adapter implements.
+
+This abstract interface is the anti-drift contract between the journal/render
+layer and each format. The journal calls only these methods, so a new format
+(xlsx, pptx) plugs in without touching journal or render code.
+
+Key invariants an implementation must uphold:
+
+* ``to_model()`` returns a tree whose ``node_id``s are **opaque and
+  edit-invariant** (never content hashes).
+* ``apply(op)`` mutates the in-memory model and **raises on a before-mismatch or
+  an oversized op** (the validation the MCP boundary also performs, enforced here
+  so direct/core callers get the same guarantee).
+* ``render_tracked()`` returns native tracked-changes bytes (for docx: real
+  ``w:ins``/``w:del`` revisions a Word/LibreOffice user can accept/reject).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from changex_core.model.nodes import Node
+from changex_core.ops.vocabulary import Op
+
+
+class AdapterError(RuntimeError):
+    """Base error for adapter operations."""
+
+
+class BeforeMismatchError(AdapterError):
+    """Raised when an op's ``before`` substring is not present in the node.
+
+    This is the boundary guard that kills blind full-node overwrites: the agent
+    must pass the exact text it intends to change, and the adapter refuses if the
+    node's current content does not contain it.
+    """
+
+
+class OversizedOpError(AdapterError):
+    """Raised when an op rewrites too much of a node or spans more than one node.
+
+    The structured message instructs the caller to split the change — the error
+    message is itself the prompt the model should act on.
+    """
+
+
+class NodeNotFoundError(AdapterError):
+    """Raised when an op targets a ``node_id`` not present in the model."""
+
+
+class UnsupportedFormatError(AdapterError):
+    """Raised when no registered adapter handles a path's file extension.
+
+    Emitted by :func:`changex_core.adapters.load_adapter` when the (sanitized)
+    path's suffix is not one of the registered formats (``.docx`` / ``.xlsx`` /
+    ``.csv`` / ``.pptx``). The message lists the supported suffixes so the caller
+    can correct the input.
+    """
+
+
+class DocumentAdapter(ABC):
+    """Abstract base for format adapters (docx implemented; others reserved)."""
+
+    @classmethod
+    @abstractmethod
+    def load(cls, path: str) -> "DocumentAdapter":
+        """Load a document from a (sanitized) path and build the model."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def baseline_sha256(self) -> str:
+        """Return the sha256 of the original document bytes captured on load."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def to_model(self) -> Node:
+        """Return the current canonical model tree (root node)."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def set_model(self, root: Node) -> None:
+        """Reset the adapter's working state to ``root`` (used by replay)."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def resolve(self, node_id: str) -> Node | None:
+        """Return the model node with ``node_id``, or ``None`` if absent."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def apply(self, op: Op) -> None:
+        """Apply one op to the model.
+
+        Raises:
+            BeforeMismatchError: if the op's ``before`` is absent.
+            OversizedOpError: if the op is too large / multi-node.
+            NodeNotFoundError: if the target node is missing.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def render_tracked(self) -> bytes:
+        """Render the applied ops as native tracked-changes bytes."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def save(self, out_path: str) -> None:
+        """Write the tracked document to a (sanitized) ``out_path``."""
+        raise NotImplementedError